Bulk Importer

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:

• Creating Custom Products
• Utilizing the Stock Module
• Content Types, Part 4
• Custom Products Webinar

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. This should match the SKU of the product in your Point of Sale System. It is OK to use UPCs or EAN-13s here. Do not use ISBNs for books or other products that already exist in the system. If you need to create unique versions of products already in the system, consider using the Store Books feature.
• 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).  We also now offer an option to upload images in a ZIP file; see "IMAGES" below.
• 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
If you have more than 100 images to upload, and using URLs from another website doesn't work, a bulk upload feature where you can send a ZIP file is now available. Please see this document for more information: https://www.bookweb.org/indiecommerce/bulk-upload-images

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).

Store Books: Used, Signed, and Unique Copies of Print Books

Store Books is a special feature that allows IndieCommerce stores to create unique versions of print books already available for sale on your IndieCommerce site. See this document for more information on how to use this feature.

LSI for Custom Products

This is a new feature to be released in 2020. More documentation and information on LSI for Custom Products will be coming soon.

Legacy Documentation

The documentation below is provided for historical purposes, and because some stores are still using these features. We recommend stores not currently using these features focus on LSI for Custom Products instead.

• Importing Attributes & Options - describes configurations not compatible with LSI for Custom Products
• Importing Stock (Legacy) - describes the older method for importing stock information.