From NewHaven Software Wiki

Contents 1 Overview 2 Capabilities 2.1 The XML, as supported just by CMS 2.2 Web service additional capabilities 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 other imports and exports. All of these are defined in our document called CMSXML.xsd. This document is available on request from NewHaven Software with a signed non-disclosure agreement.

Capabilities

The XML, as supported just by CMS

Does not include capabilities of our eCMS web service communications.

• Product Data Exports (includes descriptions, inventory and pricing (price categories but not qty discounts). See the CMSXML.xsd for a full list of data included. Also includes definitions for variable kits indicating what components are available for a variable kit. - Product Data Exports is only available to eCMS users.
• Order Importing - This option is available in CMS Standard and Professional, it is an option for Solo (Custom Order Import module)
• Catalog Request Importing - This is done through the same mechanism that is used for importing orders. It can be part of the same file used for importing orders or can be a separate file.
• Order Exporting - Option under Fulfillment, exporting allowed in a user-defined ASCII format or our stock XML format.

Web service additional capabilities

CMS also supports the following via our web service communications to CommerceV3 (CV3). Others may be possible if they emulate the WSDL CV3 hosts:

• 'Get Stores' call - Tells CMS which stores are associated with this account (so the user can tell CMS which store to upload to or download from)
• Order Download Confirmations - After downloading, send a list of reforderid's corresponding to orders CMS has downloaded so the host site can mark them as downloaded (remove pending flag, etc.)
• Order Status Uploads - CV3 supports a basic set of fields defined under a different WSDL which will upload to the web service when an invoice has shipped.
• Item Status Upload - Currently a custom solution only but it is possible for CMS to interact with a web service to tell it when specific items have been shipped (not many use cases for this.) - Used by Big Popper only now.

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 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 (Reforderid and ID respectively)
• CMS is currently configured to work with CV3's web services per their WSDL and URLs. We do not currently support letting the user redirect CMS to a different URL or to use a different web service although that option may be available through custom programming.

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.