Skip to content

Handler‐specific Usage Notes

Jump to bottom
lat9 edited this page May 29, 2026 · 3 revisions

DbIoOptionsStockFullHandler

This handler enables you to export and, more importantly, import configurations for your store's products' option-combinations! The handler can perform the following operations in support of your store's POSM configuration:

  • Export
  • Import
    • Update a record
    • Add a record, with possible "side-effects":
      1. Option-values added to an existing option
      2. Attributes added to existing products
    • Remove a record

I suggest first exporting your existing POSM configuration; that process will output a .csv that contains the field-defining headers that you'll need to import changes. In addition to that header information, the file will contain one line for each product-option-combination currently configured.

The import's processing, on a record-by-record basis, attempts to identify the associated product using the v_products_id or, if no match is found for the product's ID, its v_products_model. When a match-by-model is attempted, the model number must be unique within your products; an imported record going through match-by-model with a non-unique model will be disallowed.

Once an import-record's product has been identified, the handler next validates the v_products_options_combination value. This value identifies the option/option-value pairs for the current record's import; the field is formatted as option_name1**~**option_value_name1[**^**option_name2**~**option_value_name2 …], where the option-names and option-value-names are specified in the store's default language. Processing continues in the sequence described in the following table, stopping whenever the record has been determined to be not importable.

Condition Action Taken
No option found in the store's database matching option_namen The record is not importable.
No option-value found in the store's database matching option_value_namen If a unique option_namen has been located and no other issues are found with the record, option_value_namen will be created and associated with option_namen … for all languages supported by the store. Otherwise, the record is not importable. See Note 1, below.
No attribute is found for the current product for the combination option_namen~option_value_namen The option-combination is added (with default values) as an attribute for the current product. See Note 2, below.
All previous checks have passed. The product's option-combination is either added to, updated in or removed from the POSM configuration in the database.

Notes:

  1. For POSM versions prior to v4.1.5, newly-added option-values' sort-orders are set to 0. POSM v4.1.5 and later set the sort order to the maximum sort-order of the option-values currently defined for the option, plus 5.
  2. For POSM versions prior to v4.1.5, newly-added attribute-values' sort-orders are set to 0. POSM v4.1.5 and later set the sort order to be that associated with the specified option-value.

DbIoOptionsStockUpdateHandler

This handler enables you to export and update configurations for your store's products' option-combinations! The handler can perform the following operations in support of your store's POSM configuration:

  • Export
  • Import, update an existing record

I suggest first exporting your existing POSM configuration; that process will output a .csv that contains the field-defining headers that you'll need to import changes. In addition to that header information, the file will contain one line for each product-option-combination currently configured.

The import's processing, on a record-by-record basis, attempts to identify the associated product using the v_products_id or, if no match is found for the product's ID, its v_products_model. When a match-by-model is attempted, the model number must be unique within your products; an imported record going through match-by-model with a non-unique model will result in that record's import being disallowed.

Once an import-record's product has been identified, the handler next validates the v_products_options_combination value. This value identifies the option/option-value pairs for the current record's import; the field is formatted as option_name1**~**option_value_name1[**^**option_name2**~**option_value_name2 …], where the option-names and option-value-names are specified in the store's default language. Processing continues in the sequence described in the following table, stopping whenever the record has been determined to be not importable.

Condition Action Taken
No option found in the store's database matching option_namen The record is not importable.
No option-value found in the store's database matching option_value_namen The record is not importable.
No attribute is found for the current product for the combination option_namen~option_value_namen The record is not importable; use the DbIoOptionsStockFullHandler instead.
The product's option-combination is not currently POSM-managed. The record is not importable; use the DbIoOptionsStockFullHandler instead.
All previous checks have passed. The product's option-combination is updated in the POSM configuration in the database.

DbIoOptionsStockNamesHandler

This simple handler provides the interface to export and import the configurations that you've made to the products_options_stock_names table. As with the other handlers, I suggest performing an "Export" of the table's current contents prior to any "Import" so that you've got the field names/columns auto-created.

ProductsAttribsBasicHandler

The DbIoProductsAttribsBasicHandler supports the import and export of products' option-combinations for your Zen Cart.

