Salesforce B2C Commerce 24.7 > Administering Your Organization > Import and Export > Import and Export Object Cheatsheet

Order Object Import and Export

For integration with external systems, and for working with test data, B2C Commerce can export and import order data as XML.

Import Orders

To import orders in Business Manager, click site > Ordering > Import and Export > Orders (XML) > Import. You can import orders to any site that is on a non-Production instance or that is not live on a Production instance. To import orders that do not exist into a live site on a Production instance, contact Commerce Cloud Support.

Note: Commerce Cloud Support doesn't import data that updates existing orders. This data is skipped during the order import process.

See the order.xsd schema file for details of the order XML data format.

Importing orders placed by unregistered customers can sometimes result in duplicate customer numbers. To prevent this issue, the Customer element in the order XML contains the boolean guest element.

If guest is true, the customer number in the order data is checked against customer numbers in the system. If the customer number does not match any existing customer numbers, it is imported. Otherwise, it is skipped.
If guest is false, the customer number in the order data is checked against customer numbers in the system. If the customer number matches an existing customer number, it is imported. Otherwise, it is skipped.
(Order XML version 19.2 and later) If guest is not present, an error is logged, and the order is skipped. Other orders are not affected.

To ensure the accuracy of the customer number check, import customer data before importing orders.

Note: The guest element was added in version 18.5 of the order export data schema, but is only required as of version 19.2. To ensure that the element is checked, we recommend that you specify version 19.2 or later in your order XML.

Export Orders

You use the order.xsd schema file to export order information.

When exporting orders, consider the following information.

order status within Business Manager or your custom application
how you plan to handle credit card data
if you export orders to a .csv file after doing an advanced search, only the first 10,000 orders are exported

Set the order export Version

Salesforce B2C Commerce supports simple versioning for XML-based order export. This versioning lets you remain on a fixed version if your organization is unable to accept changes to the order XML.

To specify the version:

Select site > Merchant Tools > site > Site Preferences > Order > Order Export Format.
Select the version.
Click Apply.

Orders ignored during Export

When orders are exported, CREATED and FAILED orders are ignored. The CREATED status denotes an in-process order that isn't ready for export, while the FAILED status marks an order that isn't suitable for export.

Order export and on order Inventory

When an order for one item of product X is submitted, B2C Commerce shows the turnover amount to be one even before it's exported. If the allocation is updated, the turnover amount is reset to 0, which could lead to oversell situations.

To avoid this situation, change the setting of On Order Inventory Enabled.

Select site > Merchant Tools > site > Products and Catalogs > Inventory Lists.
Click the ID of the inventory list.
Check the On Order Inventory Enabled option.
Click Apply.

When On Order Inventory Enabled is checked, an order that has not yet been exported has an on-order amount. The product is marked as final after the order is exported. When the setting is unchecked, an order that has not yet been exported doesn't have an on-order amount. The product is marked as final after the order is exported.

If you use Business Manager to create a copy of an order export, you can run an export job without changing the job status because the orders are not cleared for export yet. Alternatively, when On Order Inventory Enabled is checked and the order export status changes to exported, all related on order inventory transactions are turned into final inventory transactions. This setting gives you control over this part of the process.

Note: This setting has no effect on the ExportOrder s pipelet.

Export orders with credit card Numbers

By default, when you export orders (via Business Manager or the ExportOrders pipelet), they contain only masked credit card data. The following is an example:

<credit-card> 
	<card-type>VISA</card-type> 
	<card-number>XXXX-XXXX-XXXX-1111</card-number>
	<card-holder>John Doe</card-holder> 
	<expiration-month>1</expiration-month> 
	<expiration-year>2010</expiration-year>
</credit-card>

If you must send credit card data to an external system, use the ExportOrders pipelet to embed an encrypted credit card number in the feed.

Open the ExportOrders pipelet in Studio.
Add the following parameters to the pipelet:

Encryption Key: A base64 encoded string representation of the public key in X.509 format (SubjectPublicKeyInfo part)
EncryptionMethod: A string specifying the encryption algorithm and parameters to be used for the encryption.
Currently, only one method is supported (RSA), which can be specified in the pipelet using the expression:

dw.order.PaymentInstrument.ENCRYPTION_METHOD_RSA

You use an RSA public key to encrypt the credit card number. Internally, B2C Commerce uses the (non-secret) public key to encrypt the credit card number. The feed is then sent to the external system, which decrypts the number using the (secret) private key. The credit card numbers of the orders are exported as base64 representations of the encrypted data. These representations are usually longer than the credit card numbers (for example, 348 characters for 16-digit card numbers using a 2048-bit key).

Note: The Credit Card Verification Number (CVN) isn't part of the order export.

Export orders that contain UTF-8 Characters

To prevent incorrect coding of some UTF-8 characters:

Ensure that you have access to the Business Manager Import & Export Settings module.
Select Administration > Global Preferences > Import & Export.
Check the Filter invalid XML characters during export setting to remove invalid XML characters from the exported data.

REPLACE Mode and Orders

Export empty Elements

Empty elements or attributes that are defined in the schema as minOccurs="0" are not exported. If an element contains a space or other character, it isn't considered empty.

Ability to commit or roll back export status Changes

The order export process marks orders as EXPORTED (Order.exportStatus == Order.EXPORT_STATUS_EXPORTED) as it progresses. You can embed the export pipelet in an explicit transaction (defined at transitions in the pipeline) to commit or roll back all export status changes.

Order export works when an order contains a service line item that isn't assigned to a shipment (line items group). In that case, no <shipment_id> element is created in the export file for that item. When the order contains a line items group (shipment) with an empty document number, order export is only successful for a FullOrderExport. To correct this problem, when a service line item is assigned to that type of a shipment, the <shipment_id>invalid<shipment_id> element is created for it.

Note: The <shipment_id> element isn't mandatory for service line items and gift certificate line items. It can be missing in the order import file for these line items. When a <shipment_id> element doesn't exist for a gift certificate line item, the line item is assigned to the default order shipment. When the <shipment_id> element doesn't exist for a service line item, the line item isn't assigned to a shipment.

Position Attribute

Each product line item element in the Order export xml includes the Position attribute. This feature is for systems that can't guarantee the order of XML tags when parsing the XML file. The Position attribute provides the order.

If you import the catalog in REPLACE mode, the internal identifier changes. However, product line items and coupon line items are linked to the order by the semantic ID and not via an internal identifier. That means, as long as product SKUs don't change, the product line items stay attached to the order. Any links are set via semantic ID and not per unique identifier, therefore the import does not break these links.

Pipelets

ExportOrders

Schema Elements

This section describes the elements in the order.xsd and considerations when creating values for them.

Element:

You can export geolocation information for latitude and longitude associated with an order.

* geoLatitude

* geoLongitude