Example: Attribute dictionary attributes and predefined values

Use the Data Load utility to insert, replace, and delete multiple attribute dictionary attributes and their predefined (allowed) values simultaneously.

This example uses a CSV file to demonstrate how to insert, replace, or delete your data. You can also create and use an XML formatted file to insert, replace, or delete your data. If you choose to create and use an XML formatted file, ensure that your XML elements use the same names as are used for CSV column names.

CSV column and XML element definitions

Identifier
(Required, String) The unique reference name for identifying the attribute. Either this field or the AttributeUniqueId is required.
AttributeUniqueId
(Required, Integer) The unique reference number of the attribute. Either this field or the Identifier is required.
Type
(Mandatory, String) The data type of the attribute.
  • STRING
  • INTEGER
  • FLOAT
This field cannot be null.
AttributeType
(String) The type of the attribute. Attribute type can be AllowedValues or 1 for an attribute with predefined (allowed) values; or AssignedValues, 2, or null for an attribute without predefined values.
Name
(String) (String) The language-specific name of the attribute.
Description
(String) A description of this attribute. This field is language sensitive.
SecondaryDescription
(String) The secondary description of this attribute. This field is language sensitive.
GroupName
(String) The name of the attribute group this attribute belongs to.

The GroupName column is renamed to AssociatedKeyword. Although both GroupName and AssociatedKeyword are supported and map to the same database column, use AssociatedKeyword instead of GroupName.

AssociatedKeyword
(String) An associated keyword for an attribute.
Field1
(Integer)A custom field for attribute information.
Footnote
(String) Use this field to store auxiliary attribute data such as a footnote.
UnitOfMeasure
(String) Use this field to specify the unit of measure that is used for the attribute.
AllowedValue1
(String|Integer|Float) A predefined value of the attribute.
AllowedValue2
(String|Integer|Float) A predefined value of the attribute.
AllowedValue3
(String|Integer|Float) A predefined value of the attribute.
Delete
(String) A flag indicating whether to delete. Specify 1 to delete the row.

The following fields are optional and are not included in the example:

Sequence
(Decimal)A number that is used to control the order in which attribute values display for an attribute dictionary attribute. Attribute values display in ascending order. The default value is 0.
Displayable
(Boolean) Indicates whether an attribute is displayable. There is no business logic that is associated with the usage of this field. It is provided by default for you to extend to meet your individual business needs. Set the column value to be true for displayable attributes. Set the column value to be false or null for attributes that are not displayable. Any value other than true automatically defaults to false.
Searchable

(Boolean) Indicates whether an attribute is indexed by and can be located in the storefront by using HCL Commerce search. Set the column value to 'true' to make an attribute searchable. Set the column value to be 'false' or null for attributes that are not searchable. Any value other than 'true' automatically defaults to false.

Comparable
(Boolean) Indicates whether an attribute is comparable. There is no business logic that is associated with the usage of this field. It is provided by default for you to extend to meet your individual business needs. Set the column value to betrue for comparable attributes. Set the column value to be false or null for attributes that are not comparable. Any value other than true automatically defaults to false.

If your store is based on the Aurora starter store, this field is used by the storefront. The storefront uses this field to determine whether to include an attribute on the Compare Products page.

