SingleFeed Integration Module for Miva Merchant
SingleFeed provides the Miva module as is and without direct technical support from SingleFeed. While it is designed to work with standard Miva stores, there are many factors which are out of our control.
This document gives instructions on installing and using this module for Miva Merchant shopping-cart systems.
The module is attached at the end of this article and downloadable from here.
If you need additional support, please contact us at firstname.lastname@example.org or file a support ticket from within your account.
This document applies to module version 1.2 for Miva Merchant version 5.x, released September 2013.
Table of Contents
- Module settings
- Automatic exports
Welcome to SingleFeed! Our Miva module will make it easy for you to access SingleFeed services with just a few clicks of your mouse.
- Product data export: You can export your store's product data to SingleFeed, for distribution to numerous comparison-shopping sites. Module settings allow you to tailor the format of the data, and to include any custom product fields that you have created.
- Tracking codes: You can monitor your store's operations via SingleFeed by using the recommended tracking codes. The module will automatically install these codes in your store pages (in most cases; see Advisory below). You can view reports on your store's activity by logging in to your SingleFeed merchant account.
- Upon installation, the module will automatically modify the store's page templates and "Item" settings, in order to put tracking codes on the pages. However, if your pages have already been edited or customized, it's possible that the module will not be able to edit the templates. In that case, the module will display warning messages during installation. If you see these messages, and you want to use tracking codes, you will need to manually edit some page templates. Instructions for this are included in the section on Page templates below. If you need more assistance, consult your hoster or Miva representative.
- The module exports product data into a file in a folder on your site, and SingleFeed retrieves it from that location. After installing the module, you will need to enter the name or path of this folder; and you will need to ensure that the folder's permission settings will allow SingleFeed to read it. This is described in more detail below in the section on Initial setup. If the folder location and permissions are not set up properly, SingleFeed will be unable to retrieve your product data. If necessary, consult your hoster or Miva representative for help with this.
What's new in version 1.2
- The export format includes a number of new data fields, including product SKU, GTIN code, and fields for marketing services such as Google AdWords. Also, a number of old, outdated fields have been removed.
- Supports "Additional Images" for stores that don't use the older Image and Thumbnail fields.
- Supports inventory variants for product attributes, such as sizes and colors. When you export a master product, the module will include all its variants in the export as well.
- The module can be run automatically by a scheduled task ("cron job") on your server.
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:
- Log in to the Miva Merchant Administration page.
- In the left-side menu, click the + icon next to the Global Settings link; this will open a sub-menu.
- In the Global Settings sub-menu, click the [Add] link next to the Modules link.
- In the right-side frame, click the Upload button.
- In the Upload box, click the Browse button.
- Navigate to the folder on your computer where the module file, singlefeed.mvc, is located, and select the file.
- In the Upload box, click Upload. After a few moments, the Upload box will close.
- In the right-side frame, click the Add button.
After the module is installed, you need to assign it to your store.
- 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.)
- Click the Utilities link (near the bottom of the store's sub-menu).
- In the right-side frame, check the box labeled SingleFeed Integration.
- Click the Update button in the lower right corner of the frame (you may need to scroll down to see it).
After installing the module, there are a few settings you need to enter.
- Click the "tab" link labeled SingleFeed Tracking.
- Enter the account ID that you were assigned by SingleFeed, and check the Enable checkbox. Then click the Update button.
- Go to the export settings page by clicking the + icon next to the Utilities link; this will open the sub-menu of utility modules. In this sub-menu, click the link labeled SingleFeed Export.
- In the Output file text box, you will need to enter the folder and file name where the module will place exported files. Also, you may need to change some of the other settings to suit your store. Then click the Update Settings button.
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.
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:
- <mvt:item name="singlefeed" param="product" /> in the Product Detail page templates
- <mvt:item name="singlefeed" param="order" /> in the Invoice page template
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.
This module has two admin pages: one for exporting product data, and another for tracking codes.
- To get to the export page, click the + icon next to the Utilities link; this will open the sub-menu of utility modules. In this sub-menu, click the link labeled SingleFeed Export.
- To get to the tracking-code page: In the left-side menu for the store, click the Utilities link. Then, in the right-side frame, click the "tab" link labeled SingleFeed Tracking.
The various settings on each page are described below.
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.
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.
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.
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.
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.
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:
- Standard product fields, such as the name, code, price, weight, etc.
- Custom product fields. This will include any custom fields that you have defined for the store, using the standard Custom Fields module that is built-in to Miva Merchant. If any other modules have defined custom product fields, they will also be available in the menu.
- Product category assignment. The module generates text for this by checking the category and sub-categories to which each product is assigned. The resulting text will show the category structure, such as Clothing > Men's > Shirts .
- Additional images. Newer versions of Miva Merchant allow you to create new images types; and you can select any of these image types for export.
- Master product. When the module exports product variants for attributes, such as sizes and colors, the module can export the product code of each variant's master product.
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.
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.
This checkbox turns the tracking-code functions on or off. This allows you to control the codes without editing your page templates.
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.
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.
- Setting up a scheduled task requires some detailed understanding of the server file system. If necessary, ask your hoster or Miva rep for assistance.
- The Singlefeed server reads your exported files between midnight and 2AM, Pacific time. To keep your data safe from incomplete transfers, do not schedule an export during this time. Set your cron job to run at least two hours before or after the prohibited time; that leaves a safety margin in case the servers get out of synch when switching in or out of Daylight Savings Time. To find out your own server's time zone, go to the Maintenance Mode page in the Miva admin; it displays the current time and date according to the server's internal clock.
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:
- YourDomain and YourPath are the domain and path for your Miva admin page. (You can see them in your browser's address bar whenever you are viewing an admin page.)
- YourUser and YourPass are the username and password for the Miva admin page.
- YourCode is the store code for this Miva store. (You may see this in the browser's address bar. If not, you can view it on the store's main admin page, the one labeled with the name of the store.)
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.
- The first time you try to run a scheduled task, it may get an error because of an incorrect file permission. On some servers, this error is normal. The next time the task runs, it should complete the export without errors.
- Once you have created a scheduled task, the Miva admin username and password will be displayed to anyone who has access to the scheduled tasks. Make sure to carefully control access to the tasks. For further security, you can create a special Miva admin user account, which is only used for running the export. You can use the store's Groups settings to restrict this account, so that it can't access other parts of the store.
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
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.
- Newer versions of Miva Merchant require that the passwords for admin users be changed every 90 days. If you create a speical user account for the cron job, remember to change the password, and also update the cron command to include the new password, every 90 days.
- Cron jobs don't always run exactly on schedule, and some servers will have problems running multiple jobs at short intervals. Always program the cron jobs at least ten minutes apart.
- You should set up a different name for each step's report file; otherwise each step's report will overwrite the previous ones.