Bulk Importer

Printer-friendly versionPrinter-friendly version

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.

BULK IMPORTER STORE BOOKS - USED, SIGNED, ETC.

This module allows stores to create 'store books', which are custom products that refer to new books available through Ingram but may be different from them. For example, they may represent used copies, signed copies, or unique editions.

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 Store Book module will be enabled on IC sites upon request, please email us to request the module be enabled.

STORE BOOK PRODUCT CLASS

This module establishes a new product class, ‘Store Book’, with many fields. The basic configuration of this product class and its fields are reserved; however, stores can add additional fields to the class if they wish.

Fields

The following fields are provided:

  • Title (title) - REQUIRED - The title of the book. Required, but will be automatically filled in using information found in the book database if left blank.
  • Sell Price (sell_price) - REQUIRED - must be supplied by the store. We will not assume these copies are for sale at the same price as the new edition.
  • SKU/Model (sku) - REQUIRED - Must be unique and must not be the book’s ISBN number, or any other ISBN. (It can be the book’s ISBN plus additional characters.) Example: 9780393356182S
  • Store Description (body) - A unique description of this copy of this book, provided by the store.
  • Published (published) - REQUIRED - Is the book "published" (active) on the site.  Must be 0 or 1.

Standard Book Data

These fields (except ISBN) will be automatically filled in using the data found in the book database if left blank. The store can optionally supply different values themselves, or change them later.

  • ISBN (fld_field_sb_isbn) - The original ISBN of the new edition of the book. Must be a valid ISBN if provided.
  • Primary Author (fld_field_sb_primary_author) - The primary author of the book. Must be in the format Last, First if provided.
  • Additional Authors (fld_field_sb_other_authors) - Any additional authors or contributors to the book. Must be in the format Last, First; Last, First if provided.
  • Binding Type (fld_field_sb_binding_type) - The binding type. Allowed values:

    • Hardcover
    • Paperback
    • Mass Market
    • Board Books
    • Cloth Textbook
    • Compact Disc
    • Imitation Leather
    • Library Binding
    • Leather
    • Loose Leaf
    • MP3 CD
    • Prebound
    • Picture Book
    • Ringbound
    • Slipcased
    • Smyth Sewn
    • Other
  • Publisher (fld_field_sb_publisher) - The publisher of the book.
  • Publication Date (fld_field_sb_pubdate) - The publication date of the book.
  • Book Description (fld_field_sb_description) - The standard publisher’s description of the book.
  • Cover Image (fld_uc_product_image)

Store Book Data

  • Condition (fld_field_sb_condition) - REQUIRED - Must be one of the following values:

    • New
    • Fine
    • Very Good
    • Good
    • Fair
    • Poor
  • Dust Jacket Condition (fld_field_sb_dj_condition) - If provided, must be one of the following values:

    • New
    • Fine
    • Very Good
    • Good
    • Fair
    • Poor
    • Missing
    • N/A
  • Signed Copy? (fld_field_sb_signed) - Yes/No
  • Inscribed? (fld_field_sb_inscribed) - Yes/No - Did the author write anything in the book in addition to signing it, such as the recipient’s name?
  • Ex-Library? (fld_field_sb_signed) - Yes/No
  • Advance Reading Copy? (fld_field_sb_arc) - Yes/No

PRODUCT MANAGEMENT

Manual

Store books can be created and maintained like any other product on the site. All fields marked REQUIRED above must be provided. Standard Book Data fields will be auto-filled on pre-save if empty.

  • The ISBN must be valid, if provided.
  • Any ISBNs that do not match will be marked as 'Unknown Book' and unpublished so the store can review/add metadata and then publish the product.

To create a store book product manually navigate to Content > Add Content > Store Book and complete the product form fields as appropriate as outlined in the document above.

Bulk Upload

Store books can also be uploaded through the IndieCommerce Bulk Importer. The field import for Store Books has a special validate process that will auto-fill Standard Book Data fields so the store can review them before importing.

Any ISBNs that cannot be found in the book database, and for which the store did not provide metadata, will be marked as errors and can be downloaded as usual. The store can add their own metadata and re-upload to process these books. (At a minimum, a title is required.)

To get started, navigate to Store > Products > Import Products Status and locate ‘Store Book’ and select the ‘Up-to-date’ link under ‘Field’ then select Download Blank CSV Template which will download a blank CSV template you can fill in with your Store Book products.

Additional Options

If you would like to add additional attributes or want to attach a stock quantity please refer to IndieCommerce Bulk Importer

MANAGE TAX

Products created within the 'Store Book' content type are not set to be taxed by default.

Navigate to Store  > Configuration > Taxes
 

  1. Select ‘edit’ in the tax row
  2. Scroll to ‘Taxed Product Types’ - find 'Store Book':

    • If the checkmark is PRESENT, the product class will be taxed
    • If the checkmark is REMOVED, the product class will not be taxed.
  3. Select 'Submit' at the bottom of the page.
  4. Repeat for ALL Tax options listed until all tax types are modified.

About ABA

The American Booksellers Association, a national not-for-profit trade organization, works with booksellers and industry partners to ensure the success and profitability of independently owned book retailers, and to assist in expanding the community of the book.

Independent bookstores act as community anchors; they serve a unique role in promoting the open exchange of ideas, enriching the cultural life of communities, and creating economically vibrant neighborhoods.

Contact

 

 

Copyright 2018 American Booksellers Association. BookWeb is a registered trademark of ABA.
Privacy Policy, Cookie Policy