Facetable
(Boolean) Indicates whether an attribute can be used for displaying facets in the storefront left sidebar to filter product listings. Facets are created in the storefront left sidebar, enabling usable filters to target meaningful product results. The storefront displays a count for each facet value. This count indicates the number of products that share that facet value. Set the column value to be true for attributes that can be used in faceted navigation. Set the column value to be false or null for attributes that are not for use in faceted navigation.Setting an attribute as for use in faceted navigation makes the attribute usable in the Search Criteria and Result target in marketing activities and search rules.
Important: When an attribute is specified as being used in faceted navigation, it is also specified as searchable in your storefront. Links are created for the attribute throughout the HCL Commerce database and search index. For reliability and consistency, these searchable links remain intact despite clearing the check box for making an attribute for use in faceted navigation. You cannot unmark an attribute as searchable. When an attribute is selected for use in faceted navigation, the attribute is automatically set as searchable in the storefront. Business users can remove the Use in faceted navigation setting, but they cannot remove the attribute from being searchable. To remove the attribute from being searchable, you must manually update the HCL Commerce database to remove the records that make the attribute searchable.
When you load data to set or change a faceted navigation attribute or to delete the attribute, the load operation can update the following HCL Commerce search database tables in addition to the attribute dictionary database tables. To update these search tables, configure the load operation to use the com.ibm.commerce.catalog.dataload.mediator.AttributeDictionaryAttributeSearchIndexMediator business object mediator.
  • FACET
  • SRCHATTR
  • SRCHATTRPROP
  • ATTRDICTSRCHCONF
  • SRCHPROPRELV
STOREDISPLAY
(Integer) Specifies that this attribute is for use as a ribbon ad in the storefront.
Merchandisable
(Boolean) Indicates that the attribute can be used as a merchandising attribute in the creation of search conditions for use by any of the following objects:
  • Marketing activities for finding catalog entries to recommend to customers in e-Marketing Spots.

    Merchandising attributes can also be used in search conditions within a marketing activity to identify a current page target.

  • Search rules for finding catalog entries.
  • Sales and rule-based categories for finding catalog entries to assign to the categories.
Only attributes with predefined values can be used as merchandising attributes. An attribute that is identified as for 'Use in merchandising' is intended for internal business use to create these rules and activities. If you set a merchandising attribute to be displayable, searchable, or facetable when you load information for an attribute, then the attribute can also appear on the storefront. Set the column value to be true for merchandising attributes. Set the column value to be false or null for attributes that are not for use in merchandising. Any value other than true automatically defaults to false. When you load data to set or change a merchandising attribute or to delete the attribute, the load operation can update the following HCL Commerce search database tables in addition to the attribute dictionary database tables. Configure the load operation to use the com.ibm.commerce.catalog.dataload.mediator.AttributeDictionaryAttributeSearchIndexMediator business object mediator.
  • SRCHATTR
  • SRCHATTRPROP
  • ATTRDICTSRCHCONF
AttributeField1
(Integer) A user-defined field available for customization purposes.
AttributeField2
(Integer) A user-defined field available for customization purposes.
AttributeField3
(String) A user-defined field available for customization purposes.
Language
(Integer) The language identifier for language sensitive fields. For example: -1 for English, -2 for French.
LanguageId
(Integer) The language identifier for language-specific fields. For example:
  • -1 for English
  • -2 for French.
The Language column is renamed to LanguageId. You must specify only one language identifier; use LanguageId instead of Language as the language identifier.
(Integer) The language ID for language-specific fields (Name, ShortDescription, LongDescription, AuxDescription1, AuxDescription2, Thumbnail, FullImage, Published, and Keyword). For instance:
  • -1 for English
  • -2 for French.
Delete
(String) A flag that indicates whether to delete. To delete a row, specify 1.

CSV file with sample attribute dictionary data

In this example, the CSV file contains attribute dictionary data.

Mapping data

