The Optimizely Service API supports the bulk import of catalog data into Optimizely Commerce. For the catalog import and export to work, you need to generate an XML file to be used by the bulk import mechanism.
See [Catalog service](🔗) for the methods to use when importing and exporting catalogs.
## Catalog XML file and elements
Generate an XML file named _catalog.xml_ and place it at the **root of a zip file to be uploaded**.
You can generate the XML file by copying a "template" file here:
For Commerce Cloud 11 and higher - Catalog.xsd
For Commerce 10 and lower - Catalog.xsd
### Catalog file
The catalog XML file starts with an XML tag followed by the Catalogs element, which holds the key elements, as shown in the following example.
### MetaDataScheme element
The MetaDataScheme element lets you add and update metaclasses and meta-fields, as shown in the following example.
The following example describes the two child element types, MetaClass and MetaField.
#### MetaClass
Namespace(required). Should always be Mediachase.Commerce.Catalog. Use if you want to be able to delete from the user interface.
Name(required). Name of metaclass should only contain letters, numbers, and underscore ( \_ ). No spaces or special characters are allowed.
FriendlyName(required). Describes the class shown in the user interface.
MetaClassType(required). Should always be User.
ParentClass(required). Either CatalogNode or CatalogEntry based on the type of MetaClass.
TableName (required). ParentClass + Ex\_ + MetaClassName (for example, _CatalogEntryEx\_import\_product_).
Description. Description of what the class is used for.
IsSystem(required). Should always be false.
IsAbstract(required). Should always be false.
FieldListChangedSqlScript. Should always be empty.
Tag. Should always be empty.
Attributes. Should always be empty.
#### MetaField
Namespace (required). Should always be Mediachase.Commerce.Catalog if you want to be able to delete from the user interface.
Name (required). Name of meta-class should only contain letters, numbers, and underscore ( \_ ). No spaces or special characters are allowed.
FriendlyName (required). Describes the class that is shown in the user interface.
Description. Description of what the field is used for.
DataType(required)
Boolean
Date
DateTime
Decimal
DictionaryMultiValue
DictionarySingleValue
Email
File
Float
LongHtmlString
ImageFile
Integer
LongString
Money
ShortString
StringDictionary
URL
Note
File and ImageFile are stored in the database.
Length (required)
Boolean. 1.
Date. 8.
DateTime. 8.
Decimal. 17.
DictionaryMultiValue. 4.
DictionarySingleValue. 4.
Email. 256.
File. 4.
Float. 8.
LongHtmlString. 16.
ImageFile. 4.
Integer. 4.
LongString. 16.
Money. 8.
ShortString. 512.
StringDictionary. 4.
URL. 512.
AllowNulls (required). True or False. This property cannot be changed after that fact, so be sure to choose properly.
SaveHistory. Legacy and not used.
AllowSearch (required). True or False, based on if you want the field to be searchable in configured search index.
MultiLanguageValue (required). True or False, based on if you want the field to be culture-specific.
IsSystem (required). Should always be false.
Tag. Should always be empty.
Attributes. A collection of Attribute elements with key and values. Valid Attributes keys are:
useincomparing. True or False based on if you want the field to be used in comparisons.
Only use the attributes when AllowSearch property of metafield is set to true:
indexfield. tokenized based on if you want the field to be tokenized. The attribute should be removed if you no longer want it tokenized.
indexsortable. True or False based on if you want the field to be able to sorted upon in search index.
indexstored. True or False based on if you want the field to be stored in the index.
includeindefaultsearch. True or False based on if you want the field to be used in default search.
Only use the attributes when DataType property of meta-field is set to ImageFile:
autoresize. True or False based on if you want the image to be auto resized.
imageheight. Number of pixels for height when resizing image.
imagewidth. Number of pixels for width when resizing image.
stretchimage. True or False based on if you want the image to stretch if the resize is bigger than the image itself.
stretchthumbnail. True or False based on if you want the thumbnail image to stretch if the thumbnail resize is bigger than the image itself.
thumbnailheight. Number of pixels for height when resizing thumbnail image.
thumbnailwidth. Number of pixels for width when resizing thumbnail image.
OwnerMetaClass. Which meta-classes this field belongs to. The linkage is done on MetaClass Name.
#### Example
The following example shows the MetaDataScheme with three classes and every type of MetaField.
### Dictionaries element
The Dictionaries element lets you add dictionaries to support catalogs, as shown in the following example.
The following describes the child element types Merchants, Packages, Tax Categories, Warehouses, AssociationTypes and Markets.
#### Merchants
A legacy element that is not used.
#### Packages
Name. Name of the package / box.
Description. Describes the intended use of the package / box.
Width. Width of the package / box.
Length. Length of the package / box.
Height. Height of the package / box.
#### TaxCategories
Name. Name of the tax category.
#### Warehouses
Name (required). Name of the warehouse.
IsActive (required). Whether the warehouse is active.
IsPrimary (required). Whether the warehouse is a primary location.
SortOrder (required). Sort order when retrieving warehouses.
Code (required). Unique identifier of warehouse; must be unique.
IsFulfillmentCenter (required). Whether the warehouse is a fulfillment center location.
IsPickupLocation (required). Whether the warehouse is a pickup location.
IsDeliveryLocation (required). Whether the warehouse is a delivery location.
FirstName. First name of primary warehouse contact.
LastName. Last name of primary warehouse contact.
Organization. Company name of warehouse.
Line1. Line 1 address of warehouse.
Line2. Line 2 address of warehouse
City. City address of warehouse.
State. State address of warehouse.
CountryCode. Country code address of warehouse.
CountryName. Country name address of warehouse.
PostalCode. Postal code address of warehouse.
RegionCode. Region code address of warehouse.
RegionName. Region name address of warehouse.
DaytimePhoneNumber. Daytime phone number of warehouse.
EveningPhoneNumber. Evening phone number of warehouse.
FaxNumber. Fax number of warehouse.
Email. Email address of warehouse.
#### AssociationTypes
TypeId. The association type.
Description. Description of association type.
#### Markets
MarketId. The unique market ID.
IsEnabled. If the market is enabled.
MarketName. The name of the market.
MarketDescription. The description of the market.
DefaultLanguage. Default language of the market.
DefaultCurrency. Default currency of the market.
Currencies. Has collection of currency elements.
Currency. The currency code.
Languages. Has collection of language elements.
Language. The language code.
Countries. Has collection of country elements.
Country. The country code.
### Catalog element
The Catalog element lets you add and update catalogs, catalog nodes, and catalog entries, as shown in the following example.
The following describes the catalog element attributes and child elements types Languages, Nodes, Entries, Relations, and Associations.
#### Catalog Attributes
### Languages element
### Nodes element
Name (required). The name of the node.
StartDate (required). The UTC date when the node becomes available.
EndDate (required). The UTC date when the node becomes unavailable.
IsActive (required). Whether or not the node is active.
SortOrder (required). The order in which the node is retrieved when getting list of nodes.
DisplayTemplate. Legacy; not used anymore.
Code (required). The unique identifier of the node.
MetaData (required). This element is responsible for updating the metadata of the node.
MetaClass
Name (required). The name of the meta-class that the node is linked to.
MetaFields
MetaField
Name (required). The name of the meta-field.
Type (required). The MetaDataType of the meta-field.
Boolean
Date
DateTime
Decimal
DictionaryMultiValue
DictionarySingleValue
Email
File
Float
LongHtmlString
ImageFile
Integer
LongString
Money
ShortString
StringDictionary
URL
Data (required). The data element always has the language attribute to tell which language the meta-field is. It also has an attribute value that is used if it is not a multi-value dictionary or string dictionary.
Item. If the data type has multiple values list each key in value as an attribute of Item element.
ParentNode (required). The parent node code of the node.
SeoInfo (required). The SEO information about the node.
Seo (required). The SEO properties for a specific language of the URL.
LanguageCode (required). The language code for the SEO information of the node.
Uri (required). The URI of the node.
Title (required). The title for the page.
Keywords (required). The meta-keywords for the page.
UriSegment (required). The URI segment for the page for routing.
### Entries element
### Relations element
The Relations element lets you create relationships between entries and nodes, nodes and other nodes, as well as entries and other entries. Below is an example of how the Relations element should look
### Associations element
The Associations element lets you create static list of entries related to an entry, as shown in the following example.
### CatalogItemAssets element
The CatalogItemAssets element lets you link assets to entries or nodes, as shown in the following example. For a linking to be created, the media must exist at the path specified.