Import Products from a Flat File

With Miva Merchant you can import product data from a flat file — a plain–text file containing set types of data separated by a tab or text character. This is an efficient way to add or make changes to many products at one time.

Overview of The Process

Before we discuss each step in detail, let's look at the big picture:

• Begin by creating a plain-text "flat file" containing the information to be imported

• Upload this file to the server via the Miva Merchant administration interface

• Specify how the fields are separated — that is what character is used as a delimiter

• Next you will see all the information presented in rows (one for each product) and columns (one for each field)

• Specify how the information should be imported and what each column contains

• Click Import and the data will be brought into your store

Create the Flat File

You can edit a file that you created by exporting categories from your store (such as products.dat) create an entirely new file or create the file by exporting data from another source such as a product information database provided by a supplier.

Enter the product data in any text editor (not a word processor) or in a spreadsheet program that supports exporting files to text files. Put information about each product on a separate line.

When you import the file you will specify the delimiter — the character (or tab) used to separate each field. The vertical pipe character | is recommended because it is unlikely to be used in any text or HTML. A tab can also be used. Although the comma is frequently used as a delimiter do not use it in this case as any commas in product descriptions would be interpreted as beginning a new field.

Delete the Header Row, If It Exists

If the flat file you are working with contains a header row, usually the first row, with the names of each field (such as PRODUCT_CODE, PRODUCT_NAME, etc.) delete that row before importing the product data. This is commonly the case if you are starting with a file exported from the store earlier, like products.dat.

If you forget and leave the row in the file it will be imported into your store as a new product. Simply delete this "product" as you would any other in the administration interface.

What Fields To Include

Miva Merchant can import any or all of the following fields or pieces of information about each product. For more detailed explanations and tips on using each field most effectively see Edit Product/Product and Inventory Settings and E-mail Notification.

Your flat file can contain more or fewer fields than those listed below and they can be in any order. For instance, if you are only updating the prices for a set of products the file would only need to include the product code and the price. When you import the data you will specify what each column contains. If there are extra fields these can simply be ignored during the import process.  You do not need to remove them from the flat file.

Yes / No Fields

For each of the Yes/No fields below the number 1 is used to indicate Yes and 0 (zero) for No. Yes and No (case insensitive) will also work and may be easier for you to read when working with the file.

If you prefer "True" (case insensitive) or any positive number is interpreted as a positive response. Leaving the field blank or entering any other text, zero, or any numbers other than positive whole numbers will be taken as a negative response.

Code

The string of characters by which the product is identified and referenced. The product code can be up to 50 characters long and must be unique. Codes can contain upper- and lower-case letters and numbers, hyphens, and underscores.

If you are importing new products the codes must not be the same as any that already exist in the store. If an imported product had the same code as an existing product the imported information could update or replace the information for the existing product depending on the options selected when importing.

If you are importing changes to existing products such as new pricing or descriptions the product code must be the same as the code that exists in the store. Using a different product code would create a new product with that code.

Name

A descriptive name which will be seen by shoppers in your store. The product name can be up to 100 characters long. Upper- and lower-case letters along with numbers, spaces and symbols can be used. You can change the name without affecting references to the product.

Category Codes

The code for the category is listed under

If you do accidentally enter an unrecognized category code that code will be ignored. The product will be imported as not belonging to a category. You can always assign it to a category later in the administration interface.

Products can belong to multiple categories. To enter several categories in this field separate the category codes with a comma. This is another good reason to avoid using a comma as the delimiter in a flat file.

Price

Enter the price using decimal numbers only. Do not use any currency symbols or text.

Cost

Enter the cost using decimal numbers only. Do not use any currency symbols or text.

Weight

Enter the weight of the product, using only numbers, and a decimal point if needed. The unit of measurement used is the one entered under Edit Store / Settings. If the weight unit for your store is kilograms, you would enter a weight of 5.25 here for a product weighing 5.25 kilos.

Description

Enter the product description using plain text or HTML.

Taxable

Is the product taxable or not? Enter 1 or 0 or Yes or No, following the guidelines above for Yes/No fields.

Active

Is the product active or not? Active products are displayed in the store. Inactive products cannot be seen by shoppers. Enter 1 or 0 or Yes or No, following the guidelines above for Yes/No fields.

Thumbnail Image

This is the smaller of two pictures of the product. Enter the path to the image file on the server including the file name.

Depending on how Miva Merchant is installed in your case this will be something like graphics/000000001/myimage-sm.gif. If you are not sure where image files are located refer to an existing one as an example. To do this in the administration interface in the menu under your store name, click Products. Locate a product which you know already has an image associated with it and click Edit. Select the Images tab at the top of the screen. The paths to the two images for that product will be shown there. If you have no products with images create one as a test case and follow the example it provides.

This is a location only — if the image is already on the server at the specified location it will be displayed when the product is viewed. If the file is not already on the server remember that you will need to upload it.

Full-sized Image

This is the larger of two pictures of the product. Enter the path to the image file on the server including the file name.

Depending on how Miva Merchant is installed in your case this will be something like graphics/000000001/myimage-lg.gif. See above for details.

Attribute Template Code

Enter the code for the Attribute Template you previously created and want to assign or copy to this product.

Adjust Stock By

If the product exists in your store already and the inventory level is being tracked, you can adjust the quantity upward or downward by entering a positive or negative number in this field. Tthis number will be added to (or subtracted from) the current quantity on hand. Do not enter the total here, enter the adjustment only.

If this is a new product or you are just now turning inventory tracking on for an existing product use this field to enter the initial quantity on hand.

Track Product Inventory

Is inventory tracking used for this product? Enter 1 or 0 or Yes or No following the guidelines above for Yes/No fields.

In Stock Message (Short)

Enter the short version of the message customers will see when this product is available.

In Stock Message (Long)

Enter the long version of the message customers will see when this product is available.

Track Low Stock Level

Is a low stock level tracked for this product? Enter 1 or 0 or Yes or No following the guidelines above for Yes/No fields.

Low Stock Level

Enter the number of items in inventory that will be considered low stock for this product. If you enter 6 when the on-hand quantity reaches 6 customers will see the low stock messages in the store. If you are using e-mail notification for this product you will be alerted by e-mail that stock is running low when this number is reached.

Low Stock Message (Short)

Enter the short version of the message customers will see when the stock level for this product reaches the low level you specified.

Low Stock Message (Long)

Enter the long version of the message customers will see when the stock level for this product reaches the low level you specified.

Track Out of Stock Level

Is an out of stock level tracked for this product? Enter 1 or 0 or Yes or No following the guidelines above for Yes/No fields.

Out of Stock Level

Enter the number of items in inventory that will be considered out of stock for this product. Many merchants use 0 (zero) but any positive, whole number can be used. If you enter 1 when the on–hand quantity reaches 1 customers will see the out of stock messages in the store. If you are using e-mail notification for this product you will be alerted by e-mail that stock has run out when this number is reached.

Hide Out of Stock Products

"Yes," "True," (case insensitive) and positive numbers all mean "yes." Any other string or numbers other than positive whole numbers mean "no."

Out of Stock Message (Short)

Enter the short version of the message customers will see when the stock level for this product reaches the out-of-stock level you specified.

Out of Stock Message (Long)

Enter the long version of the message customers will see when the stock level for this product reaches the out-of-stock level you specified.

Limited Stock Message

Enter a message to inform a customer when the inventory is not sufficient to fill their order. For instance, if you have 10 of an item on hand and a shopper attempts to purchase 15 of them this message will be displayed.

Import The Product Data

If you are not on the Import Products screen already, go there now. To do so, expand the Utilities menu below the store name in the left navigation area, then expand the Import Data menu and select Import Products from Flat File.

Upload the Flat File

Click Upload and transfer the product data file from your local machine using the following process:

• Click Upload to display the Upload File dialog box.

• Enter the path to the data file or click Browse... to find the file on your computer.

• Your standard file selection dialog box will appear. Select the data file you need. The file name cannot have spaces in it.

• The path to the file on your computer will be entered in the File field of the Upload File dialog box.

• If you have uploaded a file with the same name before and now you want to use this new file instead, select Overwrite.

• Click Upload to copy the file to your server and close the dialog box.

Specify a Delimiter

By default the Tab character (ASCII 9) is the delimiting character between fields in each record. If your import file uses a different delimiter between fields, select Other and enter the character to be used.

Click Next. This screen will offer several options and shows the first five records from the file as examples. All the records from file will be imported even though they are not visible here.

Specify How to Handle Data with Respect to Existing Products

There are three options for importing data when existing products have the same product codes. If there are no existing products, like when you initially import products into your store, any of the options will work equally well.

In all cases new products will be created when imported product codes do not exist in the store already. Products in the store which are not mentioned in the flat file will always be unaffected.

Keep Existing Products

Imports only information on new products — products that are not already present in the store. Any records in the flat file that refer to existing product codes will be ignored.

For instance, if your flat file includes old data on all the products in your store but you have added a few more new products that need to be uploaded, choose this option. The new products will imported and the existing ones will be left untouched.

Update Existing Products

Imports updated information into existing products. Other information about the updated products will remain unchanged.

For instance, if you were updating the prices for products from one manufacturer you would select this option. Only the prices for the existing products referenced in the flat file would be changed. All the other information for each product, like description, on-hand quantity and so on would remain as it was.

Replace Existing Products

Completely replaces all of the information about included products with new information from the flat file.

If you were doing a major cleanup for all the products in one category you could import entirely new information for those products. Any information not included in the flat file, if you did not specify a cost, would be deleted.

Specify How to Handle Attribute Templates

When attribute template codes are included in the flat file, you choose how they should be handled.

Select Use if attribute templates should be used by reference or Copy if they are to be copied to the products. When the attribute template is referenced a simple update to the template is immediately applied to all products referencing it. When the template is copied to a product, it creates a set of attributes for that product, independent of the template. Any future changes to the template will not affect the product's attributes.

Specify How Each Field Will Be Imported

Remember, this screen shows the first five records from the file as examples. All the records from file will be imported even though they are not visible here.

The flat file can contain just a few fields for each product or many more than you need. Specify using the drop-down lists at the top of each column how each field will be used. To ignore a field select <Skip>.

Be sure you designate one field that contains the Product Code because that is what Miva Merchant uses to find the correct records to update.

For instance for each item the file could contain (1) your supplier's name, (2) their phone number, (3) the product code, (4) description, and (5) price. To ignore the first two (supplier's name and phone number), select <Skip> at the top of the first two columns. Select Product Code for the third column, Description for the fourth, and Price for the fifth column.

Click Import and the products from the flat file will be brought into the store according to your specifications.

Upload Any Image Files

If the flat file included references to the locations and names of product image files be sure those images are actually present. If they do not exist on the server already upload them now. This is easiest when using an FTP (File Transfer Protocol) program. Your hosting company can help you get started.