The following code from the attribute and predefined values load configuration file demonstrates how to map each value to a business object logical schema path. This example shows up to 3 predefined values per attribute. 
<_config:DataMapping>
        <_config:mapping xpath="AttributeIdentifier/ExternalIdentifier/Identifier" value="Identifier" />
        <_config:mapping xpath="AttributeIdentifier/UniqueId" value="AttributeUniqueId" />
        <_config:mapping xpath="AttributeDataType" value="Type" />
        <_config:mapping xpath="AttributeType" value="AttributeType" />
        <_config:mapping xpath="displaySequence" value="Sequence" />
        <_config:mapping xpath="displayable" value="Displayable" />
        <_config:mapping xpath="searchable" value="Searchable" />
        <_config:mapping xpath="comparable" value="Comparable" />
        <_config:mapping xpath="ExtendedData/Field1" value="AttributeField1" />
        <_config:mapping xpath="ExtendedData/Field2" value="AttributeField2" />
        <_config:mapping xpath="ExtendedData/Field3" value="AttributeField3" />
        <_config:mapping xpath="AttributeDescription/language" value="Language" />
        <_config:mapping xpath="AttributeDescription/language" value="LanguageId" />
        <_config:mapping xpath="AttributeDescription/Name" value="Name" />
        <_config:mapping xpath="AttributeDescription/Description" value="Description" />
        <_config:mapping xpath="AttributeDescription/ExtendedData/SecondaryDescription" value="SecondaryDescription" />
        <_config:mapping xpath="AttributeDescription/ExtendedData/DisplayGroupName" value="AssociatedKeyword" />
        <_config:mapping xpath="AttributeDescription/ExtendedData/Field1" value="Field1" />
        <_config:mapping xpath="AttributeDescription/ExtendedData/Footnote" value="Footnote" />
        <_config:mapping xpath="AttributeDescription/ExtendedData/UnitOfMeasure" value="UnitOfMeasure" />
        <_config:mapping xpath="AllowedValue[0]/identifier" value="AllowedValue1" />
        <_config:mapping xpath="AllowedValue[0]/Value" value="AllowedValue1" />
        <_config:mapping xpath="AllowedValue[0]/displaySequence" value="1.0" valueFrom="Fixed" />
        <_config:mapping xpath="AllowedValue[0]/ExtendedValue/ValueUsage" value="1" valueFrom="Fixed" />
        <_config:mapping xpath="AllowedValue[1]/identifier" value="AllowedValue2" />
        <_config:mapping xpath="AllowedValue[1]/Value" value="AllowedValue2" />
        <_config:mapping xpath="AllowedValue[1]/displaySequence" value="2.0" valueFrom="Fixed" />
        <_config:mapping xpath="AllowedValue[1]/ExtendedValue/ValueUsage" value="1" valueFrom="Fixed" />
        <_config:mapping xpath="AllowedValue[2]/identifier" value="AllowedValue3" />
        <_config:mapping xpath="AllowedValue[2]/Value" value="AllowedValue3" />
        <_config:mapping xpath="AllowedValue[2]/displaySequence" value="3.0" valueFrom="Fixed" />
        <_config:mapping xpath="AllowedValue[2]/ExtendedValue/ValueUsage" value="1" valueFrom="Fixed" />
        <_config:mapping xpath="" value="Delete" deleteValue="1" />
</_config:DataMapping>
If you need more values, repeat these lines for each value and increment the value number: 
<_config:mapping xpath="AllowedValue[3]/identifier" value="AllowedValue4" valueFrom="InputData" />
<_config:mapping xpath="AllowedValue[3]/displaySequence" value="4.0" valueFrom="Fixed" />
<_config:mapping xpath="AllowedValue[3]/Value" value="AllowedValue4" valueFrom="InputData" />
<_config:mapping xpath="AllowedValue[3]/ExtendedValue/ValueUsage" value="1" valueFrom="Fixed" />
If you perform an insert or replace operation, do not specify the "Delete" column in the CSV file or you can leave the "Delete" column empty.

Business object mediator

The data load framework provides a business object mediator for inserting, replacing, and deleting attribute dictionary attributes and predefined values. The mediator class name is com.ibm.commerce.catalog.dataload.mediator.AttributeDictionaryAttributeMediator.

Note: When you use a mediator that is provided with HCL Commerce with the Data Load utility, the utility assumes that you are loading data for all columns for a business object. If you want to update the data in only specific columns, configure a column exclusion list for the load process. A column exclusion list causes the Data Load utility to ignore specific columns during the load operation. If you do not use a column exclusion list, the utility updates all columns in the row of a database table row when the utility updates the row. If no value is set in the input file, the utility can replace the existing column value with a default value or set the value to be null. For more information, see Configuring a column exclusion list.