SingleFeed Integration Module for Miva Merchant

This document gives instructions on installing and using this module for Miva Merchant shopping-cart systems. If you need additional support, please visit the SingleFeed support page, and review the documentation or contact your account manager.

This document applies to module version 1.2 for Miva Merchant version 5.x, released September 2013.

Table of Contents


Introduction

Welcome to SingleFeed! Our Miva module will make it easy for you to access SingleFeed services with just a few clicks of your mouse.

Customer advisory

What's new in version 1.2


Installation

The procedure for installing this module is the usual one for Miva Merchant modules: add the module to the site, and assign it to the store. The procedure is explained below in a bit more detail. If you need more information, see your Miva representative or documentation.

To install the module in your Miva domain or "mall," follow the steps below:

  1. Log in to the Miva Merchant Administration page.
  2. In the left-side menu, click the  +  icon next to the Global Settings link; this will open a sub-menu.
  3. In the Global Settings sub-menu, click the [Add] link next to the Modules link.
  4. In the right-side frame, click the Upload button.
  5. In the Upload box, click the Browse button.
  6. Navigate to the folder on your computer where the module file, singlefeed.mvc, is located, and select the file.
  7. In the Upload box, click Upload. After a few moments, the Upload box will close.
  8. In the right-side frame, click the Add button.