Feature Name Comments
Export/Import Both
Customized Fields for Export ✗
Export Filters None
Required Columns (aka Fields) for Import v_products_model, v_products_options_type, v_products_options_name, v_products_options_values_name
Database Tables Affected products_attributes
DbIo Commands ✗

CSV Column Definitions

This handler's export supplies the following information in each of CSV column:

Field Name Description
v_products_model The 'products_model' associated with the attribute's products_id. Used on import to 'find' the products_id.
v_products_options_type The integer value identifying the 'option_type' defined for v_products_options_name .
v_products_options_name The 'name' associated with the attribute's 'option'. Used on import to 'find' the options_id.
v_products_options_values_name A list (separated by ^) of currently-defined option-values' names for the named option for the product. Used on import to 'find' the options_values_id values.

Import Processing

This handler is used to import new attribute option-combinations for a product; any option-combinations already present for a product are ignored. For an option-combination to be successfully inserted for a product:

  1. There must be a product associated with the specified v_products_model.
  2. There must be a product-option with the name v_products_options_name (of type v_products_options_type) in the site's default language.
  3. For each of the options' values' names identified in v_products_options_values_name:
    • There must be a product-option-value with that name in the site's default language.
    • The option-value must be associated (in the products_options_values_to_products_options table) to the named option.

If the above validations are successful for a CSV record, all option-combinations not currently present for the associated product are inserted into the products_attributes table, using default values for all fields other than products_id, options_id and options_values_id.

ProductsAttribsRawHandler

The DbIoProductsAttribsRawHandler supports the import and export of product-attribute related fields for your Zen Cart.

Feature Name Comments
Export/Import Both
Customized Fields for Export ✗
Export Filters None
Required Columns (aka Fields) for Import v_products_id, v_options_id, v_options_values_id
Database Tables Affected products_attributes, products_attributes_download, products_options_values_to_products_options, and products (via zen_update_products_price_sorter).
DbIo Commands REMOVE

Additional Fields on Export

This handler provides some additional fields on an 'export' action to make it easier to identify the attribute; all but the v_dbio_command field are ignored on an import:

Field Name Description
v_products_model The 'products_model' associated with the attribute's products_id.
v_manufacturers_name The 'name' associated with the attribute's product's manufacturers_id.
v_products_options_name The 'name' associated with the attribute's options_id.
v_products_options_values_name The 'name' associated with the attribute's options_values_id.
v_dbio_command Can be either an empty string (no command) or REMOVE to cause the attribute to be removed from the database.

Controlling an Attribute's Download Options

An attribute's import can optionally include a download filename associated with the attribute, associated with the products_attributes_download table. The import processing depends on

  1. Whether the base attribute information is being inserted or updated.
  2. Whether an existing attribute has a pre-existing download filename.
  3. Whether a download filename (v_products_attributes_filename) is supplied for the to-be-imported record.
    • The handler supports a sub-command (REMOVE) value for this field, enabling a previously-recorded filename to be removed from the given attribute.

Here's how the processing flows:

  1. If an attribute matching the products_id+options_id+options_values_id does not exist or the attribute exists but does not currently have an associated download filename:
    1. If the products_attributes_filename field does not exist in the import or if the field exists and is an empty string:
      • No products_attributes_download record is created.
    2. Otherwise, if the filename field is not a valid filename
      • The addition of the products_attributes_download record is disallowed. Note that a new products_attributes record might have been created!
    3. Otherwise, the products_attributes_download record is created.
  2. Otherwise, an existing attribute with an existing products_attributes_download record:
    1. If the products_attributes_filename field does not exist in the import
      • No update is made to the products_attributes_download table.
    2. Otherwise, if that field is set to REMOVE (capitalization required)
      • The associated products_attributes_download table record is deleted.
    3. Otherwise, if that field is not a valid filename (including an empty string)
      • No change is made to the products_attributes_download table and the record is marked as an import error.
    4. Otherwise, the associated products_attributes_download record is updated.

Checking a Download Filename for Validity

When an import includes a v_products_attributes_filename field, there are a couple of rudimentary checks on that filename that must pass to enable the associated products_attributes_download table-record to be created or updated:

  1. The field's value must not be an empty string.
  2. The field's value must not start with a . (period).
  3. The field's value must not contain any characters in this list: [<>:"|?*].

ProductsHandler

