From NewHaven Software Wiki

Revision as of 19:00, 8 November 2013

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 the Yahoo! and 1Shopping carts. When importing a file from one of those sources, CMS 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. We would likely take the similar approach for any carts we wish to officially support in the future.

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.

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.

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.

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.