What Are the Import Options?

To import a catalog, use one of the ImportXml methods of the CatalogContext object. These methods let you specify whether to import the catalog from an XML file or as a data stream. Use the properties of the CatalogImportOptions parameter to specify the options that control the import operation. The topic CatalogImportOptions describes these options and how to use them. This section provides additional information for these options.

Important Note:
Imported catalogs can present a security risk. Catalog display names and text type custom properties may contain HTML markup, which may contain malicious script. To avoid importing malicious script, use the authentication and authorization features available in Commerce Server Core Systems to validate the sources from which you are importing your catalog data.

Properties to Import

The PropertiesToImport property specifies the properties to import. Only the properties specified and the mandatory properties are imported. You might use this property to import a catalog, but not the prices of the products in the catalog.

Import Modes

The Mode property provides two modes for importing catalog data. The Full mode erases all data in the database for the specified catalogs and replaces it with the contents of the XML file. You might select this option this during deployment to make the Catalog system mirror a line-of-business (LOB) system.

Your XML file can contain multiple catalogs. You can specify which catalogs to replace with the CatalogsToImport property. By using this property, you can replace only the selected catalogs while leaving others untouched.

You can selectively replace data in the database by using the Incremental mode. This mode adds new data and updates existing data that has changed. Items that are marked for deletion are deleted.

Last Modified Date

To determine whether data has changed, the Catalog system uses the LastModifiedDate property. First, the system filters all data in the XML file that has a timestamp greater than this property. These items are then compared with the items in the database. If the item in the XML file is newer, the database is updated. If the item does not exist in the database, it is added. If the item does not have a timestamp in the XML file, an error occurs. If the LastModifiedDate property is empty, all items are imported.

This property applies only to the catalog items. The catalog itself is imported in Full mode and has the timestamp of the current date and time.

Overwrite Relationships and Hierarchies

The Incremental mode can either overwrite existing relationships and hierarchies or merge new data with the existing data. You specify how this mode works with the OverwriteRelationships property. If this property is true, the existing values in the database are deleted and set to the values in the XML file. All existing relationships and hierarchies are deleted and reconstructed from the XML file.

If the OverwriteRelationships property is false, new data is added to the database and existing data is updated. The system adds relationships and hierarchies from the XML file.

Transaction Mode

The TransactionMode property refers to the SQL transaction and specifies how the import process behaves when an error occurs. If you select the NonTransactional mode, a transaction is used on a per-item basis, not a per-catalog basis. If an error occurs, the product is skipped, and the import continues. If the import fails, the database may be changed.

If you select the TransactionalForCatalog mode, a transaction is used for each catalog to be imported. In this case, if the import fails for a catalog, the import operation for that catalog stops, but the import process continues for any additional catalogs.

Catalogs to Import

The CatalogsToImport property specifies the list of catalogs to import.

Namespace

The Namespace property specifies the namespace in which the XML files are generated. If this property is specified, the import process verifies that the Namespace property matches the namespace in the XML file.

To use this option, you would use code similar to the following example:

string targetNamespace = https://Microsoft.CommerceServer.Test.Catalog;
catalogImportOptions.Namespace = targetNamespace;

Import Schema Changes

The ImportSchemaChanges property specifies whether schema changes should be performed during the import operation.

ExportReady

The ExportReady property specifies whether the record is ready to export.

Generate Full Text Indexes

The GenerateFullTextIndexes property specifies whether full text indexes are generated after the import operation. For more information about full text indexes, see What Is a Full-Text Catalog?

Errors during Import

In non-transactional mode, an import process proceeds until the error count reaches the value specified by the ErrorThreshold property. When this occurs, the import process stops.

Reporting Import Status

The ImportXml method returns an ImportProgress object that contains information about the status of the import operation. It contains a PercentComplete property to determine the progress of the operation. It also contains a value of CatalogOperationsStatus that specifies the status of the operation and a CatalogErrorCollection object that contains any errors that have occurred.

Validating a File

The import process examines the XML file to make sure that there are no schema errors. You determine when this validation process occurs by the value you specify for the Operation property. If you specify Validate, the XML file is checked and any schema errors are recorded. The file is not imported.

If you select ValidateAndImport, the file is first validated, any errors are recorded, and the file is imported. The import operation does not start if the errors reach the error threshold.

If you select Import, the file is validated during the import process. The import operation stops if the errors reach the error threshold.

Warning

Do not delete catalogs while they are being imported.

Warning

Do not decrease the size of a property if it has data in it. If the property has data in it that is larger than the changed size, the import fails with an error.

Importing Catalog Relationships

If you import a relationship and the related item does not exist, the relationship information is stored until the catalog is complete. At that time, the system attempts to import the relationship again. If it does not succeed, the system waits until the import operation completes and tries again. If that attempt does not succeed, an error is generated. If the relationship cannot be imported until the end of the import operation and the import is transacted per catalog, the import of the relationship will be outside of that transaction.

See Also

Other Resources

How to Import a Catalog from an XML File

How to Export Selected Fields of a Catalog

Exporting Catalog Data by Using the Catalog API