The DbIoProductsHandler supports the import and export of product-related fields for your Zen Cart.

Feature Name Comments
Export/Import Both
Customized Fields for Export ✓
Export Filters Product's Status, Product's Manufacturer, Product's Category
Required Columns (aka Fields) for Import v_products_id, v_products_model
DbIo Commands REMOVE, ADD, UNLINK (added in v1.6.4), LINK (added in v2.1.0), MOVE (added in v2.1.0)

Special Fields

This handler supports some additional "special" fields:

Field Name Description
v_manufacturers_name The 'name' associated with the product's manufacturers_id.
v_tax_class_title The 'name' associated with the product's products_tax_class_id.
v_categories_name The name(s) associated with the product's master_categories_id, using the store's default language. This is represented by ^-separated names reflecting the product's category path.
v_dbio_command Can be an empty string (no command), ADD to force the addition/insertion of a product's definition, REMOVE to cause the product to be removed from the database, UNLINK to unlink the product from a category other than its master-category, LINK to link the product to an additional category or MOVE to move the product to a new master-category.

Configuration Settings

This handler uses a couple of Database I/O Manager configuration settings that control import features:

image

Allow Duplicate Models?

This setting, which defaults to No on installation, indicates whether (Yes) or not to allow duplicate model numbers to be applied to products on an import. If set to No, a csv-line import that would result in a duplicate model-number to be applied is not imported.

Product Creation Requires Command?

This setting, added for v1.6.4, indicates whether (Yes) or not (No, the default) a DbIo ADD command is required to create a product if no matching v_products_id or v_products_model is found.

Auto-create Categories on Import?

This setting, which defaults to No on installation, indicates whether (Yes) or not to automatically create otherwise non-existent categories when importing a new product. If set to No, a csv-line import that contains an undefined v_categories_name and would result in a product's addition/insert is not imported.

Controlling a Product's Master and Linked Categories

A product's import can optionally set the product's master_categories_id or link a product to another category:

  1. If the product is new, then the v_categories_name field must be present so that the product's master_categories_id can be determined.
  2. If the product is being updated and no v_dbio_command is set, the v_categories_name (if included) identifies the product's new master_categories_id. The product's previous master_categories_id becomes a linked category.
  3. If the product exists and the v_dbio_command is set to UNLINK, the product is removed from v_categories_name if that category is not the product's current master-category.
  4. (v2.1.0+) If the product exists and the v_dbio_command is set to LINK, the product is 'linked' to the category associated with v_categories_name; the product's master_categories_id is unchanged.
  5. (v2.1.0+) If the product exists and the v_dbio_command is set to MOVE, the product is 'moved' (i.e. its master_categories_id is changed) to category associated with v_categories_name.

Export Features

The default, non-customized export for this handler gathers all the fields from the products, products_description and meta_tags_products_description tables, along with this handler's special fields.

Notes:

  1. If you are exporting all fields for a multi-lingual store, the fields from the products_description and meta_tags_products_description tables will each be grouped by language (default language first).
  2. If you are exporting customized fields for a multi-lingual store, any fields within those two language-dependent table are grouped by language (default language first).

ProductsOptionsValuesHandler

The DbIoProductsOptionsValuesHandler supports the import and export of product's' options' values fields for your Zen Cart.

Note: This handler and its I/O requirements were changed in DbIo v2.0.2. See this GitHub issue for more information.

Feature Name Comments
Export/Import Both
Customized Fields for Export ✗
Export Filters None
Required Columns (aka Fields) for Import v_products_options_values_id, v_language_id, v_products_options_values_name, v_products_options_id, v_products_options_values_sort_order
Database Tables Affected products_options_values, products_options_values_to_products_options
DbIo Commands Not supported

Importing Products' Options' Values

For the import, the CSV must contain all the required columns/fields noted above.

  1. When importing new records for a multi-language store, the import should be run once per language value. Otherwise, the products_options_values_id will get "out-of-sync" between the multiple languages.
  2. On an import:
    1. If the products_options_values_id value is 0, the import is forced to be an insert. The record is inserted using the specified language_id and a products_options_values_id that is calculated as the table's current maximum value (+1).
    2. If the associated language_id is not valid for the store, the record's import will be denied.

Clone this wiki locally