After the module is installed, you need to assign it to your store.

  1. If your Miva domain has two or more stores, in the left-side menu, click the  +  icon next to the link labeled with the name of your store. This will open the store's sub-menu. (If your Miva domain only has one store, this sub-menu will already be open.)
  2. Click the Utilities link (near the bottom of the store's sub-menu).
  3. In the right-side frame, check the box labeled SingleFeed Integration.
  4. Click the Update button in the lower right corner of the frame (you may need to scroll down to see it).

Initial setup

After installing the module, there are a few settings you need to enter.

All these settings are explained in detail below. After the above steps are completed, please read the descriptions of the other settings, and adjust them as needed to best suit your store.

Page templates

In order to place tracking codes on your store pages, the module requires <mvt:item> tags to be placed on the templates for the Product Detail (PROD) and Invoice (INVC) pages. Upon installation, the module attempts to automatically insert these tags into the page templates. However, if your pages have been customized, the module may be unable to insert the tags. Also, if you use a page-template module that provides many different templates for Product Detail pages, the module cannot modify these additional templates; you will need to insert the <mvt:item> tag manually.

The specific tags that are used are:

The best location for these tags is near the bottom of the page, but inside the HTML body element, i.e. before the </body> tag. If you need more help editing the templates, consult your hosting company or Miva representative.


Module settings

This module has two admin pages: one for exporting product data, and another for tracking codes.

The various settings on each page are described below.

Export settings

This page displays controls how you export your product data to SingleFeed. The upper section has a number of settings and an Export button that generates the data file. The lower section has a set of dropdown menus for data field assignments.

Output file path

Enter the folder and file name for the exported file. The file must be placed in your site's Miva script folder, or in a sub-folder of it. In most sites, the Miva scripts folder is your main home-page folder, which is often named public_html or www. However, the exact location of this folder will depend on your site's configuration. You may wish to create a sub-folder for the exported file. For instance, if you create a folder named singlefeed, and you want the exported file to be named products.csv, then the setting in the text box will be singlefeed/products.csv.

The folder that contains the exported file must have its permissions set so that SingleFeed will be able to read the file. If necessary, consult your hoster for help choosing and creating this folder.

Export button

Clicking this button causes the module to export the data on your store's products to the output file. If an older file exists from a previous export, it will be overwritten (the old data will be deleted).

Note: the module will only export data on active products. Inactive products can't be purchased or even viewed in the store, so exporting this data could be misleading to your customers. However, inventory variants for attributes, such as sizes and colors, are a special case. They are inactive, but the module will still export them if their master product is active.

Time limit

Your Miva store has a "global" time limit, which is set by your hosting company. Any store or module function that attempts to run longer than this will be terminated with a timeout error message. If your store has a large number of products, the module can interrupt itself and restart, in order to export all the products without timing out.

The module's time-limit setting controls how long the module will export products before it interrupts itself. This setting should be as large as possible, but slightly less than the global time limit set by the hoster. Upon installation, the module sets its limit to be five seconds shorter than the global timeout. Most stores will not need to adjust this setting. If your store has an extremely large number of products, you may need to reduce this setting somewhat, in order to allow more time at the end of the export for final "clean-up" operations.

Tip: If necessary, you can ask your hoster to increase your global timeout. Some hosters set this quite short, as a safeguard against "runaway" scripts. They may be willing to increase it when a user has a specific need.

Query size

When doing an export, the module reads product data from your store's database in large sets. If the module reads the data one product at a time, or in small sets, the export will take longer. But if the module reads too many products in one set, the data will fill up the available memory. This, too, can cause the export to run slowly, or even to fail.

Upon installation, the module sets a query size of 1000. Most stores will not need to adjust this setting. If your exports take too long, you may try raising the query size. If your products generate large amounts of data (long descriptions, lots of custom fields, etc.), you may need to reduce the size.

Inventory tracking

This menu selects how the module exports inventory status (In or Out of stock) for your products. The module is compatible with the Miva built-in inventory system, and also with the Inventory Manager module from Viking Coders. You also have a "None" setting, which causes the module to not export any inventory data. However, it is recommended that you export this information, to keep your listings as complete and up-to-date as possible.

Default field values

The module provides default values for some of the fields in the exported file. These settings will be used for any product that does not have some other data available. If you assign a source for any of these fields (using the field-assignment menus explained below), then the assigned source will be used for each product; but if the source is empty, the module will export the default value instead. If you don't assign sources to any of these fields, the module will use the default value for all products.

Tip: Some fields are not required, but are highly recommended because they increase the value of the listings to your customers. The default value settings provide a convenient way for you to make sure that these fields have a value, even if you don't have data for them elsewhere in your store.

Field assignments

The module provides a dropdown menu for each of the data fields in the exported file. You can use these menus to select where the module gets the data that it places in each field. Some of the fields are required: they must contain some data for every product that you export. These fields are highlighted in the list.

Each dropdown menu lists all the possible locations from which the module can read the data that it exports. There are three types of data sources:

For some fields, the module pre-selects a data source when it is installed. For the other fields, if they are required, you must either select a data source or enter a default value. Many of the fields are optional; but it's recommended to supply sources for as many as possible, to maximize the value of your product listings.

Tracking-code settings

This page has settings that control the use of SingleFeed tracking codes to monitor activity in your store.

If you have trouble getting tracking codes to work, there may be a problem with your page templates. Review the section on Page templates above, and check your templates to ensure that the <mvt:item> tags are properly installed.

Enable

This checkbox turns the tracking-code functions on or off. This allows you to control the codes without editing your page templates.

Account ID

Enter the SingleFeed account ID that was assigned to you when you signed up. This number is available on the Profile page of your SingleFeed account.


Automatic exports

To keep your SingleFeed listings up to date, you should run the export any time you add, remove, or change products in your store. It's quite easy to do this manually, by clicking the Export button on the module's admin page. However, you can also set up the module to run automatically, once a day, or at some other time interval that you may prefer. To have the module run automatically, you must set up a scheduled task or "cron job" on your server.

Notes:

To set up a scheduled task, you will have to specify a server command of the form:

/usr/bin/GET 'YourURL' >YourReportFile 2>&1
-- which includes a URL to run the export, and a file path where server will store a report of the module's activity.

Normally, running the export requires that you log in to the admin page, navigate to the module's admin page, and then click the Export button. For automatic execution, you can create a URL that will log in and run the export, all in one operation. The module will display a report of its execution, and the cron command will save the report in a file that you can view later.

The URL will be of the form:

http://YourDomain/YourPath/admin.mvc?Action=LOGN&username=YourUser&password=YourPass&Store_Code=YourCode&Screen=SUTL&Module_Code=SINGLEFEED&SGFD_auto=start

-- where:

The rest of the URL should be exactly as shown above, but all on a single line, with no spaces, tabs, or other white-space characters.

The exact format of the report file path, YourReportFile, will depend on your server setup; if necessary, consult your hoster or Miva rep. You should be able to set up a path that will place the report file in a folder where you can retrieve it by FTP or view it with a browser. The file format is HTML, so you can view it with any Web browser. The filename can be anything you like; something clear such as singlefeed_auto_report.html is recommended.

Your server may have a control-panel page where you can enter the URL and set the time interval. In some cases, you will have to manually edit a "crontab" text file. Check with your hoster if you need help with this.

Notes:

Timeouts during automatic exports

As mentioned above, the module has the ability to interrupt and restart itself, to prevent timeout errors in case the export takes longer than your server's time limit. However, this only works when you run the export manually from a Web browser. When you use scheduled tasks to run the export, you may need to take some extra steps to ensure that the export runs to completion. Specifically, you may need to set up two or more scheduled tasks.

To find out whether you need additional tasks, try running the export from the browser. If it restarts itself, you will see a message on the screen: Export will continue; please wait ... followed by Resuming export (step 2). If the store has a large number of products, you may see step 3, 4, etc. before the export completes.

If your export requires two or more steps, you will need to schedule another task for each additional step. For safety, it's a good idea to always set up one more step than you think you need.

The cron command for step 2 and beyond is almost the same as for step 1. The URL parameter

&SGFD_auto=start
must be changed to
&SGFD_auto=continue
Also, you will probably want to use a different file name for the step 2 report file. Otherwise, step 2's report will overwrite step 1's.

For an export that takes two steps, you will program the &continue task to run a few minutes after the &start task. You must leave enough time between them so that step 1 can complete before step 2 starts. The maximum length of a step is shown on the module's admin page. In the gray box near the top of the page, you will see the label "Global limit:" followed by the time limit in seconds.

If your export requires 3 or more steps, you will need a 3rd, 4th, etc. scheduled task. These tasks all use the &SGFD_auto=continue parameter.

Notes: