IndieCommerce Bulk Importer

    Welcome to the IndieCommerce custom product bulk importer! This system is designed to help you create and manage a large number of custom products on your IndieCommerce website.

    REQUIRED READING

    Before using this system, it's important to be up on the basics of custom products. If you've never created a custom product class before, please see the help documentation on BookWeb.org:

    NOTE: The IndieCommerce Bulk Importer module will be enabled on IC sites upon request, please email us to request the module be enabled.

    KEY CONCEPTS

    Now that we've got the basics out of the way, there are a couple of key concepts used in this bulk import system:

    • Staging Table - a "temporary" table which holds uploaded product data for review before it is imported into your website.
    • CSV Template - a spreadsheet file in the .CSV format that holds information about your custom products.
    • Headers - the first row of the CSV template file. The headers describe which data in the CSV corresponds to which fields on your website.
    • Staging Table Schema - the columns in the staging table. You can think of the staging table as an online copy of your CSV file. When you upload a CSV file, the server reads the headers in your CSV file and copies the data you uploaded into the Staging Table for processing. Sometimes, when you make changes to product classes on your website, such as adding fields or attributes, the Staging Table Schema can become "out of date" and a rebuild may be required. You can think of this as an automated process that recreates the storage system with updated headers.

    STAGING TABLES

    Each product class on your website has three staging tables:

    • Field - this table defines the basic properties of each product, such as the title, description, label, and base sell price. To create new products, you must upload a file to this table first. REQUIRED.
    • Attribute - this table allows you to define variations of your existing products using attributes and options; for example, to specify size and color variations. OPTIONAL.
    • Stock - this table allows you to provide information about the quantities on hand per product, or per attribute/option combination. OPTIONAL.

    IMPORT ACTIONS

    To get started, navigate to Store > Products > Import Products Status and choose a product class and table (probably Field) to begin with. Click the link that says "Up-to-date" to see the available actions:

    • View and Import Staged Products - choose this link to view staged products that have been imported already, and to import a new CSV file.
    • Download Blank CSV Template - use this option to download a blank CSV template you can fill in with new products.
    • Download CSV Export of Existing Products - this option allows you to download a CSV template which is pre-populated with all existing products of that class. This can be useful for making bulk updates, as well as for a backup.
    • Rebuild - choose this option to rebuild the Schema of the Staging Table.

    IMPORTING PRODUCTS (FIELD STAGING TABLE)

    COLUMNS

    The Field Import provides the following columns:

    • SKU - the product SKU. Also called "model" in Ubercart. This must be a unique value, and will be used to identify the product in subsequent uploads to update it.
    • Title - the title of the product.
    • Sell Price - the price the product sells for.
    • Published - whether the product is published (shown to customers) or hidden on the site. Must be 1 (published) or 0 (unpublished).
    • fld_body - the product description (body field). HTML can be added here.
    • fld_uc_product_image - the main product image. Use a valid URL where the image can be retrieved (i.e. http://www.another-website.com/images/yourproduct.jpg).
    • Other Columns Beginning fld_ - these represent other fields on your site which are part of the given product class. Fill in values as appropriate for these fields when uploading.

    USUAL WORKFLOW

    1. To import new products, start by downloading a CSV template for the Field Staging Table for a product class of your choice.
    2. Click "View and Import Staged Products" for the product class you have chosen. In addition to an upload form for your CSV file, this page will provide more information about the columns in your CSV file, including any custom ones.
    3. Fill in the CSV file with a few new products. It can be helpful to start with a small number to get the hang of the importer.
    4. Use the upload field provided to upload your CSV file.
    5. Uploaded products will appear in the Staging Table afterward. Check the data to make sure everything looks OK (no columns reversed, etc.)
    6. If anything looks off, you can use the "Truncate Table" link to empty the table of its contents, then upload a new file.
    7. Click the "Validate Now" link to validate the staged products.
    8. Validating the products will add values to the "Status" column. Any errors will appear in the "Messages" column at the far right of the table.
    9. If any products have errors, they cannot be imported at this time. However, any entries without errors can still be imported. The system will tell you how many of each there are.
    10. If any products have errors, you can download a CSV file with just those products, along with any error messages. This can make it easier to correct just those entries and re-upload.
    11. Click the "Import Ready Products" to import all products without errors. This will create live content on your website, so check carefully before clicking this link!
    12. When in doubt, you can always truncate the table, update your CSV file, and upload again.

    IMAGES
    Images must be stored on an external server and provided as links in your spreadsheet.

    LIMITATIONS

    • Fields with multiple values are not supported at this time. Just one value per field.
    • File fields other than images are not supported.

    TIPS & TRICKS

    • Start with a small number of products until you're comfortable with how the import process works.
    • You can omit a column entirely from your CSV file if you don't want to update it at this time.
    • Check existing products to see whether they have the status "ready_update" or "ready_new" after validation and before import. If they say "ready_update", the importer has matched them to an existing product. If they say "ready_new", it thinks they are new products and may create duplicates. The SKU may not match (check case).

    IMPORTING ATTRIBUTES

    Use this workflow to extend your custom products with attributes and options, creating product variations customers can choose from when they add the product to their cart.

    COLUMNS

    • SKU - the original SKU/model of the base product.
    • Adjusted SKU - a different SKU per product variation.
    • Fields Beginning attr_ - represent attributes created on the site. Must be filled in with a valid option value.
    • Fields Beginning attr_ and Ending _price - price adjustments from the base price (sell_price, defined in the field upload) for a given option selection.

    USUAL WORKFLOW

    1. Before importing attributes & options, you must first define both the attributes and the specific option values you wish to import in the usual way. It is NOT necessary to specifically add the attributes and options to the class you want to work with. All attributes/options you define will be available for any class.
    2. Download a CSV template for the class of your choice.
    3. You will need to provide a line for each product variation you wish to create. Set the SKU equal to the SKU for the product. This means that if you are creating six variations, you will need to provide the same SKU on all six lines.
    4. Provide a different "adjusted SKU" for each product variation. For example, if I have a product with SKU "TSHIRT" and I am creating a small red T-Shirt, the adjusted SKU might be "TSHIRT-R-S".
    5. Each attribute (i.e. Size, Color) will appear as a column prefixed with "attr_", for example, attr_Size. Fill this column in with the exact option value for the variation (i.e. Small).
    6. Each attribute also has a column providing a "price" option. Just like when editing attributes and options directly through the site, this field is used to set an adjustment on the regular price for the product. For example, if the XL size is $5.00 extra, you would put "5.00" in this field.
    7. Once your CSV file is ready, follow the same procedure as for the Field file to upload and process it.

    TIPS AND TRICKS

    • Because of a limitation in the way Ubercart works, all possible combinations of a product will be created for SKUs with multiple attributes. For example, if you define a Small Red T-Shirt, a Large Red T-Shirt, and a Small Blue T-Shirt, a Large Blue T-Shirt will also become available to buy, even if you do not define it explicitly. It is therefore important to use stock (described next) to manage inventory levels for product variations. By setting a variation's inventory level to 0, you can keep that variation from being purchased.
    • Attributes & Options cannot be removed using this importer. You will need to remove them through the web interface.

    IMPORTING STOCK

    The stock feature allows you to specify inventory levels for your custom products. It can be set on individual products, as well as on adjusted SKUs.

    COLUMNS

    • SKU - the original SKU/model of the base product.
    • Adjusted SKU - a different SKU per product variation.
    • Stock Active - 1 or 0; are stock numbers tracked for this product?
    • Stock - the inventory number on hand for this product/product variation
    • Stock Threshold - if stock dips below this number, an administrator will be notified via email.

    USUAL WORKFLOW

    1. Download a CSV template or full export file for the class of your choice.
    2. Use the SKU column to specify the product, and the Adjusted SKU column to specify the variation. If the product has no variations, supply the original SKU in both columns.
    3. Stock Active is a boolean field (0 or 1) specifying whether stock numbers are tracked for this product or not. It is off (0) by default, meaning customers can purchase as many of the product as they like without restrictions. If you are intending to provide specific stock numbers for a product, you should turn this on (1).
    4. Stock is the actual inventory number. Provide the inventory count here.
    5. Stock Threshold refers to the level at which, if inventory drops below this number, an email will be sent to an administrator. This can be helpful as a reminder to replenish inventory, or to prepare to deactivate a listing if supply is limited.
    6. Upload and process the file in the same way as the field or attribute files.

    TIPS AND TRICKS

    • If you are also selling a product in-store, or through another venue the website doesn't know about, it's important to refresh inventory numbers often.
    • To stop using the stock feature for a given product or variation, just set its Stock Active column equal to 0. The system will ignore any stock values previously entered and allow customers to purchase it.

    MASTER STOCK/PRICE IMPORT

    This is an advanced tool for making bulk updates to all products on the site. Sometimes you might want to update prices and stock numbers for many products across different classes. Using the import system above, this could require multiple file uploads, two per class (one for price, and one for stock). With this feature, you can update these fields for all products at once.

    You can find the Master Stock/Price Import by navigating to:
    Store > Products > Import Products Status > Import Master Stock/Price File

    From this screen, you can generate an export of existing products for download. It's a good idea to do this, both as a backup, and to familiarize yourself with the file format. The file has four columns:

    • sku - REQUIRED - the base SKU (model) for the product.
    • adjusted_sku - REQUIRED - the SKU for the product variant. If no variants exist, this will be the same as the base SKU.
    • sell_price - the sell price of the product. Note that this is the base price of the product, and does not affect any adjusted prices based on attributes/options. To change those prices, you must use the Attributes import.
    • stock - the quantity of the product currently on hand.

    Use the form provided to upload and process your stock & price updates. Unlike the other imports, there is no staging table and no preview--changes will be applied immediately, so take care when preparing your file before uploading.