How-To

Create XML Mapping Documentation

eAdaptor
31 October 2016

This Technical Document will guide you through suggestions on how to create Universal XML
mapping documentation when interfacing between an external system and CargoWise One.

These instructions are targeted at someone who is familiar with CargoWise One that will provide the
necessary documentation for a developer to create the Universal XML.

Contents
1 Introduction ................................................................................................................................... 2

1.1 What you will have after following this Process? .................................................................... 2

1.2 Steps to create your documentation from CargoWise One .................................................... 2

1.3 Exporting Universal XML ......................................................................................................... 5

1.4 Importing Universal XML ......................................................................................................... 6

2 Sample DataSource Mapping ...................................................................................................... 7

3 Screenshots (CTRL-Click to follow links) .................................................................................. 7

3.1 Basic Registration Tab ............................................................................................................ 8

3.2 Routing Tab ............................................................................................................................. 8

3.3 Packing Tab ............................................................................................................................ 9

3.4 Addresses Tab ........................................................................................................................ 9

© 2016 WiseTech Global Page 1 of 10

1 Introduction
When mapping external systems to and from Universal XML, the first step is to work out what you
want to map. Once you know what you want, it helps to create documentation a developer can work
from to complete their end of the mapping. For technical information on the most common forms of
Operational and Reference File integrations including initial loads of data, updates of data, exports of
data, imports of data, and event management processing, refer to the eAdaptor Developer’s Guide.

This document gives a process you can follow to build a document containing a list of all fields within
CargoWise One you want to map to, screenshots of where the data should go for testing purposes,
and a sample file that a developer can use in conjunction with the Universal XML XSD schema files to
either generate or interpret Universal XML.

The instructions are targeted at someone who is familiar with CargoWise One, and does not assume
that you have a great deal of experience with XML files or data mappings. A basic working knowledge
of Microsoft Word is also required.

There is also a sample DataSource Mapping document that you can use as a template for creating
your own following the instructions below.

1.1 What you will have after following this Process?

1. DataSource Mapping document showing where all data comes from in CargoWise One.
2. A Sample XML file with the same data in it as the screenshots in the DataSource Mapping
Document.
3. A full set of Universal XML XSD Schema files that you can give to a developer along with the
Document and the Sample file.

These three things give a developer enough information to map Universal XML data to the fields you
specify in CargoWise One. They do not give any information about any external systems or how to
map to them.

1.2 Steps to create your documentation from CargoWise One

1. Identify the fields you want to have in the XML data making note of where they are within
CargoWise One. Create a Word document and put them in a table. A sample of how the
DataSource Document should look is shown below.
2. Create a Forwarding Shipment, or whichever entity you want to import or export. For the purposes
of this document we will assume that you wish to import or export a Forwarding Shipment.
3. Fill in all of the fields that you want to have in the XML with data that will be easily identifiable
within the XML. Don’t use the same values in all fields. Make every value is different so you can
easily find them in the XML.
4. Save the Forwarding Shipment.
5. Take screenshots of every tab where you entered data using “Alt+PrtScn” and paste them into the
bottom of the Word Document along with a title that identifies the tab being shown.

© 2016 WiseTech Global Page 2 of 10

6. Select the Actions menu > Send Universal XML > Universal Shipment from the top of the
Shipment form.

7. Fill in the “Manually Send XML Universal Shipment” dialog with a Recipient Type of “ORP”
(Organization Proxy).

You can also fill in the Event Type, Purpose Code, and Trigger Description if you want to see
where they end up in the data, but they are not required to export a Universal Shipment.

Additional information regarding the option to manually send Universal XML files has been covered in
the Learning Unit 1COR143. This Learning Unit includes the configuration of the Org. Proxy
Organization.

8. Click on the Send & Close button. You may get a dialog telling you that EDI Communications
settings have not been found on the Recipient Organization.
If you see the above dialog, follow the instructions, save the Org. Proxy Organization, then come
back into the Shipment and go back to Step 6.
9. If this is configured correctly on the Org. Proxy Organization, you will see a dialog telling you a
Universal Shipment has been queued.

© 2016 WiseTech Global Page 3 of 10

10. On the Shipment, go to the Workflow & Tracking tab > Events. You should see a ‘DEX - Data
Export’ event created.

11. If you click on the DEX event in the grid, you will see an EDI Message Information section at the
bottom right of the tab as shown above. Click on the View button. This opens the View Messages
window.

12. Click on the Save to Disk button, and choose the location you want to save your sample file in.
Now you have your sample file to go with your Data Source and Mapping document.

© 2016 WiseTech Global Page 4 of 10

