DHL Integration
From NewHaven Software Wiki
Contents |
Integrating CMS with DHL EasyShip
Overview
This document is designed to give the CMS user and their DHL rep an overview of what the integration between CMS and EasyShip looks like and how to create. Comments are made throughout with each audience in mind. Ideally this document would be reviewed by both parties in advance of attempting the integration so prerequisites and questions can be addressed. A meeting should be scheduled with NHS Technical Support so we know when your DHL rep will be onsite and we can ensure someone is available here to assist as needed.
The Integration
The method of integration used between CMS and EasyShip (detailed below under the heading of Setup) is via an ODBC connection. EasyShip will connect to a table (actually a database view) that CMS maintains specifically for this integration and is called DHLPackages. It simplifies the mapping by having a single table to connect to which contains all the package information needed to process the shipment. This table is also limited to only contain unshipped packages which are scheduled to ship via DHL. These restrictions of the table will help ensure only the proper packages are sent via DHL and no packages are double-shipped.
Getting the package data into EasyShip is only half of the processing though. Shipped package data must also be written back to the CMS database so it knows what packages shipped when, by which method and what the tracking number is. This is accomplished by writing a record into CMS’s External_Shipping table. CMS will automatically update package and invoice records correspondingly with database triggers for records written to this table. This is a critical step and must be done otherwise packages and their invoices will not be set as shipped and thus their payments may not be capturable.
The method in which packages are processed will be via a ‘keyed import’ style, processing packages individually and identifying them for import by their package number.
Setup
1) Prerequisites for the workstation - The workstation running EasyShip must be joining the same domain that the CMS server is running on AND a CMS workstation install must exist (or be performed) before proceeding. Even if there is no intent to run CMS on that workstation, the workstation install will add the necessary database access components to the workstation to facilitate the EasyShip’s ODBC connection to the CMS database. Note: Any connection to the CMS server uses a license, whether it is from CMS or any other application. Multiple connections from the same workstation still only count as one license. Answers to common questions on CMS licensing can be found at http://www.newhavensoftware.com/downloads/CMS_License_FAQ.pdf. 2) Prerequisites for CMS – At least one DHL shipping choice must be setup in Setup>Shipping>Shipping Choices>Add. Please be sure to select the proper DHL service method as this is how DHL will know which service level you are wanting to use. 3) The DSN – An ODBC datasource should be created under the System DSN tab of the ODBC Data Source Administrator in Windows. This DSN should be named CMSPackages but otherwise mimic all of the settings used by the CMS datasource. 4) The Import Mapping – Using DHL’s DB Connect software (or its current equivalent) your DHL representative will create the communication link between EasyShip and CMS by mapping fields in CMS’s DHLShipping table to those in EasyShip. Here are some notes on those fields:
- The primary key will be on PackageReference. This field will always be in the format Order-Invoice-Package (e.g. 9875-1-1)
- The email address for the buyer (not shipping or billing) will be provided in the DHLPackages table (if available) to facilitate shipment confirmation emails.
- The estimated weight will be present in the table but generally should be ignored as most installations will require weighing of each package to determine its proper weight. In some installations the weight is know ahead of time (e.g. all items ship in their own box so their weight is constant) so the weight of this table could then be used.
- Our primary address line for the shipping address is Addr3.
- The remainder of the fields should be self-explanatory.
Note: There is a field for PONumber which many customers want printed on their shipping label.
5) The Export Mapping – EasyShip should be configured to write back shipped package data to CMS either after a shipment is processed or after end of day. The preferred method is to have the shipped package data written back immediately after processing.
Writing Back Shipped Package Data
Data written back to CMS will go into the table External_Shipping.
This table is also used for UPS and FedEx integrations as well so you will see fields specifically for those carriers.
The crucial element to be written back is PACKAGENUMBER (serving as our key.) No other fields are required and your passing back a record with this number will tell CMS to set the shipped date as today. Strongly recommended content would include the tracking number, weight, and DHL_Shipmethod.
Shipped_date is assumed to be the day the record is created but can be forced by passing the date in the format YYYY-MM-DD. It does not have to be zero padded (e.g. 2008-1-1 or 2008-01-01 are acceptable for Jan 1, 2008.)
VOID responses would be Y or N.
Testing
Once setup is complete, some testing should be done both to ensure the integration was created successfully and to familiarize the user with the process of using it.
If a keyed import is attempted and no data is returned check the DHLPackages table to see if the record exists. If so there must be a mapping problem to resolve. If it is not there, reasons would include:
- The package is already set as shipped
- The package is scheduled to go by another carrier
- The package is virtual – this is a fake package used to hold package level data (like shipping method) for shipments that are scheduled to ship in the future (e.g. back ordered merchandise.) Such packages are not shippable until they are fulfilled. The fulfillment process creates a real and shippable package.
In any case, examining the order in CMS’s Order Entry would likely reveal which of these is the case. Fixing the invoice and removing its package level shipped date and/or changing its carrier to DHL as appropriate will then allow the package to be shipped.
Once all of the packages for an invoice have been set as shipped then the invoice itself will be set as shipped, not before.
Please contact us if you need any assistance or have found any inaccuracies in this document.
