From NewHaven Software Wiki

Contents 1 Overview 2 The XML 3 Tech Tips 4 Transforms 5 Order Importing 5.1 Payment Methods 5.2 Shipping Methods 5.3 Addresses 5.4 Notes 5.5 Countries 5.6 Encryption 5.7 Testing 5.8 Credit Card Processing

Overview

CMS uses XML as its primary means of order importing and also is used for assorted other data imports and exports. A full specification is defined in our document CMSXML.xsd. This document is available on request from NewHaven Software with a signed non-disclosure agreement.

For more information on order file importing and eCommerce integration capabilities please see our related article.

The XML

XML is our file format of choice. It is extremely flexible, robust, and widely used. If you are unable to obtain your orders in our described XML format, NewHaven Software can be contracted to write a transform for you that will convert your current file format (ASCII, other XML, etc.) into our XML for importing into CMS. This can be done with a few clicks or, with our eCMS module, fully automated.

The balance of this guide provides additional information about the preparation and use of XML with CMS.

Tech Tips

• Orders imported are treated as new orders. You cannot use XML to import order history.
• Imported catalog requests will not update a customer's address if a customer number is being passed to match it to an existing customer.
• Matching
  • CMS will attempt to match imported orders and catalog requests to existing customers based on this logic when a customer number is not passed.
  • New customer records will be created if no match can be established.
• All orders must be manually verified before saved as new orders or use the optional Automated Imports Module to validate as many as can pass your chosen validation checks.
• Inventory for imported orders is allocated at the time of validating.
• CMS order numbers are assigned to imported orders at the time of saving the validated order, not when imported.
• Catalog requests do not require nor can they be validated. They are automatically processed.
• Catalog requests and orders both require unique identification numbers (ID and Reforderid respectively)

Transforms

It is unlikely CMS will support other XML specifications in the future. Instead, whenever we need to import from a source that cannot provide XML in our format, we would instead put that data through a transform process to convert it from their native format into CMS's expected format.

Currently this process is done with our support for CommerveV3 and Magento, for example. When importing a file from one of those sources, the CMS plug-in for that store calls a .dll to transform the file on the fly into our spec and then the file is imported. This process is transparent to the user. Something similar is possible using a .xslt transform in conjunction with our generic plug-in.

Another solution is to use a tool called MapForce that can be purchased (not from us) and used by our customers if they wish to write/execute their own transforms. This includes converting not only from other XML formats but also from ASCII, spreadsheets, etc. NewHaven Software can also offer Mapforce setup and mapping services as a professional service.

Order Importing

The information listed here addresses common questions and mistakes made when preparing XML for importing orders into CMS.

Payment Methods

Payment methods they must be passed in the XML using the following names: (note - XML is case sensitive)

• American Express
• Check
• JCB
• MasterCard
• Diner's Club
• Money Order
• Discover
• Visa
• PayPal
• GoogleCheckout

Any user defined payment methods created in CMS that are to be used on the website must also have their names match identically, including letter case.

Shipping Methods

For the shipping methods we recommend you use the 'hotkeys' the user has setup for each shipping method in CMS and pass it in the XML as such:

<DefaultShipMethod IndexBy="Code">FG</DefaultShipMethod>

where FG is the hotkey they've setup in CMS to represent FedEx Ground, for example.

The above corresponds to the order's default shipping method and will be used for all packages on the order. You can additionally pass a shipping method at the recipient/package level if a recipient on the order must ship via an method other than the order default. We recommend only setting this when they differ since CMS treats this explicit setting of a recipient method as an override that cannot be automatically updated by any changes the user makes to the order's default shipping method (an edit that would otherwise cascade to alter the shipping methods on all recipients not explicitly set.)

Addresses

At minimum an address should be passed in the <Customer> node (this is the primary address) and the <Recipient> node (this is the shipping address). The billing address is optional and will default to the address passed in the Customer node if a billing address is not passed. In CMS, AddressLine3 is the primary address line. Any additional address lines should go onto AddressLine2 and only use AddressLine2 if 3 and 2 are already used.

Notes

<Notes> should be used for notes to the buyer. <GiftMessage> should be used for notes to a gift recipient (when the recipient is not the buyer.)

Countries

If you do not pass a country CMS will assume the country is the same as that defined in CMS Setup for the company's address. If you are passing the country you should use <CountryID> and use ISO3166 codes. CountryName can be used but requires an EXACT match with the ISO3166 or UPS list of country names which has a much lower chance of matching correctly.

Encryption

CMS does not currently support a method of field or file level encryption with XML. You may consider using PGP as a solution for encryption and then decrypt just before importing into CMS. We expect to add support for encryption options in the future.

When using our eCMS Module to connect to your web site's web service or an FTP location, CMS can enforce the use of secure connections for orders that contain credit card data. This method ensures that a file with unencrypted card data never resides on your machine/network. The order data goes straight into the database and is encrypted before it is written to the table.

Testing

We can assist the end user with setting up a test database to facilitate testing of imports before it is used in production. When testing, you should both be testing for the success of the import and checking to make sure all data required is being passed.

Credit Card Processing

Our XML supports importing unapproved, approved or even captured credit cards. We strongly discourage capturing credit cards outside of CMS however. CMS can adjust the payment amount to match the new amount of the order if the order total needs to be adjusted down due to items on back order, for example.

Also, make sure your expiration dates are in the proper format of YYYY-MM. Improper formatting of the expiration date is probably the most common error we see.