13. To obtain a set of the current Universal XML Schemas, go to Maintain > System > EDI Message
function within CargoWise One, then select Actions > Save Universal Operational XML Schemas
from the module tool buttons as shown below.

14. Select a folder to write the schema files out to. It is recommended that you create an empty folder
for this purpose, or use a folder containing just your sample file and the document you created
following the instructions shown above.
15. Put the DataSource Mapping document, the sample file, and the schemas from steps 15-16 into a
folder (if you haven’t done so already), right click on the folder containing these items and select
Send To > Compressed (zipped) folder. You will now have a zip file containing everything a
developer needs to be able to map the data you want mapped via the Universal Shipment XML
schema.

As an Added Suggestion

If you want to make things easier, you can add an Index to the first page to allow you to jump to each
screenshot as required. In Word 2010, you can do this by selecting References > Table of Contents
from the Ribbon (tabs) at the top of Word.

1.3 Exporting Universal XML

The ZIP file you have created following the steps above contain everything a developer needs to start
mapping Universal Shipment XML to an external system. The developer will of course need
documentation for the external system being mapped to, but little else should be required to get
started. As development proceeds, it is likely that they will need a few more sample files with different
data loads to properly test the interface being developed. These can easily be generated by following
steps 2 to 14 with varying contents in the Forwarding Shipment (or other entity) that you create.

© 2016 WiseTech Global Page 5 of 10

1.4 Importing Universal XML

Anybody wanting to Import Universal Shipment XML should read and understand the eAdaptor
Developer’s Guide. There are two topics that you need to know about in particular.

1. The DataTargetCollection – For incoming data you will need to add an element to the
DataTargetCollection with a Type that matches up to the module you want the data to be
imported into. For example, to target your data at the Forwarding Shipment module you would
include the following XML in the DataContext element:
<DataTargetCollection>
<DataTarget>
<Type>ForwardingShipment</Type>
</DataTarget>
</DataTargetCollection>

2. Matching to existing entities – Upon Import, CargoWise one tries to match incoming data to
existing jobs using a series of fallback matches based on various fields in the incoming data
depending on the module you are targeting your data for. Information on how each module
matches incoming data is present in the eAdaptor Developer’s Guide. In general terms,
CargoWise One will try and match in the following ways in the order shown:

a. Job Number Match – Happens when you include a <Key> element with the Job Number in it
in the <DataTarget > element shown above.
b. Natural Key Match – These are defined per module, and are something like a combination of
Master Bill and House Bill that make a relatively unique candidate key for the module you are
targeting.
c. Combination Key Match – All references within the data are searched for in all jobs in the
module targeted. The Job with the highest number of matches will be seen as a match.

The above is only an overview of what is available in general terms, please consult the eAdaptor
Developer’s Guide for more specific information on how DataTargets and matching schemes work
within each module.

© 2016 WiseTech Global Page 6 of 10

2 Sample DataSource Mapping
Data Item Location in CargoWise One
BillOfLading Basic Registration tab, House Bill field top middle.
LocalClient Basic Registration tab, Local Client field bottom left.
TransportLegCollection Routing tab.
Carrier Routing tab, column 9.
Consignor Addresses tab, row 1.
Pick Up Address Addresses tab, row 2.
Consignee Addresses tab, row 3.
Delivery Address Addresses tab, row 4.
Packing Line information
PackQty + Type Packing tab, columns 1, 2.
Weight + Unit Packing tab, columns 4, 5.
Volume + Unit Packing tab, columns 6, 7.
Commodity Packing tab, column 8.
Detailed Description Packing tab, column 9.
Goods Description Packing tab, column 10.
Item No. Packing tab, column 11.
Length Packing tab, column 12.
Width Packing tab, column 13.
Height Packing tab, column 14.
Length Unit Packing tab, column 15.
Line Price Packing tab, column 16.
Reference Number Packing tab, column 17.
Marks & Numbers Packing tab, bottom right.

3 Screenshots (CTRL-Click to follow links)

Basic Registration Tab (page 8)

Routing Tab (page 8)

Packing Tab (page 9)

Addresses Tab (page 9)

© 2016 WiseTech Global Page 7 of 10

3.1 Basic Registration Tab

3.2 Routing Tab

© 2016 WiseTech Global Page 8 of 10

3.3 Packing Tab

3.4 Addresses Tab

© 2016 WiseTech Global Page 9 of 10

Contact Information

If you have questions on this How-To, contact us within CargoWise One. Go to Help > eRequest /
Incident

More information on this module is available in our WiseLearning material and Functional Guides.
Within CargoWise One go to Help > myaccount.cargowise.com

© 2016 WiseTech Global Page 10 of 10