0% found this document useful (0 votes)

1K views

eAdaptorDevelopersGuide - 11 March 2024

The document provides technical guidance for developing interfaces between a company's systems and CargoWise software using the eAdaptor or xHub. It describes different connectivity options, XML formats, and concepts like code mapping and validation that are important for interface development.

Uploaded by

ppaizes

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

1K views

eAdaptorDevelopersGuide - 11 March 2024

Uploaded by

ppaizes

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 239

Technical guide

eAdaptor - Developer’s Guide

Ver 24.03.11

a. Development of interfaces between CargoWise and your In-House Systems/Middleware;

and
b. Development of interfaces between CargoWise and your Clients' Systems via your
Middleware,

(collectively, the "Permitted Purpose").

Any person within your organization who accesses this eAdaptor Developer's Guide (irrespective
of how it is accessed) may only do so only for the Permitted Purpose. All intellectual property
rights in this eAdaptor Developer's Guide are owned by WTG and are the sole and absolute
property of WTG, throughout the world.

Neither you, nor any person within your organization who accesses this eAdaptor Developer's
Guide is permitted to copy or distribute, forward, or publicly display the contents of this Adaptor
Developer's Guide (or any part of it) to any third party without first obtaining the written consent
of WTG.

eAdaptor - Developer’s Guide | 1

© 2024 WiseTech Global 11 March 2024
Contents
1. Introduction ....................................................................................................................................... 7
1.1 eAdaptor or xHub.................................................................................................................................................. 7
1.2 Which type of XML should I use .................................................................................................................. 8
1.2.1 Universal Event XML......................................................................................................................... 8
1.2.2 Universal Transaction XML ........................................................................................................... 9
1.2.3 Universal transaction Batch XML .............................................................................................. 9
1.2.4 Universal Shipment XML ................................................................................................................ 9
1.2.5 Universal Activity XML ....................................................................................................................10
1.2.6 Native XML .............................................................................................................................................10
1.3 What about Legacy XML and InterfaceConnector ........................................................................... 11
1.4 How should I use this Guide? ....................................................................................................................... 11
2. Connectivity Options .................................................................................................................... 12
2.1 Overview .................................................................................................................................................................. 12
2.1.1 eAdaptor SOAP ................................................................................................................................... 12
2.1.2 eAdaptor HTTP+XML ...................................................................................................................... 12
2.1.3 XNDT Service ....................................................................................................................................... 12
2.2 How to Develop your end of the interface ........................................................................................... 13
2.3 Getting Setup to use our interfaces ......................................................................................................... 13
2.4 eAdaptor SOAP ................................................................................................................................................... 14
2.4.1 Overview .................................................................................................................................................. 14
2.4.2 Development Plan ............................................................................................................................. 16
2.4.3 Using the Sample SOAP Client/Service .............................................................................. 16
2.4.4 WSDL and SOAP used by the interface ............................................................................ 40
2.5 eAdaptor HTTP+XML......................................................................................................................................45
2.5.1 Overview ................................................................................................................................................ 45
2.5.2 Implementing the HTTP/HTTPS Connection ................................................................... 47
2.5.3 Universal Shipment query component .................................................................................52
2.5.4 Universal Document Query Component ............................................................................ 56
2.5.5 Universal Inbound Synchronous Component ................................................................. 64
2.5.6 Universal Inbound Asynchronous Component............................................................... 68
2.5.7 Universal Accounting Transaction Batch Export Component ............................... 69

eAdaptor - Developer’s Guide | 2

© 2024 WiseTech Global 11 March 2024
2.5.8 Universal Interchange Requeue Component ................................................................... 75
2.5.9 Native Query Component............................................................................................................. 78
2.5.10 Native Inbound Synchronous component ........................................................................... 81
2.5.11 Universal Response Message Number .............................................................................. 83
2.6 XNDT Web Service interface .....................................................................................................................84
2.6.1 Interface overview ............................................................................................................................ 84
2.6.2 Using the Retrieve method ......................................................................................................... 85
2.6.3 Using the Update Method ........................................................................................................... 88
2.6.4 Using the XNDT Sample Client ............................................................................................... 92
3. Common XML concepts ............................................................................................................. 93
3.1 Obtaining current XML Schemas .............................................................................................................93
3.2.1 Native list of Entities ....................................................................................................................... 96
3.2.2 Universal list of Entities ................................................................................................................ 96
3.3 Encoding and Extended Character Sets ............................................................................................. 97
3.3.1 Limitations of the XML standard ..............................................................................................97
3.3.2 Limitations of SQL database storage ................................................................................... 98
3.3.3 Which fields support Extended Characters? ................................................................... 98
3.4 Code mapping .................................................................................................................................................. 100
3.4.1 Functional overview ...................................................................................................................... 100
3.4.2 Step One - Establishing the Target Company ................................................................ 101
3.4.3 Step Two - Reading the Data Provider Foreign Code ..............................................103
3.4.4 Step Three - Mapping the Data Provider Foreign Code to an Organization
103
3.4.5 Step Four - Mapping from Foreign Codes to Local Codes ................................... 104
3.4.6 Configuring Mappings for an Organization ..................................................................... 104
3.4.7 Evidence Code Mapping has taken place. ..................................................................... 105
3.5 Validation during data import....................................................................................................................106
3.6 Applying updates from incoming XML ................................................................................................ 107
4. Native XML (Refer to Native XML Guide) ............................................................................108
4.1 Concepts ...............................................................................................................................................................108
4.1.1 Namespace ........................................................................................................................................ 108
4.1.2 Native XML Schemas .................................................................................................................. 109
4.1.3 Schema names................................................................................................................................ 109

eAdaptor - Developer’s Guide | 3

© 2024 WiseTech Global 11 March 2024
4.1.4 Published Schemas ...................................................................................................................... 109
4.1.5 Table Keys............................................................................................................................................ 110
4.1.6 Foreign Keys/Related Items ...................................................................................................... 110
4.1.7 Action attributes................................................................................................................................... 111
4.2 Automated Native XML .................................................................................................................................. 113
4.2.1 Importing Native XML via eAdaptor SOAP........................................................................113
4.2.2 Exporting Native XML via eAdaptor SOAP .....................................................................120
4.3 Manual Native XML operations ............................................................................................................... 133
4.3.1 Manually exporting Native XML.............................................................................................. 133
4.3.2 Manually Importing Native XML ............................................................................................. 134
4.4 Matching and translating ..............................................................................................................................137
4.4.1 EDI Code Mapping ......................................................................................................................... 137
4.4.2 Organization Code generation ................................................................................................ 139
4.4.3 Code Lists ............................................................................................................................................ 139
4.5 Database Schema and Field definitions ............................................................................................140
4.5.1 Tools for understanding Field definitions ......................................................................... 140
4.6 Importing and exporting Notes ..................................................................................................................141
4.6.1 Note Types Registry setting....................................................................................................... 141
4.6.2 Note Types in the GUI ................................................................................................................... 141
4.6.3 Plain Text Notes............................................................................................................................... 143
4.6.4 Rich Text Notes ................................................................................................................................ 143
4.6.5 Tips for Notes in Native XML ................................................................................................... 144
4.7 Native XML Datasets..................................................................................................................................... 145
4.7.1 Reference Files ................................................................................................................................ 145
4.7.2 Locations .............................................................................................................................................. 148
4.7.3 Performance Management ........................................................................................................ 148
4.7.4 Workflow Manager.......................................................................................................................... 149
4.7.5 User Admin ......................................................................................................................................... 149
4.7.6 Other ...................................................................................................................................................... 150
5. Universal XML (Refer to Universal XML Guide) ................................................................. 151
5.1 Concepts .................................................................................................................................................................151
5.1.1 Overview ................................................................................................................................................ 151

eAdaptor - Developer’s Guide | 4

© 2024 WiseTech Global 11 March 2024
5.1.2 Universal Data types ..................................................................................................................... 152
5.1.3 DataContext element .................................................................................................................... 153
5.1.4 DataContext when exporting XML ........................................................................................ 153
5.1.5 DataContext when importing XML ........................................................................................ 155
5.1.6 Link Elements ................................................................................................................................... 160
5.1.7 CollectionContent attributes and importing Collections ........................................... 162
5.1.8 Customized Fields .......................................................................................................................... 164
5.1.9 Dates and Timezones................................................................................................................... 165
5.2 Sending Universal XML ............................................................................................................................... 167
5.2.1 Overview ............................................................................................................................................... 167
5.2.2 Configuring Communications ................................................................................................... 167
5.2.3 Sending automatically via Workflow ....................................................................................169
5.2.4 Adding Workflow Triggers ..........................................................................................................169
5.2.5 Automatically Populating Workflow Triggers .................................................................. 173
5.2.6 Sending Manually via Actions Menu ................................................................................... 174
5.3 Receiving Universal XML............................................................................................................................ 175
5.3.1 Wrapping Universal XML into Universal Interchange ............................................... 175
5.3.2 Requesting a Processing result response ........................................................................177
5.3.3 Manual queuing for import (for test purposes only) .................................................. 180
5.3.4 Logging and processing after import ................................................................................... 182
5.3.5 UMI Service Task ............................................................................................................................ 183
5.3.6 Universal Data Buss ...................................................................................................................... 187
5.3.7 Key matching on import............................................................................................................... 187
5.3.8 Verbose Logging............................................................................................................................... 191
5.4 Universal Shipments ...................................................................................................................................... 192
5.4.1 Overview ............................................................................................................................................... 192
5.4.2 Milestones ............................................................................................................................................ 193
5.4.3 Job Costing (Billing) and Consol Costs ............................................................................. 195
5.4.4 SendersLocalClient and LocalClient Organization elements ............................. 208
5.4.5 Additional References ....................................................................................................................211
5.4.6 Importing and Exporting Notes ............................................................................................... 215
5.5 Universal Events .............................................................................................................................................. 218

eAdaptor - Developer’s Guide | 5

© 2024 WiseTech Global 11 March 2024
5.5.1 Overview ............................................................................................................................................... 218
5.5.2 Universal Event Schema ............................................................................................................ 219
5.5.3 Common implementation aspects......................................................................................... 219
5.5.4 Events Showing in CargoWise................................................................................................ 231
5.5.5 Sending eDocs to DocManager using Universal Event XML ..............................234
5.6 Universal Activities ......................................................................................................................................... 238
5.6.1 Overview ..............................................................................................................................................238
5.6.2 Module Mapping Guide ..............................................................................................................238
5.7 Universal Transactions................................................................................................................................ 238
5.7.1 Overview ..............................................................................................................................................238
6. Module implementation overviews ...................................................................................... 239

eAdaptor - Developer’s Guide | 6

© 2024 WiseTech Global 11 March 2024
1. Introduction
Welcome to the world of XML Integration available from within CargoWise. This reference guide
covers the most common forms of Operational and Reference File Module integrations, including
initial loads of data, updates of data, exports of data, and event management/processing.

There are two key questions you need to be able to answer before using this guide.

1.1 eAdaptor or xHub

WiseTech Global provides a suite of products that empower the CargoWise user to unlock the
value that electronic messaging offers, delivering data to the center of your operation.

First, are you going to build your own integrations with your customers and partners that are
specific to your needs, using eAdaptor SOAP or HTTP+XML to map to our XML interfaces
yourself? Or are you going to be using WiseTech Global’s next generation middleware platform
xHub and have us do the mapping for you?

xHub has replaced eHub and provides the stability, scalability, and redundancy that our
customers demand to meet the needs of their expanding businesses, ensuring CargoWise
remains at the forefront of supply-chain technology. xHub messaging interfaces are available in
all industry supported message formats and transport protocols. You will specify your interfacing
requirements; we’ll manage the project from analysis to delivery and provide on-going support.

If you will use xHub, this guide will help you understand what happens within CargoWise once the
XML comes in or before it leaves, but the sections on transport (eAdaptor SOAP or HTTP+XML)
and how to formulate our XML will be of less interest to you. The workflow configuration sections
will also be of interest to you.

Where you are transferring data from one CargoWise system to another, it is easy to use xHub as
every CargoWise system is connected to xHub out of the box. Refer to our E2E Messaging guides
available from our My Account web portal for more information on this.

If you want to use eAdaptor SOAP or eAdaptor HTTP+XML and map to our XML dataset yourself,
you will need to make yourself thoroughly familiar with this guide. You will also need middleware
that will connect using the eAdaptor interface and arrange transformation and transfer of data
when dealing with non-CargoWise systems. eAdaptor provides a single interface suitable for in-
house; middleware is then used to build and maintain interfaces from eAdaptor to internal and
external systems and parties.

Before you choose to use eAdaptor, you will need staff with an appropriate level of
experience mapping between different forms of XML along with web service development
experience before attempting this. This means you need a Senior Web Developer with strong
experience using SOAP Web Services, WSDL, XML, XSD, and RESTful Web Services if you want
to proceed using eAdaptor SOAP or eAdaptor HTTP+XML.

eAdaptor - Developer’s Guide | 7

© 2024 WiseTech Global 11 March 2024
If you do not have an experienced Senior Web Developer on staff, you can engage one of our
WiseTechnical Partners to provide this resource for you.

You will also need staff well versed in the module you wish to interface with and configuring
Workflow Templates in those modules. They will be responsible for specifying the setup
within CargoWise and, of course, testing during implementation.

If your staff does not have these capabilities. However, if you would still like to manage the
mappings and workflow yourself, you can engage one of our WiseService Partners with
experience with the modules you are targeting, along with Setup & Maintenance of Workflow
and Developing Bespoke Service-based Interfaces.

If you are unsure about any of the above, we recommend that you talk to your WiseTech
Global representative about having us do your mappings for you using xHub.

1.2 Which type of XML should I use

To answer this question, you have to know which module you want to work with and what you
want to do in it. Following is an overview of the types of XML available and their functions within
each module. More complete information on each of these follows in later sections in the guide.

For more information on Universal XMLs refer to Universal XML Guide. For more information
on Native XMLs refer to the Native XML Guide

1.2.1 Universal Event XML

All modules within CargoWise allow Events to be recorded against the entities within that module
that are used to record when events occur in the life of that entity. Examples of some of the
event types used are Departed, Arrived, Document Imported, and Cleared Customs. If this is the
kind of data you are planning to exchange, you can use Universal Event XML to do this.

These can be sent out from modules with a Workflow tab automatically when an event is
recorded within CargoWise. They can also be sent into those same modules when you want to
record an event from an external source. There is one Universal Event XML schema that covers all
modules, which is why it’s called Universal.

A good example where Universal Events are used is for Airline Messaging, where Airlines send
status updates (FSU messages) for Air Waybills as they occur. We map these status updates into
Universal Events and forward them to CargoWise systems, where they then appear against the
matching Forwarding Consol. Events can be configured to trigger automatic processes via
Workflow automation; for more information, see our Workflow Automation user guides.

eAdaptor - Developer’s Guide | 8

© 2024 WiseTech Global 11 March 2024
1.2.2 Universal Transaction XML
If you are trying to interface using posted accounting transactions, then you will want to use the
Universal Transaction XML. As is common across all forms of Universal XML, there is only one
schema for all transaction types supported. AR and AP invoices use the same schema as Credit
Notes, Payments, and Journals.

This is done by having all elements for all supported transaction types present in the one
schema. Where values are common across multiple transaction types like Posted Date, Local
Total, and Currency, the same elements are used. Each transaction type uses elements relevant
to that transaction type and ignores those not relevant. As an example, you might have a Check
Number on a Payment but not on an AR Invoice.

For unposted job related costs and revenue, you should use the JobCosting element in the
Universal Shipment XML mentioned below.

1.2.3 Universal transaction Batch XML

Some global businesses choose to amalgamate their accounting transactions into one centrally
run accounting system. For those who want to do that, our eAdaptor web service interface allows
you to batch up all posted but unbatched transactions, then query the same interface for the
content of that batch. For more information on this, please refer to section 2.5.7 Universal
Accounting Transaction Batch Export Component.

1.2.4 Universal Shipment XML

Operational modules where movement of freight is involved interface using Universal Shipment
XML. This means that for most operational modules (except accounting), this is what is used to
transfer job information into and out of those modules.

The Universal Shipment XML schema contains all possible elements from all modules
implementing this interface. With our global logistics worldview, we found many data elements
across all business areas (weight, volume, packages, origin, destination, etc.). Wherever possible,
we use the same common elements from the Universal Shipment schema to store the same
common data.

That’s why we call it Universal XML. You can map to Universal once and then use it across
multiple modules.

You can send Universal Shipment XML into any operational module involving movement of goods.
You can send it out of the same modules automatically using Workflow Automation, or you can
query for Universal Shipment XML using the Universal Shipment Query interface.

eAdaptor - Developer’s Guide | 9

© 2024 WiseTech Global 11 March 2024
This also allows data generated from one module in one CargoWise system can be sent to
another module in another CargoWise module. This forms the basis of our E2E or Enterprise
to Enterprise product offering used by many CargoWise customers allowing automated data
transfer between trading partners.
To start using E2E Messaging, partners on CargoWise exchange Enterprise System IDs. Once
Workflow templates are configured correctly at each end, shipment information flows
automatically between partners via xHub as each booking is finalized. If you would like more
information on E2E Messaging, please raise a CR9 eRequest.

1.2.5 Universal Activity XML

The modules making up the PAVE productivity tools built into CargoWise integrate their
operational data using the Universal Activity XML schema. These include the Customer Service
Ticket, Project, and Work Item modules.

Just like the other Universal XML schemas, one schema is used across all PAVE modules, making
it possible to transfer data across modules and systems seamlessly.

Once you have mapped to a Universal XML schema, you can target any module supporting that
schema without having to remap for the next business process you want to implement.

1.2.6 Native XML

Native XML is used to manage and publish reference file data in CargoWise Unlike Universal XML,
where one schema is used across many modules sharing common data, Native XML is used for a
range of datasets where there is very little crossover or common data.

All of our Reference Files are accessible using Native XML datasets for both data import and
export. Reference Files include entities like Products, Organizations, Locations, and
Currencies/Exchange Rates.

Native XML can be pushed in or queried via the XNDT Web Service Interface; it can be sent in as
a message via eAdaptor or xHub and sent out via eAdaptor or xHub where Workflow Automation
has been implemented on the Reference File Module concerned.

Complete information on Native XML is found in the Native XML sections of the guide following.

eAdaptor - Developer’s Guide | 10

© 2024 WiseTech Global 11 March 2024
1.3 What about Legacy XML and
InterfaceConnector
Native and Universal XML have replaced the previous Legacy XML message set, which is being
phased out over time. If you are unsure if a sample you are looking at is current or not, Legacy
XML can be identified by its namespace, which is http://www.edi.com.au/EnterpriseService/.

Legacy XML was generally published and imported using a legacy product called
InterfaceConnector, which is unavailable in CargoWise InterfaceConnector and has not been
available as a new license under ediEnterprise for several years now. It is not advisable to develop
any new interfaces using Legacy XML.

1.4 How should I use this Guide?

If you’re reading this section, what you probably REALLY want to ask is, “So how do I get started
developing an Interface with CargoWise?”

This Reference Guide covers the broader functionality of our core XML services; although it’s a
good reference, it is not the only resource available. Each module that is mapped to a Universal or
Native XML dataset will have a Module Mapping Guide that covers that module’s specific
implementation details.

Module Mapping Guides describe the keys used for matching, give an overview of how the
schema is mapped, and provide a list of element level mappings describing each field’s location
in the GUI. They can be found in WiseTech Academy under Integration Options – Mapping Guides

At the time of writing this section, Module Mapping Guides exist for many modules across
CargoWise, and there are many that are still in progress. If you cannot find one for a module
you are working with, please raise an incident to register your interest.

You should also read the eAdaptor System Administrator’s Guide, which covers the installation
and initial setup required to get the eAdaptor interface working. Web Services are an optional
component of CargoWise and have some additional deployment requirements covered in that
guide.

So, where does this Reference Guide fit in? Once you have a general understanding of how things
work end to end and have a high-level picture in mind of what you want to do, this reference
guide is best used to obtain specifics on individual pieces of functionality as the need for in-
depth detail arises.

It’s recommended to review this guide to appreciate the range of functionality available. There’s a
lot in there, and although you probably don’t want to dig into every detail at first, it’s helpful to
have at least an overview of what’s available and, therefore, possible. Later on, when you
encounter a problem or are unsure how to proceed, you’ll know which sections you want to
check in this guide.

eAdaptor - Developer’s Guide | 11

© 2024 WiseTech Global 11 March 2024
2. Connectivity Options
2.1 Overview
There are three main forms of connectivity you can use when interfacing with CargoWise. Each
interface is optimized for a different interfacing paradigm. Following is a brief summary of all
connectivity options, then a more detailed section for each showing how you can develop your
own interfaces.

2.1.1 eAdaptor SOAP

This is a scalable message-based interface designed to work well with most forms of middleware.
Built for large message flows, this interface provides an efficient push-based interface into our
internal message processing queue and a push-based message interface that can feed back out
to your choice of middleware.

The interface self publishes a WSDL describing the requirements of the interface, and we provide
documentation describing the functionality of the interface as part of this guide. You can also
download a Sample Client from the Technical Guides section of our My Account web portal.

At the SOAP level, we use the same Web Service interface in both directions. This means that you
can also use the eAdaptor SOAP Sample Client to test your interface implementation before
connecting it up to CargoWise.

2.1.2 eAdaptor HTTP+XML

This is a RESTful web service developed as a synchronous web service interface. An HTTP POST is
sent with an incoming XML Message, and the response is an XML message containing the result
of the operation requested. XSD Schemas of all messages used are available from within
CargoWise.

This interface provides a lighter alternative to the SOAP-based interface, where an ordered
queue is not required. It also allows for Queries to be made requesting current data from active
jobs within CargoWise. You can also download a Sample Client from the Technical Guides section
of our My Account web portal.

2.1.3 XNDT Service

This is a pair of simple SOAP-based web methods that can be used to query and directly update
Reference File data using Native XML only. Calls to this service return a synchronous response.
You can download a Sample Client from the Technical Guides section of our My Account web
portal.

The functionality available via the XNDT Service will be made available from the eAdaptor
HTTP+XML interface at some point in the future.

eAdaptor - Developer’s Guide | 12

© 2024 WiseTech Global 11 March 2024
2.2 How to Develop your end of the interface
We provide sample Services and Clients for all of our interfaces. Our documentation describes
the content being sent and received, WSDLs are published as part of each SOAP web service,
XSDs are provided for all XML, and HTTP Header information is provided for the RESTful eAdaptor
HTTP+XML interface.

These are all tools that an experienced Senior Web Services Developer will be able to use to build
connections using our interface. The sample Clients and Services are not a basis for your own
development; they are working samples that can be used to test and demonstrate the operation
of both our Interfaces; and, in some cases, your own implementation.

You will need to have your own Developer using your own choice of middleware to interface with
CargoWise successfully. Your Developer will need to be familiar with tools like Fiddler (web
service transport layer debugging tool) and SOAP UI (tool for working with WSDL to produce
SOAP), although they may have their own tools of choice.

This guide does not tell you how to develop your own interface. It provides the information
required for a Senior Web Services Developer to develop one for you. If you do not have an
experienced Web Services developer on staff, please get in touch with one of our WiseTechnical
Partners to arrange a suitable resource.

Module Mapping Guides describe the keys used for matching, give an overview of how the
schema is mapped, and provide a list of element level mappings describing each field’s
location in the GUI. They can be found in WiseTech Academy under Integration Options -
eAdaptor Guides.

2.3 Getting Setup to use our interfaces

Before you can start using any of the interfaces described above, you will need to have the Web
Components part of CargoWise installed on a suitably provisioned and hosted IIS server.

Information on setting up eAdaptor can be found in the eAdaptor System Administrator’s Guide.
Once you have completed the instructions in that guide, you will have two URLs, one for eAdaptor
SOAP/HTTP+XML components and one for the XNDT Web Service component.

eAdaptor - Developer’s Guide | 13

© 2024 WiseTech Global 11 March 2024
2.4 eAdaptor SOAP
2.4.1 Overview
eAdaptor SOAP is a message-based interface that allows all forms of XML supported in
CargoWise to be pushed into our inbound message queue and pushed out from the outbound
message queue.

We provide a sample web client and web service, which can be used to test and/or demonstrate
the setup of the eAdaptor SOAP interface in your own CargoWise system once the Web
Components have been deployed.

If you don’t already have this, it’s available for download from WiseTech Academy in
Integration Options – eAdaptor Guides

Queued messages in both directions show in the EDI Interchange and EDI Message Modules
within CargoWise.

The UMI and NMI service tasks pick up incoming XML from the inbound message queue and
process them in received order.

Workflow Automation is used to queue outgoing XML for the eAdaptor Outbound Service Task to
pick up and push to the eAdaptor SOAP interface you implement in your middleware.

Please refer to the diagram following, which gives an overview of this functionality. The sample
webclient/web service can be used in place of your own middleware as you develop a
connection in your middleware.

The CargoWise xHub Interface functions in parallel with the eAdaptor SOAP Interface via the
same message queue (EDI Message Module). Messages are then processed inbound and
outbound using the same service tasks and automations. This means you have access to all
the same facilities we use when implementing automations within CargoWise.

eAdaptor - Developer’s Guide | 14

© 2024 WiseTech Global 11 March 2024
eAdaptor - Developer’s Guide | 15
© 2023 WiseTech Global 11 March 2024
2.4.2 Development Plan
A good plan of attack during development of the eAdaptor SOAP Interface in your middleware is:

1. Test the CargoWise setup using the sample web client and/or service (depending on which
directions of message flow you require). This will familiarize you with basic operations and
allow you to use Fiddler to obtain samples of the interface functioning in your own
environment.
2. Implement the eAdaptor SOAP Interface in your middleware using the WSDL from your
CargoWise setup and samples you generated from step one. Test your implementation using
the sample web client and/or web service.
3. Configure your CargoWise setup and your middleware to point at each other and test using
real data. It’s this step that requires a little more knowledge of CargoWise, although everything
you need to know is found later in this guide.
4. Move onto the Data Flow section later in this chapter.

As mentioned previously, you will need an experienced Senior Web Service Developer to
implement this interface in your choice of middleware. This guide does not tell you how to build a
web service interface; it provides information about the eAdaptor SOAP Interface and gives some
general pointers for web service developers who are not yet familiar with CargoWise.

2.4.3 Using the Sample SOAP Client/Service

2.4.3.1 Sample C# Web Client
This section assumes that you have already downloaded and unzipped the eAdaptor Sample
Interface Pack and have a current version of Visual Studio installed. You will also need to have
deployed Web Services for your copy of CargoWise and know the URL of your eAdaptor Inbound
Web Service.

First, you will need to build the eAdaptorSamples solution. Navigate to the folder you have
extracted the eAdaptorSampleInterfaces zip file to open the SOAP.C# folder and open the
contained eAdaptorSamples solution in Visual Studio.

All samples applications provided in eAdaptor Sample Interface Pack are for demonstration
purpose only. Sample Applications or libraries should not be used in Production environment.

eAdaptor - Developer’s Guide | 16

Once you have opened the solution, select Debug > Start Debugging from the menu or press the
F5 key.

Figure 2 Debugging.

eAdaptor - Developer’s Guide | 17

Figure 3 eAdaptor Sample Client

Paste the URL of your eAdaptor Inbound Web Service into the Service Address field. Ensure you
add https before entering the service address to ensure the web service is correctly processed.

The next field that you will need to enter is the Recipient ID. The Recipient ID field must contain
the nine-character CargoWise license code of the system you are sending data into. This will be
used to control which Company the incoming data is processed under.

2.4.3.1.1 Finding your CargoWise license code

To find your CargoWise license code, open your instance of CargoWise, log into the Company
you want to obtain a license code for, navigate to the Jump Menu, select the Help action menu
button at the bottom, and then About. The window below will open, and the nine-digit CargoWise
license code will be listed towards the top just under your company name.

Figure 4 CargoWise license code

eAdaptor - Developer’s Guide | 18

Copy the nine-character CargoWise license code (excluding dashes) and enter it into the
Recipient Id field on your eAdaptor client interface. For example, the license code for the system
shown above is HYEDAUA04. Ensure you use the correct casing when entering the Recipient Id.

Finally, you will need to enter a Sender Id and Password. Both of these are set in the registry of
CargoWise, to locate them go to Maintain > System > Registry > eServices > eAdaptor >
Inbound > Basic Authentication.

Figure 5 Registry setting > eAdaptor Inbound Authentication

You can copy the user name from this registry setting. In order to enhance password security,
the password field is read-only. Users won’t be able to type a password, but instead, a complex
password will be generated.

eAdaptor - Developer’s Guide | 19

© 2024 WiseTech Global 11 March 2024
If a password already exists, a Warning will be provided to confirm the reset of password as seen
below.

The password should be copied before saving the form. The generated password will be masked
once the Save button is pressed:

eAdaptor - Developer’s Guide | 20

© 2024 WiseTech Global 11 March 2024
If you don’t know the password, you will need to either obtain it from someone in your
organization who knows what it is or change it to a new password so that you know what it is.

Take the user name and password entered on the eAdaptor Inbound Basic Authentications page
and enter them into their corresponding fields on the eAdaptor interface. Your eAdaptor Sample
Client Form should look something like this if you've followed all the instructions.

Figure 6 eAdaptor Sample Client

You are now ready to send Universal XML to your instance of CargoWise. You can click on the
Ping button, which will check to see if your URL is valid and responding, or you can send a test
message.

eAdaptor - Developer’s Guide | 21

To send a test message you will need to have a valid xml file. For this guide we have elected to
use a RefUNLOCO XML file, which is shown below. This sample is included in the SampleXML
folder in NativeUNLOCO_AUANN.xml

When this XML is imported into CargoWise, the UNLOCO for Annandale in Sydney, Australia
(AUANN) will be updated to have the Is Rail flag turned on.
<UniversalInterchange xmlns="http://www.cargowise.com/Schemas/Universal/2011/11">
<Header>
<SenderID>MYSENDER</SenderID>
<RecipientID>MYRECIPIENT</RecipientID>
</Header>
<Body>
<Native xmlns="http://www.cargowise.com/Schemas/Native/2011/11">
<Header>
<OwnerCode>MYSENDER</OwnerCode>
<EnableCodeMapping>false</EnableCodeMapping>
</Header>
<Body>
<UNLOCO version="2.0">
<RefUNLOCO Action="UPDATE">
<Code>AUANN</Code>
<PortName>Annandale</PortName>
<HasRail>true</HasRail>
</RefUNLOCO>
</UNLOCO>
</Body>
</Native>
</Body>
</UniversalInterchange>

To select the file you want to send, click on Browse, and the file explorer window will open.
Navigate to and select the example XML file described as shown.

Figure 7 eAdaptor Sample Interfaces

eAdaptor - Developer’s Guide | 22

© 2024 WiseTech Global 11 March 2024
Once you select the file, click on the Open button then you will see the Message File field gets
filled in. Click on the Send button.

Figure 8 eAdaptor Sample Client

If you see a ‘Send message successful.’ message, that means the XML you sent was accepted by
CargoWise and is stored in the DB as an EDI Interchange, ready for the service tasks to process.
You will be able to see the XML you submitted in the EDI Interchanges modules as described in
Section 2.4.6.1 Inbound XML in CargoWise.

If the details you entered are incorrect, or the XML you submitted is malformed, you will get an
error message indicating what it was that caused the problem. Fix the details indicated by the
error message and click on the Send button again until you see a Send message successful
message and are ready for the next step.

eAdaptor interface also can be tested using tools like SoapUI, Postman etc.

For more information on processing of inbound messages, refer to our learning units:
1COR193 - How do I check data imports through EDI Messages?
1COR417 – Understanding Service Tasks?

eAdaptor - Developer’s Guide | 23

© 2024 WiseTech Global 11 March 2024
2.4.3.2 Sample C# Web Service
This section of the guide will demonstrate how to build and configure the eAdaptor Sample Web
Service. As provided, this service will write each incoming XML message out to an individual file in
a preconfigured folder. This is intended as a working sample to demonstrate an implementation
so that you can get a feel for the interface before implementing your own in your middleware.

Once this is built and configured, you can then send data to the URL you have configured for the
eAdaptor Sample Web Service from your CargoWise system. You can also use this to test an
eAdaptor Web Client you have developed in your own middleware before you try and send XML
into your CargoWise system.

This web service is provided as a sample for demonstration and test purposes only. You will
need to have a copy of Microsoft Visual Studio installed along with an IIS instance running to
use this sample.

2.4.3.2.1 Creating a Web Site

You will need to create a Web Site on your IIS instance to host the eAdaptor Sample Web Service.
One the computer hosting your IIS instance, right-click on your Computer/This PC icon and
select the Manage option. This will open the Computer Management window and navigate to
Computer Management > Services and Applications > Internet Information Services (IIS)
Manager.

Expand your web server in the Connections pane, right-click on Sites, and select Add website.

Figure 9 IIS Manager Add Website

eAdaptor - Developer’s Guide | 24

© 2024 WiseTech Global 11 March 2024
The Add Website window will appear. Enter a Site name of eAdaptorOutbound and select the …
Search button next to the Physical Path field.

A file explorer window will open. Navigate to the root folder of your web server. (The default path
for IIS is C:\inetpub\wwwroot)

Create a new folder using the Make New Folder button called eAdaptorOutbound. Select the
new eAdaptorOutbound folder and click the OK button. This will return you to the Add Website
window as shown below.

Figure 10 eAdaptorOutbound Folder

Click on the OK button to finish creating your website. You may get a dialog telling you there is a
conflict with another site.

You can either assign another port number or continue on anyway. If you choose to continue, it
will stop the other website from running. Keep in mind that if you choose a non-standard port
(suggest something in the 80xx series), you will have to make sure you use the port number you
choose as part of your URL. You should also be aware that https and http use different ports, so
you will need to check any port specified in the URL when switching between those.

eAdaptor - Developer’s Guide | 25

In order to use eAdaptor securely, you must create and/or configure an SSL Certificate for the
site you just created.

You can create a self-signed certificate if you don’t already have a certificate for your IIS
server/site. Instructions on how to do this can be found under Obtain a Certificate, Create Self
Signed Certificate here: http://learn.iis.net/page.aspx/144/how-to-set-up-ssl-on-iis-7/

2.4.3.2.3 Binding your Web Site to the SSL Certificate

You now have an SSL Certificate and a new Web Site, so you need to create a new binding on
your website to enable SSL (https) using your certificate, and assuming that you still have IIS
Manager open, right-click on your new eAdaptorOutbound web service and select Edit Bindings.

Click on the Add button, then select a Type of https. You will then see a drop-down menu where
you can select the SSL certificate you created in the previous steps.

Figure 11 Add Site Binding SSL Certificate

Assuming you have resolved any port conflicts that came up, you now have a website ready and
prepared for you to deploy your eAdaptor Outbound Web Service. The next step is to build the
Sample Service and deploy it to the folder your website operates from.

2.4.3.2.4 Building and Deploying the eAdaptor Sample Web Service

This section assumes that you have already downloaded and unzipped the eAdaptor Sample
Interfaces and have a current version of Visual Studio installed.

eAdaptor - Developer’s Guide | 26

In the eAdaptorSampleWebService project, open the eAdaptorSampleWebService.cs file. Go to

line 19 and change the destination folder to an existing accessible folder on the web server you
are going to deploy to. This is the folder where the messages sent from CargoWise to the Sample
Web Service will be saved to.

Figure 13 eAdaptor Sample Web Service Destination Folder

While you are there, you can remove the #warning line that’s there to remind you to complete
this step.

eAdaptor - Developer’s Guide | 27

© 2024 WiseTech Global 11 March 2024
Make sure the folder exists on the web server you are going to deploy to. Otherwise, you will
get errors showing back in the eAdaptor Outbound Messaging (EAM) service task log within
CargoWise, and your interchanges will not be able to be sent.

In the same project, navigate to and open the Web. config file. Find the behavior section for the
eAdaptorStreamedServiceBehavior and change the find Value property to the name of your
machine-running instance of Internet Information Service. This tells your web service where to
find the certificate you generated earlier in the process.

Figure 14 eAdaptorStreamedServiceBehavior Value Property

Select build from the top drop-down menu, select the build solution option, or press the F6 key.
If the solution builds with no errors or warnings, you are now ready to publish the service you just
built.

eAdaptor - Developer’s Guide | 28

After completing the build of the eAdaptor Sample Web Service project, you will need to deploy
it. Right-click on the eAdaptorOutboundWebService project and select publish from the list of
options.

Figure 15 Publishing the eAdaptor Sample Web Service

eAdaptor - Developer’s Guide | 29

© 2024 WiseTech Global 11 March 2024
A new window will appear, allowing you to configure the deployment of the project. Enter the
location of the eAdaptorOutbound website you just created, select Delete all existing files prior
to publish, and only files needed to run this application, and then select publish.

Figure 16 Publish WCF Service Delete All Existing Files Prior to Publish

As long as no errors come up during the publish, you now have your eAdaptor Outbound Web
Service set up and ready to use. You can confirm this has been successful by looking in the
target location to see if the svc file and bin folder have been deployed.

Figure 17 eAdaptor Outbound Web Service

The next step is to test the https URL for the web service, then configure CargoWise to send
interchanges to your deployed Sample Web Service.

eAdaptor - Developer’s Guide | 30

Re-open your computer management window, find IIS Manager in the tree, navigate to the
eAdaptorOutbound application, switch to content view (see bottom of the form), and right-click
on eAdaptorOutboundWebService.svc and select browse.

Figure 18 IIS Manager HTTPS URL for Your Web Service

Your choice of web browser should start, and if all is working properly, you will see the following
landing page.

Figure 19 eAdaptor Sample Outbound WebService Landing Page

eAdaptor - Developer’s Guide | 31

© 2024 WiseTech Global 11 March 2024
Copy the address located next to svcutil.exe, removing the ?wsdl parameter from the end. This is
the http URL of your eAdaptor Outbound Web Service. In the example above, the http URL is:

http://sydco-wbjg-1.wtg.zone/eAdaptorSampleWebService.svc

Before you can put your URL into the registry, you need to convert it to an https URL. Generally,
it’s as simple as changing the http at the beginning of the URL to be https. If you chose to use
non-standard ports when creating your new site in IIS Manager and creating an https binding, you
will need to either update or remove the port numbers in the URL as well.

Take the https URL you have just calculated and enter it in your browser’s address box. If your
https binding is set up correctly and your certificate correctly keyed to your IIS host, you should
see the same landing page with no certificate errors.

Figure 20 eAdaptor Sample WebService URL

Once this is working as above, take note of the https URL in your browser’s address bar. This is
your Sample Web Service URL. You will need to enter this into your CargoWise registry, so the
system knows how to find your web service. In this example, the URL is:

https://sydco-wbjg-1.wtg.zone/eAdaptorSampleWebService.svc

eAdaptor - Developer’s Guide | 32

Once you have your Sample Web Service URL, open your instance of CargoWise and go to
Maintain > System > Registry > eServices > eAdaptor. Go to Outbound, then “Service URL”
within the registry tree. Tick the Override Default box and paste the https URL from the previous
step. Click on the Save button to save your changes.

Figure 21 Registry setting eAdaptor > Outbound > Service URL

eAdaptor - Developer’s Guide | 33

© 2024 WiseTech Global 11 March 2024
You can optionally set a password for each company communicating with your eAdaptor Sample
Web Service implementation under the eAdaptor > Outbound > Password.

Figure 22 Registry setting eAdaptor > Outbound > Password

To set up a web service password, select the Company you want to enter a password for, tick the
Override Default box, enter the password, and click on the Save button to save your changes.

When the EAM (eAdaptor Outbound Messaging) service task sends EDI Interchanges out to your
Web Service implementation, it sends from each company individually. In the security section of
the SOAP message, the username will be the Enterprise License Code for the Company the EDI
Interchange was generated under, and the password will be from that company’s registry setting.

In the Sample Web Service, the username and password from the incoming SOAP are passed
through to the eAdaptorUserNamePasswordValidator class, which you can modify to reject
unauthorized connections. This may be useful in testing security rejections from your own Web
Service Client implementation in your middleware.

You are now ready to send a test message.

eAdaptor - Developer’s Guide | 34

To send XML out from CargoWise via the eAdaptor SOAP interface, you need to configure an EDI
Communications Mode on an Organization that you are sending the XML to. The easiest
Organization to use for this is the Company Org Proxy in a test system. Go to Maintain > User
Admin > Companies, then find the company where the name matches the company you are
logged in under. You can see you’re logged in company in the title of the form, as shown below.

Figure 23 Sending a test interchange

Open the company and find the Organization Proxy field. Select the area, then press the F3 key.
This will bring up the Organization that is your current company’s Org Proxy.

Open the Details > Config > EDI Communications tab in the Org Proxy Organization.

eAdaptor - Developer’s Guide | 35

There are four Communications Modes set up in the sample above. They are used to say how and
where different types of XML messages will go when sent from a given module to this
Organization.

The Module is where the XML is coming from; the Direction indicates this is for sent XML (TRX –
Transmit), the File Format shows XUE and XUS, which are Universal Shipment and Event XML, and
the Transport Layer is EDP – eAdaptor. The Recipient ID is included in the header of the Universal
Interchange when XML is sent out via eAdaptor. Generally, the Recipient ID is used within your
middleware to identify the intended recipient of the XML you are sending.

When testing, it’s advised that you set up a row for both Universal XML File Formats (XUE and
XUS) for the module you are testing. If you are not sure exactly what your business process is
going to be and are just getting the transport layer working, add the four EDI Communications
modes shown above, allowing you to send test messages from the Forwarding Shipment and
Consol modules while you establish your business process.

Refer to our learning unit: 1COR147 - How do set up EDI Communications?

Once you are done, click on the Save and Close button, then go to the Forwarding Shipment
module under Operate > Forwarding > Forwarding > Shipment. Either open a new shipment or
create one with minimal information required to save.

You can work out the mandatory fields by clicking on the New button, then click straight on the
Save button when the form comes up. A dialog will pop up telling you what is mandatory, and
those fields will be highlighted as red when you close the error dialog. Fill the red fields in and

eAdaptor - Developer’s Guide | 36

© 2024 WiseTech Global 11 March 2024
save again. You can press the equal key to select the first organization already in the database for
the Consignor and Consignee fields.

Once you have a Forwarding Shipment open and saved in the database, select Actions > Send
Universal XML > Universal Event from the menu.

Figure 25 Send XML Universal Shipment Dialogue box

Fill in the dialog shown above to send an Authorized event to the Organization Proxy you
previously configured for eAdaptor, then click on the Send & Close button.

Figure 26 Send XML Universal Shipment Dialogue box

If the dialog following shows Universal Event queued for sending to Organisation [xxxx], you have
queued an event for sending.

Refer to our learning materials:

1COR172 - How can I send Universal XML for Testing Purposes?
1PRO023 - Where do I set up Message Trigger Purposes, and how do they work?
How-To - How to create XML Mapping Documentation?

eAdaptor - Developer’s Guide | 37

You can see the queued outbound interchange if you go to the Maintain > System > EDI
Interchanges module.

Figure 27 EDI Interchange Search Screen

You can see the interchange we just created with a status of AQU (Queued eAdaptor). Once this
has been sent out by the EAM (eAdaptor Outbound) Service Task, the status will change to SNT
(Sent).

To make testing the transport layer easier, you can resubmit interchanges by right-clicking on
them and selecting Actions > Reset Status to Queued. This also works when multiple rows are
selected in the grid for a bulk resend.

If you double click on an interchange, you can see the XML that will be sent. You can also click the
Save to Disk button to save the content to a file.

eAdaptor - Developer’s Guide | 38

Within the Logs tab, you can see a history of send attempts, and if there is a failure, there will also
be a log recorded. There may also be a note recorded in the Notes tab with additional
information depending on the cause of the failure.

If the interchange stays with a status of AQU, this can indicate either your service task has not
run yet or may be turned off, in which case you will need to start your service tasks for your
message to be sent.

If the interchange is not sending or is set to an Error status, check the service task log for the
EAM (eAdaptor Outbound) service task to see what is happening in the Maintain > System >
Service Tasks module.

If you open up the EAM service task itself and navigate to the Log Files tab, you will see any errors
that occur when sending to your web service here. You will also see a log of all interchanges sent
to allow you to monitor the flow of interchanges from your CargoWise system.

Refer to our learning units:

1COR193 - How do I check data imports through EDI Messages?
1COR417 – Understanding Service Tasks?

Once the EDI Interchange status changes to SNT (Sent), if you open the folder on your Web
Server that you configured to receive outbound interchanges, you will see a file containing the
Universal Event you have sent.

Congratulations! You have successfully set up the eAdaptor Sample Web Service.

Now that your eAdaptor Sample Web Service is built and configured, you should see a new file
created in the destination folder every time you send Universal or Native XML out via eAdaptor.

eAdaptor - Developer’s Guide | 39

© 2024 WiseTech Global 11 March 2024
2.4.4 WSDL and SOAP used by the interface
The interface used in both directions is identical; the same WSDL/SOAP messages are used.

Because the same interface is used in both directions, you can use the sample web client and
web service to test the eAdaptor SOAP Interface implementation as you build it into your own
middleware. This can be very useful when testing your own end of the interface as it reduces the
reliance on CargoWise during initial interface development.

CargoWise has some additional validation for inbound messages, like making sure the Application
Code is recognized and that the recipient company targeted exists. These issues are usually easy
to deal with once you know the transport layer is working.

The sample web client can also connect to the sample web service; everything uses the same
interface/transport layer.

The eAdaptor SOAP interface self publishes a WSDL describing the requirements of the interface.
If you take the eAdaptor URL provided from the Web Components setup and enter it in a web
browser, you will see a landing page for the eAdaptor SOAP interface, as shown below.

Figure 29 eAdaptor SOAP interface WSDL

Two blue underlined links will bring up the WSDL describing the form of XML used when
connecting via this interface. The WSDL describes the following three web service methods.

• Ping – Accepts a simple SOAP Ping message returning success if the service is alive
• ProcessStream – Not used. This was part of a poll based interface and has been
superseded
• SendStream – Accepts a SendStreamRequest with multiple eHubGatewayMessages. This is
the method you use to push XML messages into CargoWise. Each eHubGatewayMessage
becomes one Interchange in the EDI Interchanges module within CargoWise. The content
of each EDI Interchanges is split out into EDI Messages, which are then processed as
described in the diagram above

eAdaptor - Developer’s Guide | 40

• ApplicationCode – UDM for Universal XML, NDM for Native XML

• ClientID – This is the sending system ID recorded as the Sender on the EDI Interchange.
Can be up to 20 characters
• EmailSubject – Not used Inbound. Outbound contains the value entered on the EDI
Communications Mode on the Recipient Organization within CargoWise
• FileName – Not used Inbound. Outbound contains the value entered on the EDI
Communications Mode on the Recipient Organization within CargoWise
• MessageStream – XML content being sent. Native and Universal XML messages are
wrapped within a Universal Interchange contained within this stream. Content is gzipped,
then base64 encoded.
• TrackingID – This is an identifying GUID generated by the sending system. Is stored against
the EDI Interchange within CargoWise
• SchemaName – “http://www.cargowise.com/Schemas/Native#UniversalInterchange” for
Native XML, “http://www.cargowise.com/Schemas/Universal/2011/11#UniversalInterchange”
for Universal XML

SchemaType – Always ‘Xml’Sample SOAP

You are always best to use a web service debugging tool like Fiddler from Telerik to capture
SOAP samples from your own working interface. (http://www.telerik.com/fiddler) The following
samples are provided purely, so you know what you are looking for when using your choice of
web service debugging tool.

SendStream Post
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-utility-1.0.xsd">
<s:Header>
<h:SendStreamRequestTrackingID xmlns:h="http://CargoWise.com/eHub/2010/06">483560eb-dc8a-4661-a42d-
3593a9b37785</h:SendStreamRequestTrackingID>
<o:Security s:mustUnderstand="1" xmlns:o="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<u:Timestamp u:Id="_0">
<u:Created>2016-06-10T04:23:53.138Z</u:Created>
<u:Expires>2016-06-10T04:28:53.138Z</u:Expires>
</u:Timestamp>
<o:UsernameToken u:Id="uuid-0c344944-2c97-46d6-9d0f-b7ee94816994-19">
<o:Username>abc</o:Username>
<o:Password o:Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-
1.0#PasswordText">123</o:Password>
</o:UsernameToken>
</o:Security>
</s:Header>
<s:Body>
<SendStreamRequest xmlns="http://CargoWise.com/eHub/2010/06">
<Payload>
<Message
ApplicationCode="UDM"
ClientID="WTGCWISYD"
TrackingID="5c2643ed-6ae7-4cbe-bf35-8db3c875aea2"
SchemaName="http://www.cargowise.com/Schemas/Universal/2011/11#UniversalInterchange"
SchemaType="Xml"
EmailSubject=""
FileName="">
H4sIAAAAAAAEAO29B2AcSZYlJi9tynt/SvVK1+B0oQiAYBMk2JBAEOzBiM3mkuwdaUcjKasqgcplVmVdZhZAzO2dvPfee++999577733ujudTif33
/8/XGZkAWz2zkrayZ4hgKrIHz9+fB8/Iv7Hv/cffPzVsrjM6yYrTy/zZZu+W5TL5rOP5m27enT37tXV1Xia1RfVVdHk42m1uPt6Os8XWXPXvnZ3b2
d39+7u7kcp/i6q5Wcf7Y53Pzr6jZM0fcww+Vf642nWZifVss3fmY/0wzfUQ96eVGWZT1uCYL8Nvvc+pc/fXK/yo2dVfZXVs2J58XperBbU1+O7/EX
Q9PfKr49e79CzS/9/fBd/eh3cjfTgfxigZRuc0jDqVU1UOXt69N03nz++G3xi273OayILffL693n6+K79y35/Ui1W2TJA6KSa5Ucn3z17fJd/cziF
bQVHR0/9lCn+pljkRzQvn27v0P8evtnde3Rv79Hu3nh/jxC1LYJXQLbjN9823xsq6t/0+2M35+aj/wf7vUSQQAIAAA==
</Message>
</Payload>
</SendStreamRequest>
<s:Body/>
</s:Envelope>

eAdaptor - Developer’s Guide | 41

© 2024 WiseTech Global 11 March 2024
SendStream Response
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-utility-1.0.xsd">
<s:Header>
<o:Security s:mustUnderstand="1" xmlns:o="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<u:Timestamp u:Id="_0">
<u:Created>2016-06-10T04:23:53.517Z</u:Created>
<u:Expires>2016-06-10T04:28:53.517Z</u:Expires>
</u:Timestamp>
</o:Security>
</s:Header>
<s:Body/>
</s:Envelope>

Data Flows

Inbound XML in CargoWise

As data comes into CargoWise, each eHubGatewayMessage becomes an EDI Interchange which
is visible in the EDI Interchanges module under Maintain > System > EDI Interchange.

Figure 30 EDI Interchange Search Screen

There are many types of interchanges shown here; it’s easy to narrow this down to interchanges
you are creating using the filters at the top of the module. The Application Code is the same as
you specified in the eHubGatewayMessage, UDM for Universal XML, and NDM for Native XML.
There are many other filters available; this module is useful to make sure that your data got into
CargoWise but does not indicate processing success.

Assuming that the content you sent in was correctly wrapped in a Universal Interchange, each
EDI Interchange will cause one or more EDI Messages to be created. These are visible in the EDI
Messages module found under Maintain, then System, then EDI Message.

eAdaptor - Developer’s Guide | 42

If you can see EDI Messages created with a valid ‘Sub Type’ on them (anything except ‘UNK –
Unknown’), then your transport layer is working, and you are at the point where you can work on
your content in more detail. If you can see EDI Interchange, but not EDI Messages, that means
that your transport layer is working, but the content you are sending is not quite correct.

Either way, once you can see EDI Interchanges being created, it’s time to work on your content
using information in the following sections regarding Native XML and Universal XML content.

Outbound XML

Outbound is the reverse of Inbound. Referring back to the diagram at the beginning of this
section, Workflow is used to create outgoing XML. An EDI Interchange is created for each EDI
Message generated on the outbound side with a status of AQU – Queued for eAdaptor. Assuming
the eAdaptor Outbound Messages (EAM) service task is running, it will try and push any queued
EDI Interchanges to the URL configured in the registry.

eAdaptor Outbound guarantees delivery, but guarantees at least once delivery, not once only
delivery. Under exceptional circumstances, there is a small possibility that an interchange will be
sent to the middleware, and the Interchange queued in the database will not be marked as sent. If
this happens, the interchange will be sent again. If duplicates cause problems, the receiving
middleware can discard duplicates with the same TrackingID on the eHubGatewayMessage.

eAdaptor Outbound service requires an HTTP 2XX response for all requests with SOAP response
message as per 2.4.5.2 SendStream Response. Any non-2XX response will be treated as sent
failed and will get re-queued until it has received a valid response. This will block all other
messages in the queue to maintain the message queue order. Messages may be failed manually
via EDI Message Module to allow the queue to process new messages.

eAdaptor - Developer’s Guide | 43

© 2024 WiseTech Global 11 March 2024
Outbound XML in production should always be driven by Workflow Automation rather than
being sent or queued manually. Although there are some manual send options, these are
intended as a last resort or for debugging purposes only. Any process relying on the manual
options indicates a failure in the business analysis process as the key to true efficiency is
automation made possible by having a deeper understanding of the process at hand.

For more information on how to send Universal XML, please see section 5.2 Sending Universal
XML

Merging Outbound Messages

There may be instances where multiple eAdaptor outbound Universal Interchange Messages are
pending from the same ClientID (i.e., RecipientID). In such cases, when an EAM Service task
triggers an outbound message, the pending messages will be merged into a single envelope.
Below is an example of multiple pending messages from the same ClientID being presented in an
eAdaptor SOAP outbound message:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-utility-1.0.xsd">
<s:Header>
<h:SendStreamRequestTrackingID xmlns:h="http://CargoWise.com/eHub/2010/06">483560eb-dc8a-4661-a42d-
3593a9b37785</h:SendStreamRequestTrackingID>
<o:Security s:mustUnderstand="1" xmlns:o="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<u:Timestamp u:Id="_0">
<u:Created>2016-06-10T04:23:53.138Z</u:Created>
<u:Expires>2016-06-10T04:28:53.138Z</u:Expires>
</u:Timestamp>
<o:UsernameToken u:Id="uuid-0c344944-2c97-46d6-9d0f-b7ee94816994-19">
<o:Username>abc</o:Username>
<o:Password o:Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-
1.0#PasswordText">123</o:Password>
</o:UsernameToken>
</o:Security>
</s:Header>
<s:Body>
<SendStreamRequest xmlns="http://CargoWise.com/eHub/2010/06">
<Payload>
<Message
ApplicationCode="UDM"
ClientID="WTGCWISYD"
TrackingID="5c2643ed-6
SchemaName="http://www.cargowise.com/Schemas/Universal/2011/11#UniversalInterchange"
SchemaType="Xml"
EmailSubject=""
FileName="">
H4sIAAAAAAAEAO29B2AcSZYlJi9tynt/SvVK1+B0oQiAYBMk2JBAEOzBiM3mkuwdaUcjKasqgcplVmVdZhZAzO2dvPfee++999577733ujudTif33
/8/XGZkAWz2zkrayZ4hgKrIHz9+fB8/Iv7Hv
</Message>
<Message
ApplicationCode="UDM"
ClientID="WTGCWISYD"
TrackingID="5c2643ed-6ae7-4cbe-bf35-8db3c875aea2"
SchemaName="http://www.cargowise.com/Schemas/Universal/2011/11#UniversalInterchange"
SchemaType="Xml"
EmailSubject=""
FileName="">
H4sIAAAAAAAEAO29B2AcSZYlJi9tynt/SvVK1+B0oQiAYBMk2JBAEOzBiM3mkuwdaUcjKasqgcplVmVdZhZAzO2dvPfee++999577733ujudTif33
/8/XGZkAWz2zkrayZ4hgKrIHz9+fB8/Iv7Hv/cffPzVsrjM6yYrTy/zZZu+W5TL5rOP5m27enT37tXV1Xia1RfVVdHk42m1uPt6Os8XWXPXvnZ3b2
d39+7u7kcp/i6q5Wcf7Y53Pzr6jZM0fcww+Vf642nWZifVss3fmY/0wzfUQ96eVGWZT1uCYL8Nvvc+pc/fXK/yo2dVfZXVs2J58XperBbU1+O7/EX
Q9PfKr49e79CzS/9/fBd/eh3cjfTgfxigZRuc0jDqVU1UOXt69N03nz++G3xi273OayILffL693n6+K79y35/Ui1W2TJA6KSa5Ucn3z17fJd/cziF
bQVHR0/9lCn+pljkRzQvn27v0P8evtnde3Rv79Hu3nh/jxC1LYJXQLbjN9823xsq6t/0+2M35+aj/wf7vUSQQAIAAA==
</Message>
</Payload>
</SendStreamRequest>
<s:Body/>
</s:Envelope>

eAdaptor - Developer’s Guide | 44

© 2024 WiseTech Global 11 March 2024
2.5 eAdaptor HTTP+XML
2.5.1 Overview
In addition to our SOAP-based interface, we have implemented eAdaptor as an HTTP+XML web
service interface. The HTTP protocol is used to POST an XML-based Request message, and an
XML-based Response message is returned as the result. There are many Components, or
functional facilities available using this one form of connection.

You choose the component you want by the XML content you send in the request. Each
component has its own XML schema for the request, which is how the single connection or
endpoint knows how to process your request and respond.

That means that you need to know how to use the single Connection first (that’s the HTTP part),
and then you need to know which content to use for the Component you want to use (the XML
part).

2.5.1.1 Connection
There is no SOAP layer involved. This avoids the inevitable interoperability complications that
arise when trying to implement SOAP messaging on different platforms using different languages
and SDKs. HTTP provides security, encryption, and compression and is simple to implement on all
messaging platforms. XML provides the content and is also universally understood. The
combination provides everything you need and nothing you don’t.

If an HTTP GET request is sent to the same URL, the eAdaptor HTTP+XML service returns HTTP
containing documentation on how to get started with the interface. This means that if you simply
browse to the URL of your eAdaptor web service using your browser of choice, once credentials
have been established, it will show you getting started documentation including links to further
documentation. As more functionalities becomes available via this interface, the documentation
here will also be expanded. You will only see documentation on facilities that are actually
available on the version you are running, so there should be no confusion about what is and what
is not available.

This interface can use either HTTP or HTTPS simply by changing the protocol prefix on the URL. If
you are connecting via an open connection across the internet, you should always use HTTPS as
it encrypts all sent and received XML messages along with the username and password used to
authenticate. HTTP should only be used where the associated security risks are completely
understood, and steps have been taken to mitigate those via other means. If you are hosted with
WiseTech Global, always use HTTPS with TLS v1.2 or above.

Over time, we will move all Web Service-based components across to HTTP+XML providing the
simplest and most effective integration layer possible. This is a simple, light, efficient web
service-based interface that will be using for all new web services from this point.

eAdaptor - Developer’s Guide | 45

© 2024 WiseTech Global 11 March 2024
2.5.1.2 Components
Each component of this interface sends its own distinctive schema of XML, which the interface
uses to identify which component you want to use. More complete information is available in the
chapter for each component in the document following.

• Universal Shipment Query – Query to have any current job in CargoWise returned as
Universal Shipment XML.
• Universal Document Query – Query to extract eDocs (electronically archived documents)
stored against any current job in CargoWise Returns Universal Event XML, including all
matching documents as base64 encoded binary content.
• Universal Inbound Synchronous – Send in Universal Shipments and Events synchronously.
Returns the processing status and logs as Universal Events in the result.
• Universal Inbound Asynchronous - Send in Universal Shipments and Events
asynchronously, leaving the processing to occur from the EDI Message Queue. The result
confirms that the inbound XML is in the processing queue. Processing results can
optionally be returned via the eAdaptor SOAP Outbound channel.
• Universal Accounting Transaction Batch Export – Create and/or Export Accounting
Transaction Batches. Used by those who want to feed Accounting Transactions generated
in CargoWise into an external accounting or analysis engine.
• Universal Interchange Requeue Component - Using the eAdaptor HTTP+XML web service
interface, you can bulk resubmit EDI Interchanges for sending out via the eAdaptor
Outbound web service interface.

Universal Events can contain eDocs as part of their payload which means that Universal
Inbound can process inbound eDocs as well.

2.5.1.3

2.5.1.4 XSD Schemas for All eAdaptor Messages

You can generate and save a complete set of XSD schemas for your current version of CargoWise
by navigating to the Maintain > System > EDI Messages module, then selecting Save Universal +
Native XML Schemas. This process is covered in more detail in Section 3.1 Obtaining Current XML
Schemas.

eAdaptor - Developer’s Guide | 46

© 2024 WiseTech Global 11 March 2024
2.5.2 Implementing the HTTP/HTTPS Connection
2.5.2.1 Obtaining and Testing your URL
Once you have covered the steps outlined in Section 2.3 Getting Setup to use our Interfaces, you
will have the URL for your eAdaptor SOAP connection as a result. If everything is set up correctly,
this should be entered in your CargoWise registry under eServices > eAdaptor > Inbound >
Service URL as shown below.

Figure 32 Registry setting eAdaptor > Inbound > Service URL

If there is nothing in this registry item, please raise a CR9 eRequest to have this setup or to
provide your URL. If your URL is present, you can work out what your eAdaptor HTTP+XML web
service URL is by removing the file name from the end of the eAdaptor SOAP URL (everything to
the right of the last ‘/’) and adding the suffix eAdaptor. This means that for the example shown
above:

https://***tstservices.wisegrid.net/eAdapterStreamedService.svc

…becomes:

https://***tstservices.wisegrid.net/eAdaptor

In this example “***” correlates to your enterprise code, if using WiseCloud hosted eAdaptor.

For hosted customers, the webservice endpoint exposed using HTTPS and the minimum TLS
version required to connect is TLS v1.2.

eAdaptor - Developer’s Guide | 47

© 2024 WiseTech Global 11 March 2024
You will also need the Username and Password from the registry item eServices > eAdaptor >
Inbound > Basic Authentication. The SOAP and HTTP+XML web service interfaces share the
same username and password.

If you change the username and password, you will need to update all clients connecting via
both interfaces where applicable. You will also need to have the Web Services restarted if
you want an immediate effect when these are changed, as the values are cached for a period
of time.

Once you have your URL, username, and password, you can test them by entering the URL into
the address bar of your favorite browser. If the web service is correctly configured, you will be
asked for a username and password. If you enter these correctly, you will see a simple landing
page as per below:

Figure 33 eAdaptor WebService Landing Page

The landing page will have documentation added to it in future releases.

You have now verified that you have the web service setup correctly and that you have the
correct URL, Username, and Password. The next step is to try sending a query using the Sample
Client.

2.5.2.2 Using the Sample Client

The HTTP+XML Sample Client is provided as a ZIP file and includes a sample client with C#
source code that you can build and modify using Microsoft Visual Studio 2013 and above. You
can download a free copy of this for evaluation purposes from Microsoft if you do not have a
licensee and use other development tools currently. If you don’t plan to continue using it, you can
uninstall Visual Studio when you are done.

You may also want to download and install Fiddler from Telerik. (http://www.telerik.com/fiddler)
This is a free tool that will allow you to see the web traffic as it occurs. A very handy way to see
what is happening at the HTTP level and essential if you plan to implement your client using
something other than Microsoft .NET.

Once Visual Studio is installed, unzip the HTTP+XML Sample Client ZIP file to an appropriate
location. Once you have it unzipped, double click on HTTP+XML Sample Client.sln to open.

eAdaptor - Developer’s Guide | 48

There is very little code in the Sample Client itself. You can use this code as a sample for your
own connectivity solution, or you can use it to understand how the HTTP+XML interface works at
a lower level using Fiddler to implement it in another environment.

If you press the F5 key (or click on the Start button on the toolbar), the client will start.

Figure 35 eAdaptor Test Client

eAdaptor - Developer’s Guide | 49

© 2024 WiseTech Global 11 March 2024
The UI has the connection details at the top along with an option for turning on and off
compression, then a large text box at the top for the sent message, a Post button, and a large
text box at the bottom where the session log will show. Every time you click on the Post button,
session log is cleared, the message at the top is sent, and the progress is then shown as it occurs
in the session log text box.

You can switch between HTTP and HTTPS by simply changing the URL prefix. Authentication is
HTTP Basic Authentication, so there is no need to pre-share certificates out of the box.

You can turn compression on and off for response messages using the check box provided at the
top of the form. That will allow you to see what compressed responses look like using Fiddler.
Note that the compression used in the Sample Client is GZIP, although some other alternatives
are available by modifying the code depending on what the web server you are using supports.

This is all part of the standard HTTP protocol; our software supports whatever HTTP and your web
server support in this area. Keep in mind that it may be more efficient not to use compression
when you know the request and response are going to be small.

You will note that there is a default sample UniversalShipmentRequest message present in the
sample client. If you have a Forwarding Consol in your system with the number C00001000 as
most CargoWise users will, this query will return the content of that Consol as UniversalShipment
XML.

More information on how to use the UniversalShipmentRequest follows in a later section; for now,
enter your eAdaptor URL, username, and password in the appropriate spaces and click on Post. If
there is no Consol present with that reference, you will see a UniversalResponse XML message
coming back like this:

eAdaptor - Developer’s Guide | 50

The status is ERR for Error, and the ProcessingLog indicates that a matching entity could not
be found, and there is nothing in the Data element.

If the Consol is present in the system your query, you will get a UniversalResponse with a status
containing PRS for Processed Ok, the ProcessingLog will be empty, and the Data element will
contain UniversalShipment XML representing that Consol.

There are more complicated ways you can use the UniversalShipmentRequest, and there are
other XML requests you can send. These are documented in the following sections: this section
deals with the connection only. Any XML that is not recognized will generate an error response
telling you what forms of requests are supported by your system.

eAdaptor - Developer’s Guide | 51

© 2024 WiseTech Global 11 March 2024
2.5.2.3 Implementing your connection
With the information and sample client provided above, you can run Fiddler while using the
Sample Client to see what happens at the transport layer. The XML entered in the sample client is
sent in an HTTP POST message, and the response showing in the Response Body section at the
bottom of the sample client is returned in the HTTP response.

With that information in hand, it is up to you as a Senior Web Services Developer to select the
tool that works best with your application and develop your connection from there. Once the
Connection is working, the content you can send and receive for each Component available
through this interface is described in the following chapters.

2.5.3 Universal Shipment query component

To use the Universal Shipment Request component, you send a UniversalShipmentRequest XML
message and expect a UniversalResponse XML message in return. The UniversalResponse will
either contain the requested UniversalShipment or a failure status and a reason why a
UniversalShipment could not be returned.

2.5.3.1 UniversalShipmentRequest
The UniversalShipmentRequest is designed to query for and return a single UniversalShipment
matching the parameters enclosed in the message. Every module that supports exporting
UniversalShipment XML works with the UniversalShipmentRequest interface.

Each ‘well formed’ UniversalShipmentRequest sent (opening and closing tags matching/present
and no mandatory elements missing) will get a UniversalResponse XML back.

Following is a sample query for a Customs Declaration:

<UniversalShipmentRequest xmlns="http://www.cargowise.com/Schemas/Universal/2011/11" version="1.1">
<ShipmentRequest>
<DataContext>
<DataTargetCollection>
<DataTarget>
<Type>CustomsDeclaration</Type>
<Key>B00001000</Key>
</DataTarget>
</DataTargetCollection>

The UniversalShipmentRequest content is used to Target a particular data source entity in a

particular module which is then used to generate the Universal Shipment XML that is returned.

eAdaptor - Developer’s Guide | 52

The following content is used to target a particular data source entity:

• DataTarget Type and Key

The DataTarget Type (CustomsDeclaration) determines which module you want to retrieve the
data from. The DataTarget Type is mandatory. If you do not include it, you will get an Entity Not
Found result no matter what else you include.
The DataTarget Key identifies the job or entity within the module you are querying. Each module
has a designated Key field of fields that uniquely identify rows within that module, usually a job
number like the Shipment, Consol, and Declaration Numbers.
The DataTarget Type and Key contain, the same values you see in the DataSource of a
UniversalShipment or UniversalEvent exported from any module supporting the
UniversalShipmentRequest.
• EnterpriseID, ServerID and Company Code
Some modules like Customs are Company Specific in that each job is tied to a particular
Company. For those modules, you will need to provide the EnterpriseID, ServerID, and Company
Code elements to identify the Company you are querying from. If you do not provide this
information where it is required, you will get an Entity Not Found response. Most Customs
modules are Company specific which is also how they are linked to a given Country (as each
company is tied to a country).
Where a module is not Company Specific (like Forwarding Consol or Forwarding Shipment), you
can still send the EnterpriseID, ServerID, and Company Code where known. This will not affect
which entity is returned, but it will affect the filtering of content that is Company Specific, like Job
Costing or Billing information. If you are not using these sections of the returned XML, you do not
need to provide these elements in the query.
You can tell if a module is Company Specific or not by logging into the same system under two
different companies. If you can see the same set of jobs in a given module, it is not Company
Specific.

Demo Companies can be used to send messages within CargoWise. However, when sending
data externally Demo Companies cannot be used. For more information on Demo Companies
refer to What is the purpose of the Demo Company?

eAdaptor - Developer’s Guide | 53

At this point, only querying by DataTarget Key in the DataContext is implemented. In upcoming
releases. The DataTarget Key will become optional, and queries by other references will be
possible. This is planned to be done using the Reference and Party ID matching facility already
available when importing Universal Shipment XML.

This works by following the premise that References issued by a given Party are globally unique
where you can identify the issuing Party. This means that you can query by things like House Bill
number where you can identify the Issuing (Sending) Forwarder, and query by Order Number
where you can identify the Buyer.

Each module has a list of Reference and Party ID pairs that are known to be good identifiers in
that module’s context. Examples in use right now are:

Forwarding Consol

Master Bill + Shipping Line

Booking Reference + Shipping Line

Agent’s Reference + Sending Forwarder

Agent’s Reference + Receiving Forwarder

Forwarding Shipment

House Bill + Sending Forwarder

Interim Receipt + Consignor

Booking Reference + Consignor

Booking Reference + Consignee

Customs Declaration

Owner’s Reference + Consignor

Owner’s Reference + Consignee

This set will be added to as required where truly unique references can be identified for each
module.

eAdaptor - Developer’s Guide | 54

Each ‘well formed’ UniversalShipmentRequest sent with opening and closing tags
matching/present and no mandatory elements missing will get a UniversalResponse XML back.
The UniversalResponse contains:

• Status - Either ERR for Error or PRS for Processed Ok

• ProcessingLog - Contains Errors and Warnings that were detected during processing of the
sent query. Even for Processed Ok there may be warnings regarding processing the
content of the incoming query XML. (e.g., Over length element values being truncated on
import)
• Data - When the status is Processed Ok, contains the resulting UniversalShipment XML.

Following is a sample of what you would expect to see in the HTTP+XML Sample Client on a
successful query:
Posting...
Begin POST to https://xxxtstservices.wisegrid.net/eAdaptor
<<<------------------------------------------------- Begin Message Body ----------------------
--------------------------->>>
<UniversalShipmentRequest xmlns="http://www.cargowise.com/Schemas/Universal/2011/11" version="1.1">
<ShipmentRequest>
<DataContext>
<DataTargetCollection>
<DataTarget>
<Type>ForwardingConsol</Type>
<Key>C00001000</Key>
</DataTarget>
</DataTargetCollection>

Waiting Response...

Response Received, Status:- 200 - OK

<<<------------------------------------------------- Be.g.in Response Body -------------------
------------------------------>>>
<?xml version="1.0" encoding="utf-8"?>
<UniversalResponse xmlns="http://www.cargowise.com/Schemas/Universal/2011/11" version="1.1">
<Status>PRS</Status>
<Data><UniversalShipment xmlns="http://www.cargowise.com/Schemas/Universal/2011/11" version="1.1">
<Shipment>
<DataContext>
<DataSourceCollection>
<DataSource>
<Type>ForwardingConsol</Type>
<Key>C00001000</Key>
</DataSource>
</DataSourceCollection>
... Content Removed for Brevity...
</DataContext>

eAdaptor - Developer’s Guide | 55

© 2024 WiseTech Global 11 March 2024
<AWBServiceLevel>
<Code>STD</Code>
<Description>Standard</Description>
</AWBServiceLevel>
<BookingConfirmationReference></BookingConfirmationReference>
<ChargeableRate>0.0000</ChargeableRate>
<ContainerCount>1</ContainerCount>
... Content Removed for Brevity ...
<TransportMode>Sea</TransportMode>
<VesselLloydsIMO>9159646</VesselLloydsIMO>
<VesselName>BUNGA TERATAI 3</VesselName>
<VoyageFlightNo>343</VoyageFlightNo>
</TransportLeg.>
</TransportLegCollection>
</Shipment>
</UniversalShipment>
</Data>
<ProcessingLog />
</UniversalResponse>
<<<-------------------------------------------------- End Response Body ----------------------
---------------------------->>>

HTTP POST Complete.

Using the Universal Document Request

Each ‘well formed’ UniversalShipmentRequest sent (opening and closing tags matching/present
and no mandatory elements missing) will get a UniversalResponse XML back.

A malformed request will return an HTTP ‘400-Bad Request’ response with nothing in the body.

2.5.4 Universal Document Query Component

The Universal Document Query Component allows you to retrieve documents from jobs by
sending a UniversalDocumentRequest XML. A UniversalResponse XML will be sent in return,
containing the requested documents as base64 encoded binary content inside a Universal Event.
In the case of failures to retrieve the documents a failure status and reason will be provided in
place of the requested documents.

2.5.4.1 UniversalDocumentRequest
The UniversalDocumentRequest is designed to query for and return documents via a
UniversalEvent containing documents matching the parameters and filters enclosed in the
message. Every module that supports exporting UniversalEvent XML works with the
UniversalDocumentRequest interface. Additionally it is possible to retrieve documents from the
eDocs tab across modules using <DataTarget> as ‘DocManager’ and <DataTarget> key as ‘Module
code Job number’

Each ‘well formed’ UniversalDocumentRequest sent (opening and closing tags matching/present
and no mandatory elements missing) will get a UniversalResponse XML back.

The UniversalDocumentRequest has two main sections, the DataContext and the FilterCollection.
Information from the DataContext is used to Target a particular data source entity or job in a
particular module. The eDocs against that job is then queried using information in the

eAdaptor - Developer’s Guide | 56

© 2024 WiseTech Global 11 March 2024
FilterCollection and any eDocs matching all of the supplied Filters are returned in the resulting
Universal Event XML.

Following is a sample query/request for all documents with a document type of ARN from
Customs Declaration B00001000:
<UniversalDocumentRequest xmlns="http://www.cargowise.com/Schemas/Universal/2011/11" version="1.1">
<DocumentRequest>
<DataContext>
<DataTargetCollection>
<DataTarget>
<Type>CustomsDeclaration</Type>
<Key>B00001000</Key>
</DataTarget>
</DataTargetCollection>
<Company>
<Code>CWI</Code>
</Company>
<EnterpriseID>WTG</EnterpriseID>
<ServerID>SYD</ServerID>
</DataContext>
<ReturnDocumentDescriptionsOnly>true</ReturnDocumentDescriptionsOnly>
<FilterCollection>
<Filter>
<Type>DocumentType</Type>
<Value>ARN</Value>
</Filter>
</FilterCollection>
</DocumentRequest>
</UniversalDocumentRequest>

Below is a sample query/request for documents in the Product Warehouse module using the
<DataTarget> type of ‘DocManager’:
UniversalDocumentRequest xmlns="http://www.cargowise.com/Schemas/Universal/2011/11" version="1.1">
<DocumentRequest>
<DataContext>
<DataTargetCollection>
<DataTarget>
<Type>DocManager</Type>
<Key>WTD W000027944</Key>
</DataTarget>
</DataTargetCollection>
<Company>
<Code>CWI</Code>
</Company>
<EnterpriseID>WTG</EnterpriseID>
<ServerID>SYD</ServerID>
</DataContext>
</DocumentRequest>
</UniversalDocumentRequest>

For more information on <DataTarget> type of ‘DocManager’ refer to Enhancement for

eDocs document retrieval using UniversalDocumentQuery

eAdaptor - Developer’s Guide | 57

The following content is used to target a particular data source entity:

• DataTarget Type

The DataTarget Type is used to determine which module you want to retrieve the data
from. The DataTarget Type is mandatory. If you do not include it, you will get an Entity Not
Found result no matter what else you include.

• DataTarget Key

The DataTarget Key is used to identify the job or entity within the module you are
querying. Each module has a designated Key field of fields that uniquely identify rows
within that module, usually a job number like the Shipment, Consol and Declaration
Numbers.

The DataTarget Type and Key contains the same values you see in the DataSource of a
UniversalShipment or UniversalEvent exported from any module supporting the
UniversalShipmentQuery.

An example of these two fields can be seen in the below extract:

<DataTargetCollection>
<DataTarget>
<Type>CustomsDeclaration</Type>
<Key>B00001000</Key>
</DataTarget>
</DataTargetCollection>

EnterpriseID, ServerID and Company Code

Some modules like Customs are ‘Company Specific’ in that each job is tied to a particular
Company. For those modules, you will need to provide the EnterpriseID, ServerID and Company
Code elements to identify the Company you are querying from. If you do not provide this
information where it is required, you will get an Entity Not Found response. Most Customs
modules are Company specific which is also how they are linked to a given Country. (As each
company is tied to a country)

Where a module is not ‘Company Specific’ (like Forwarding Consol or Forwarding Shipment), you
can still send the EnterpriseID, ServerID and Company Code where known. This will not affect
which entity is returned, but it will affect filtering of content that is Company Specific like Job
Costing or Billing information. If you are not using these sections of the returned XML, you do not
need to provide these elements in the query.

You can tell if a module is ‘Company Specific’ or not by logging into the same system under two
different companies. If you can see the same set of jobs in a given module, it is not Company
Specific.

eAdaptor - Developer’s Guide | 58

The FilterCollection is an optional section that you use when you want to return only some of the
eDocs present on a given Job/Entity. If the FilterCollection is not included or contains no
elements, all eDocs from the matching parent Job/Entity will be returned.

Each Filter element contains two sub elements, Type to indicate what type of filter to and Value
to provide the value that filter is going to use. Where a Filter is not included for any given type,
the default behavior is to return all eDocs. This means that for a filter like CompanyCode, default
behavior when this type is not specified is to return all documents regardless of company
affiliation.

Where multiple filter elements are provided with the same Type, these are treated as an ‘Or’ style
filter so any document matching any of the values presented will be returned. Filter elements
with different Types are treated as an ‘And’ style filter where all values must match on eDocs
being returned.

Some filters only work with one per request, these are noted in the definitions following.

Filter types available are:

DocumentType – Retrieve only documents matching the specified document type.

IsPublished – Retrieve only published or un-published documents. Possible values for this filter
are: True and False. This can only be specified once.

SaveDateUTCFrom – Retrieve only documents that were added or modified on or after the
specified date/time (provided in UTC time). This can only be specified once.

SaveDateUTCTo – Retrieve only documents that were added or modified on or before the
specified date/time (provided in UTC time). This can only be specified once.

CompanyCode – Retrieve only documents related to the specified company or non-company

specific. The default behavior without this Type being filtered is to return all documents
regardless of company affiliation.

BranchCode – Retrieve only documents related to the specified branch code.

DepartmentCode – Retrieve only documents relevant to specified department code.

FileName – Retrieve only document matching with the specified File Name.

DocumentID – Retrieve only document matching with specified DocumentID (Primary Key –
GUID).

Related eDocs – Retrieve documents attached any Related eDocs which are specified. For
example, it will return the eDocs under the related CustomsEntry of a Declaration in addition to
the eDocs in the Declaration itself.

Refer to Documents attached on Related eDocs can now be retrieved via a

UniversalDocumentRequest update note for more information about how to use the
related eDocs filter.

eAdaptor - Developer’s Guide | 59

© 2024 WiseTech Global 11 March 2024
Additionally, list of eDocs files can be fetched using below request element for all (or filtered)
eDocs on a job without bulky content.

DocumentID will be now provided with response message for UniversalDocumentRequest

and as well from Document related Events (i.e., DDI, DDR, DDD, etc)

Sample Filters
• Using filter: FileName
<FilterCollection>
<Filter>
<Type>FileName</Type>
<Value>sample file.docx</Value>
</Filter>
</FilterCollection>

• Using filter: DocumentID

<FilterCollection>
<Filter>
<Type>DocumentID</Type>
<Value>BDF6A934-304B-49B6-B9C6-A88E91FF093A</Value>
</Filter>
</FilterCollection>

• Using filter: RelatedEDoc

<FilterCollection>
<Filter>
<Type>RelatedEDoc</Type>
<Value>Customs Entry*</Value>
</Filter>
</FilterCollection>

Sample Request XML

<UniversalDocumentRequest xmlns="http://www.cargowise.com/Schemas/Universal/2011/11" version="1.1">

<DocumentRequest>
<DataContext>
<DataTargetCollection>
<DataTarget>
<Type>CustomsDeclaration</Type>
<Key>B00001000</Key>
</DataTarget>
</DataTargetCollection>

<FilterCollection>
<Filter>
<Type>DocumentID</Type>
<Value>BDF6A934-304B-49B6-B9C6-A88E91FF093A</Value>
</Filter>
</FilterCollection>
</DocumentRequest>
</UniversalDocumentRequest>

eAdaptor - Developer’s Guide | 60

Example filters – multiple filters in one filter collection: Only return document type is ‘ARN’ And
file name is ‘sample file.docx’ Or ‘sample file 2.docx’

<FilterCollection>
<Filter>
<Type>FileName</Type>
<Value>sample file.docx</Value>
</Filter>
<Filter>
<Type>FileName</Type>
<Value>sample file 2.docx</Value>
</Filter>
<Filter>
<TYpe>DocumentType</Type>
<Value>ARN</Value>
</Filter>
</F1ilterCollection>

2.5.4.2 UniversalResponse
Each ‘well formed’ UniversalDocumentRequest sent with opening and closing tags
matching/present and no mandatory elements missing will get a UniversalResponse XML back.
The UniversalResponse contains:

Status - Either ERR for Error or PRS for Processed Ok

ProcessingLog - Contains Errors and Warnings that were detected during processing of the sent
query. Even for Processed Ok there may be warnings regarding processing the content of the
incoming query XML (e.g., Over length element values being truncated on import)

Data - When the status is Processed Ok, contains the resulting UniversalEvent XML

Following is a sample of what would come back from the sample UniversalDocumentRequest
shown earlier in this section assuming there was a matching Customs Declaration, and that
entity/job had an eDoc attached with a Document Type of ARN:

eAdaptor - Developer’s Guide | 61

© 2024 WiseTech Global 11 March 2024
<UniversalResponse xmlns="http://www.cargowise.com/Schemas/Universal/2011/11" version="1.1">
<Status>PRS</Status>
<ProcessingLog />
<Data>
<UniversalEvent xmlns="http://www.cargowise.com/Schemas/Universal/2011/11" version="1.1">
<Event>
<DataContext>
<DataSourceCollection>
<DataSource>
<Type>CustomsDeclaration</Type>
<Key>B00001000</Key>
</DataSource>
</DataSourceCollection>
<Company>
<Code>CWI</Code>
</Company>
<EnterpriseID>WTG</EnterpriseID>
<ServerID>SYD</ServerID>
</DataContext>
<EventTime>2016-06-08T09:48:13</EventTime>
<EventType>DEX</EventType>
<IsEstimate>false</IsEstimate>
<ContextCollection>
<Context>
<Type>HBOLNumber</Type>
<Value>HB432178972345</Value>
</Context>
</ContextCollection>
<AttachedDocumentCollection>
<AttachedDocument>
<FileName>ArrivalNotice.pdf</FileName>
<DocumentID>99129579-eb3f-4756-a281-cea4b7b493f3</DocumentID>
<FileSizeInBytes>957</FileSizeInBytes>
<ImageData>JVBERi0xLjQKJ --- base64 encoded binary stream --- kKJSVFT0YK</ImageData>
<Type>
<Code>ARN</Code>
<Description>Arrival Notice</Description>
</Type>
<IsPublished>true</IsPublished>
<SaveDateUTC>2022-12-07T03:11:00</SaveDateUTC>
<SavedBy>
<Code>WTG</Code>
<Name>CargoWise Support</Name>
</SavedBy>
<Source>
<Code></Code>
<Description></Description>
</Source>
<VisibleBranchCode></VisibleBranchCode>
<VisibleCompanyCode></VisibleCompanyCode>
<VisibleDepartmentCode></VisibleDepartmentCode>
</AttachedDocument>
</AttachedDocumentCollection>
</Event>
</UniversalEvent>
</Data>
</UniversalResponse>

eAdaptor - Developer’s Guide | 62

FileName – Name of this document File.

DocumentID – Primary Key of this document – GUID.

FileSizeInBytes - File Size in Bytes of this document.

ImageData - Document contains as a base64 encoded binary stream. The sample above was
truncated for brevity.

Type - Document type

IsPublished – “True” if published or “False” – for an un-published documents.

SaveDateUTC – UTC time when this document gets saved in CW1

SavedBy – User <Code> and <Name> who saved this document.

Source – The source of the Document <Code> and <Description>

VisibleBranchCode / VisibleCompanyCode / VisibleDepartmentCode - Return the Branch /

Company/Department code if the visibility is set to specific Branch / Company / Department.

The <ImageData> element will not be returned if <ReturnDocumentDescriptionsOnly> filter is set to

“True”

If there is a failure matching to a parent entity/job using information from the requested
DataContext, or no eDocs are found matching the filters specified, you will get a
UniversalResponse back with a status of ERR for Error and a reason in the Processing Log like so:
<UniversalResponse xmlns="http://www.cargowise.com/Schemas/Universal/2011/11" version="1.1">
<Status>ERR</Status>
<ProcessingLog>
CustomsDeclaration B00001000 was found, but no eDocs were found matching the filters specified.
</ProcessingLog>
<Data />
</UniversalResponse>

A malformed request will return an HTTP ‘400-Bad Request’ response with nothing in the body.

eAdaptor - Developer’s Guide | 63

© 2024 WiseTech Global 11 March 2024
2.5.5 Universal Inbound Synchronous Component
The Universal Inbound Synchronous Component accepts incoming Universal Shipments,
Activities, or Events, processes then publishes the XML through CargoWise and returns the
processing result as Universal Events wrapped in UniversalResult XML.

This is a direct path to the Universal Data Buss. This can publish Universal XML to all operational
modules within CargoWise.

There is no EDI Interchange, EDI Message, or any Service Tasks involved in processing in this
manner. Although this is a direct, light, and efficient channel by its very nature, keep in mind that
you will need to manage data processing, logging, and reprocessing within your own
Middleware/ESB.

This section covers the transport layer with one sample coming in and samples of the
possible responses that might come back in the UniversalResult XML. It does not contain in-
depth information on all of the possible forms and uses of Universal Shipment and Event XML.
Detailed information about these, their usage and their capabilities are available in the
Universal Shipment and Universal Event sections of this document. If you are already using
the eAdaptor SOAP interface, this channel accepts and processes the same content minus
the Universal Interchange XML wrapper.

2.5.5.1 Submitting Universal XML

The schemas that are processed via this Component are the Universal Shipment, Universal
Activity, and Universal Event. XSD Schemas of all messages used are available from within
CargoWise.

Following is a sample XML file that will add a small text file as a PreAlert document to the eDocs
tab of Forwarding Shipment S00001000 if that job exists in the target system.
<UniversalEvent xmlns="http://www.cargowise.com/Schemas/Universal/2011/11" version="1.1">
<Event>
<DataContext>
<DataTargetCollection>
<DataTarget>
<Type>ForwardingShipment</Type>
<Key>S00001000</Key>
</DataTarget>
</DataTargetCollection>
<EnterpriseID>WTG</EnterpriseID>
<ServerID>SYD</ServerID>
<Company>
<Code>CWI</Code>
</Company>
</DataContext>
<EventTime>2016-06-09T12:32:12.42</EventTime>
<EventType>DDI</EventType>
<EventReference>PAL</EventReference>
<IsEstimate>false</IsEstimate>
<AttachedDocumentCollection>
<AttachedDocument>
<FileName>Tiny PreAlert.txt</FileName>
<ImageData>SGV5ISBXYWtlIFVwIQ==</ImageData>
<Type>

eAdaptor - Developer’s Guide | 64

© 2024 WiseTech Global 11 March 2024
<Code>PAL</Code>
<Description>Pre Alert</Description>
</Type>
<IsPublished>true</IsPublished>
</AttachedDocument>
</AttachedDocumentCollection>
</Event>
</UniversalEvent>

To use this sample in your own testing, you would need to make sure that there was an ‘Active’
Forwarding Shipment present in the target system with the Shipment Number S00001000, or
you could change the DataTarget Key to match another Shipment. You will also need to make
sure that the EnterpriseID, ServerID and Company Code match the registered values in the
system you are testing.

For more information on how to target entities using Universal XML, please see Section 5.1.5
DataContext when Importing XML

2.5.5.2 UniversalResponse
Each ‘well formed’ UniversalShipment or UniversalEvent XML sent with opening and closing tags
matching/present and no mandatory elements missing will get a UniversalResponse XML back.
The UniversalResponse contains:

• Status - Either ERR for Error or PRS for Processed Ok

• ProcessingLog - Contains Errors and Warnings that were detected during processing of
the sent query. Even for Processed Ok there may be warnings regarding processing the
content of the incoming query XML (e.g., Over length element values being truncated on
import)
• Data - When the status is Processed Ok, will contain the resulting UniversalEvent XML

eAdaptor - Developer’s Guide | 65

Following is a sample of what would come back from the sample UniversalEvent XML shown
earlier in this section assuming there was a matching Forwarding Shipment present in the target
system, and the EnterpriseID, ServerID and Company Code all match the registration of the target
system:
<UniversalResponse xmlns="http://www.cargowise.com/Schemas/Universal/2011/11" version="1.1">
<Status>PRS</Status>
<ProcessingLog />
<Data>
<UniversalEvent xmlns="http://www.cargowise.com/Schemas/Universal/2011/11" version="1.1">
<Event>
<DataContext>
<DataSourceCollection>
<DataSource>
<Type>ForwardingShipment</Type>
<Key>S00001000</Key>
</DataSource>
</DataSourceCollection>

<Company>
<Code>CWI</Code>
</Company>
<EnterpriseID>WTG</EnterpriseID>
<ServerID>SYD</ServerID>
</DataContext>
<EventTime>2016-06-08T09:48:13</EventTime>
<EventType>DIM</EventType>
<IsEstimate>false</IsEstimate>
<ContextCollection>
<Context>
<Type>HBOLNumber</Type>
<Value>HB432178972345</Value>
</Context>
</ContextCollection>
</Event>
</UniversalEvent>
</Data>
</UniversalResponse>

You can see that the Status element is shown as PRS (Processed Ok) and the EventType element
in the Universal Events is set to DIM (Data Imported). The combination of these two elements
needs to be checked to indicate complete success.

You will also see that the DataSourceCollection will contain the DataSource Type and Key
identifying the entity/job that was updated using the incoming data. The ContextCollection will
contain supplementary references from the entity/job being updated that can be used as
alternate references if required.

The Data element in the UniversalResponse may contain multiple UniversalEvents if multiple
modules elect to consume the Universal Event you sent in. This is because incoming
Universal XML is published to all modules in parallel via the Universal Data Buss. More
information is available on the Universal Data Buss in Section 5.3 Receiving Universal XML.

2.5.5.2.2 Failure Response (Business Failure)

eAdaptor - Developer’s Guide | 66

© 2024 WiseTech Global 11 March 2024
These occur when the content of the XML is recognized and parseable, but the data supplied is
not able to be used for a variety of Business reasons. Examples of this include the targeted
entity/job not existing (no references match), or the targeted entity/job exists, but is marked
‘InActive’ and cannot be updated, or there is mandatory information missing from the data that
was defined in the business layer, not the message syntax layer.

The Status on the UniversalResponse will still show PRS (Processed OK) as a status code as the
message was successfully parsed and passed Message level validation. The Universal Event
contained in the Data element will have an EventType of DIF (Data Import Failure) and in the
ContextCollection you will see a Context element with a Type of FailureReason and a Value
containing a human readable explanation of the Business validation failure.

Unlike the Success response, there will not be a DataSourceCollection where no matching
entity/job was found. Following is a sample where the references supplied did not match any
entity/job in any module:

<UniversalResponse xmlns="http://www.cargowise.com/Schemas/Universal/2011/11" version="1.1">

<Status>PRS</Status>
<ProcessingLog />
<Data>
<UniversalEvent xmlns="http://www.cargowise.com/Schemas/Universal/2011/11" version="1.1">
<Event>
<DataContext>
<Company>
<Code>CWI</Code>
</Company>
<EnterpriseID>WTG</EnterpriseID>
<ServerID>SYD</ServerID>
</DataContext>
<EventTime>2016-06-08T10:42:13</EventTime>
<EventType>DIF</EventType>
<IsEstimate>false</IsEstimate>
<ContextCollection>
<Context>
<Type>FailureReason</Type>
<Value>
No Module found a Business Entity to link this Universal Event to.
Message Discarded.
</Value>
</Context>
</ContextCollection>
</Event>
</UniversalEvent>
</Data>
</UniversalResponse>

eAdaptor - Developer’s Guide | 67

These occur when the content of the XML is not processable as sections defined as mandatory
in the XSD are missing or contain invalid data.

There is no UniversalEvent present in the Data element as the UniversalEvent part of the
response is only generated when the XML is able to be published on the Universal Data Buss.

Following is a sample where the EventType element was not included on an inbound Universal
Event message:
<UniversalResponse xmlns="http://www.cargowise.com/Schemas/Universal/2011/11" version="1.1">
<Status>ERR</Status>
<ProcessingLog>
Error - Missing mandatory element [EventType] at root level.
</ProcessingLog>
<Data />
</UniversalResponse>

A malformed request (invalid characters/malformed/non-XML content) will return an HTTP ‘400-

Bad Request’ response with nothing in the body.

2.5.6 Universal Inbound Asynchronous Component

This functionality is proposed future functionality. Content here is the current design
specification for this functionality published to give an indication of what we have planned.
This content is updated weekly; functionality may change before final delivery.

This component provides the same functionality available via the eAdaptor SOAP Inbound web
service, but as a RESTful web service without the need to use SOAP. This means you can use this
to queue the content of a Universal Interchange in the EDI Interchange and EDI Message modules
for processing using the UMI and NMI service tasks.

This is intended for use with any interface where you do not need the processing result back
immediately and would rather that your client application be able to continue on processing
items instead of waiting for the full import to proceed.

To use this component, you can send in either Universal or Native XML wrapped in
UniversalInterchange XML. The fact that your Universal or Native XML payload is wrapped in a
UniversalInterchange tells our application that you would like to have this processed via the
asynchronous channel. The UniversalInterchange XML will be stored in an EDI Interchange, and
assuming the content of the interchange is recognized it will be immediately split out into EDI
Messages.

Once the EDI Messages have been created, a UniversalResponse will be returned with a success
status. If the content is syntactically correct XML but the message content is not present,
recognized, or parseable, a Universal Response will be returned with a failure status and a
message indicating what the cause of the failure was. All other forms of malformed request will
return an HTTP ‘400-Bad Request’ response with nothing in the body.

eAdaptor - Developer’s Guide | 68

© 2024 WiseTech Global 11 March 2024
Screen shots and samples will be provided when this functionality becomes Work in
Progress.

2.5.7 Universal Accounting Transaction Batch Export

Component
The Universal Accounting Transaction Batch interface is a web service-based interface that
allows users of CargoWise to integrate with an external accounting system. This interface allows
you to make requests to ‘Create’ accounting batches, ‘Export’ accounting batches and a new
composite request to ‘Create And Export’ accounting batches.

All messages are processed through the eAdaptor HTTP+XML web service. The HTTP protocol is
used to POST an XML based ‘Request’ message, and an XML based ‘Response’ message is
returned as the result.

This development is an extension to existing web services used to create and extract accounting
transaction batches and integrates the accounting web services functionality into the new
eAdaptor HTTP+XML web service.

This integration usually involves middleware software that prompts CargoWise to batch
transactions that have not yet been batched and retrieve transactions for a given batch number.

It includes all accounting transactions posted in CargoWise and all general ledger effects caused
by those transactions.

2.5.7.1 UniversalTransactionBatchRequest
The UniversalTransactionBatchRequest message format is used to request the creation of
accounting batches, the export of accounting batches, and a composite message type that both
creates and exports an accounting batch.

All three types of requests contain a DataContext to establish the context in which your request
is being made, and an ActionType element describing the action being requested. The
ActionType contains a single Code element, following are the accepted values:

• CRE – Create Batch – This action will create accounting batch database records. The
response to this message type will contain an empty TransactionCollection node.
• EXP - Export Batch– This action will generate the accounting transaction batch XML and
include it in the Data node of the response. The response to the Export message will
contain the TransactionCollection node populated with the transactions in the requested
batch.
• CEX – Create And Export Batch – This action combines the Create and Export actions into
a single request. When the system receives a ‘CreateAndExport’ message, it will create the
accounting batch database records and generate the accounting transaction batch XML.
The response to the CreateAndExport message will contain the TransactionCollection node
populated with the transactions in the newly created batch.

eAdaptor - Developer’s Guide | 69

© 2024 WiseTech Global 11 March 2024
The DataContext element contains a number of sub elements that are used to identify the
registered Company you want to target for a given request, and when using the EXP (Export
Batch) ActionType must contain a single DataTarget element identifying the Batch Number you
would like to request.

2.5.7.1.1 Identifying the Company

To identify the target Company, you must include the EnterpriseID, ServerID, and Company.Code
elements as part of the DataContext. These three elements are mandatory for all
UniversalTransactionBatchRequests. You will need to make sure that the EnterpriseID, ServerID
and Company Code you provide match the registered values for a registered Company in the
target CargoWise system or your request will be rejected.

For more information on how to target entities using Universal XML, please see Section 5.1.5
DataContext when Importing XML

2.5.7.1.2 Identifying a Requested Batch

When you are using the EXP (Export Batch) ActionType Code, in addition to the Company
identification elements, you will also need to identify the batch number you are requesting. You
do this by including the DataTargetCollection with one DataTarget element. The DataTarget must
contain a Type of BatchNumber and include the batch number being requested in the Key
element as shown in sample following.
<UniversalTransactionBatchRequest xmlns="http://www.cargowise.com/Schemas/Universal/2011/11">
<TransactionBatchRequest>
<DataContext>
<DataTargetCollection>
<DataTarget>
<Type>BatchNumber</Type>
<Key>3</Key>
</DataTarget>
</DataTargetCollection>
<Company>
<Code>ABC</Code>
</Company>
<EnterpriseID>CW</EnterpriseID>
<ServerID>ENT</ServerID>
</DataContext>
<ActionType>
<Code>EXP</Code>
</ActionType>
</TransactionBatchRequest>
</UniversalTransactionBatchRequest>

For the other ActionType Codes, the DataTargetCollection is not required. Following is a sample
CRE (Create Batch) request.

eAdaptor - Developer’s Guide | 70

© 2024 WiseTech Global 11 March 2024
<UniversalTransactionBatchRequest xmlns="http://www.cargowise.com/Schemas/Universal/2011/11">
<TransactionBatchRequest>
<DataContext>
<Company>
<Code>ABC</Code>
</Company>
<EnterpriseID>CW</EnterpriseID>
<ServerID>ENT</ServerID>
</DataContext>
<ActionType>
<Code>CRE</Code>
</ActionType>
</TransactionBatchRequest>
</UniversalTransactionBatchRequest>

2.5.7.2 UniversalResponse
Each ‘well formed’ UniversalTransactionBatchRequest sent with opening and closing tags
matching/present and no mandatory elements missing will get a UniversalResponse XML back in
the body of the HTTP POST response with a 200 status. The UniversalResponse contains:

Status - Either ERR for Error or PRS for Processed Ok

Data - When Status is Processed Ok, contains the resulting UniversalTransactionBatch XML. Will
be empty if you get an Error status.

If there is a serious error attempting to interpret malformed or invalid XML to the eAdaptor
HTTP+XML web service, you may get a 500 status returned with an error message in the body of
the response.

eAdaptor - Developer’s Guide | 71

This will contain a UniversalResponse with a single UniversalTransactionBatch element in the Data
element with the elements required to identify the new Batch, but no Transactions as follows.
<UniversalResponse xmlns="http://www.cargowise.com/Schemas/Universal/2011/11">
<Status>PRS</Status>
<Data>
<UniversalTransactionBatch xmlns="http://www.cargowise.com/Schemas/Universal/2011/11">
<TransactionBatch>
<BatchType>
<Code>CRE</Code>
<Description>Transaction Batch Created</Description>
</BatchType>
<DataContext>
<DataSourceCollection>
<DataSource>
<Type>BatchNumber</Type>
<Key>2</Key>
</DataSource>
</DataSourceCollection>
<Company>
<Code>ABC</Code>
<Country>
<Code>ES</Code>
<Name>Spain</Name>
</Country>
<Name>ABC COMPANY</Name>
</Company>
<DataProvider>CWENTABC</DataProvider>
<EnterpriseID>CW</EnterpriseID>
<ServerID>ENT</ServerID>
</DataContext>
<TransactionCollection>
</TransactionCollection>
</TransactionBatch>
</UniversalTransactionBatch>
</Data>
<ProcessingLog>
New batch 2 is created
</ProcessingLog>
</UniversalResponse>

eAdaptor - Developer’s Guide | 72

This will contain the same information as the response to the CRE (Create Batch) request but will
also include the transactions on the TransactionCollection within the UniversalTransactionBatch.
<UniversalResponse xmlns="http://www.cargowise.com/Schemas/Universal/2011/11">
<Status>PRS</Status>
<Data>
<UniversalTransactionBatch xmlns="http://www.cargowise.com/Schemas/Universal/2011/11">
<TransactionBatch>
<BatchType>
<Code>CEX</Code>
<Description>Transaction Batch Created and Exported</Description>
</BatchType>
<DataContext>
<DataSourceCollection>
<DataSource>
<Type>BatchNumber</Type>
<Key>3</Key>
</DataSource>
</DataSourceCollection>
<Company>
<Code>ABC</Code>
<Country>
<Code>ES</Code>
<Name>Spain</Name>
</Country>
<Name>ABC COMPANY</Name>
</Company>
<DataProvider>CWENTABC</DataProvider>
<EnterpriseID>CW</EnterpriseID>
<ServerID>ENT</ServerID>
</DataContext>
<TransactionCollection>
<Transaction>
<Branch>
<Code>SPA</Code>
<Name>SPAIN BRANCH</Name>
</Branch>

<PostingAmount>847.4600</PostingAmount>
<PostingCurrency>
<Code>EUR</Code>
<Description>Euro</Description>
</PostingCurrency>
<PostingDate>2017-05-24T00:00:00</PostingDate>
</Transaction>
</TransactionCollection>
</TransactionBatch>
</UniversalTransactionBatch>
</Data>
<ProcessingLog>
New batch 3 is created and exported
</ProcessingLog>
</UniversalResponse>

eAdaptor - Developer’s Guide | 73

This will contain the same information as the CEX (Create and Export Batch).

2.5.7.3 Transitioning from direct web services to eAdaptor

HTTP+XML web service
Customers using these web services at the moment may be using web services specifically
configured for the Accounting Transaction Batch XML – for example, hosted customers may have
a URL similar to the following:

https://{EnterpriseCode}{ServerCode}accounting.wisegrid.net/AccountingTransationExportServi
ce.asmx

That web service provides two methods – ‘CreateBatch’ and ‘ExportBatch’. Those two web
service methods are directly replaced by the new message explained in this Update Note, using
the ‘Create’ and ‘Export’ action types.

The new action type of ‘CreateAndExport’ can be used instead of making two separate web
service calls.

2.5.7.4 Transitioning from Legacy Batch Export to Universal

Transaction Batch Export
When you are ready to transition from the Legacy XML Batch Export to the Universal Transaction
Batch Export, it’s important to follow a managed transition process to ensure that no transactions
are duplicated or missed. Please follow the process described here to ensure a seamless
transition between the legacy and universal batch export.

We recommend that you test this process in your test system before performing this in your
production system so that you are both familiar and comfortable with the process. Steps are as
follows:

1. Check that you can still access the legacy batch export via Manage > General Ledger >
Export Transactions. Raise a CR9 eRequest to temporarily re-enable this if necessary.
2. Negotiate a changeover time with your users and integration team. This is when you will stop
using the legacy batch export and start using the universal batch export. It is recommended
that you stop users from posting accounting transactions for a short period of time while your
complete steps 3-6.
3. When you’re ready to change over, ask users to stop using the CargoWise accounting system,
Billing and Job Costing menus. This will make the reconciliation process easier and is highly
recommended, but not mandatory.
4. Create your final legacy batch export manually or using the service task. This will be the last
legacy batch export that you will create and will include all transactions up to this point. You
should import these transactions into your external accounting system.

eAdaptor - Developer’s Guide | 74

If you receive a message that there are no transactions to batch, this means that nobody has
posted any transactions since step 3. You will not need to do anything further to handle
duplicate transactions in your external accounting system.

If you see a message that batch 1 was created successfully, this means that users have
created transactions after step 3, and you will need to manually remove any transactions that
appear in both the last legacy batch file and the second universal batch file. You can use
Transactions Export Batching Report to see which transactions were included in each batch.
You should export this batch and import it into your accounting system.

6. The process is complete. Let your users know that they can start using the accounting system
again at this point.

Once you start using Universal Transaction Batch Export, you should no longer go back to
Legacy Batch Export, in order to avoid duplication. It is important to note that Universal
Transaction Batch Export excludes transactions, which were previously exported using
Legacy Batch Export. However, subsequent Legacy Batch Exports will include transactions
previously exported by Universal Batch Export.

2.5.8 Universal Interchange Requeue Component

Using the eAdaptor HTTP+XML web service interface, you can bulk resubmit EDI Interchanges for
sending out via the eAdaptor Outbound web service interface.

To use this component, you send a UniversalInterchangeRequeueRequest XML message into the
eAdaptor HTTP+XML web service interface, and you will get a UniversalResponse XML message in
return. Upon successful completion, the UniversalResponse will contain a single Universal Event
indicating success including a count of the Interchanges that were re-queued.

Each ‘well formed’ requeue request sent (opening and closing tags matching/present and no
mandatory elements missing) will receive a UniversalResponse XML back. A malformed request
will return an HTTP ‘400-Bad Request’ response with nothing in the body.

This functionality can only be used to requeue EDI Interchanges that were sent out using
eAdaptor SOAP. EDI Interchanges sent via xHub are generally requeued at the xHub end after
consultation with WiseTech Global representatives.

eAdaptor - Developer’s Guide | 75

© 2024 WiseTech Global 11 March 2024
2.5.8.1 Universal Interchange Requeue Request Content
The Universal Interchange Requeue Request contains a FilterCollection to specify the Filters used
when selecting which EDI Interchanges to requeue. Each Filter element in the FilterCollection
contains a Type element defining the value being filtered on and for range-based filters, the
operator as well. Following is an example of a request that would requeue one hour’s worth of EDI
Interchanges.
<UniversalInterchangeRequeueRequest xmlns="http://www.cargowise.com/Schemas/Universal/2011/11">
<InterchangeRequeueRequest>
<FilterCollection>
<Filter>
<Type>CreateDateUTCFrom</Type>
<Value>2017-03-20T01:00:00</Value>
</Filter>
<Filter>
<Type>CreateDateUTCTo</Type>
<Value>2017-03-20T02:00:00</Value>
</Filter>
</FilterCollection>
</InterchangeRequeueRequest>
</UniversalInterchangeRequeueRequest>

An important note when building Filter elements is that they must include a ‘CreateDateUTC’
range, and the range specified must not span more than a 24-hour period. If there is no create
data range specified, the request will fail. This places a limit on the amount of data that can be
updated in a call to this service which limits the amount of work that will be done in the one
transaction.

It should be rare that you need to resubmit more than one day’s worth of interchanges. If this is
the case, you can call the method multiple times.

The following Filter Types are available:

CreateDateUTCFrom/ CreateDateUTCTo – A date range is always needed in a requeue request.

This means that CreateDateUTCFrom is mandatory and implies a ‘greater than or equal to’
operator. CreateDateUTCTo implies a ‘less than’ operator and is optional. If CreateDateUTCTo is
not specified and the CreateDateUTCFrom value specified is more than 24 hours in the past, the
request will be rejected.

ApplicationCode – Can include multiple to generate an ‘Or’ filter.

InterchangeNumberFrom/InterchangeNumberTo – InterchangeNumberFrom implies a ‘greater

than or equal to’ operator. InterchangeNumberTo implies a ‘less than or equal’ operator.

SenderCode – Can include multiple to generate an ‘Or’ filter.

RecipientCode – Can include multiple to generate an ‘Or’ filter.

BranchCode – Can include multiple to generate an ‘Or’ filter.

eAdaptor - Developer’s Guide | 76

© 2024 WiseTech Global 11 March 2024
2.5.8.2 Universal Response Content
Each ‘well formed’ UniversalInterchangeRequeueRequest sent with opening and closing tags
matching/present and no mandatory elements missing will get a UniversalResponse XML back.
The UniversalResponse contains the following elements:

• Status - Either ERR for Error or PRS for Processed Ok

• ProcessingLog - Contains Errors and Warnings that were detected during processing of the
sent query. Even for Processed Ok there may be warnings regarding processing the content of
the incoming query XML (e.g., Over length element values being truncated on import)
• Data - When status is Processed Ok, contains the resulting UniversalEvent XML

When Interchanges are successfully re-queued for sending, a UniversalResponse will be returned
with a status of PRS (Processed OK) and a single Universal Event in the Data element. The number
of Interchanges re-queued will be included in an InterchangeRequeueCount typed Context
element in the ContextCollection of the Universal Event. Following is a sample of a
UniversalResponse returned from a successful requeue request.
<UniversalResponse xmlns="http://www.cargowise.com/Schemas/Universal/2011/11" version="1.1">
<Status>PRS</Status>
<ProcessingLog />
<Data>
<UniversalEvent xmlns="http://www.cargowise.com/Schemas/Universal/2011/11" version="1.1">
<Event>
<DataContext>
<DataSourceCollection>
<DataSource>
<Type>EDIInterchange</Type>
</DataSource>
</DataSourceCollection>
<Company>
<Code>CWI</Code>
</Company>
<EnterpriseID>WTG</EnterpriseID>
<ServerID>SYD</ServerID>
</DataContext>

<EventTime>2017-03-20T05:47:12</EventTime>
<EventType>EDT</EventType>
<EventReference>Changed status: ->AQU</EventReference>
<IsEstimate>false</IsEstimate>
<ContextCollection>
<Context>
<Type>InterchangeRequeueCount</Type>
<Value>1203</Value>
</Context>
</ContextCollection>
</Event>
</UniversalEvent>
</Data>
</UniversalResponse>

eAdaptor - Developer’s Guide | 77

© 2024 WiseTech Global 11 March 2024
When a failure occurs, a UniversalResponse will be returned with a status of ERR (Error) and a
message in the ProcessingLog element explaining why the failure occurred. Following is an
example of a failure response.
<UniversalResponse xmlns="http://www.cargowise.com/Schemas/Universal/2011/11" version="1.1">
<Status>ERR</Status>
<ProcessingLog>
UniversalInterchangeRequeueRequest failure - Missing mandatory CreateDateUTC filter.
You must specify a CreateDateUTC filter with a span of under 24 hours to limit the
scope of each single requeue request.
</ProcessingLog>
<Data />
</UniversalResponse>

A malformed request will return an HTTP ‘400-Bad Request’ response with nothing in the body.

2.5.9 Native Query Component

The Native Query component can be used to extract Native XML content from CargoWise upon
demand. The data from any module that implements Native XML is accessible via this
component. A full list of Native datasets available can be obtained by extracting the current
Native XML schemas from CargoWise as described in section 3.1 Obtaining Current XML
Schemas.

This component functions in the same manner as the XNDT Web Service Retrieve Method
described in section 2.6.2 Using the Retrieve Method. This component is a replacement for that
service implementing HTTP Basic Authentication, HTTPS, and GZIP compression for better
security, performance and scalability.

To use the Native Query component, you send a Native XML message, and expect a
UniversalResponse XML message in return. The UniversalResponse will either contain the
requested Native XML, or a failure status and a reason why the requested Native XML could not
be returned.

eAdaptor - Developer’s Guide | 78

© 2024 WiseTech Global 11 March 2024
2.5.9.1 Native Request
The Native Request is designed to query for and return one or many Native XML entities
matching the criteria specified in the request. Every module that supports exporting Native XML
works with the Native interface.

Each ’well formed‘ Native Query sent (opening and closing tags matching/present and no
mandatory elements missing) will get a UniversalResponse XML back.

Following is a sample query for a UNLOCO:

<Native xmlns="http://www.cargowise.com/Schemas/Native">
<Body>
<UNLOCO>
<CriteriaGroup Type="Key">
<Criteria Entity="RefUNLOCO" FieldName="Code">
AUSYD
</Criteria>
</CriteriaGroup>
</UNLOCO>
</Body>
</Native>

The Native Request has a single Body element which then contains a single child element
representing the Native Dataset that is being queried. In this case the Native UNLOCO Dataset is
being queried.

The Dataset element will contain a list of CriteriaGroup elements with Criteria elements
contained within. These Criteria are used to filter the data when loading the Dataset requested.

More information on the proper use of Criteria and CriteriaGroups can be found in section 2.6.2
Using the Retrieve Method.

2.5.9.2 UniversalResponse
Each “well formed” Native Request sent with opening and closing tags matching/present and no
mandatory elements missing will get a UniversalResponse XML back. The UniversalResponse
contains:

• Status - Either ERR for ’Error or PRS for ’Processed Ok

• ProcessingLog - Contains Errors and Warnings that were detected during processing of
the sent query. For ’Processed Ok‘ this will contain information about how the matching
entity was found
• Data - When ’Status‘ is ’Processed Ok‘ contains the resulting Native XML.

Where the Native Request is malformed (not valid XML with matching opening and closing tags)
an HTTP ’400-Bad Request‘ response with nothing in the body.

If the Native Request is well formed, but the elements within are not used correctly (eg:
CriteriaGroup used with no Criteria contained) a Universal Response will be returned with an ’ERR‘
Status. A human readable error message describing the reason for rejection will be included in
the ProcessingLog element as per the sample following.

eAdaptor - Developer’s Guide | 79

© 2024 WiseTech Global 11 March 2024
<UniversalResponse xmlns="http://www.cargowise.com/Schemas/Universal/2011/11">
<Status>ERR</Status>
<Data>
</Data>
<ProcessingLog>Error - Key based retrieval only supports Primary or Candidate keys as field name.
“Codde” is not a primary or candidate key for table RefUNLOCO</ProcessingLog>
</UniversalResponse>

Where matching data is found, the result is then serialized into Native XML and returned within a
Universal Response as per the sample following.
<UniversalResponse xmlns="http://www.cargowise.com/Schemas/Universal/2011/11">
<Status>PRS</Status>
<Data>
<Native xmlns="http://www.cargowise.com/Schemas/Native/2011/11">
<Body>
<UNLOCO>
<RefUNLOCO>
<PK>ad87872e-96b8-4c9a-bc0b-6a4088247a64</PK>
<PortName>Sydney</PortName>
<CoOrdinates>3351S 15112E</CoOrdinates>

<IATA>SYD</IATA>
<Code>AUSYD</Code>
<CountryCode TableName="RefCountry">
<Code>AU</Code>
<PK>e4eb6e97-aa78-4c46-bf86-35b7fbb5fb0e</PK>
</CountryCode>
</RefUNLOCO>
</UNLOCO>
</Body>
</Native>
</Data>
<ProcessingLog>Information - 1 match found.</ProcessingLog>
</UniversalResponse>

Where multiple rows match the Criteria specified in the NativeRequest, there will be one Native
element generated under the Data element for each matching row.

Where the query is well formed, but no matching data is found, a UniversalResponse with a Status
of ’PRS‘ (Processed OK) and no Data content will be returned. The ProcessingLog will indicate that
no matches were found as per the sample following.
<UniversalResponse version="2.0" xmlns="http://www.cargowise.com/Schemas/Universal/2011/11" >
<Status>PRS</Status>
<Data>
</Data>
<ProcessingLog>Information - 0 matches found.</ProcessingLog>
</UniversalResponse>

2.5.9.3 Further Reading

This component functions in the same manner as the XNDT Web Service described in section
2.6.2 Using the Retrieve Method. More detailed information on the correct usage of Criteria and
CriteriaGroups can be found in that section.

To get a better understanding of the Native XML content that will be returned within the
UniversalResponse Data element, please read section 4 Native XML.

eAdaptor - Developer’s Guide | 80

© 2024 WiseTech Global 11 March 2024
2.5.10 Native Inbound Synchronous component
The Native Inbound Synchronous component can be used to push Native XML content directly
into CargoWise Any module that implements Native XML is accessible via this component. A full
list of Native datasets available can be obtained by extracting the current Native XML schemas
from CargoWise as described in section 3.1 Obtaining Current XML Schemas.

This component functions in the same manner as the XNDT Web Service Update Method
described in section 2.6.3 Using the Update Method. This component is a replacement for that
service implementing HTTP Basic Authentication, HTTPS, and GZIP compression for better
security, performance and scalability.

To use the Native Inbound Synchronous component, you send a properly formed Native XML
message, and expect a UniversalResponse XML message in return. The UniversalResponse will
either contain a success status and a human readable note describing what was updated, or a
failure status and a reason why the inbound Native XML could not be processed.

2.5.10.1 Native XML inbound

Native XML is comprised of a group of Datasets that span most Reference File modules within
CargoWise. All Native XML Datasets have a root element of “Native”, an optional Header element,
then a Body element containing a Dataset. The name of the first element in the Body element
defines the Dataset type. Each Dataset relates to a specific module within CargoWise examples
of Dataset types are Organization, Product, UNLOCO and Vessel.

eAdaptor - Developer’s Guide | 81

© 2024 WiseTech Global 11 March 2024
To import and process Native XML via eAdaptor HTTP+XML, you simply send in a properly formed
Native XML Dataset. The following is an example of a UNLOCO Dataset that would change the
“Port Name” of the AUSYD UNLOCO to be “Sydney (My Town)”.
<Native xmlns="http://www.cargowise.com/Schemas/Native/2011/11">
<Body>
<UNLOCO>
<RefUNLOCO Action="Merge">
<Code>AUSYD</Code>
<PortName>Sydney (My Town)</PortName>
</RefUNLOCO>
</UNLOCO>
</Body>
</Native>

There is no interchange wrapper or additional information required. eAdaptor HTTP+XML

recognizes Native XML, will parse and import it, then return Universal Response XML describing
the result.

For more information on building Native XML, please refer to section 4 Native XML.

2.5.10.2UniversalResponse
Where the Native XML sent is malformed (not valid XML with matching opening and closing tags)
an HTTP ’400-Bad Request‘ response with nothing in the body.

If the Native XML sent is well formed, but the data could not be processed or imported for any
reason, a Universal Response will be returned with an ’ERR‘ Status. A human readable error
message describing the reason for rejection will be included in the ProcessingLog element as per
the sample following.
<UniversalResponse version="2.0" xmlns="http://www.cargowise.com/Schemas/Universal/2011/11">
<Status>ERR</Status>
<Data>
</Data>
<ProcessingLog> Error - There is no UNLOCO with the following values: [Code:XXZZ_][PortName:Sydney
(My Town)].</ProcessingLog>
</UniversalResponse>

Where the update is successful, a Universal Response is returned with a PRS (Processed OK)
status and a human readable description of the scope of the update in the ProcessingLog
element.
<UniversalResponse version="2.0" xmlns="http://www.cargowise.com/Schemas/Universal/2011/11" >
<Status>PRS</Status>
<Data>
</Data>
<ProcessingLog>Information - RefUNLOCO - 0 inserts, 1 updates, 0 deletes</ProcessingLog>
</UniversalResponse>

eAdaptor - Developer’s Guide | 82

© 2024 WiseTech Global 11 March 2024
2.5.11 Universal Response Message Number
Both Universal and Native response messages will contain a <MessageNumberCollection> for
identification purposes.

The Universal Response message from CargoWise will include the collection as seen in the below
sample:

<UniversalResponse version="1.1" xmlns="http://www.cargowise.com/Schemas/Universal/2011/11">

The Native Response Message from CargoWise will include the collection as seen in the below
sample:

<Native xmlns="http://www.cargowise.com/Schemas/Native/2011/11" version="2.0">

The below Types are used withing the Message Number Collection:

• Tracking ID - <MessageNumber Type="TrackingID">

A unique tracking number created from CargoWise EAM Service Task.
• Interchange Number - <MessageNumber Type="InterchangeNumber">
Interchange number created by EDI Interchange module for messages via eHub / eAdaptor
• Message Number - <MessageNumber Type="MessageNumber">
EDI message number which can be accessed via the EDI Message Module.

eAdaptor - Developer’s Guide | 83

© 2024 WiseTech Global 11 March 2024
2.6 XNDT Web Service interface
2.6.1 Interface overview
The XML Native Data Transfer (XNDT) Service is comprised of two SOAP based web methods that
are used to query and directly update Reference File data using Native XML only. This interface
self publishes a WSDL describing the requirements of the interface. If you take the XNDT Web
Service URL provided from the Web Components setup and enter it in a web browser, you will
see a landing page for the XNDT Service interface as shown below.

Figure 37 XML Native Data Transfer (XNDT) Service

There are two blue underlined links that will bring up the WSDL describing the form of XML used
when connecting via this interface. The WSDL describes five web service methods; two of those
are used for current functionality.

Retrieve – Used to query reference tables returning a Native XML representation of any
matching data found.

Update – Used to update reference tables using Native XML. Updates occur while the HTTP
connection is held open, and the processing result is returned in the response.

Each method takes a single Native XML message parameter containing the Native XML that
constitutes the message, and returns a Response XML message containing:

Status – ‘Accepted’ when the Native XML message was able to be processed, ‘Rejected’ when
there was an error processing the Native XML message.

Information – A series of plain text Item segments giving either a description of the error causing
rejection, or a description of what was done in response to an accepted message.

eAdaptor - Developer’s Guide | 84

© 2024 WiseTech Global 11 March 2024
EntityInfo – Contains information identifying the top-level entity being retrieved or updated
when a match is found.

Data – when calling RetrieveData, if the requested entity is found, it will be returned inside the
Data element in the format specified in the Native XML Schema for that entity type.

Both of these web methods can be called using the XNDT Sample Client described in following
sections to demonstrate the functionality available. The demonstrations describe the
functionality available using these two web methods in more detail.

There are three other web service methods, RetrieveData, UpdateData and Service that were
added to provide the same features provided by Retrieve and Update for some legacy
middleware. These have been deprecated for some time and are not required for any current
implementation.

2.6.2 Using the Retrieve method

A Retrieve request takes the standard Native XML form but uses the Body element only. The first
sub element in the body defines the entity type being requested and contains a sequence of
CriteriaGroups used to match or filter the entities being returned.

Each CriteriaGroup can contain multiple Criteria, and can either be Unique Key based, or Partial
Match based as described below.

2.6.2.1 Unique key based retrieval

This is the retrieval of data by providing a candidate key (unique reference). Following is an
example of a Retrieve request using a candidate key:

This message requires that the Code property on the table OrgHeader is a candidate key to work.
If you specify a FieldName that is not a candidate key, a Rejection status will be returned with an
appropriate error message.

When using unique key based retrieval, only a single key can be specified. There will only be one
Criteria element, as multiple criteria with different unique keys would never return a result. This is
because you could never find an organization with a code of ABC and XYZ.
<Native xmlns="http://www.cargowise.com/Schemas/Native">
<Body>
<Organization>
<CriteriaGroup Type="Key">
<Criteria Entity="OrgHeader" FieldName="Code">
ABCDEF
</Criteria>
</CriteriaGroup>
</Organization>
</Body>
</Native>

eAdaptor - Developer’s Guide | 85

© 2024 WiseTech Global 11 March 2024
2.6.2.2 Partial Match retrieval
You can retrieve entities by providing field names along with either complete values or partial
values using wildcards to filter by. Multiple criteria items can be provided, and multiple groups of
criteria can be provided.

All items within a criteria group assume an ‘And’ operation, whilst an ‘Or’ operation is performed
between each criteria group.

The following example will retrieve all Organizations where the Code element begins with A and
the Organization has the IsBroker element set to true, or all Organizations where the FullName
element begins with BA.
<Native xmlns="http://www.cargowise.com/Schemas/Native">
<Body>
<Organization>
<CriteriaGroup Type="Partial">
<Criteria Entity="OrgHeader" FieldName="Code">
A%
</Criteria>
<Criteria Entity="OrgHeader" FieldName="IsBroker">
True
</Criteria>
</CriteriaGroup>
<CriteriaGroup Type="Partial">
<Criteria Entity="OrgHeader" FieldName="FullName">
BA%
</Criteria>
</CriteriaGroup>
</Organization>
</Body>
</Native>

The value of the Table property can be any table within the entity set specified. As an example,
the below request retrieves Organizations where a custom code exists of type DUN for country
US with a value starting with 1234.
<Native xmlns="http://www.cargowise.com/Schemas/Native">
<Body>
<Organization>
<CriteriaGroup Type="Partial">
<Criteria Entity="OrgHeader.OrgCusCode" FieldName ="CodeType">DUN</Criteria>
<Criteria Entity="OrgHeader.OrgCusCode" FieldName="CustomsReg.No">1234%</Criteria>
<Criteria Entity="OrgHeader.OrgCusCode.CodeCountry" FieldName="Code">US</Criteria>
</CriteriaGroup>
</Organization>
</Body>
</Native>

eAdaptor - Developer’s Guide | 86

© 2024 WiseTech Global 11 March 2024
2.6.2.3 Retrieve response
The response to a Retrieve request will contain a Status element, and zero or more resulting data
items. A successful response will look something like this:
<Response xmlns="http://www.cargowise.com/Schemas/Universal">
<EntityInfo>
<Name>Organization</Name>
</EntityInfo>
<Status>Accepted</Status>
<Information>
<Item>Severity - Individual Notification</Item>
<Item>Severity - Individual Notification</Item>
</Information>
<Data>
<DataItem>
<Organization>
<OrgHeader>

</OrgHeader>
</Organization>
</DataItem>
<DataItem>
<Organization>
<OrgHeader>

</OrgHeader>
</Organization>
</DataItem>
</Data>
</Response>

In the above example, the Data element is returning two DataItems. Each data item will contain
the data of the relevant data item requested.

The possible values of Status are:

• Accepted
• Accepted with Notifications
• Rejected

Zero or more information items can be included in the Information element. For successful
requests, an information element will specify how many data items are being returned.

If a Rejected status is returned, no Data element will be provided.

eAdaptor - Developer’s Guide | 87

© 2024 WiseTech Global 11 March 2024
2.6.3 Using the Update Method
2.6.3.1 Overview
An update data service call will operate on a single set of data provided. The update is always key
based and cannot be pattern match based or partial search based. This means that every item in
the update request must contain a unique key.

It is also important to note that every item within the hierarchy of that entity set contains an
Action attribute. This attribute defines what operation to perform on that single data item only.
Actions allowed are:

• INSERT – Add a new row to the database. (must be no rows with a matching key)
• UPDATE – Update existing row using matching key.
• MERGE – Update existing row using matching key, otherwise add new row.
• DELETE – Delete existing row using matching key.

Insert will cause a failure if a row already exists with a matching key. Update and Delete will
cause a failure if no row exists with a matching key.

Action attributes are not inherited – meaning that to delete an item, all children must also have
the Delete attribute applied.

If a table has children that are not defined in the entity set, the system will reject the entity
deletion.

The lack of an action attribute implies that that data item will not cause any update during the
update process. Values in an element without an Action will be used to match to a row so that
any child elements can then match using the matched row as a parent.

eAdaptor - Developer’s Guide | 88

© 2024 WiseTech Global 11 March 2024
The structure of an update data request is as follows:
<Native xmlns="http://www.cargowise.com/Schemas/Native">
<Body>
<Organization>
<OrgHeader>

<Code>ABC1234</Code>
<Name>Some Organisation</Name>
<OrgAddressCollection>
<OrgAddress Action="UPDATE">

<PK>2E166A12-1834-4b94-BF30-E90E3A2176CF</PK>
<Address1>Some changed value</Address1>
<Address2>Some existing value</Address2>
</OrgAddress>
<OrgAddress Action="DELETE">

<PK>2E166A12-1834-4b94-BF30-E90E3A2176CF</PK>
</OrgAddress>
<OrgAddress Action="INSERT">

<Address1>New Address 1</Address1>
<City>Copenhagen</City>
</OrgAddress>
</OrgAddressCollection>
<OrgContactCollection>
<OrgContact>

<Name>Some One</Name>
<Phone>+61 430 000 000</Phone>
</OrgContact>
</OrgContactCollection>
<OrgCusCodeCollection>
<OrgCusCode Action="MERGE">

<CustomsRegNo>4091310</CustomsRegNo>
<CodeType>LSC</CodeType>
<PremisesAddress TableName="OrgAddress" />
<CodeCountry TableName="RefCountry">
<Code>AU</Code>
</CodeCountry>
</OrgCusCode>
</OrgCusCodeCollection>
</OrgHeader>
</Organization>
</Body>
</Native>

Every item that has an action of either Delete or Update must contain an element that is a valid
candidate key for that data item. A candidate key could contain multiple columns according to
the definition of a given table.

eAdaptor - Developer’s Guide | 89

© 2024 WiseTech Global 11 March 2024
If there is more than one candidate key for a target table, the system will randomly choose a valid
candidate key to find the item. There are very few tables with more than one candidate key.
Following is a simple example of updating an item with candidate key:
<Native xmlns="http://www.cargowise.com/Schemas/Native">
<Body>
<Organization>
<OrgHeader Action="UPDATE">
<Code>ZAYZUBBNE</Code>
<FullName>Zayden Zubin</FullName>
</OrgHeader>
</Organization>
</Body>
</Native>

2.6.3.2 Update Response

The response from an Update Data request service call contains only status and information
messages in the following structure. This is identical to the status/notifications structure for the
Retrieve Data service.
<Response xmlns="http://www.cargowise.com/Schemas/NativeNative">
<EntityInfo>
<Name>Organization</Name>
<PrimaryKey>xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</PrimaryKey>
<LocalCode>XXXXXXX</LocalCode>
<ExternalCode>XXXXXXXX</ExternalCode>
</EntityInfo>
<Status>Accepted</Status>
<Information>
<Item>Severity - Individual Notification </Item>
<Item>Severity - Individual Notification </Item>
</Information>
</Response>

If an update is successful, the Information element will include a list of table names affected, with
the number of inserts, updates and deletes specified per table.

eAdaptor - Developer’s Guide | 90

© 2024 WiseTech Global 11 March 2024
When sending a simple Insert message for an organization as follows:
<Native xmlns="http://www.cargowise.com/Schemas/Native">
<Body>
<Organization>
<OrgHeader Action="INSERT">
<Code>ZAYZUBBNE</Code>
<FullName>Zayden Zubin</FullName>
<ClosestPort TableName="RefUNLOCO">
<Code>AUBNE</Code>
</ClosestPort>
</OrgHeader>
</Organization>
</Body>
</Native>

…this is what the successful update response looks like:

<Response xmlns="http://www.cargowise.com/Schemas/Native">
<EntityInfo>
<Name>Organization</Name>
<PrimaryKey>44829ee5-b89d-4c80-ba7f-84bb81d867cb</PrimaryKey>
<LocalCode>ZAYZUBBNE</LocalCode>
<ExternalCode>ZAYZUBBNE</ExternalCode>
</EntityInfo>
<Status>Accepted</Status>
<Information>
<Item>Information - OrgHeader - 1 inserts, 0 updates, 0 deletes</Item>
</Information>
</Response>

eAdaptor - Developer’s Guide | 91

© 2024 WiseTech Global 11 March 2024
2.6.4 Using the XNDT Sample Client
Both of these web methods can be called using the XNDT Sample Client.

This is available as part of the eAdaptor Sample Interfaces pack available from our WiseTech
Academy in Integration Options – eAdaptor Guides

If you download the eAdaptor Sample Interfaces pack and unzip it, you will see a folder XNDT.C#.

Figure 38 Unzip XNDT Sample Client

If you have .NET C# experience and a copy of Microsoft Visual Studio installed, you can use the
source code provided to gain a better understanding of the XNDT Web Service by opening the
WTG.XNDT.SampleClient.sln Solution file.

If all you want to do is test or demonstrate the XNDT Web Service Interface, you can run the
XNDTSampleClient.exe file that is provided already built using the source code provided.

eAdaptor - Developer’s Guide | 92

© 2024 WiseTech Global 11 March 2024
3. Common XML concepts
3.1 Obtaining current XML Schemas
All XML datasets available from CargoWise have XSD Schemas available.

For Native and Universal XML, the schema set that matches the version of CargoWise you are
running is available from within your own CargoWise system. We add to our schemas over time,
and although we don’t make breaking changes (remove or rename elements) it is better to use
the set of schemas that match your current version of CargoWise when beginning new mappings.

The module where both Universal and Native XML messages are most visible is the EDI Messages
module under Maintain, EDI Messaging, and then EDI Message. This is where you have the option
for saving your own copy of our schemas.

Figure 39 Menu path Maintain > EDI Messaging > EDI Message

eAdaptor - Developer’s Guide | 93

© 2024 WiseTech Global 11 March 2024
Within the EDI Messages Search screen, click on the Actions drop-down menu at the top of the
tool bar then select Save Universal+Native XML Schemas option as shown below:

Figure 40 Actions Menu >Save Universal + Native XML Schemas

You will then be asked to select a folder to write the Schemas to:

Figure 41 Destination Folder to Write Schemas

It’s a good idea to create a new folder if you don’t already have one, multiple files will be
created in the folder you select.

eAdaptor - Developer’s Guide | 94

© 2024 WiseTech Global 11 March 2024
Once you’ve selected a folder, the schemas will be written out. The following system prompt will
display showing displaying the names of the schema files, and confirming where they were saved:

Figure 42 System Prompt Confirming Saved Schemas

When completing a mapping into or out of CargoWise, these are used in conjunction with Sample
XML that you can generate yourself by exporting XML from your own CargoWise system or one
of our test systems.

If you don’t have access to a test CargoWise system, please contact your WiseTech Global
representative for more information on available options for test systems. Testing is a key
part of any Electronic Data Interchange implementation.

Our schemas are designed to be used as a set using both references from the Native Common
schema to the Universal Namespace and the ‘include’ element between Universal entities and the
Universal Common schema. Please make sure your middleware supports these facilities before
trying to use these schemas.

If your middleware does not support these facilities, this problem can be worked around by
merging the schemas manually. As this process varies between different middleware
depending on what is and is not supported, it’s not something we can provide specific advice
on. In some cases, this can be fixed by updating to the current version of your middleware.

eAdaptor - Developer’s Guide | 95

© 2024 WiseTech Global 11 March 2024
3.2.1 Native list of Entities
Once you have saved the Current Universal+Native Schema you will see one file per Native XML
Dataset as shown below:

• Airline
• CommodityCode
• Container
• CurrencyExchangeRate
• DangerousGood
• Organization
• ServiceLevel
• Vessel
• Company
• Staff
• Country
• UNLOCO
• Product
• Rate
• CusStatement
• AcceptabilityBand
• BMSystem
• Tag
• TagRule
• WorkflowTemplate
• Native (common)

3.2.2 Universal list of Entities

Below is the current list of schemas for Universal:

• Activity
• Common
• Event
• Interchange
• Schedule
• Shipment

eAdaptor - Developer’s Guide | 96

Any new Universal schemas released will be added to this functionality as they become available.

3.3 Encoding and Extended Character Sets

Universal and Native XML support Non-English Language Character Sets (also known as Extended
Character Sets) with full Unicode support when encoded using UTF-8. There are some
restrictions on the characters that can be processed that vary depending on the module you are
targeting.

There are two kinds of restrictions, those imposed by what can be stored by SQL in various
column types, and those imposed by limitations of the XML standard itself.

3.3.1 Limitations of the XML standard

Universal and Native XML are both implemented under the XML 1.0 standard. Acceptable Unicode
characters are as follows:

• U+0009 (Horizontal Tab)

• U+000A (Line Feed)
• U+000D (Carriage Return)
• U+0020–U+D7FF
• U+E000–U+FFFD
• U+10000–U+10FFFF

You will find that this covers all printable characters used in all languages. The values excluded
from XML are control characters that are often non-printable and therefore redundant for
documentary purposes. For more information on what constitutes valid characters in XML, please
see https://en.wikipedia.org/wiki/XML#Valid_characters.

Where characters are used that are not within the acceptable ranges as per the XML 1.0
specification, the entire XML stream will be rejected.

eAdaptor - Developer’s Guide | 97

© 2024 WiseTech Global 11 March 2024
3.3.2 Limitations of SQL database storage
Depending on the type of column used in the SQL schema, there is a limitation on what can be
stored within many fields in CargoWise. Most fields in CargoWise do not have a business need to
support extended character sets. This is because the Latin character set is used predominantly
in documentation for International Freight Forwarding and Logistics.

A good example of this is Origin and Destination UNLOCO columns or any column containing an
ISO Country Code where the characters used are A-Z and in some cases for the UNLOCOs, 0-9.
Numbers are represented using European Digits, and weight, volume, and units of quantity use
units that are also represented using the Latin character set.

To best meet the business requirement for those fields, varchar columns are used. These limit
the character set that can be stored, but use half the storage space, and have increased
performance when indexed as the indexes are smaller too. Each character takes one byte in the
database. In CargoWise, we use code page 1252 for varchar columns. This includes the complete
Latin character set which meets the documentary requirements for international trade.

For fields where full multi-lingual support is required like Marks and Numbers (a box may have
identifying marks in any language), CargoWise uses nvarchar columns in the SQL schema which
allows the full Unicode character set. This allows both Latin characters (also known as Western
European language characters) and Extended Characters. These are recorded in the database
using an encoding which uses either two or four bytes to store each character but can store any
character from any language.

3.3.3 Which fields support Extended Characters?

There is no indication in the XSD schema as to what the allowable character set is for a given
element as this is limited by the target module and its database schema, not the XML engine
itself. The majority of fields in CargoWise are limited to the characters in code page 1252.

In the GUI you can tell which fields support Extended Character Sets by trying to type or paste in
text in a language using non-Latin characters. For fields that are limited to code page 1252, you
will see an error telling you that only western European languages are supported in that field.
Where a field supports the full Unicode character set, there will be no error.

Figure 43 Extended Character Sets

eAdaptor - Developer’s Guide | 98

© 2024 WiseTech Global 11 March 2024
You can see from the screenshot above that when trying to enter "Boxed Hats (盒装帽子)" into a
field that supports Unicode like Marks & Numbers, there is no error. Goods Description gives an
error and will not let you save as it only supports Western European characters.

If you try and import Universal XML containing Extended Characters into fields that do not
support them, you will not get any errors or warnings when processing. The characters will come
in as question marks indicating a character that was present in the data source but could not be
stored.

If you try and import "Boxed Hats (盒装帽子)" in both Marks and Numbers and Goods Description
using the XML shown below:
<UniversalShipment xmlns="http://www.cargowise.com/Schemas/Universal/2011/11" version="1.1">
<Shipment>
<DataContext>
<DataTargetCollection>
<DataTarget>
<Type>ForwardingShipment</Type>
<Key>S00001000</Key>
</DataTarget>
</DataTargetCollection>
</DataContext>

<GoodsDescription>Boxed Hats (盒装帽子)</GoodsDescription>

<NoteCollection Content="Partial">
<Note>
<Description>Marks & Numbers</Description>
<IsCustomDescription>false</IsCustomDescription>
<NoteText>Boxed Hats (盒装帽子)</NoteText>
</Note>
</NoteCollection>
</Shipment>
</UniversalShipment>

You will then see question marks (?) in place of each unsupported character where extended
characters are not supported. Where extended characters are supported, they will be imported
as they are shown in the XML.

Figure 44 Unsupported Characters Sets and Extended Character Sets

When mapping XML into CargoWise, watch for unexpected question marks. This tells you that
there were characters in the inbound XML that were not supported in this location.

If there is a value in your XML containing Extended Characters that you need to have recorded
and there is no field that will accept it in CargoWise, you can import that value as a Note or a
Customized Field. Notes support Extended Characters in all modules, as do Customized Fields.

eAdaptor - Developer’s Guide | 99

© 2024 WiseTech Global 11 March 2024
3.4 Code mapping
The Universal and Native XML Engine has the capability to translate externally defined codes into
the local codes used in your CargoWise system on the way in. It does this by allowing users to
define a list of ‘Code Mappings’ from the codes the external system uses (aka: Foreign Codes) to
the codes you use internally.

An example of where you could use this is where you have a partner sending you Universal
Shipments containing Consols they want you to process. When they send you their XML
messages, the Organizations they send would have their Organization Codes in them. They may
be completely different to the codes you use for the same Organizations in your own system.

If you have entered Code Mappings from their codes to your codes before the file is imported,
the correct Organizations will be saved in your CargoWise system even though the XML provided
had their codes in it.

3.4.1 Functional overview

Once the benefits are fully understood, CargoWise users typically exchange electronic data with
multiple partners. Each partner is known as a Data Provider as they provide data to be imported
into CargoWise. Code mappings are configured per Data Provider along with other information
you keep track of for your trading partners in the Organizations module.

Each Company in a CargoWise system will want the ability to determine their own set of Data
have their own set of EDI Trading partners. For this reason, there are actually two stages of code
mapping that occur. The first mapping is completed using the Target Company to map from the
supplied Data Source Code to the Data Provider Organization, then all other codes are mapped
using the mappings defined on the Data Provider Organization established in the previous step.

The following steps are followed:

1. Establish the Target Company for the XML being imported.

2. Check the XML to get the Data Provider Foreign Code and see if Code Mapping is enabled for
the message. (Stop at this point if not enabled.)
3. Use the Code Mappings from the Target Company Organization Proxy to map from the Data
Provider Foreign Code to find the Data Provider Organization.
4. Use the Code Mappings from the Data Provider Organization to map all Foreign Codes in the
supplied to XML to the codes used in the target CargoWise system.

These steps are covered in more detail in the following sections. The process for entering Code
Mappings against an Organization is the same for Steps Three and Four, so it is only described
once using examples suitable for Step Four.

eAdaptor - Developer’s Guide | 100

© 2024 WiseTech Global 11 March 2024
3.4.2 Step One - Establishing the Target Company
The first step for Code Mapping is to establish the Company that is importing the XML data.
There are two ways that can be used to determine the Target Company, channel specific and
XML message specific. If the Target Company is specified in the XML message, that is what is
used falling back to the channel specific Target Company.

3.4.2.1 Channel specific Target Company

There are a number of channels that can be used to import XML into CargoWise, and each
channel has a different way of determining the Company you are importing into.

3.4.2.1.1 Import from File

Native XML allows users to import directly from file using options in the Action button for all
modules supporting Native XML. Universal XML allows System Administrators to queue Universal
XML for processing in the EDI Messages module using an option under the Action button there.
(Intended for debugging purposes only)

For both forms of XML, the Target Company will be the Company the user is logged into when
importing from file.
xHub and eAdaptor SOAP

When XML messages are sent into CargoWise via xHub or eAdaptor SOAP, the interface requires
a Company to be specified. The first active Branch found against the Company specified is
recorded against any resulting EDI Message. This can be seen in the EDI Messages module in the
Branch column.

Figure 45 EDI Message Search Screen

eAdaptor - Developer’s Guide | 101

Neither of these channels have an implicit Company context. If you are using these channels, you
must include the Target Company context in the XML message content as described in the
following section. If you don’t specify a Target Company, a random Company will be used for the
initial stage of Code Mapping.

3.4.2.2 XML message content Target Company

Where a Target Company context is required for code mapping, it’s best to include the target
Company identifiers in the XML itself as this method works no matter which transport layer you
choose to use. Both the Native and Universal XML allow you to include a DataContext element.
For Native XML, the DataContext element is added in the Native > Header element as follows.
<Native xmlns="http://www.cargowise.com/Schemas/Native/2011/11" version="2.0">
<Header>
<OwnerCode>HYECMTDAU</OwnerCode>
<EnableCodeMapping>true</EnableCodeMapping>
<nv:DataContext xmlns="http://www.cargowise.com/Schemas/Universal/2011/11"
xmlns:nv="http://www.cargowise.com/Schemas/Native/2011/11">
<DataSourceCollection>
<DataSource>
<Type>Organization</Type>
<Key>AUSBEAMEL</Key>
</DataSource>
</DataSourceCollection>
<Company>
<Code>DAU</Code>
</Company>
<EnterpriseID>HYE</EnterpriseID>
<ServerID>CMT</ServerID>
</nv:DataContext>
</Header>
<Body>
<Organization version="2.0">

</Organization>
</Body>
</Native>

For Universal XML, the DataContext is included in the first top level element as follows.
<UniversalShipment xmlns="http://www.cargowise.com/Schemas/Universal/2011/11" version="1.1">
<Shipment>
<DataContext>
<DataSourceCollection>
<DataSource>
<Type>AsycudaManifest</Type>
<Key>MAN0000066</Key>
</DataSource>
</DataSourceCollection>

<Company>
<Code>DAU</Code>
</Company>
<EnterpriseID>HYE</EnterpriseID>
<ServerID>CMT</ServerID>
<DataProvider>HYECMTDAU</DataProvider>
</DataContext>

</Shipment>
</UniversalShipment>

eAdaptor - Developer’s Guide | 102

© 2024 WiseTech Global 11 March 2024
If the values from the EnterpriseID and ServerID elements match the registration of the target
CargoWise system, and the value from the Company > Code element matches to a registered
Company Code, then that will become the Target Company used for code mapping. The Target
Company will also be used for any other functionality where Company context is required during
the import process.

3.4.3 Step Two - Reading the Data Provider Foreign Code

Both Universal and Native XML Messages allow the sending party to include an element with a
Code in it used to identify the Data Provider Organization. This is called the Data Provider Foreign
Code.

3.4.3.1 Native XML

The Native > Header element contains two elements that are used for Code Mapping.

• OwnerCode – Identifies the Owner or Provider of the data, becomes the Data Provider
Foreign Code for Code Mapping
• EnableCodeMapping – Boolean value that must be included with a value of ‘true’ for Code
Mapping to work.

You can see both of these elements in the sample XML provided on the previous page.

3.4.3.2 Universal XML

All forms of Universal XML have a DataContext element directly contained in the top-level
element. In the DataContext element, there are two elements that are used for Code Mapping.

• DataProvider - Contains the Data Provider Foreign Code for Code Mapping
• CodesMappedToTarget – Optional Boolean element that can be used to disable Code
Mapping in Universal XML. If ‘true’, no code mapping will occur.

You can see the DataProvider element in the sample XML provided on the previous page.
CodesMappedToTarget is included at the same level as the DataProvider element where
required.

3.4.4 Step Three - Mapping the Data Provider Foreign

Code to an Organization
If a Data Provider Foreign Code is included in the XML, and Code Mapping is enabled according to
the elements in the provided XML, CargoWise finds the Company Organization Proxy for the
Target Company established in the previous step and reads the Code Mappings defined on that
Organization. If there is a Code Mapping present with a Foreign Code matching the Data Provider
Foreign Code which points towards an organization, then that becomes the Data Provider
Organization, and Code Mapping will proceed.

eAdaptor - Developer’s Guide | 103

© 2024 WiseTech Global 11 March 2024
3.4.5 Step Four - Mapping from Foreign Codes to Local
Codes
Once the Data Provider Organization has been established in the previous step, the EDI Code
Mappings are read from that Organization and used to translate the Foreign Codes to Local
Codes as the rest of the XML is imported. Instructions on how to configure code mappings follow.

3.4.6 Configuring Mappings for an Organization

Go to the Maintain > Reference Files > Organizations module and open an organization. Navigate
to the Details > Config > EDI Code Mapping sub tab where you will see the EDI Mapping grid. The
Foreign Code field represents the codes as supplied by the Data Provider Organization. The
Relationship drop-down menu allows you to select the type of code being mapped, which in turn
identifies the related module. The Local Code field is the internal code that the Foreign Code will
be mapped to in your CargoWise system.

Figure 46 Organization > Config > EDI Code Mapping tab

You can see in the screen shot above that if the Data Provider for Imported XML was the
Organization AUSBEAMEL, the Organization codes ABC, DEF and GHI would be translated to
A1CHEMSYD, DE50IMHAM, and GAAEMEMEL as the XML was imported. There are many different
types of coded lists that can be translated upon import using CargoWise. To see a full list of
mapping types available, click on the drop-down menu in the Relationship column.

eAdaptor - Developer’s Guide | 104

3.4.7 Evidence Code Mapping has taken place.

With Universal XML, you can tell if Code Mapping occurred on an individual message as codes
that are successfully mapped are recorded in the Data Import Log. You can see this log by
opening up the EDI Message that the Universal XML was imported from and clicking on the Notes
tab to show the Data Import Log Note as shown below.

Figure 47 View Message > Notes tab

You can see that the Data Provider Organization used for code mapping is identified, and all
codes mapped are shown as well.

eAdaptor - Developer’s Guide | 105

© 2024 WiseTech Global 11 March 2024
3.5 Validation during data import
Our XML Import Services do not validate during import apart from database constraints that
preclude the ability to store the data supplied in the target module’s SQL dataset. There are very
few constraints of this kind, so the vast majority of well-formed XML with correct data types will
be imported.

There are two reasons for this, the first is performance. Validating incoming data costs
processing effort and hence time. Data being sent in via XML has generally already been
validated by the Middleware that has mapped the data in from the source format. Validating
already validated data is a waste of processing resources reducing the maximum possible speed
attainable. This is doubly redundant when you consider that validation will also occur in the User
Interface.

The second is expediency, or the quality of being convenient and practical despite possibly
being improper. In production, operators would not want a 10,000-line Commercial Invoice
Import to be stopped because the Currency was missing when it can easily be added by a user
before it is used on a job. Even if there was a problem with a value on every line, users can use
the Bulk Update functionality to correct the data in bulk once it’s in the system.

Not being able to get correctable data imported can cost many hours of manual data entry when
nobody technical is available to fix the source data. Operators are very good at fixing this kind of
data, so it’s best to let them do it without having to obtain assistance. There is a requirement to
validate, but that only needs to be done before the data is used in an operational module.

In all modules, when a user tries to edit an entity created by an import that has missing or
incorrect data, validation will tell them what is wrong and make them correct it before they can
save. Users can either make an informed decision on how to fix appropriately or leave the entity
unsaved and escalate to their team leads for fixing.

This happens naturally in operational modules as users try and process jobs within those
modules. For reference modules, operational modules consuming the data will validate their own
specific requirements when the data is selected for use. This will force users to fix and update
these as the reference data is consumed.

eAdaptor - Developer’s Guide | 106

© 2024 WiseTech Global 11 March 2024
3.6 Applying updates from incoming XML
Our XML services are designed to have the same capability that any user has when updating data
within each module within CargoWise. For this reason, information from incoming XML messages
is processed as though a user manually entered the data from each element included.

When an element is included with a value, it will replace whatever is in the target field for that
element. When an element is included with no value (i.e., blank or empty value), then the target
field will be overwritten to blank. When an element is not included in the XML, the corresponding
target field will be left alone. The value will not be changed or affected.

We call this an Authoritative Update process. The incoming XML is accepted as the most current
authority for the target being updated. This does not necessarily mean it has ALL the information
that the target may contain, but all elements included in incoming messages are treated as the
authority on what the current target will become.

The below UniversalShipment will update Forwarding Shipment S00001000 to match the
information it contains:
<UniversalShipment xmlns="http://www.cargowise.com/Schemas/Universal/2011/11" version="1.1">
<Shipment>
<DataContext>
<DataTargetCollection>
<DataTarget>
<Type>ForwardingShipment</Type>
<Key>S00001000</Key>
</DataTarget>
</DataTargetCollection>
</DataContext>
<GoodsDescription></GoodsDescription>
<GoodsValue>0.00</GoodsValue>
<IsCancelled>false</IsCancelled>
<Currency>
<Code>AUD</Code>
<Description>Australian Dollars</Description>
</Currency>
</Shipment>
</UniversalShipment>

Provided that Forwarding Shipment S00001000 exists, every element of this message will be
used to update it. Regardless of what they were prior, the Goods Description will be changed to
be blank, the goods value will become 0.00, the shipment will be marked as not cancelled and
the currency will become AUD.

CargoWise considers well-formed Universal and Native XML messages to be authoritative

sources of data. If the XML targets existing entities, then the data from those entities will be
overwritten. Ensure that XML messages contain only information that needs to be updated or
used for matching.

eAdaptor - Developer’s Guide | 107

The content in this section is no longer being updated and will be deleted as we move
towards the Native XML Guide. For more current information on Native XMLs please refer to
the Native XML Guide in WiseTech Academy.

4.1 Concepts
Native XML schemas are generated from the SQL DB schema used by CargoWise. When data is
read from and written to the DB, it is done using native SQL (no business layer). That’s why this
form of XML is called Native XML.

Why go Native?

1. As fields are added to the CargoWise schema, they are automatically included in the Native
XML Schemas.
2. Going direct to the DB bypasses business process and validation enabling a:
a. Higher level of performance due to less overhead.
b. Get the data in and allow the user to fix approach.

This does mean that as we change our SQL DB Schemas you will need to test your interfaces as
you update your software. Make sure you have an adequate test and release pattern as
described in previous chapters.

There are a number of common design patterns used in the Native XML schemas. These are
explained below.

4.1.1 Namespace
The namespace of all schemas defined by the Native XML architecture is:

http://www.cargowise.com/Schemas/Native/2011/11

As described in previous chapters, this does not change unless we make a major breaking
change to our schemas. An example of a breaking change would be moving or removing sections
of our XML. Adding new elements is not a breaking change and can happen any time you choose
to upgrade your CargoWise system.

eAdaptor - Developer’s Guide | 108

© 2024 WiseTech Global 11 March 2024
4.1.2 Native XML Schemas
Each Native XML schema set will currently reference a common Native schema set defined in a
separate file. This schema defines common types that will be used across all schema sets. This
common schema is referenced using an ‘include’ element at the top of all Native schema files like
so:
<xs:include schemaLocation="Native.xsd" />

The common schema includes definitions of the common types and attributes, which are
discussed later in this document. Currently this schema includes:

• Native (the common Root element)

• Action (attribute)
• emptiableDateTime (used for Dates/Times throughout Native XML)

4.1.3 Schema names

Each Native XML schema set has a name using the following style:

• Native<Description>.xsd

For example, NativeOrganization.xsd

4.1.4 Published Schemas

All available entity set schemas can be exported from your current version of CargoWise. As you
upgrade CargoWise, new fields available in that version of CargoWise will automatically appear in
the schemas you generate live from CargoWise.

This means that you can always obtain a full set of XSD schema files that exactly match the
version of CargoWise you are running.

Figure 48 Actions Menu >Data Transfer > Native XML Schemas

You will then be prompted to select a destination folder, and the schemas will then be generated
and saved in the selected folder.

eAdaptor - Developer’s Guide | 109

© 2024 WiseTech Global 11 March 2024
4.1.5 Table Keys
Each data item within the set has a candidate key made up of the parent data item, plus one or
more fields on the data item itself. These keys are not identifiable in the XML data itself, but are
shown in the XSD Schema as a Candidate Key comment at the top of definition of each.
<xs:complexType name="OrgHeader">
<xs:all>

<xs:element name="CustomValues" type="CustomValues" />
<xs:element name="Code" cw:required="false" minOccurs="0">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="12" />
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="IsActive" cw:required="false" minOccurs="0" type="xs:boolean" />
...
</xs:all>
<xs:attribute name="Action" type="Action" />

</xs:complexType>

If a candidate key is made up of multiple fields combined, it will be identified in a single

Candidate Key comment using a plus symbol to separate the key fields.

If the candidate key involves a field on a related object, the field name will be prefixed with that
table/data item name as shown here:

The values that make up these candidate keys are included as for any other data element in the
schema.

4.1.6 Foreign Keys/Related Items

If a foreign key is identified, and the related item is not part of the specific entity set currently
being dealt with, it will be included in the schema as a special type called an External Entity.

CargoWise will identify the foreign key relation by external entity type and provide enough
information to allow identification of the related item.

Depending on the definition of the external entity, CargoWise may provide only the candidate
key or the whole external entity.

An example is shown below with a ClosestPort as an External Entity to the OrgHeader entity.
<OrgHeader>
...
<Code>BRAPHI</Code>
<ClosestPort name="ClosestPort" table="RefUNLOCO">
<Code>AUMEL</Code>
</ClosestPort>
...
</OrgHeader>

eAdaptor - Developer’s Guide | 110

© 2024 WiseTech Global 11 March 2024
The Port Name and other fields are not included, just the Code which is sufficient to identify
the port in question.

4.1.7 Action attributes

When importing Native XML, Action attributes are used at each level to indicate what action
should be taken with the data provided. If there is no Action attribute at a given level, the data in
that item will not be used to update any records in CargoWise.

Elements from a parent with no Action attribute will only be used to obtain a candidate key to
identify an existing record at that level. In the case of an Organization this means that it would
use the Code to identify an existing Organization but would not then update the Name.

It is important to note that every item within the hierarchy of that entity set contains an Action
attribute. This attribute defines what operation to perform on that single data item only. Actions
are:

• Insert
• Update
• Merge
• Delete

Action attributes are not inherited, meaning that to delete an item all children must also have the
Delete attribute applied.

If a table has children that are not defined in the entity set, the system might reject the entity
deletion.

eAdaptor - Developer’s Guide | 111

© 2024 WiseTech Global 11 March 2024
Please keep in mind that without an action attribute, the data in that item will not be used to
update any data. The structure of an update data request is as follows:
<Native xmlns="http://www.cargowise.com/Schemas/Native/2011/11">
<Body>
<Organization>
<OrgHeader>
<Code>ABC1234</Code>
<Name>Some Organisation</Name>
<OrgAddressCollection>
<OrgAddress Action="UPDATE">
<PK>2E166A12-1834-4b94-BF30-E90E3A2176CF</PK>
<Address1>Some changed value</Address1>
<Address2>Some existing value</Address2>
</OrgAddress>
<OrgAddress Action="DELETE">
<PK>2E166A12-1834-4b94-BF30-E90E3A2176CF</PK>
</OrgAddress>
<OrgAddress Action="INSERT">
<Address1>New Address 1</Address1>
<City>Copenhagen</City>
</OrgAddress>
</OrgAddressCollection>
<OrgContactCollection>
<OrgContact>
<Name>Some One</Name>
<Phone>+61 430 000 000</Phone>
</OrgContact>
</OrgContactCollection>
</OrgHeader>
</Organization>
</Body>
</Native>

Every item that has an action of either ’Delete‘ or ‘Update‘ must contain an element that is a valid
candidate key for that data item. A candidate key could contain multiple columns according to
the definition of a given table. If there is more than one candidate key in the item, the system will
randomly choose a valid candidate key to find the item. There are very few tables with more than
one candidate key. Following is a simple example of updating an item with candidate key:
<Native xmlns="http://www.cargowise.com/Schemas/Universal/Native/2011/11">
<Body>
<Organization>
<OrgHeader Action='Update'>
<Code>ZAYZUBBNE</Code>
<FullName>Zayden Zubin</FullName>
</OrgHeader>
</Organization>
</Body>
</Native>

eAdaptor - Developer’s Guide | 112

© 2024 WiseTech Global 11 March 2024
4.2 Automated Native XML
The most powerful form of Native XML operation is one that happens automatically without user
interaction. With Native XML, both data Import and Export operations can be automated using a
group of Web Services and Service Tasks included with eAdaptor.

Native XML can be:

• Imported via eAdaptor SOAP/NMI Service Task

• Exported via Workflow/eAdaptor SOAP
• Imported via XNDT Web Service
• Queried (Exported) via XNDT Web Service

The two XNDT Web Service options are covered in the 2.6 XNDT Web Service Interface section
earlier in this guide.

The eAdaptor SOAP based options are described below.

4.2.1 Importing Native XML via eAdaptor SOAP

When you send Native XML in via eAdaptor to be imported, the Native XML data must be
wrapped in Universal Interchange XML for it to be recognized and processed in CargoWise. An
Interchange is like an envelope. It contains a Sender, a Recipient, and some outer level processing
information.

This Interchange envelope is removed when the Interchange is processed and split up into EDI
Messages. Like an ordinary envelope, one interchange can contain multiple XML messages, upon
processing each contained message will become one EDI Message.

There is an XSD schema for the Universal Interchange included when you export the schemas as
described earlier ion this guide. The Universal Interchange XML in its most basic form looks like
this:
<?xml version="1.0" encoding="utf-8"?>
<UniversalInterchange xmlns="http://www.cargowise.com/Schemas/Universal/2011/11" version="1.0">
<Header>
<SenderID>ABCDEFGHI</SenderID>
<RecipientID>CARGOWSYD</RecipientID>
</Header>
<Body>

</Body>
</UniversalInterchange>

You can generate your own sample XML to see how this works by exporting Native XML from one
of the modules supporting Native XML. Many of the modules under Maintain > Reference Files in
CargoWise support Native XML, for this example we will use the Containers module. Open a
Container and Export as Native XML as shown in section 4.3.1 Manually Exporting Native XML .

eAdaptor - Developer’s Guide | 113

© 2024 WiseTech Global 11 March 2024
Remove the “<?xml version="1.0" encoding="utf-8"?>” element line at the beginning of the file and
remove all child elements under the RefContainer element except the Code and Description.
Your file should look like this:
<Native xmlns="http://www.cargowise.com/Schemas/Native/2011/11" version="2.0">
<Header>
<OwnerCode>CARGOWSYD</OwnerCode>
<EnableCodeMapping>true</EnableCodeMapping>
</Header>
<Body>
<Container version="2.0">
<RefContainer Action="MERGE">
<Code>20GP</Code>
<Description>Twenty foot general porpoise</Description>
</RefContainer>
</Container>
</Body>
</Native>

The Code element will be used for matching to the existing Container row, and the Description
element will update the description on that row. You can see for the example above the word
‘purpose’ has been replaced with ‘porpoise’ so you can see a change made when the update
occurs.

Now you need to wrap the Native XML in a Universal Interchange so that it can be sent in via the
eAdaptor SOAP interface. Take the Universal Interchange sample and insert the Native XML in
place of the “” element.
<?xml version="1.0" encoding="utf-8"?>
<UniversalInterchange xmlns="http://www.cargowise.com/Schemas/Universal/2011/11" version="1.0">
<Header>
<SenderID>ABCDEFGHI</SenderID>
<RecipientID>CARGOWSYD</RecipientID>
</Header>
<Body>
<Native xmlns="http://www.cargowise.com/Schemas/Native/2011/11" version="2.0">
<Header>
<OwnerCode>CARGOWSYD</OwnerCode>
<EnableCodeMapping>true</EnableCodeMapping>
</Header>
<Body>
<Container version="2.0">
<RefContainer Action="MERGE">
<Code>20GP</Code>
<Description>Twenty foot general porpoise</Description>
</RefContainer>
</Container>
</Body>
</Native>
</Body>
</UniversalInterchange>

You now have Native XML wrapped in a Universal Interchange envelope ready to send in via
eAdaptor SOAP.

4.2.1.1 Sending a Universal Interchange in via eAdaptor SOAP

eAdaptor - Developer’s Guide | 114

© 2024 WiseTech Global 11 March 2024
Take the sample XML file you have just created and send it into your CargoWise system using the
Sample Client as described in section 2.4.3.1 Sample C# Web Client . Once you have done this,
you will be able to see the XML you sent in both the EDI Interchanges and EDI Message module.

4.2.1.2 Finding the XML Interchange and Message in CargoWise

When data from xHub or your own web service is received, it will be saved in the EDI
Interchanges module. If the XML is well-formed, and contains a recognizable Interchange with
recognized contained messages, those messages will be broken out into EDI Messages for further
processing.

You can see the incoming EDI Interchanges and EDI Messages in their respective modules in
CargoWise under Maintain>System as shown below.

Figure 49 Menu path Maintain > System > EDI Message

Refer to our learning unit 1COR193: How do I check data imports through EDI Messages?

eAdaptor - Developer’s Guide | 115

© 2024 WiseTech Global 11 March 2024
4.2.1.3 Processing Inbound EDI Messages
When Native XML first comes into the EDI Message Module, it has status of QUE (Queued). The
Native Messaging Inbound (NMI) service task picks up all queued messages and imports them in
the order in which they were received.

In order to have Native XML messages imported in a timely manner, ensure you have the NMI -
Native Messaging Inbound service task active and running.

Refer to our learning unit 1COR417 – Understanding Service Tasks?

As messages are processed, the status on each message will change to one of the following:

Status Description

PRS – Processed OK Message was processed successfully and was able to be

imported into the target module.

WAR – Processed with Warnings Message was processed with minor non-fatal issues. The
message was able to be imported into the target module.

ERR – Processed with Errors Message was process with data loss that should be
checked/reviewed. The message was able to be imported
into the target module but with some data loss.

DCD – Discarded – No Match Message was well formed but there was no matching job,
Found module or entity to import against. The message was not
able to be imported into a module.

REJ – Rejected Message was malformed or was missing mandatory data.

The message was not able to be imported into a module.

RKN – Recognized The status initially given to an incoming message upon

CW1 receiving it. This will be updated as the message gets
processed. If the status remains RKN, it is an indication
that there is an error, and the message was not processed
correctly.

eAdaptor - Developer’s Guide | 116

© 2024 WiseTech Global 11 March 2024
You can see in the following example one Container message that was processed successfully,
and one that failed according to the Status column. The first message is the sample previously
shown, the second is the same files, but with the Description element changed to have a value
that is over the maximum allowable length.

Figure 50 EDI Message Search Screen

Double click on a message in the module grid. You will see the detail of the message including the
XML itself and the processing result as a status code.

You can see that the Interchange wrapper has been removed when the XML transitioned from
the EDI Interchanges module to the EDI Message module.

Figure 51 Edit Message Details tab

eAdaptor - Developer’s Guide | 117

© 2024 WiseTech Global 11 March 2024
When you click on the Notes tab of a processed message, you will see a log showing details of
what happened when the message was processed.

Figure 52 View Message > Notes tab

In the above example, a Container was updated with the contents of the imported XML file.

You can also see when an update was made on the Container that was updated. If you open the
Container Type with a local code of 20GP in the Maintain > Reference Files > Containers
module, you will see a DIM Event on the Logs tab showing when Container data was imported.

Figure 53 Edit Container Type > Logs tab

eAdaptor - Developer’s Guide | 118

© 2024 WiseTech Global 11 March 2024
If the XML was missing mandatory segments, or unable to be imported for any reason, the status
will show as REJ – Rejected. Opening up the Rejected message from the EDI Messages module
shown previously, you can see an error message describing the reason for rejection on this Notes
tab of that message as shown below.

Figure 54 View Message > Notes tab

The error above says, “The value violates the MaxLength limit of the column”. This was because in
this example, the container name in the XML was extended to well beyond the maximum
allowable number of characters. There are many different reasons for message rejection, but
there should always be a message indicating what the problem is.

eAdaptor - Developer’s Guide | 119

© 2024 WiseTech Global 11 March 2024
4.2.2 Exporting Native XML via eAdaptor SOAP
Native XML can be sent automatically from any module supporting both Native XML and
Workflow Automation. Native XML generated via Workflow Automation can be sent from
CargoWise using the eAdaptor SOAP Web Service interface or via xHub as required.

To send Native XML automatically you will have:

• A Workflow Trigger configured on that entity that responds to that type of Event
• A Trigger Action on that Trigger that sends Native XML to a Recipient Organization
• An EDI Communications Mode on the Recipient Organization that says how to send the
XML (eAdaptor or xHub web service interface)
• An Event logged against the entity you want to send. Adding the Event starts the process
• The LWK (Log Walker) Service Task running to process the Workflow Trigger and Action.
(generates and queues the XML as EDI Messages/Interchanges for sending)
• The EAM (eAdaptor Outbound Messages) or EHO (xHub Outbound Messages) service task
running. (sends the queued XML from CargoWise via the nominated web service interface)

With all of these things in place, Native XML data can flow automatically in response to Events
raised in CargoWise through eAdaptor SOAP or xHub.

4.2.2.1 Workflow Configuration

Workflow Automation is a powerful set of tools available across many modules within CargoWise.
This guide provides an overview of the functionality available, gives information on workflow
functionality specific to this functionality, and a worked example so you can see it in action.

Workflow responds to Events by firing Triggers and closing Milestones which can both have
Trigger Actions on them. Trigger Actions cause automated functions to occur, one of them being
sending Native XML. All of these entities are pre-configurable on Workflow Templates so that
when a new entity or job is created, the Workflow Automation Configuration is populated from
those Templates.

Refer to our learning units:

1PRO003 - How do I create a workflow template?
1PRO005 - How do I set up Milestones in a Workflow Template?
1PRO007 - How do I set up Triggers in a Workflow Template?
1PRO008 - How do I create an XML file Trigger Action in a workflow template?

Normally you would configure Workflow Triggers and Trigger Actions using Templates as those
will populate to all new entities automatically. For this example, we will create the Workflow
Configuration on a single Organization to demonstrate how Events, Triggers and Trigger Actions
work together with EDI Communications Modes to send Native XML.

eAdaptor - Developer’s Guide | 120

Go to the Maintain > Reference Files > Organization module and open an Organization that you
would like to send. Select the Workflow & Tracking > Triggers tab and add a Trigger in the top
grid, and a Trigger Action in the bottom grid.

Figure 55 Workflow & Tracking > Trigger tab Completion Trigger Actions

Enter the following pieces of information as shown above:

Trigger > Description: (Action Authorized) Identified the sending Trigger, is included in the
outgoing XML in the TriggerDescription element of the DataContext.

Trigger > Event Code: (ATH) Identifies the type of Event the Trigger will respond to.

Trigger Action > Action: (XMN) Means Send as Native XML.

Trigger Action > Recipient: (ORP) The Organization Type to send the XML to. In this case it is set
to Organization Proxy which is the Organization associated with your registered Company in
CargoWise.

eAdaptor - Developer’s Guide | 121

© 2024 WiseTech Global 11 March 2024
Trigger Action > Purpose: (Blank) This is an optional user defined Purpose Code that is:

• Included in the outgoing XML in the Purpose element of the DataContext

• Used in the target system to know the intended purpose of the data being sent
• Optionally used to select a recipient address and transmission method from the EDI
Communications Modes configured on the Recipient Organization

With the above configuration, when an ATH Event is logged against this Organization, Native XML
will be sent to the Organization Proxy.

Record the Company code showing on the Trigger created. This will be used to find the right
Company Org Proxy.

Refer to our learning unit 1PRO008: How do I create an XML file Trigger Actions in a workflow
template?

4.2.2.2 Configuring EDI Communications Modes on the Recipient

Organization
The next step is to configure how the XML data (also known as EDI) will get sent to the Recipient
Organization.

EDI Communications modes are the EDI equivalent of a list of Contacts with Phone Numbers on
an Organization. When you want to call a company, you look for a Contact that has a matching
Title depending on the purpose of your call. Then you take the phone number for that contact
and call them.

When you choose to send XML, CargoWise looks for an EDI Communications Mode on the
recipient Organization with a matching Sending Module, Data Type, and Purpose Code. Where a
match is found, the XML is sent using the Communications Mode (eAdaptor or xHub) and
Recipient ID (Address) from the matching Communications Mode.

Refer to our learning unit: 1COR147 - How do set up EDI Communications?

eAdaptor - Developer’s Guide | 122

© 2024 WiseTech Global 11 March 2024
First step is to find the Recipient Organization, which in this case is the Company Org Proxy. Take
the Company Code you recorded from the Trigger you added and go to the Maintain > User
Admin > Companies module. Find the Company with the matching Code and open it.

Figure 56 Organization Proxy

You will see the Organization Proxy as shown above on the Company form. Click on the field to
select it, then press the F3 key to edit the Organization. This will be the Recipient Organization
when the Workflow Trigger Action is executed.

eAdaptor - Developer’s Guide | 123

© 2024 WiseTech Global 11 March 2024
The following shows how the Recipient Organization can be configured for this worked example
to send Native Organization XML out via eAdaptor with a Recipient ID of My3rdPartySystem.

Figure 57 Organization >EDI Communications tab

The values relevant to sending Native XML are:

Module: (ORG) Matched to the source module for the data. Organizations.

Comm. Direction: (TRX) Used when sending data. (Transmit)

File Format: (XML) Matched to the form of data we will send. XML or ALL match with Native XML.

Message Purpose: (blank) Matched to the purpose of the data being sent. (Blank means ‘Any’)

Comm. Transport: (EDP) Specifies the transport layer used to send. (eAdaptor/xHub)

Recipient ID: (My3rdPartySystem) Used for Recipient Addresses, is included in the Universal
Interchange in the RecipientID element. Also included in the ClientID attribute on the SOAP
Message element.

Email Subject: Value included in the EmailSubject attribute on the SOAP Message element.

File Name: Value included in the FileName attribute on the SOAP Message element.

Once you have this setup as shown, click the Save & Close button, and go back to the
Organization that you are trying to send.

eAdaptor - Developer’s Guide | 124

© 2024 WiseTech Global 11 March 2024
4.2.2.3 Raising an Event
Events are logged automatically by many actions performed by operators in their day to day
usage of CargoWise. They can also be sent in automatically from external sources (Customs,
Airlines, Ports, Shipping Lines etc.), or they can be raised manually by operators from the
Workflow > Events tab present in modules where Workflow is implemented.

Refer to our learning unit: 1PRO012 - How are Events automatically logged?

In this example, we will add an Event manually to demonstrate the process. Ideally, your
production system should be configured to use events that are already automatically logged in
the entity you are sending from.

Go to the Workflow & Tracking > Events tab of the Organization you are sending, right-click on
the Events grid and select Add New Event.

Figure 58 Workflow & Tracking > Events tab > Add New Event

Enter ATH as the Event Code, then click the Add Event button.

eAdaptor - Developer’s Guide | 125

Figure 59 Workflow & Tracking > Triggers tab

Save your changes. Now that you have an Action on a Trigger that has been triggered by an
Event, Workflow Automation will send a Native XML message via eAdaptor.

eAdaptor - Developer’s Guide | 126

© 2024 WiseTech Global 11 March 2024
4.2.2.4 Processing of Workflow Automation by the LWK Service
Task
In order for events to be processed and configured actions performed, the LWK – Event Log
Walker Service task must be active and running.

Refer to our learning unit 1COR417 – Understanding Service Tasks?

To check if the event has been exported, double-click on the LWK service task in the Maintain >
System > Service Tasks module, then click on the Log Files tab. You will be able to see these two
logs when your Event has been processed:

• [WorkflowEventTrigger] processing one logged event(s).

• [WorkflowEventTrigger] finished processing logs.

Figure 60 Edit Service Task > Log Files tab

You may see other events depending on what level of logging you have configured on your
service tasks, but the two logs mentioned above mean that your event was successfully picked
up and processed. If your Trigger Action and EDI Communications Modes are configured
correctly, you will then see an EDI Message and an EDI Interchange ready for the EAM service task
to send out.

4.2.2.5 Checking the EDI Message and Interchange

eAdaptor - Developer’s Guide | 127

Figure 61 Menu path Maintain > System > EDI Message

After selecting appropriate filters and clicking the Find button, you will see any Native XML that
have been exported but not sent with a status of AQU – eAdaptor Queued. This means they are
now waiting to be picked up and processed by eAdaptor.

Figure 62 EDI Message Search Screen

In this example, the service tasks were running, so the message had already been picked up
and sent.

eAdaptor - Developer’s Guide | 128

© 2024 WiseTech Global 11 March 2024
You can also see the EDI Interchange with its own status under the Maintain > System > EDI
Interchange Search screen using appropriate filters as shown below.

Figure 63 EDI Message Search Screen

Double click on the EDI Interchange to see the content of the Interchange. Within the View
Interchange window, click on the Save Body to Disk button to save a copy of the Interchange
sent.

Figure 64 View Interchange Details tab

In the example above, you can see the start of the Universal Interchange wrapping the Native
XML (highlighted in blue).

eAdaptor - Developer’s Guide | 129

© 2024 WiseTech Global 11 March 2024
Click on the Logs tab to see a log of when the message was generated, and when it was then sent
by the EAM (eAdaptor Outbound Messaging) or XTO (xHub Outbound) service task.

Figure 65 View Interchange Logs tab

Refer to our learning unit 1COR193: How do I check data imports through EDI Messages?

eAdaptor - Developer’s Guide | 130

© 2024 WiseTech Global 11 March 2024
4.2.2.6 Checking the EAM Service Task
If the EDI Interchange status is not changing from AQU (Queued for eAdaptor) to SNT (Sent), then
you should check the EAM Service Task logs. (For xHub, check the XTO service task instead) If all
goes well, you should see an Information row saying one interchange(s) sent to eAdaptor
Outbound Messages.

Figure 66 Edit Service Task > Log Files tab

If there is a problem, you may see an error or exception. If you click on the row with the error or
warning showing, you will see more information on the cause of the problem at the bottom of the
form.

eAdaptor - Developer’s Guide | 131

If you see an exception reported like this, it will generally be an exception thrown by your
eAdaptor SOAP Service Implementation, not by the service task itself. External exceptions
are logged here as an aid to development, but that does not mean the problem showing is
caused by the eAdaptor Service Task itself.

eAdaptor - Developer’s Guide | 132

© 2024 WiseTech Global 11 March 2024
4.3 Manual Native XML operations
Although Workflow Triggers give you a way to automate the export of Native XML data, you may
want to export data as a one-off action, either to generate test data or to export operational data
to then import into a local external tool.

4.3.1 Manually exporting Native XML

Open the form for the data record you want to export, and select the ’Export as Native XML’
menu item as shown below:

Figure 68 Actions Menu Manual Export Native XML

After selecting the Export as Native XML option, you will see a save file dialog where you can
change the file name and select the location to save the Native XML file.

eAdaptor - Developer’s Guide | 133

Click on the Save button after setting the file name and file path. A dialog will display the status
of the export process. A system prompt will display when the export is complete; click on the OK
button to continue.

Figure 70 System Prompt Export Process is Complete

4.3.2 Manually Importing Native XML

Go to the Module grid in CargoWise that you want to import the data file to, for example when
importing Organizations, you would go to Maintain > Reference Files > Organization.

Figure 71 Menu path Maintain > Reference Files > Organization

eAdaptor - Developer’s Guide | 134

© 2024 WiseTech Global 11 March 2024
Click on the Actions drop-down menu at the top of the tool bar then select Data Transfer >
Import Native XML, which opens the Import Form

Figure 72 Organization Search Screen

Figure 73 Import File Dialogue box

Click on the Import button to select the XML file you want to import. You will be prompted to
select a file to import.

Figure 74 Import File Location Dialogue box

eAdaptor - Developer’s Guide | 135

© 2024 WiseTech Global 11 March 2024
Select your file and click the Open button. To stop the process at any time, click on the Cancel
button.

Figure 75 Import File Dialogue box

During the import, if the XML file contains multiple entities, for example multiple organizations or
multiple airlines etcetera, each entity is saved to the database separately. This means that if an
error occurs in a single job the other jobs will still be saved to the database.

eAdaptor - Developer’s Guide | 136

© 2024 WiseTech Global 11 March 2024
4.4 Matching and translating
4.4.1 EDI Code Mapping
In CargoWise, the user can define a code mapping for a number of entity types. Native XML
Importing will translate these user-defined codes into local codes used in CargoWise on the way
in and translate to externally used codes on the way out.

You can enter these code mappings against any Organization in CargoWise through the
Organization module as shown below. From within the Edit Organization window, go to Details >
Config > EDI Code Mapping, then create an EDI Code Mapping for the Organization:

Figure 76 Organization > EDI Code Mapping tab

In example above, we have added a mapping for Port Codes so that where ABC is provided, it will
be mapped to ZAAAM. This mapping will come into effect when the OwnerCode supplied maps
to the Organization the mapping is entered against. In this case, it would be the Organization with
a code of YOUUNICHI.

After the above Code Mapping is created, the foreign code can be used when updating the entity
via Native XML.

For Code Mapping to take place, you must include the OwnerCode element in the header along
with the EnableCodeMapping element so CargoWise knows it should perform Code Mapping, and
which Organization it should get the Code Mapping configurations from. Below is an example to
update using the ’ABC‘ code we mapped above:

eAdaptor - Developer’s Guide | 137

© 2024 WiseTech Global 11 March 2024
<Native xmlns="http://www.cargowise.com/Schemas/Native/2011/11" version="2.0">
<Header>
<OwnerCode>YOUUNICHI</OwnerCode>
<EnableCodeMapping>true</EnableCodeMapping>
</Header>
<Body>
<UNLOCO>
<RefUNLOCO Action="UPDATE">
<Code>ABC</Code>
...
</RefUNLOCO>
</UNLOCO>
</Body>
</Native>

In the above example, the Native XML importer will translate ABC to ZAAAM and update the
corresponding record.

If EnableCodeMapping is true, the Local code used in CargoWise will be shown in the response
message where applicable:

<Native xmlns="http://www.cargowise.com/Schemas/Native/2011/11"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Status>Accepted</Status>
<EntityInfo>
<Name>UNLOCO</Name>
<LocalCode>ZAAAM</LocalCode>
<ExternalCode>ABC</ExternalCode>
</EntityInfo>
<Information>
<Item>Information - UNLOCO - 0 inserts, 1 updates, 0 deletes </Item>
</Information>
</Native>

Code Mapping also works on the OwnerCode itself. This allows you to map OwnerCodes supplied
by external systems to Organizations within CargoWise. Mappings at this level are entered on the
Company level Organization Proxy for the Company you are logged into and are applied before
trying to find the Organization that contains the EDI Code mappings for the rest of the elements.

Refer to our learning unit 1COR224 - How do I setup EDI Code Mapping?

eAdaptor - Developer’s Guide | 138

© 2024 WiseTech Global 11 March 2024
4.4.2 Organization Code generation
CargoWise generates Organization Codes from the Company Name and the main UNLOCO for
the Organization when you add an Organization using the Organizations form. When you import
an Organization using Native XML, the same thing happens.

If an Organization Code is supplied in the incoming XML, it is treated as an external code, not the
code to be used in CargoWise. A Code is generated and used for the import. Then if the import is
successful, a Code Mapping record is created linking the external code to the generated code on
the Organization itself. This mapping can then be found on the EDI Code Mapping sub tab
described above on the Organization found using the OwnerCode.

If you do not want the Organization Code to be generated and mapped as described above, you
must include the EnableCodeMapping element with a value of ‘false’ as shown below:

<Native xmlns="http://www.cargowise.com/Schemas/Native/2011/11 ">

<Header>
<EnableCodeMapping>false</EnableCodeMapping>
</Header>
<Body>
<Organization>
<OrgHeader Action="INSERT">
<Code>CODETOKEEP</Code>
<IsActive>true</IsActive>
<FullName>Codfish Tokai</FullName>
...
<ClosestPort eventleName="RefUNLOCO">
<Code>NZWKA</Code>
</ClosestPort>
</OrgHeader>
</Organization>
</Body>
</Native>

This will disable Code Mapping, which also turns off Organization Code Generation. Without Code
Mapping there would be no way to keep track of the link between externally supplied codes and
their internally maintained equivalents.

If you want to specify your own Organization codes when creating Organizations using Native
XML, you should disable Code Mapping as described above.

4.4.3 Code Lists

A number of Coded Lists exists within the CargoWise application. Most code fields are
represented in the database and in the schema as fields of type xs:string (char) with a max length
of three.

To assist with development, a list of all fields that use code lists is shown below. A number of lists
are hard-coded, in which case the exact values are provided, while a number come from the
system registry which can be accessed through the CargoWise application.

The development of a web service to retrieve the values of a registry or database defined
code/reference data list will be considered in Phase Two of the Native Data Transfer project.

eAdaptor - Developer’s Guide | 139

© 2024 WiseTech Global 11 March 2024
For a definition of the Code Lists used on the Organization Entity Set, go to Integration
Options – eAdaptor Guides

4.5 Database Schema and Field definitions

The Native XML schemas have a near identical model to that of the CargoWise database schema.
Diagrams explaining the standard CargoWise database schema can be used to understand the
hierarchical structure of the entity set data. Fields mappings and names are identical; however,
the two-character table identifying prefixes on each field name have been removed.

4.5.1 Tools for understanding Field definitions

To understand the context and meaning of a specific data element, the CargoWise application
can be used. By using the shortcut key combination CTRL-SHIFT-R on any field on any screen,
the actual data field name can be seen.

This field name will map to a field name within the entity set generated Xsd/Xml. As mentioned
previously, the only difference is that prefixes have been removed.

An example is shown below:The field OH_FullName will exist in the entity set schema as
FullName.

Figure 77 DataSource and Binding Member

eAdaptor - Developer’s Guide | 140

4.6 Importing and exporting Notes

Notes in Native XML are represented by StmNote elements within a StmNoteCollection. They
appear within a number of datasets as they are commonly implemented within CargoWise. There
are two types of notes you can have in CargoWise, Text Only and Rich Text Notes. These are both
represented by StmNote elements but use different elements with different kinds of content.

4.6.1 Note Types Registry setting

The Note Types for each module are configured in the Custom Defined Note Types registry item

Go to Maintain > System > Registry then open up the sub-tree System > Custom Defined Note
Types.

When a Note is imported via Native XML, the Note Type Description from the <Description>
element is used to try and find a Note Type in the registry for the target module. If the Note Type
is found in the Custom Defined Note Types registry item for the target module, or it matches a
pre-existing System Defined Note Type, and the Text Only flag is set for that Note Type, then that
is imported as a Text Only note.

For all other cases including notes with a Custom Description, the note will be treated as a Rich
Text Note. The registry item above affects Native XML and the GUI in different ways, but they
both have different behaviors for Plain Text and Rich Text notes.

4.6.2 Note Types in the GUI

Looking at the Notes tab on the Organizations form following you can see examples of three
different Note Types. The first one is Goods Handling Instructions.

eAdaptor - Developer’s Guide | 141

When that is selected, you will see that above the text box where you type your note, it says the
note is Text Only. This is the simplest way to tell which Note Types/Descriptions are Text Only.
You will see that there is no formatting available, and all you can enter is plain text.

When you select the Internal Work Notes note, the text entry section at the bottom of the form
changes to allow you to select fonts, colours, styles, and insert pictures.

Figure 79 Organization Notes tab

eAdaptor - Developer’s Guide | 142

© 2024 WiseTech Global 11 March 2024
This means that Internal Work Notes is a Rich Text note type. Both of these note types are pre-
defined system note types, the last type of notes are Custom notes.

When you turn on the Custom flag on a note, you are allowed to enter any Description/Note Type
you like as long as it doesn’t match a system defined note type. All Custom Notes are
automatically Rich Text notes.

4.6.3 Plain Text Notes

Plain Text notes include the text as a string in the NoteText elements as shown in the sample
following. These are much simpler to process both inbound and outbound.
<StmNote Action="MERGE">
<PK>7edf29e4-a875-4084-969a-e99ab5936e07</PK>
<Description>Goods Handling Instructions</Description>
<IsCustomDescription>false</IsCustomDescription>
<ForceRead>true</ForceRead>
<NoteData></NoteData>
<NoteText>Fragile. Keep upgright and dry. Stack 3 high max.</NoteText>
<NoteType>PUB</NoteType>
<NoteContext>AAA</NoteContext>
<RelatedCompany TableName="GlbCompany" />
</StmNote>

The NoteData element is not used in this case and will be empty.

4.6.4 Rich Text Notes

Rich Text notes include the note content as base64 encoded rich text in the NoteData element.
<StmNote Action="MERGE">
<PK>e6c6c5ba-495e-41fc-879e-e8ae615560f0</PK>
<Description>Internal Work Notes</Description>
<IsCustomDescription>false</IsCustomDescription>
<ForceRead>true</ForceRead>
<NoteData>
e1xydGYxXGFuc2lcYW5zaWNwZzEyNTJcZGVmZjBcbm91aWNvbXBhdFxkZWZsYW5nMTAzM3tcZm9udHRibHtcZj
BcZm5pbFxmY2hhcnNldDAgTWljcm9zb2Z0IFNhbnMgU2VyaWY7fXtcZjFcZm5pbCBNaWNyb3NvZnQgU2FucyBT
ZXJpZjt9fQ0Ke1wqXGdlbmVyYXRvciBSaWNoZWQyMCAxMC4wLjE1MDYzfVx2aWV3a2luZDRcdWMxIA0KXHBhcm
RcZjBcZnMyMFxsYW5nMzA4MSBZb3UgY2FuIHJlYWxseSBzdGFjayB0aGVzZSA2IGhpZ2guIFNwYWNlIHdpdGgg
YSBwYWxsZXQgZm9yIHNoaXBwaW5nLlxmMVxsYW5nMTAzM1xwYXINCn0NCg==
</NoteData>
<NoteText></NoteText>
<NoteType>INT</NoteType>
<NoteContext>AAA</NoteContext>
<RelatedCompany TableName="GlbCompany" />
</StmNote>

The NoteText element is not used for Rich Text Notes. The base64 encoded rich text in the
NoteData element shown above looks like this after it is base64 decoded.

{\rtf1\ansi\ansicpg1252\deff0\nouicompat\deflang1033{\fonttbl{\f0\fnil\fcharset0 Microsoft Sans

Serif;}{\f1\fnil Microsoft Sans Serif;}}

{\*\generator Riched20 10.0.15063}\viewkind4\uc1

\pard\f0\fs20\lang3081 You can really stack these 6 high. Space with a pallet for
shipping.\f1\lang1033\par

eAdaptor - Developer’s Guide | 143

© 2024 WiseTech Global 11 March 2024
You can see that the text that was entered is present in the decoded value but includes rich text
formatting and layout syntax around the text itself. Your application will need to be able to work
with raw rich text content if you want to consume or generate Rich Text notes. It will also need to
be able to encode and decode base64 byte streams.

4.6.5 Tips for Notes in Native XML

Anything we export, we import. This means that a practical way to find out how to work with an
existing Note Type is to create a dummy Organization for testing purposes, add some sample
notes using the Types you are interested and export them. While you are doing that, you can also
tell from the GUI what type of note you are dealing with for each Note Type/Description as per
the Note Types in the GUI section above.

When importing Notes, make sure you put the data in the right element for the Note Type
Description you are using with the right encoding. If in doubt, create a note of the type you want
to Import in the module you want to target, and export the XML to get a sample of how the
import file should look.

eAdaptor - Developer’s Guide | 144

© 2024 WiseTech Global 11 March 2024
4.7 Native XML Datasets
Each Native XML schema describes a single Native XML Dataset. Each dataset is tied to a given
module in CargoWise and contains a database-centric view of the data presented in that
module. This section contains a list of all available Native XML Datasets, instructions on where to
find the associated module for each in CargoWise and describes any significant differences
between how data is represented in the CargoWise GUI and the Native XML Schema.

As Native XML was designed for working with internal Reference File datasets, you will find most
of the associated modules under the ’Maintain‘ module tab within CargoWise. The schemas
themselves are obtained from your own copy of CargoWise following the instructions found in
section 3.1 Obtaining Current XML Schemas.

4.7.1 Reference Files

4.7.1.1 Airline
Schema File – NativeAirline.xsd

CargoWise Module – Maintain > Reference Files > Airlines

The Airline Dataset is related to the Airlines Master File which contains a list of all of the Airlines
used in the International Forwarding, Customs and Rating modules. There is no single unique
natural key for this table as none of the codes representing airlines are both mandatory and
unique.

4.7.1.2 CommodityCode
Schema File – NativeCommodityCode.xsd

CargoWise Module – Maintain > Reference Files > Commodities

The CommodityCode Dataset represents user defined categories of goods used across the
majority of modules in CargoWise. The natural key for this table is [Code], this is guaranteed
unique in the database.

4.7.1.3 Container
Schema File – NativeContainer.xsd

CargoWise Module – Maintain > Reference Files > Containers

The Container Dataset represents user defined types or categories of Containers. This is used for
all types of Containers including ULDs. The natural key for this table is [Code], this is guaranteed
unique in the database.

eAdaptor - Developer’s Guide | 145

CargoWise Module – Maintain > Reference Files > Currencies

Currencies are very rarely read or updated without referring to the associated exchange rates.
For this reason, Currency and Exchange Rate are all part of the one dataset. The dataset consists
of a list of Exchange Rates with a related Currency for each, along with the Company that the
exchange rate is related to. Both the Currency and Company are required values and are
identified using Code element from each.

4.7.1.5 DangerousGood
Schema File – NativeDangerousGood.xsd

CargoWise Module – Maintain > Reference Files > Dangerous Goods

The Dangerous Goods Dataset contains a set of standardized UNDG information that is used
across most modules within CargoWise.

There are two separate natural keys for this table, [Code] and [UNNO + Variant]. The two keys are
actually equal to each other, if you add UNNO and Variant, you get the value present in the Code
and vice versa. If you are sending in updates you will need to make sure you follow this pattern
and update both keys with the same value for the system to work properly.

Most interfaces only use this dataset as a lookup, when reading you can query by either key
without worrying about the other one. Both keys will of course be present in the resulting data.

4.7.1.6 Organization
Schema File – NativeOrganization.xsd

CargoWise Module – Maintain > Reference Files > Organization

The Organization dataset contains everything that a user can configure against an Organization in
CargoWise. This is quite a large dataset and has a few aspects that you will need to understand
to work with it effectively.

• Org. Code Generation – When you change the detail on an Organization in the CargoWise
user interface, by default the ’Code‘ used to identify the Organization is re-generated using
the first three letters of the first word of the company name, followed by the first three
letters of the second word of the company name, followed by the last three letters of the
UNLOCO for that Organization. This same functionality works when importing Organization
data using Native XML. As a side effect, this makes the Company Name and Closest Port
elements mandatory when creating a new Organization. Without these values, the code
cannot be generated, and the import will fail
• Keys and Code Mapping – The natural key for this Dataset is the Code, but if Code
Mapping is enabled using the OwnerCode and EnableCodeMapping elements in the Native

eAdaptor - Developer’s Guide | 146

© 2024 WiseTech Global 11 March 2024
Header element, then the code is mapped before it is used to find the target Organization.
Code Mapping also works in with Org. Code Generation so that even when a code is
provided, when a new Organization is sent in, a new code is generated from the Company
Name and Closest Port, and a Code Mapping record is automatically added. This maps
from the supplied code to the generated code so that the next time an Organization is sent
in with that code, it is automatically mapped to the same Organization
• OrgAddress (Address) Rows – Every Organization must have at least one OrgAddress
with it, and there is no place on the main Organization element to post Address details.
There should always be at least one ’Main‘ address which is identified by having a child
OrgAddressCapability element with an AddressType of ’OFC‘ and the IsMainAddress
element set. The natural key for an OrgAddress is the Code element which is generated
from the Address Details when entered in the GUI
• Company Specific Values – Settings entered on Organizations related to Accounting like
AR and AP settings are stored in the database per company. In the CargoWise GUI, you
only see the settings for the Company you are logged in under. In Native XML, as per the
underlying database structure, company specific values are found in the child
OrgCompanyData elements. In one CargoWise system, there may be multiple Companies
configuring their own AR and AP settings on the one Organization. Native XML is a Global
level system, so you will see one OrgCompanyData element for every Company that has
AR or AP settings configured on a given Organization. The Company element is mandatory
for each OrgCompanyData element and uses the child Code element to identify the
Company the data relates to. If no matching Company is found, the data is rejected

If you open any Organization in the GUI that has either the ’Receivables‘ or ’Payables‘ flag set on
the main tab and select Actions > Export as Native XML from the menu, you will see the patterns
described above so you can better understand how they work.

4.7.1.7 ServiceLevel
Schema File – NativeServiceLevel.xsd

CargoWise Module – Maintain > Reference Files > Service Levels

The Service Level Dataset represents Service Levels/Agreements used across the majority of
modules in CargoWise usually in conjunction with Rating. The natural key for this table is [Code],
this is guaranteed unique in the database.

4.7.1.8 Vessel
Schema File – NativeVessel.xsd

CargoWise Module – Maintain > Reference Files > Vessels

The Vessel Dataset is related to the Vessel Master File which contains a list of all of the Ocean
and Seafreight Vessels used in the International Forwarding, Customs and Rating modules. The
natural key for this table is [Code], this is guaranteed unique in the database.

eAdaptor - Developer’s Guide | 147

CargoWise Module – Maintain > Locations > Countries

The Country Dataset is related to the Country Master File which contains a list of Countries
identified by their two character ISO codes. The natural key for this table is [Code], this is
guaranteed unique in the database.

4.7.2.2 UNLOCO
Schema File – NativeUNLOCO.xsd

CargoWise Module – Maintain > Locations > UNLOCO

The UNLOCO Dataset is related to the UNLOCO Master File which contains a list of Locations
identified by a five character UNLOCO. The natural key for this table is [Code], this is guaranteed
unique in the database.

4.7.3 Performance Management

The schemas in this section are only relevant if you are using the PAVE Performance Management
system in CargoWise. If you cannot see this section in your CargoWise system and would like to
know more, please raise a CR9 eRequest.

4.7.3.1 AcceptabilityBand
Schema File – NativeAcceptabilityBand.xsd

CargoWise Module – Maintain > Performance Management > Acceptability Bands

The Acceptability Band Dataset is related to the Acceptability Band Master File used for
configuring Acceptability Bands for use on Buffer Boards. The natural key for this table is [Name],
this is guaranteed unique in the database.

4.7.3.2 BMSystem
Schema Filename – NativeBMSystem.xsd

CargoWise Module – Maintain > Performance Management > Buffer Management Systems

The natural key for this table is [Name], this is guaranteed unique in the database.

eAdaptor - Developer’s Guide | 148

CargoWise Module – Maintain > Performance Management > Tag Groups

The natural key for this table is [Code], this is guaranteed unique in the database.

4.7.3.4 TagRule
Schema Filename – NativeTagRule.xsd

CargoWise Module – Maintain > Performance Management > Tag Rules

The natural key for this table is [Name], this is guaranteed unique in the database.

4.7.4 Workflow Manager

4.7.4.1 WorkflowTemplate
Schema Filename – NativeWorkflowTemplate.xsd

CargoWise Module – Maintain > Workflow Manager > Workflow Templates

This dataset contains Workflow Template configuration data, which is used to setup default
workflow automation setups in new jobs and entities across CargoWise. The natural key for this
table is [Name], this is guaranteed unique in the database.

4.7.5 User Admin

4.7.5.1 Company
Schema Filename – Native Company.xsd

CargoWise Module – Maintain > User Admin > Companies

This dataset contains information about Companies licensed to used CargoWise that is present
in that Company’s CargoWise instance. The natural key for this table is [Code], this is guaranteed
unique in the database.

eAdaptor - Developer’s Guide | 149

CargoWise Module – Maintain > User Admin > Staff and Resources

This dataset contains basic information from the Staff module within CargoWise. Please note that
this does not include the user security tree controlling what a user has access to, but it does
include the groups they belong to (recommended way to control security). The natural key for
this table is [LoginName], this is guaranteed unique in the database.

4.7.6 Other
4.7.6.1 Product
Schema Filename – NativeProduct.xsd

CargoWise Module – Maintain > Customs > Customs Files > Products

This dataset contains Product information that is used by the Customs modules for classification
information, and Warehouse modules for identifying and tracking inventory. Matching to existing
Products is done using a combination of the PartNum and Organizations identified in the
OrgPartRelationCollection.

4.7.6.2 Rates
Schema Filename – NativeRate.xsd

CargoWise Modules –

• Manage > Tariffs & Rates > Client Rates

• Manage > Tariffs & Rates > Company Tariffs
• Manage > Tariffs & Rates > Costing
• Manage > Tariffs & Rates > Quotations

As you can see from the list of modules above, the Rate Dataset covers most of the modules in
the Tariffs & Rates product area. That is possible as all of these modules share a common table
structure, and the Native XML engine works from table structures, not the coded business
objects the modules themselves use.

The RateType and RecipientRole elements contained within incoming Native Rate XML determine
which module will be targeted when the dataset is imported.

Refer to the following update notes for more information regarding Native Rate XML.
3 Feb 2015 - Rates Automated Native XML
4 May 2016 - Rates Automated Native XML – Base Company Tariff

eAdaptor - Developer’s Guide | 150

CargoWise Modules – Used for some Country’s Customs Systems.

• US – Customs > Customs > Statements/ACH Payments

• ZA – Customs > Customs > Customs Statement

Some Countries Customs Authorities choose to send periodic statements for deferred and client
settlement accounts which are managed in the modules listed above. These can be exported
using the Native CusStatement dataset where clients want to make this data available in a
secondary system.

5. Universal XML (Refer to Universal XML

Guide)

The content in this section is no longer being updated and will be deleted as we move
towards the Universal XML Guide. For more current information on Universal XMLs please
refer to the Universal XML Guide in WiseTech Academy.

5.1 Concepts
5.1.1 Overview
Universal XML schemas are CargoWise schemas that apply across multiple areas or modules in
CargoWise. Unlike the Native XML schemas, which contain every piece of data available from that
reference module only, Universal XML schemas contain information from multiple areas in
CargoWise represented in a more generic and universal data structure.

The advantage of the ‘Universal’ approach we used defining our Universal XML schemas is that by
mapping your data into one common schema, you can import into and export from many
different areas or modules within CargoWise.

Universal XML schemas include all possible fields from all modules that have been mapped, so
the schemas are quite comprehensive. At first glance, the schemas seem quite large, but we do
not duplicate the same fields twice on any element, and we only include elements mapped to or
used in a particular module when exporting data. Although the schemas are broad to cover all
modules, the datasets are smaller than the schemas tend to indicate.

eAdaptor - Developer’s Guide | 151

© 2024 WiseTech Global 11 March 2024
All dates and times included in Universal XML are in local time. Local time is generally in relation
to the Company sending the data, but there are some exceptions where there is a location
associated with the date/time. Examples of this are Departure Date and Arrival Date, which will be
in the time zone indicated by the Origin and Destination UNLOCOs.

5.1.2 Universal Data types

Universal Shipment - This can represent a Consolidation, Consolidation with Shipments, a
Shipment, Shipment with Sub shipments, a Declaration, Shipment and Declaration pair, a
Forwarding Booking, a Transport Booking, or any data type that can be related to a Freight
Movement throughout CargoWise. The dataset includes Shipment data, Transport Legs,
Commercial Invoices, Packing Information, and Customs Entries.

Universal Event - These are used to record and publish events that occur in the life of a given
job or entity. They contain an Event Type, the date the event occurred, or in the case of an
estimated event, the date the event is estimated to occur on. They also contain a list of ‘Context’
values that identify what the event applies to and provide supplementary information about the
event.

Universal Activity – Represents the operational entities from the PAVE modules including the
Customer Service Ticket, Project, and Work Item modules.

Universal Accounting Transaction - Represents any form of Accounting Transaction including

Invoice, Credit Note, Payment, and Journal.

Universal Accounting Batch - Is a batch of accounting transactions, contains a Batch Reference

and a list of Accounting Transactions. Once generated can be requested by Batch Reference, but
not imported.

eAdaptor - Developer’s Guide | 152

© 2024 WiseTech Global 11 March 2024
5.1.3 DataContext element
Universal XML schemas have a DataContext element at the top. This is used to describe where
the Universal Data came from when exporting XML, and is used when importing XML to describe
how the data should be applied within CargoWise. This element is optional for data coming into
CargoWise, but is always present when data is exported from CargoWise. Shown below is the
DataContext element from a Universal Event exported from a Forwarding Shipment:

<DataContext>
<DataSourceCollection>
<DataSource>
<Type>ForwardingShipment</Type>
<Key>S00001006</Key>
</DataSource>
</DataSourceCollection>

<ActionPurpose>
<Code>APP</Code>
<Description>As Per Payload</Description>
</ActionPurpose>
<Company>
<Code>SAM</Code>
<Name>Sample Company Inc.</Name>
</Company>
<EnterpriseID>CGW</EnterpriseID>
<EventType>
<Code>AED</Code>
<Description>All Export Documents Received</Description>
</EventType>
<ServerID>SYD</ServerID>
<TriggerCount>1</TriggerCount>
<TriggerDate>2011-06-07T09:46:17.433</TriggerDate>
<TriggerDescription>EXPORT DOCS RECEIVED</TriggerDescription>
<TriggerType>Trigger</TriggerType>
</DataContext>

The elements shown above are broken into functional groups as described in the following
sections.

5.1.4 DataContext when exporting XML

When Universal Data is sent from a CargoWise system, the DataContext element contains
enough information to uniquely identify the entity being exported globally. To do this, you use a
combination of elements included in the DataContext to make up a globally unique key as
follows:

• EnterpriseID - Three-character code identifying a group of companies globally

• ServerID - Three-character code identifying a server used by a group of companies. The
combination of EnterpriseID + ServerID gives you a globally unique code for a CargoWise
installation
• Company.Code Three-character code identifying a company registration on a CargoWise
installation. For modules where there are separate job number streams per company, you
would need to include this code as part of the key. For global modules like Forwarding, this
would technically not be required

eAdaptor - Developer’s Guide | 153

© 2024 WiseTech Global 11 March 2024
• DataSourceCollection - Elements in the DataSourceCollection contain DataSource Types
and Keys identifying which job or entity the Universal Data was generated from. The Type
identifies the CargoWise module; the Key is a job or entity reference unique to the
CargoWise installation

The combination of these elements can be used to globally identify the source of any Universal
XML. The Enterprise ID and Server ID uniquely identify a particular system, and the Company
Code plus DataSource identify the source entity within that system

5.1.4.1 DataSourceCollection elements

In XML exported from CargoWise, the first element in the DataSourceCollection always identifies
the source of the data for the Top Level Universal Shipment. This first element is always added by
CargoWise on any Universal Shipment or Event.

If there is only one DataSource in the collection, then the Universal Shipment contains data from
that data source in CargoWise including all child and related Universal Shipments. A good
example of this would be a Forwarding Consolidation with a collection of all its child Forwarding
Shipments in the SubShipmentCollection.

Additional DataSource elements can be added on the Top Level DataContext element. (i.e., not in
DataContexts on Universal Shipments in the SubShipmentCollection) When this happens, it
means that a subset of data has been exported from CargoWise, not a complete set. The
additional DataSource elements identify the DataSource (or DataSources) of SubShipments that
contain complete data within the set.

An example of where this is used is for Forwarding Shipments where there is a parent
Consolidation. When a Forwarding Shipment is exported, the Top Level Universal Shipment will be
created using data from the Consolidation. The Forwarding Shipment itself will be included as a
Universal Shipment in the SubShipmentCollection. Any other Forwarding Shipments on the
Consolidation will not be included in the SubShipmentCollection.

In this case, the DataSourceCollection on the Top Level Universal Shipment contain a reference
to the Consolidation and the Forwarding Shipment, and the DataSourceCollection on the
Universal Shipment in the SubShipmentCollection will contain a reference to the Forwarding
Shipment. This setup allows you to tell which Shipments, Sub-Shipments, or even Sub-Sub-
Shipments contain complete data including all children.

The advantage of working this way is that when processing the incoming data, you know that you
always have all parent information. It doesn't matter if you export from a Consolidation, a
Shipment, or a Sub-Shipment, you always work with the same top down structure starting at the
top and including everything relevant to the level you are exporting. In the words of our Architect,
“It's Shipments all the way down”.

5.1.4.2 Workflow Trigger Action Information

As well as showing what CargoWise system and which Job/Entity in CargoWise data comes from,
the DataContext also has information about the Workflow Trigger Action that caused the export

eAdaptor - Developer’s Guide | 154

© 2024 WiseTech Global 11 March 2024
of Universal XML. The following elements are completed from the Trigger Action configured to
send Universal XML and its parent Milestone, Trigger, or Exception:

• <ActionPurpose> - This is taken from the Purpose field on the Trigger Action. This element
includes sub elements containing the Purpose Code and its associated description. New
Purpose Codes can be defined under Maintain > EDI Messaging > Purpose Code and allow
you to include an Intended Use or Purpose for the data you are sending
• <EventType> - On the Milestone, Trigger, or Exception, there is an Event field where you
can enter an Event Code. This element includes sub elements containing the Event Code
and its associated description
• <EventUser> - The user who added the Event that tripped the Trigger or Milestone. Allows
you to know who performed the action that resulted in the Universal XML being sent
• <TriggerCount> - Contains the number of times the Milestone, Trigger, or Exception has
been fired so far. The count starts at ‘1’ and increments for every export so you have a Send
Count or Data Version Number in the receiving system
• <TriggerDate> - Event time of the Triggering Event.
• <TriggerDescription> - The Description field from the associated Milestone, Trigger, or
Exception
• <TriggerType> - Contains either Milestone, Trigger, or Exception depending on the type of
Workflow entity the Trigger Action is defined against. TriggerType will be “Manual” when the
XML get generated by a user action using “Send Universal XML” option in CW.
• <Company> - Is the Company from the Trigger or Milestone that caused the Universal XML
to be sent. Each Trigger or Milestone in CargoWise has a Company Code against it in the
grid. For more information on Triggers and Milestones

Refer to our Workflow learning units for more information on the Workflow entities mentioned
above.

5.1.5 DataContext when importing XML

When importing Universal XML into CargoWise, the DataContext is used to describe how the data
should be applied within CargoWise. The content of the DataContext is used to determine:

• The Company to import the XML under

• The Module(s) to import the XML into
• Which Job/Entity to Update
• Code Mapping options

eAdaptor - Developer’s Guide | 155

© 2024 WiseTech Global 11 March 2024
5.1.5.1 Targeting a Company
To target a Company, you need to identify the Company in the DataContext using the following
elements:

• EnterpriseID – Three-character code identifying a group of companies globally.

• ServerID – Three-character code identifying a server used by a group of companies.
• Company.Code – Three-character code identifying the company you want to target
within a CargoWise installation.

The combination of EnterpriseID + ServerID + Company.Code provides a globally unique code for
a particular Company within the target CargoWise installation. The Company Code is ignored
unless all three values are provided, and they match to a valid Company registered within the
target system.

5.1.5.2 Targeting a Branch (Universal Shipment only)

When importing a Universal Shipment, there are a series of fallbacks used to select the branch
used when processing the XML content.

1. Match using the Branch.Code element from the Universal Shipment.

2. Match the ’Recipient‘ OrganizationAddress to a Branch Org Proxy.
3. Match the ’Recipient‘ OrganizationAddress Port to a Branch Port/Additional Related Port.
4. Match using a Recipient Role and Port Code Match.
5. Default to the first branch of the target Company.

Options 1 through 3 are useful when sending Universal Shipments from middleware applications
to CargoWise.

Option 4 provides the best functionality for our E2E product.

Option 5 is the fallback where none of the first four options are able to be applied.

The Branch selected will affect things like Job Number generation where the system is
configured to use the creating branch as part of a Job Number.

5.1.5.2.1 Option 1 - Specifying the Target Branch in the “Branch” Element

If you include the target Branch Code in the Universal Shipment XML, and the Company Code,
Server ID and Enterprise Code from the DataContext element match the target system, and the
branch code matches an active Branch, then that is the Branch that will be used when importing
that XML.

eAdaptor - Developer’s Guide | 156

CargoWise looks for an OrganizationAddress with an AddressType of ‘Recipient‘ within the

Shipment.OrganizationAddressCollection element. The ’Recipient‘ AddressType is not generated
in messages sent from CargoWise but can be added using middleware. This allows the targeted
CargoWise system to know the intended recipient branch.

When importing the Universal Shipment, CargoWise attempts to match the ’Recipient‘
OrganizationAddress to an organization within the target system. If a match is found via Code
Mapping or Address Matching, and the matched organization is configured on a branch as that
branch’s Org Proxy, that branch will be used when importing the Universal Shipment.

5.1.5.2.3 Option 3 - Recipient Related Port Match

When the ’Recipient‘ OrganizationAddress is included using middleware as described in Option 2,

and there is a UNLOCO specified, that UNLOCO will be used to try and locate a branch with a
matching ’Home Port‘. Branches can also have ’Additional Related Ports‘ entered on them
indicating other ports also handled by that Branch. These are also used when trying to locate a
matching Branch.

Figure 80 Edit Branch > Additional Related Ports

eAdaptor - Developer’s Guide | 157

Where no Branch is found using the Branch element or by using the ’Recipient‘
OrganizationAddress, then a Branch will be calculated using a combination of Recipient Role
elements from the data context collection, and the Ports present in the Universal XML.

This import will only match to branches on the target company when performing this kind of
match. If the branch does not exist against that company, then the system will move to the
next fallback.

Examples of this include:

Recipient Role Ports used for Match

Sending Agent (SAG), Export Broker (BRE) Port of Loading then Port of Origin

Receiving Agent (RAG), Import Broker (BRI) Port of Discharge then Port of
Destination

Departure CFS (DCF), Departure Carrier (DCR), Port of Loading

Departure CTO (DCT), Departure Container Yard
(DCY)

Arrival CFS (ACF), Arrival Carrier (ACR), Arrival CTO Port of Discharge
(ACT), Arrival Container Yard (ACY)

Consignor (CNR) Port of Origin

Consignee (CNE) Port of Destination

5.1.5.2.5 Option 5 - Default the first Branch of the Target Company

The last resort for Branch Defaulting is to pick a random active branch from the Company the
message was sent to. This functionality only exists as we need some sort of default for the
circumstance where none of the above matching options were successful. The only other option
would be to reject the message outright, which we do not consider a viable alternative as there is
then no way to get the data into your system.

eAdaptor - Developer’s Guide | 158

© 2024 WiseTech Global 11 March 2024
5.1.5.3 Targeting a module
Incoming Universal XML could potentially apply to many modules throughout CargoWise as the
same schemas are mapped to multiple modules. There are two ways to target a module. One is
to specify a RecipientRole that is recognized by a given module, the other is to specify a
DataTarget in the DataTargetCollection which forces the module to process the data.

The DataTarget in the DataTargetCollection is not used when sending data from CargoWise, but
is used when importing Universal Data into CargoWise.

DataTargets allow you to specify which module or modules should be updated by the incoming
data. Each DataTarget has a mandatory Type, which, like elements in the DataSourceCollection,
relates to a Module within CargoWise.

You can optionally include a Key in a DataTarget, but that is not required unless you want to
match to existing entities in that module by entity reference (e.g., job number).

5.1.5.4 Targeting a Job by Entity Reference (for example, Job

Number)
If you include a DataTarget element, and you also provide a Key as part of that DataTarget, that
Key will be used to match to an existing entity in the module. If an entity does not exist with that
key, the XML Import will be rejected as no entity was found.

More information on the matching process follows below in ‘Context Key Matching on Import’.
There are more forms of matching that can be used when updating existing data, information on
which keys are used in which module is detailed in the Module Mapping Guides.

Module Mapping Guides describe the keys used for matching, give an overview of how the
schema is mapped, and provide a list of element level mappings describing each field’s
location in the GUI. They can be found under in WiseTech Academy under Integration
Options – Mapping Guides

eAdaptor - Developer’s Guide | 159

© 2024 WiseTech Global 11 March 2024
5.1.5.5 Code Mapping options
The DataProvider element is an optional element that can be used to identify the source or
provider of the data. Code Mapping looks at this element and tries to find an Organization within
the target CargoWise system it can use to draw Code Mapping configuration from.

First, Code Mapping looks up the Company Org Proxy for the Company selected as described in
Targeting a Company above. If the DataProvider element is present, and the value is present in
the code mapping against the Company Org Proxy pointing towards an Organization, then that
Organization is used as a Code Mapping configuration source. If no Organization is found, then
the Company Org Proxy itself is used as a Code Mapping configuration source.

The CodesMappedToTarget element is used to indicate that Code Mapping is not required as the
codes provided already match those used in the receiving Company’s system.

More information on Code Mapping is available in section 4.4.1 EDI Code Mapping of this
document.

5.1.6 Link Elements

XML is a good data type for representing a tree based data structure. Related elements can
easily be represented by child elements, and one-to-many parent-child relationships can be
represented as a sequence of typed elements within a ‘Collection’ sub element.

XML does not intrinsically describe cross relations between child elements. For this reason,
where relations between branches in the tree are required, we have used our own standard built
around integer based Link elements across Universal XML.

Cross relations utilize a Link element on the parent element with an integer value used to identify
that parent element uniquely within the file. These are not added to every element type, just to
those where there are other elements relating to these.

The child element in the relationship will have an element on it with the name made up of the
parent type being related to plus the suffix Link. Where the same integer value is present in a
parent's Link element, and a child's [ParentType]Link element, a relationship is implied.

As an example, the following relationship exists within Universal Shipment XML:

Parent: OrderLine.Link

Child: CommercialInvoiceLine.OrderLineLink

The relationship implied may be one-to-one, it may be many to many. There is no change in
notation for either of these cases. The values used in Link elements are not persisted between
sends, but they are guaranteed unique per Parent Type within each serialized Universal XML
message.

eAdaptor - Developer’s Guide | 160

© 2024 WiseTech Global 11 March 2024
Right now, types have only been required in the Universal Shipment XML Dataset. The following
table is a list of Links currently implemented for the Universal Shipment.

Parent Children

OrderLine.Link CommercialInvoiceLine.OrderLineLink
PackedItem.OrderLineLink

AdditionalBill.Link InBondMoveDetail.AdditionalBillLink

Container.Link InstructionContainerLink.ContainerLink
PackingLine.ContainerLink
ContainerLink.Link * see Note 1 below

CommercialInvoiceLine.Link PackedItem.CommercialInvoiceLineLink

EntryInstruction.Link CommercialInvoiceLine.EntryInstructionLink
EntryHeader.EntryInstructionLink

PackingLine.Link InstructionPackingLineLink.PackingLineLink

TransportLeg.Link Confirmation.Leg.Link * see Note 2 below

Note 1: This particular case does not include the Parent Type as part of the Link element
name as this is a many to many relationship where the parent type itself is already named
ContainerLink. In usage, the ContainerLink.Link element is used in a collection on the
InBondMoveDetail describing the many to many relationship that exists between these two
entities.

Note 2: This was an early use of the Link functionality which was implemented before the
standard naming convention was settled on. The only kind of ‘Leg’ in the schema is the
TransportLeg, so it was deemed better to accept this exception to the rule rather than break
existing interfaces relying on the current state of affairs.

eAdaptor - Developer’s Guide | 161

© 2024 WiseTech Global 11 March 2024
5.1.7 CollectionContent attributes and importing
Collections
The default behavior of collections within Universal XML is that where they are included, they are
seen as a complete replacement for any rows existing in the target module. New rows are added,
existing rows are updated, and rows not included in the supplied XML are removed or deleted.
This is known as a ‘complete’ replacement.

There is one notable exception to this default behavior which is the SubShipmentCollection. The
Shipments in this collection are only ever used to add or update existing rows, never remove
them. Partial SubShipment information is commonly provided in a Universal Shipment. For that
reason, this collection defaults to a ‘partial’ replacement where rows not included in the XML are
left as is.

Although all collections have a default behavior (either complete or partial update), some
collections allow you to specify on import whether the data you are providing is a complete
representation of the collection, or only a partial representation of the collection. This is done
using the CollectionContent attribute, which can have a value of either Complete or Partial.

By stating that the collection contains partial information, you are saying there may be other data
in this collection that you have not included, so rows you don’t include in the XML will be left
alone. If you define it as a collection with complete information, any rows present in the database
that are not included in the collection will be deleted.

The CollectionContent attribute is defined in the XSD on all collections that allow its use.

5.1.7.1 ‘Complete’ CollectionContent update behavior

There are two methods that can be used for a complete replacement. The method used depends
on whether or not there is a natural key for a given collection. A natural key is a value that
uniquely identifies the context of an incoming row, like a container number for containers, or line
number for order lines.

Where there is a natural key, elements supplied are matched to existing rows. Rows are updated
when a match is found, added when not found. Where rows exist with no match in the elements
from the collection, they are deleted.

Where there is no natural key, there is no way to match to existing data, so any existing rows are
deleted, then the elements in the collection are used to build new rows in their place.

Both of these complete replacement methods bring the data in CargoWise in line with the data
provided in the XML.

eAdaptor - Developer’s Guide | 162

© 2024 WiseTech Global 11 March 2024
5.1.7.2 ‘Partial’ CollectionContent update behavior
Like the complete replacement, there are two methods that can be used depending on whether
or not there is a natural key for a given collection. Both methods are identical, except that when
executing a partial replacement, rows not included in the XML are left alone instead of being
deleted.

Where there is no natural key, there is no way to match to existing data. As there is no way to
match to existing rows to update, and unmatched rows will not be deleted, in this case all
elements in the collection are used to create new rows. This is not an option to be used lightly, as
multiple sends with the same data will cause the same rows to be added multiple times.

5.1.7.3 Collections Supporting the ContentCollection Attribute

Following is a list of all collections supporting the ContentCollection attribute, along with the
default natural key. All of these are from the Universal Shipment schema. This functionality is
generic and can be supported in any Universal schema but is only used in the Universal Shipment
XML at this point.

Collection Default Natural Key

Shipment.AdditionalReferenceCollection Type + ReferenceNumber

Shipment.ContainerCollection ContainerNumber

Shipment.PackingLineCollection Module specific, refer to following note.

Shipment.NoteCollection Description + NoteContext

Shipment.Order.OrderLineCollection LineNumber

Shipment.InBondMoveHeaderCollection. Type + ReferenceNumber

InBondMoveHeader.AdditionalReferenceCollection

eAdaptor - Developer’s Guide | 163

© 2024 WiseTech Global 11 March 2024
The default natural keys shown above are used in most modules importing Universal XML,
however each module can override the natural key to suit its own particular business case.

For more specific descriptions of the natural keys used for collections, please refer to the Module
Mapping Guide for that module. These can be found on our myaccount web portal in the
CargoWise Technical Reference Guides section along with this document.

In the case of Packing Lines, there is no default behaviour. The Forwarding Shipment module
implements some very specific matching behavior which is described in the Update Note:
Updating multiple pack lines through Universal Shipment XML.

5.1.8 Customized Fields

CargoWise allows users to define Customized Fields as an extension of most operational
modules within the product. These can be configured in three different ways for three different
business cases.

1. Using the Custom Fields tab on the Workflow Template configuration form (All modules at
the Shipment level).
2. For an Organization by defining a Customized Label configured from the Custom >
Customization tab. (Specific modules at various levels)
3. From the Custom Attribute settings in the Registry (Specific modules at various levels).

For more information on how to configure Custom Fields, Customized Labels, or Custom
Attributes, please see the relevant guides from WiseTech Academy.

All three types of Customized Fields are represented the same way in Universal XML. These are
represented as collections of CustomizedField elements, each containing a Field Name (Key) with
the Value and DataType elements to describe the content contained within.

CustomizedFieldCollections are found as sub elements of the following element types:

• Shipment
• Container
• PackingLine
• TransportLeg
• OrderLine
• CommercialInvoiceHeader
• CommercialInvoiceLine
• Instruction

eAdaptor - Developer’s Guide | 164

© 2024 WiseTech Global 11 March 2024
5.1.8.1 Exporting Customized Fields
All types of Customized Fields available on a given entity are exported as Universal XML. They are
added to the outbound collection one after the other, order is not guaranteed. If two different
Customized Field mechanisms define the same Key (label), the first value found with that key will
be exported starting with the Customs Attributes then the Customized Labels, then the Workflow
Custom Fields.

5.1.8.2 Importing Customized Fields

When importing Customized Fields, there is one collection of incoming values, but there are three
different mechanisms used for configuring and in fact storing those values. Different mechanisms
are used in different locations across CargoWise. Their usages are covered in more detail in the
content available for each module from our myaccount Web Service Portal.

Importing follows the same logical sequence no matter which mechanisms are used. For each
Key and Value provided as part of a CustomizedField element, the steps below are followed:

1. Where Custom Attributes are available and there is an Attribute defined with the Name
matching the Key provided, the Value is imported as a Custom Attribute and nothing else.
2. Where Customized Labels are available and there is a Customized Label defined with the
Label matching the Key provided, the Value is imported as a Customized Label and nothing
else.
3. If Workflow Custom Fields are available, the Value is imported as a Custom Field regardless
of whether there is a Custom Field defined with the Name matching the Key provided or
not.

Workflow Custom Fields allow for values that are note configured to be stored, displayed, and
edited. For this reason, where Workflow Custom Fields are available, non-configured Customized
Field values can be imported. When values are removed in the GUI from non-configured
Customized Fields, the fields will no longer appear after the parent entity is saved.

5.1.9 Dates and Timezones

Most date and time fields in CargoWise do not have a time zone directly recorded against them.
When they are recorded in the database, there is no way to set and record the time zone. This is
consistent across the vast majority of date and time fields in CargoWise.

This may seem strange considering CargoWise is a globally scaled logistics package with a
comprehensive International Freight Forwarding module built in. This was a design decision made
to facilitate interoperability with global data feeds and messaging systems.

The Universal XML interface is consistent with the application. This means that datetime
elements in Universal XML do not include a time zone offset on export. Any time zone offset
included within a datetime element in Universal XML being imported is ignored as there is no
place to store it.

eAdaptor - Developer’s Guide | 165

© 2024 WiseTech Global 11 March 2024
5.1.9.1 Global Data Feeds
There are many data feeds within the global logistics ecosphere where no time zone is provided.
If we built CargoWise requiring a time zone, we would not be able to accurately process these
feeds unless we had a location for each date/time provided so we could calculate the time zone.
This is often not provided in those feeds.

In the airfreight domain, many types of FSU status messages do not have the time zone. Airline
departure and arrival schedules are published in the local time of each airport, or “port time” as
are Seafreight, Road and Rail schedules. Cutoff times, Availability times and Slot dates are all
published with no time zone as they are all tied to a port which infers the time zone.

If we required a time zone for all date and time based fields in CargoWise, we would not have
been able to integrate as many data feeds as we do. The question then arises, “How do we deal
with time zones for transit time calculations?”

5.1.9.2 Calculating Time Zones Where Required

Because different external interfaces have different date, time and time zone requirements,
datetime translation is done within the middleware.

In all International modules within CargoWise, for each date/time entered, there is a
corresponding location that is provided. The location relating to each date/time field infers the
time zone for that field. This means that the Time of Departure is entered assuming the time zone
of the Port of Departure, and Time of Delivery is entered assuming the time zone of the Port of
Delivery.

We use UNLOCOs to describe locations within CargoWise. If you need a UTC time, or a time
including the time zone, you can use the associated UNLOCO to calculate the time zone offset.
This offset can then be appended to the datetime to give a datetime with time zone offset or
subtracted from the datetime value to give a UTC time.

As an example, if the Port of Arrival was AUSYD (Sydney, Australia), the time zone offset would be
+10 and would be applied as follows.

Datetime from CargoWise: <ArrivalDate>2012-04-13T11:00:00</ArrivalDate>

With time zone +10 added: <ArrivalDate>2012-04-13T11:00:00+10</ArrivalDate>

Or converted to UTC: <ArrivalDate>2012-04-13T01:00:00Z</ArrivalDate>

5.1.9.3 Universal XML Elements that Have a Time Zone

There are currently no Universal XML elements that have a time zone. There are no fields within
CargoWise that allow setting of a time zone along with the date and time that have been mapped
to a Universal XML dataset.

eAdaptor - Developer’s Guide | 166

© 2024 WiseTech Global 11 March 2024
5.2 Sending Universal XML
5.2.1 Overview
Previous XML messaging systems implemented in CargoWise used transmission methods such
as Email, FTP, or manually saving a file to a specified location. All of these methods are ‘store and
forward’ transmission methods where data sits on various servers along the way waiting to be
picked up by a polling service.

Rather than continuing using transmission methods that by their nature introduce delays and
provide no guarantee of delivery or knowing when a delivery has failed, Universal XML is sent from
CargoWise using our eAdaptor web service interface.

eAdaptor provides an easy connection to our eHub Gateway. Previously we provided customized
data mappings for CargoWise systems by writing code which was then deployed as an upgrade.
This meant that an upgrade had to be run every time we added or changed a mapping. Now
those changes can be handled via xHub and updated without clients having to run an upgrade on
their CargoWise systems allowing us to respond more quickly to client's needs.

You can also configure eAdaptor to point to your own internal web service. Using the eAdaptor
SOAP web service interface, you can send Universal XML to a Local Web Service running
middleware technology like Microsoft BizTalk. This gives you complete control over routing and
mapping of data to meet your own or your client’s requirements, but you are then responsible for
creating and maintaining the mappings over time.

5.2.2 Configuring Communications

Before you can send Universal XML, you need to define which data you want to send to which
Web Service. You do this on the EDI Communications sub tab of the Organization you want to
send Universal Data to. If you were sending data internally, you would generally use the
Organization linked to the Company you log into in CargoWise (otherwise known as your
Company Organization Proxy).

First, go to the Organizations module within CargoWise and open the Organization you want to
send Universal XML to. Make sure the Details tab is selected, then the Config sub tab, then the
EDI Communications sub tab.

In the EDI Communication Modes grid, you need to define for each Module and Universal Data
Type where the data is going (xHub or Local Web Service), and the Recipient Code that the
target Web Service can use to route your message if required. You enter this information in the
following fields as described below:

eAdaptor - Developer’s Guide | 167

• Module – Must contain the Module Code the data is being sent.
• Comms. Direction – Always contains TRX for Transmit.
• File Format – This is where you enter the Universal Data Type. Commonly used options
here are:
• XUE – XML Universal Event
• XUS – XML Universal Shipment
The options change depending on which Module you have selected to indicate the
functionality available in that module; all Universal Data options have a description
containing ‘XML Universal’ and the data type.
• Message Purpose – This is an optional field, used when you want finer control over the
destination of data than Module and Data Type give. You can specify a Purpose Code on a
Workflow Trigger Action. When a Trigger Action is configured to send Universal Data,
CargoWise first looks for a match on Module + Data Type + Purpose Code, then falls back
to a row with matching Module and Data Type, but no Purpose Code.
• Comm. Transport – The two options you can select here are HUB - eHub Gateway and
EDP – eAdaptor Interface. If you try and select any other options, an error is displayed
indicating you can only send Universal Data via eAdaptor to xHub or a Web Service
implementing the eAdaptor Interface.
• Destination Address – When sending via the eAdaptor Interface or to xHub, you must
specify a Destination Address. This can be anything you like when sending to your own
eAdaptor Interface, but when sending via xHub must match the Destination Address Code
supplied by our internal eServices team so that xHub can process your data appropriately.

eAdaptor - Developer’s Guide | 168

© 2024 WiseTech Global 11 March 2024
Refer to our learning units:
1COR147 - How do set up EDI Communications?
1PRO023 - Where do I set up Message Trigger Purposes and how do they work?

5.2.3 Sending automatically via Workflow

The best way to send Universal Datasets is to use Workflow Trigger Actions to automatically push
Universal Datasets out of CargoWise. Workflow is supported in all CargoWise modules where
Universal Data is supported, and it’s the timeliest and most reliable way of getting data published
from your CargoWise system.

Rather than having to remember when to manually export operational data, using Workflow allows
you to pre-configure what conditions have to be met, or what event has to occur before
Universal Data will automatically be generated and sent. As timelines shorten, having operational
data pushed to all concerned parties as soon as possible is a major concern.

Workflow driven data exports remove the operator delay and error from the process. For this
reason, we recommend using Workflow wherever you can when sending Universal XML.

5.2.4 Adding Workflow Triggers

Assuming you have the destination web service configured correctly on the Organization on your
Company Organization Proxy, you can setup Workflow Triggers to automatically send data when
pre-defined events occur. If you open the Module you specified in the EDI Communication Mode
(SHP meaning the Forwarding Shipment module) then open an Item from within the Module, you
can setup a Trigger on the Triggers sub tab under the Workflow & Tracking tab on that Item.

To test this, start by creating a Shipment as you normally would, then select the Workflow &
Tracking tab, then the Triggers sub tab. Add a Trigger in the Triggers grid at the top of the tab
with a Description and an Event code.

Refer to our learning unit 1COR172 - How can I send Universal XML for Testing Purposes?

Add an Action to your Trigger in the Completion Trigger Actions grid at the bottom of the tab. Set
the Action code to XUE (Send XML Universal Event), the Recipient to ORP (Org Proxy) and the
Purpose code to what you set the Message Purpose as in the Company Org Proxy Form.

Refer to our learning unit 1PRO008 - How do I create an XML file Trigger Action in a workflow
template?

eAdaptor - Developer’s Guide | 169

Next, go to the Events sub tab and create a new Event by right clicking within the grid and select
the Add New Event option.

Figure 83 Workflow & Tracking > Events tab > Add New Event

eAdaptor - Developer’s Guide | 170

Figure 84 New Event Dialogue box

Click on the Find button and you will see the event you just created. Click on the Save & Close
button to save the event.

You can export other forms of Universal XML from modules that support them by using different
Trigger Action Codes.

• Universal Activity – XUA (Send XML Universal Activity)

• Universal Shipment - XUS (Send XML Universal Shipment)
• Universal Transaction – XUT (Send XML Universal Transaction)

As long as your Service Tasks are running, the Event Log Walker Service Task (LWK) will process
the event and export it.

Refer to our learning unit 1PRO012 - How are Events automatically logged and can I create
them manually?

To check if your Service Tasks are running, go to Maintain > System > Service Tasks.

Use filters to search for the LWK Service Task and then click on the Find button. As you can see
below, the Event Log Walker Service Task is running, but currently idle.

Figure 85 Service Task Search screen

Refer to our learning unit 1COR417 – Understanding Service Tasks?

To find the resulting EDI Message, go to Maintain > System > EDI Message. Use the filters, you
can see any events that have been exported with a status of AQU (eAdaptor Queued), which
means they are now waiting to be picked up and processed by eAdaptor.

eAdaptor - Developer’s Guide | 171

Figure 87 EDI Message Search screen

When you use a Trigger Action with Action Code XUS, the LWK Service Task will pick up the
Universal Shipment and export it using the same process as with the Universal Event. It will show
the same log types on the Service Task similar to the Universal Event.

If you do this, then add another Event, then go back to the EDI Messages module, you will see a
Universal Shipment with a status of AQU waiting to be picked up and sent by eAdaptor.

eAdaptor - Developer’s Guide | 172

Refer to our learning unit 1COR193: How do I check data imports through EDI Messages?

5.2.5 Automatically Populating Workflow Triggers

Workflow Triggers are generally setup in the Workflow Templates module so that Triggers for
each new Shipment can have a default set of Triggers defined. If the Workflow Templates are
setup properly, the user will never have to think about it. The Workflow Template functionality is
explained further in the Workflow core documentation.

Refer to our Workflow Administration learning units.

eAdaptor - Developer’s Guide | 173

© 2024 WiseTech Global 11 March 2024
5.2.6 Sending Manually via Actions Menu
If you need to send Universal XML on a one-off basis, from the Actions menu, select Send
Universal XML without setting up Workflow Trigger Actions.

Figure 89 Actions Menu > Send Universal XML

When you select this, the following window will appear. Manually enter the information
required to send Universal Data that would normally send from the Workflow module.

Figure 90 Manually Send XML Universal Shipment Dialogue Box

Click on the Send & Close button. Provided that EDI Communication Modes are setup correctly
under the Recipient Organization, the following prompt will display indicating the XML has been
successfully.

eAdaptor - Developer’s Guide | 174

Refer to our learning unit 1COR143 - How can I manually send Universal XML files?

5.3 Receiving Universal XML

Universal XML can be sent into CargoWise via eAdaptor SOAP, eAdaptor HTTP+XML, or from the
xHub Service provided by WiseTech Global. These channels allow Universal XML to be sent in for
asynchronous queue based processing. When sending in XML using one of these channels, the
Universal Interchange is used as a wrapper to group multiple XML Messages into one Interchange.

The Universal Interchange also allows you to optionally request processing result responses so
that you can monitor processing results in your middleware or send them back to external
systems. When requesting processing responses, you can specify the circumstances under
which you want a response (success/failure/both) and the channel/recipient you want the
response to be sent to.

Processing result responses are optional as there are a number of other ways you can monitor
message processing within CargoWise itself. These are described later in the following sections
covering Message Processing Logs and Notification Emails.

5.3.1 Wrapping Universal XML into Universal Interchange

Each Universal XML message must be wrapped in a Universal Interchange before sending into
CargoWise via eAdaptor SOAP as this is an asynchronous communication channel. You can
include multiple Messages within the one Interchange, and they will be processed in the order in
which they are included in the Interchange.

The Universal Interchange is required if you are using eAdaptor SOAP, but not required if you
are using eAdaptor HTTP+XML to send in Universal XML.

eAdaptor - Developer’s Guide | 175

© 2024 WiseTech Global 11 March 2024
Below is a sample Universal XML message that will add a CMI (Commercial Invoice Imported)
event against Shipment S00043996.
<UniversalEvent xmlns="http://www.cargowise.com/Schemas/Universal/2011/11" version="1.1">
<Event>
<DataContext>
<DataTargetCollection>
<DataTarget>
<Type>ForwardingShipment</Type>
<Key>S00043996</Key>
</DataTarget>
</DataTargetCollection>
<Company>
<Code>DAU</Code>
</Company>
<DataProvider>HYECMTDAU</DataProvider>
<EnterpriseID>HYE</EnterpriseID>
<ServerID>CMT</ServerID>
</DataContext>

<EventTime>2016-11-30T13:52:03.153</EventTime>
<EventType>CMI</EventType>
<CreatedTime>2016-11-30T02:52:14.963</CreatedTime>
<IsEstimate>false</IsEstimate>
<ContextCollection>
<Context>
<Type>MBOLNumber</Type>
<Value>HBL85161TRN</Value>
</Context>
<Context>
<Type>HBOLNumber</Type>
<Value>423908</Value>
</Context>
</ContextCollection>
</Event>
</UniversalEvent>

Taking the XML file, you would like to wrap, delete the “<?xml version="1.0" encoding="utf-8"?>” tag
at the beginning of the file (where present) then copy the remaining file using CTRL+A to select
all, then CTRL C to copy the content.
<UniversalInterchange xmlns="http://www.cargowise.com/Schemas/Universal/2011/11" version="1.0">
<Header>
<SenderID>ABCDEFGHI</SenderID>
<RecipientID>HYEBENBEN</RecipientID>
</Header>
<Body>

</Body>
</UniversalInterchange>

eAdaptor - Developer’s Guide | 176

© 2024 WiseTech Global 11 March 2024
Paste the UniversalEvent XML content in place of the “” comment
element of the universal interchange wrapper shown above. You should end up with a properly
wrapped Universal Event as shown following.
<UniversalInterchange xmlns="http://www.cargowise.com/Schemas/Universal/2011/11" version="1.0">
<Header>
<SenderID>ABCDEFGHI</SenderID>
<RecipientID>HYEBENBEN</RecipientID>
</Header>
<Body>
<UniversalEvent xmlns="http://www.cargowise.com/Schemas/Universal/2011/11" version="1.1">
<Event>
<DataContext>
<DataTargetCollection>
<DataTarget>
<Type>ForwardingShipment</Type>
<Key>S00043996</Key>
</DataTarget>
</DataTargetCollection>
<Company>
<Code>DAU</Code>
</Company>
<DataProvider>HYECMTDAU</DataProvider>
<EnterpriseID>HYE</EnterpriseID>
<ServerID>CMT</ServerID>
</DataContext>

5.3.2 Requesting a Processing result response

When sending in Universal XML via eAdaptor, you can request an asynchronous
acknowledgement message to be sent back when the contained XML is processed by the
Universal Shipment/Event Messaging Inbound (UMI) Service Task. The acknowledgement will
contain basic processing results represented as a Universal Event indicating either success or
failure.

This allows you to create your own automated monitoring and alert system via your middleware
rather than monitoring XML processing using the EDI Message module in CargoWise.

eAdaptor - Developer’s Guide | 177

© 2024 WiseTech Global 11 March 2024
5.3.2.1 Requesting an Acknowledgement
Acknowledgements are requested using a new ’Acknowledgement‘ request element as shown in
the following XML template.
<UniversalInterchange xmlns="http://www.cargowise.com/Schemas/Universal/2011/11">
<Header>
<SenderID>MIDDLEWARE_SND</SenderID>
<RecipientID>HYEBENDDE</RecipientID>
<Acknowledgement>
<Required>OnAll</Required>
<Channel>eAdaptor</Channel>
<RecipientID>MIDDLEWARE_RCV</RecipientID>
<ContextCollection>
<Context>
<Type>MyJobReference</Type>
<Value>BAT0000455347</Value>
</Context>
</ContextCollection>
</Acknowledgement>
</Header>
<Body>

</Body>
</UniversalInterchange>

The parameters specified in the Acknowledgement request element will be used when
processing each Universal XML message contained within that Universal Interchange. The
Acknowledgement element contains the following sub elements:

• Required – Describes when an acknowledgement is required. Options are:

• OnAll – For every message sent.
• OnError – Only for those that error or are rejected.
• OnSuccess – Only for those that succeed.
• Channel – The channel used for sending the acknowledgement back. Options are xHub, or
eAdaptor
• RecipientID – The RecipientID that will be used in the Universal Interchange when sending
the Acknowledgement back via the designated channel. (The SenderID will be the
EnterpriseID, ServerID and Company Code from the Company processing the Universal
XML)
• ContextCollection – Any Context elements specified in the ContextCollection of the
Acknowledgement Request will be returned in the ContextCollection of any Universal
Events that are returned. This is where you can specify your own Job and/or Message
identifiers that you can use to help identify which sent message the response relates to

5.3.2.2 Acknowledgements sent back

Acknowledgements are sent back in the form of Universal Events wrapped in a Universal
Interchange with the following information.

• SenderID – The EnterpriseID, ServerID and Company Code from the processing CargoWise
system

eAdaptor - Developer’s Guide | 178

© 2024 WiseTech Global 11 March 2024
• RecipientID – The RecipientID that was specified in the inbound Acknowledgement
Request element. This is typically used in middleware to target the response to a particular
interface or pipeline
• EventType - The EventType will always be DIM (Data Imported) as that is the action that
occurred, even on failure
• ContextCollection – The ContextCollection will contain all of the Context elements that
were provided in the ContextCollection of Acknowledgement elements from the inbound
XML. This will also contain the processing results for the submitted Universal XML in
Context elements with the following Types
• ProcessingResultStatus – Three-character code indicating processing success or failure.
This is the same code that appears in the Status column in the EDI Message Module. For a
complete list of options, please see the eAdaptor Developer’s Guide
• DataImportLog – Human readable processing log containing the same information you see
on the Notes tab of the EDI Message in the Data Import Log Text note
• DataContext – This will contain supplementary information identifying the System and
Company targeted when processing the inbound XML

If the sample Universal Interchange XML shown previously was used to send a Universal Event
successfully, the Acknowledgement XML sent back would look like this.
<UniversalInterchange xmlns="http://www.cargowise.com/Schemas/Universal/2011/11" version="1.1">
<Header>
<SenderID>HYEDDEBEN</SenderID>
<RecipientID>MIDDLEWARE_RCV</RecipientID>
</Header>
<Body>
<UniversalEvent xmlns="http://www.cargowise.com/Schemas/Universal/2011/11" version="1.1">
<Event>
<DataContext>
<Company>
<Code>DDE</Code>
</Company>
<DataProvider>HYEBENDDE</DataProvider>
<EnterpriseID>HYE</EnterpriseID>
<ServerID>BEN</ServerID>
</DataContext>
<EventTime>2017-03-02T07:26:28.36</EventTime>
<EventType>DIM</EventType>
<ContextCollection>
<Context>
<Type>MyJobReference</Type>
<Value>BAT0000455347</Value>
</Context>
<Context>
<Type>DataImportLog</Type>
<Value>Linked Event to Shipment S00001000 (House Bill='FRED235478923').</Value>
</Context>
<Context>
<Type>ProcessingResultStatus</Type>
<Value>PRS</Value>
</Context>
</ContextCollection>
</Event>
</UniversalEvent>
</Body>
</UniversalInterchange>

eAdaptor - Developer’s Guide | 179

© 2024 WiseTech Global 11 March 2024
5.3.3 Manual queuing for import (for test purposes only)
For testing purposes, you can manually queue Universal XML for processing by the UMI service
task.

This is not a facility that is intended for use in your Production system.

Start by creating your Universal XML file with valid Universal XML content.

Then go to the Maintain > System > EDI Messages module.

Click on the Actions drop down menu, select Add Inbound Universal XML Message.

Figure 92 Actions Menu >Add Inbound Universal XML Message

eAdaptor - Developer’s Guide | 180

Figure 93 Import File Location Dialogue box

When you select a valid sample file and click the Open button, you will see a system prompt
confirming the successful creation of your Universal XML EDI Message:

Figure 94 System Prompt Confirmation of Universal Shipment or Universal Event

Then click on the Find button on the EDI Messages module search screen with the appropriate
filters you will see the EDI Message you have just created with a Status of QUE - Queued for
Processing.

Figure 95 EDI Message Search Screen

eAdaptor - Developer’s Guide | 181

© 2024 WiseTech Global 11 March 2024
If you try to select a file that does not contain XML with matching opening and closing tags, or a
file that does not have a root element matching the signature of a supported Universal XML
schema, the system will display an error message similar to the one shown below.

Figure 96 Error Message

5.3.4 Logging and processing after import

Universal XML comes into CargoWise via the eAdaptor Web Service Interface from either xHub or
your own eAdaptor Web Client implementation. As long as the XML sent in has matching opening
and closing tags and is generally well formed, each Universal Interchange will be added into the
EDI Interchanges Module under Maintain > System > EDI Interchanges.

Each Universal XML Message contained within the Body element will then be extracted out into
the EDI Messages module found under Maintain > System > EDI Messages. If the content type
(determined by the root element type) is recognized, there will be a Message Sub Type code on
each EDI Message row identifying the type of Universal XML contained in the message as shown
below.

Figure 97 EDI Message Search Screen

eAdaptor - Developer’s Guide | 182

© 2024 WiseTech Global 11 March 2024
When messages first come in, they will show with a status of QUE - Queued. From this point, the
Universal Data Messaging Inbound - UMI Service Task will pick up all queued messages and
process them appropriately. The status will then be changed to a code describing the processing
result for each incoming message.

Refer to our learning unit 1COR193: How do I check data imports through EDI Messages?

5.3.5 UMI Service Task

When Universal XML first comes into the EDI Message module, it has a status of QUE - Queued as
shown above. From this point, the Universal Data Messaging Inbound - UMI Service Task will pick
up all queued messages and process them appropriately.

As messages are processed, the status on each processed message will change to one of the
following:

• PRS – Processed OK – The message was processed without issue and the data was applied.
• WAR – Processed with Warnings – The message imported and was processed with minor
non-fatal issues. Examples include over length data provided for elements and out of range
individual values.
• ERR – Processed with Errors – The message was processed and imported with data loss that
should be reviewed. Examples include not being able to import Job Costing data as part of a
Shipment and excluding chunks of data due to missing mandatory elements.
• DCD – Discarded – No Match Found – Message passed validation and is valid for import but
there was no matching job, module or entity that this data could be imported against or into.
Examples include not having a job that the supplied references match to, or not having a
DataTarget/Recipient Role included that indicates a module to be targeted.
• REJ – Rejected – The message was rejected without being processed. The message either
failed validation or was not valid for the CargoWise receiving system. Examples include
mandatory elements at the core of the XML provided were either missing, critical values being
invalid preventing the system from searching for a match, or there is a serious structural
problem with the xml provided that stopped our systems from being able to process the data
provided.

eAdaptor - Developer’s Guide | 183

© 2024 WiseTech Global 11 March 2024
If you double click on an EDI Message after it has been processed by the UMI Service Task, and
go to the Notes tab, you will see a Data Import Log note showing what was done with the
imported data:

Figure 98 View Message > Notes tab

You can see from the above example that Forwarding Shipment S00043996 was updated with
the contents of the imported XML File.

If the XML was missing mandatory segments, or unable to be imported for any reason, any error
messages generated will show in this log so that you can see what is wrong with the incoming
message.

If you then open the related Business Object the data was applied to, and go to the Workflow &
Tracking tab, then the Events sub tab, you will see the Event that was logged as a result of the
data import.

eAdaptor - Developer’s Guide | 184

Whenever you select an event that was created from a Universal XML import or export, you will
see all Context Information sent with the dataset showing at the bottom of the tab

For imported Universal Events, the Event Code on the Event will be the Event Code from the
incoming XML and the Context Information includes all items from the ContextCollection in the
XML. This is so that when Universal Events are generated from external sources, additional data
can be included with the Universal Event to help inform the users exactly what the event relates
to.

For all other types of imported Universal XML including Universal Shipments, Activities, and
Transactions, the Event Code will be DIM (Data Import), and the Context Information will contain
basic information about the data taken from the DataContext element and its contents.

For all Universal XML exported, there will be a DEX (Data Export) event with the same Context
Information showing at the bottom of the tab.

For all Events related to incoming and outgoing Universal XML, there is an area to the right of the
Context Information that gives basic information about the EDI Message that contains the data
that was imported, and a View button.

eAdaptor - Developer’s Guide | 185

© 2024 WiseTech Global 11 March 2024
Click on the View button, which opens the View Message window containing the XML Message
itself along with information about where the message came from, what time it was processed
and whether it was transmitted or received.

Figure 100 View Message Details tab

Refer to our learning unit 1COR193: How do I check data imports through EDI Messages?

eAdaptor - Developer’s Guide | 186

© 2024 WiseTech Global 11 March 2024
5.3.6 Universal Data Buss
When Universal XML comes into CargoWise, as long as basic XML validation is passed and all
mandatory top level elements are present, the data will be offered to all modules via the
Universal Data Buss. Based on the content of the Universal XML, each module will decide whether
the data is applicable to that module, and if it is applicable how it will be used.

If you specify a DataTarget Type, the module described by the DataTarget Type will always try
and import the data. For Universal Events this is not always possible as you must be able to find
an existing job or entity to apply an Event against. For other Universal XML types like the Universal
Shipment, Activity, or Transaction, if a matching job or entity is not found, a new one will be
created using the content of the incoming Universal Data.

Even where you specify a DataTarget pointing towards a module or modules, another unrelated
module may decide to use the data as well. It might decide to update a job or entity where data
relevant to that module is found in the incoming data that it doesn’t already have. An example of
this is Container Events where a single Universal Event with a Container Number and Master Bill
on it can match to jobs in the International Forwarding, Customs and Domestic Transport
modules.

5.3.7 Key matching on import

CargoWise uses various combinations of Keys in a series of fallbacks when trying to find existing
jobs or entities that incoming data is related. Keys are relatively unique references that
CargoWise matches on, like House Bills, Master Bills, Order Numbers, and Booking Numbers. They
can all be used to help match incoming data to existing jobs and entities within CargoWise.

There are three levels of fallback when trying to match to existing jobs or entities. The last level of
fallback will use one of two different matching methods depending on a registry setting and what
the target module supports. The first two types of matching are Job Number match, then Module
Specific Match (where implemented). The last type of matching used will either be Combination
Key matching, or Reference and Party ID matching.

Combination Key matching was found to give many false positive matches in Forwarding and
Customs modules due to the way references are used in those modules. For this reason, we
implemented Reference and Party ID matching. This matching algorithm yields far less false
positives as it requires a match on both a reference and its issuing party/organization.

It is recommended that you turn on Reference and Party ID matching in the registry,
especially if you are engaging in E2E Messaging with other CargoWise systems.

eAdaptor - Developer’s Guide | 187

© 2024 WiseTech Global 11 March 2024
5.3.7.1 Job Number matching
Job number matching is attempted when the EnterpriseID and the ServerID from the
DataContext element match the Enterprise ID and the Server ID of the CargoWise installation
processing the incoming data. When the Enterprise ID and Server ID match, CargoWise knows
that the job numbers, entity codes, and other system specific codes will match to the system
data is being imported into.

As an alternative to providing the EnterpriseID and ServerID in the DataContext element, you can
force job number matching by supplying the CodesMappedToTarget element with a value of
‘true’. This has the same effect as providing a matching EnterpriseID and ServerID in the incoming
data. Job numbers, entity codes, and other system specific codes will then be used for matching
even though the EnterpriseID and ServerID have not been supplied.

If the above criteria have been met, the DataTarget Type from each element in the
DataTargetCollection is used to decide which module to look in, and the Key from the DataTarget
provides the Job Number to search with. This means that a DataTarget with a Type of
ForwardingShipment and a Key of S00002847 would be matched to a Forwarding Shipment with
a Shipment Number of S00002847.

5.3.7.2 Module Specific matching

Most modules have candidate keys other than the Job Number that are specific to that module.
Sometimes they involve multiple parts or crossing multiple modules to get a match. These are
coded per module per incoming data type.

A good example of this is Master Bill + House Bill matching across the Forwarding Consolidation
and Shipment modules. These matches occur regardless of the value of the EnterpriseID,
ServerID and CodesMappedToTarget elements.

5.3.7.3 Combination Key matching

Entities in each module in CargoWise contain a different set of References specific to the
business area the module is designed to service. Combination Key Matching applies three
processes in order when trying to find the right entity to match to within a module. It continues
through the processes until there is only one matching entity.

Where a process returns no matches, it is skipped, and the next process is engaged. If a process
returns multiple matches, the results are passed to the next process. The matching processes
are applied in order as follows:

• Reference Match Count – Looks for the entity with the most matching references, i.e.,
three matching references would beat two matching references. No weighting on the type
of reference is done at this point. If there are multiple entities that equal the highest match
count, those with the highest match count are passed onto the next matching process. If
there’s only one entity with the highest match count, that’s the match made. If there’s none
at this point, it means that there’s no entity in CargoWise with any matching references, so
no further matching occurs

eAdaptor - Developer’s Guide | 188

© 2024 WiseTech Global 11 March 2024
• Reference Type Weighting – Some reference types in a given module may be given a
better weighting than others. A match on House Bill + Order Number in a given module may
get a better rating than two Order Numbers. The weighting works its way through the
weighted list of reference types from the strongest reference to the weakest reference
excluding any matches where some have the reference type and the others do not. If at
any stage in this process there is only one match left, that is returned.
If no matches exist with that reference type at all, leaving zero matches, that reference
type is not used for exclusion. If multiple matches are still present at the end of this
process, the reduced list is passed onto the final matching process
• Context Fallback Matching – Some incoming data includes values that are not references
but provide context to the references provided. Two good examples of this type of data
are Origin Port and Destination Port. UNLOCOs are unique references to a particular
location, but they are not a reference as there will be many jobs with the same Origin
and/or destination in a given CargoWise system. They can however be used to exclude
false positives in the rare cases where references do not give a clear match. If only one out
of all the remaining entities matches all context fallback values, then that is returned as a
match.
• Each Module has its own set of references and context values. Those values are present in
different places in different Universal XML schemas, but the matching principles are
applied in the same way to those references and context values. Documentation on each
module’s implementation below gives you the references in weighted order (strongest
reference first) and the context values used for Context Fallback Matching

5.3.7.4 Reference and Party ID matching

The problem with matching by reference numbers alone is that many different parties use the
same or overlapping number sequences when issuing reference numbers. The House Bill number
S00001234 will identify completely different Shipments when issued by different International
Forwarders.

The primary concept behind Reference and Party ID matching is that when you know who the
issuing party is for a reference, and you can match the issuing party as well as the reference to a
target entity, you have a very reliable match to that target entity. This form of matching is only
implemented for Universal Shipment XML as other forms of XML do not commonly contain the
OrganizationAddress based information used to identify issuing Parties.

As a secondary concept, where you have a reference provided in the incoming data, and that
same type of reference is present on a target entity, but the two values are different, that can be
seen as a ‘conflict’ and reduce the possibility of a match

Reference and Party ID matching is enabled using the eServices > Universal XML > Use
Combined Reference and Party ID Matching registry item. It is recommended that you turn this
option on, especially if you are engaging in E2E Messaging with other CargoWise systems.

Once enabled, in modules where Reference and Party ID matching has been implemented, the
system will try to match using Reference and Party ID pairs. Each module where this has been
implemented has its own set of References and Party ID pairs, along with scores for a Match,

eAdaptor - Developer’s Guide | 189

© 2024 WiseTech Global 11 March 2024
Partial Match (Reference Only) and Conflict (Reference present in both XML and target entity, but
different). A sample of how scoring is arranged follows.

Reference Element Party ID Type Match Partial Conflict

BookingConfirmationReference Consignor 90 10 0

BookingConfirmationReference Consignee 90 10 0

InterimReceiptNumber Consignor 90 10 0

WayBillNumber SendingForwarder 180 30 -180

References from the Reference Elements that are six characters in length or longer are used to
build a list of entities where any of the references match. Scores are calculated for each
Reference and Party ID type, and they are added up for each entity. The entity with the highest
result is the match, although given the relative uniqueness of the references used, there is
generally only one entity matching by these references in a target system.

Not all modules support this method of matching. For modules that do not support Reference
and Party ID matching, Combination Key Matching will be used instead. For modules that do
support Reference and Party ID matching, you will find a Reference and Party ID scoring table as
shown above provided within the Module Mapping Guide for that module.

Module Mapping Guides describe the keys used for matching, give an overview of how the
schema is mapped, and provide a list of element level mappings describing each field’s
location in the GUI. They can be found under Integration Options – Mapping Guides

eAdaptor - Developer’s Guide | 190

© 2024 WiseTech Global 11 March 2024
5.3.8 Verbose Logging
When importing Universal XML, there is a log generated as part of each import describing
processing results for many data types and functions. This log can be found on the Notes Tab of
an Inbound EDI Message as described in section 5.3.5 UMI Service Task.

There is a registry item, eServices > Universal XML > Enable Verbose Logging that turns on
additional logging. Verbose Logging shows why a certain result was achieved, or how the result
was calculated, rather than logging just the result. This can be useful when trying to diagnose why
matches occur when importing Universal XML into CargoWise.

Verbose Logging registry item default behavior is set to ‘No’ as it adds a significant amount of
additional text to the Data Import Logs. This logging is only useful when you cannot work out why
a certain matching result has occurred.

The functionalities that can write Verbose Logs include the following.

• Organization Matching
• Universal Shipment Job Level Matching
• Universal Event Job Level Matching
• Branch Targeting

The Verbose Logs provide an additional insight into how these functionalities work in practice. It
is advisable to turn this on in your CargoWise test system while developing new interfaces.

eAdaptor - Developer’s Guide | 191

© 2024 WiseTech Global 11 March 2024
5.4 Universal Shipments
5.4.1 Overview
There are many modules in CargoWise that have a similar, common set of data. Each business
area or module holds operational details specific to the tasks associated with that business area,
but there are common themes across the modules. To make it easier for people to map their
shipment related data to each module available in CargoWise, we have created one common
Dataset that can be exported or imported from a range of modules across our product.

The following sections in this chapter deal with generic functionality related to the Universal
Shipment dataset that is common across all modules. An example of this is that in all areas where
the Universal Shipment has been mapped, you can configure Workflow to export Universal
Shipments by configuring a trigger action of XML Universal Shipment.

Module Mapping Guides describe the keys used for matching, give an overview of how the
schema is mapped, and provide a list of element level mappings describing each field’s
location in the GUI. They can be found under Integration Options – Mapping Guides

eAdaptor - Developer’s Guide | 192

© 2024 WiseTech Global 11 March 2024
5.4.2 Milestones
Milestones are included in exported Universal Shipment XML under the MilestoneCollection
element. Every module that can send Universal Shipments has Workflow enabled, so this means
that Milestones are included from every module when sending a Universal Shipment.

The default behavior is all Published (non-Internal) Milestones are included in outgoing XML. Each
Milestone can have this set individually both on the template and on each instance of a Milestone
on each job.

Figure 101 Workflow & Tracking > Milestones tab

If you want to send both Published and Internal Milestones to a particular recipient, there is an
option configurable for each Recipient Organization that allows you to include Internal Milestones
as well. You can set this option when configuring the EDI Communications Mode for the sending
module for the File Format of XUS (Universal Shipment).

eAdaptor - Developer’s Guide | 193

Milestones from Universal Shipment XML are never imported. Workflow is always configured from
within a target system. This is to stop a sending system from controlling a receiving system's
Workflow configuration along with any associated automations.

If you want to send XML Messages to mark off Milestones in a target CargoWise system, you can
send Universal Events with the Event Code and Parameters matching the Milestone that has been
met.

Events give a way of sending updates in a timely manner as they are sent as soon as the event
itself is recorded in the host system. They will trigger any Trigger Actions configured within the
receiving CargoWise system so they cause Workflow to operate, but they will not interfere with
the Workflow configuration determined by the recipient.

Milestones are included so that third party systems can see a brief historical summary of the
progression of a job where they are not able to handle timely updates via Universal Events.
Events are always the preferred option for progress updates as they are a real time push based
mechanism providing timely and scalable progress updates.

eAdaptor - Developer’s Guide | 194

© 2024 WiseTech Global 11 March 2024
5.4.3 Job Costing (Billing) and Consol Costs
Most operational modules in CargoWise have a Billing Tab which contains a list of charges applied
to that job. When you send a Universal Shipment, this job costing information can be included
under the JobCosting element in the Universal Shipment XML schema.

In the Forwarding Consol module, there is a Consol Costing Tab instead of a Billing Tab. This
functions differently to the Billing Tab. It is used to track Consol costs, apportion costs to
attached Shipments, and also for profit sharing. The information from the Consol Costing Tab can
be included in the Universal Shipment XML under the ConsolCosts element.

The JobCosting and ConsolCosts elements (known collectively as the Costing elements) share
some common functionality. When exporting Universal Shipment XML, they are only included
when certain conditions are met. When importing Universal Shipment XML, the Charge Lines on
the Costing elements must contain ImportMetaData elements that tell the processing CargoWise
system how and when to match to existing rows.

This common functionality is described in more detail in the following sections.

5.4.3.1 Exporting Costing elements and Charge Lines

Costing elements and Charge Lines contain sensitive information. Most companies prefer not to
share information about where they make their profit with everyone. For this reason, Costing
elements are not included in Universal Shipment XML by default. This prevents users from
sending job profit and/or cost price information to third parties.

When sending Universal XML from CargoWise, one of the Recipient Roles you can use is ORP (Org
Proxy) which is intended for use when sending Universal XML to your own in-house systems.
Because it is a common and reasonable requirement for in-house systems to have access to
costing information, the Costing elements are included when you send XML using the Recipient
Role ORP.

5.4.3.2 Importing Costing elements and Charge Lines

The bulk of the information for both kinds of Costing elements is contained in the Charge Line
elements. For the JobCosting element, the Charge Lines are contained in the
ChargeLineCollection, and for the ConsolCosts elements, the Charge Lines are in the
ConsolCostLineCollection.

Each Charge Line element imported must have an ImportMetaData element included with it, or it
will be ignored upon import. The ImportMetaData element tells the target CargoWise system how
to import the row, and what data to use to match to existing rows where updates or deletes are
required. In short it tells the target system how to merge the supplied information along with any
existing charge lines.

eAdaptor - Developer’s Guide | 195

© 2024 WiseTech Global 11 March 2024
When exporting Charge Lines, CargoWise does not include ImportMetaData elements. These are
added by your middleware or business processes when sending data into your CargoWise
system only.

ImportMetaData is not included when exporting from CargoWise for two reasons. Exchanging
charges information directly between CargoWise systems without a business process in
between yields undesirable effects as your costs are not generally another party’s costs. You also
don’t know how the recipient wants to match and account for costs in their system, so there has
to be some sort of business process in place to manage this kind of transfer. These are usually
added by middleware.

5.4.3.2.1 Requisite Data Context elements

To import ConsolCosts and/or JobCosting data, as well as having a valid DataTarget, the
DataContext must contain a matching EnterpriseID and ServerID, and the CompanyCode must
match a valid Company in the system. In the event where any of these values are missing or
invalid, the ConsolCosts and JobCosting data elements will be ignored.

Figure 103 View Message > Notes tab

In the event where the branch specified in the JobCosting data element does not belong to the
company processing the XML import (i.e., CompanyCode), the EDIMessage will be rejected.

Figure 104 View Message > Notes tab

eAdaptor - Developer’s Guide | 196

5.4.3.3.1 Instructions

When importing Charge Lines, CargoWise needs instructions on how to import each line,
depending on the instruction, matching criteria to be used when trying to find an existing line to
update or delete.

There are four possible instructions that can be specified in the Instruction element within the
ImportMetaData element.

• Insert – Add a new charge.

• Update – Update existing charge using matching criteria
• UpdateAndInsertIfNotFound – Update existing row using matching criteria if one exists,
otherwise add new charge
• Delete – Delete existing charges using matching criteria

In the event where the ImportMetaData element is not included, the

ChargeLine/ConsolCostLine element will not be imported. It will be skipped by the import
process.

5.4.3.3.2 Matching criteria

Unless you are using the INSERT instruction, you must also supply matching criteria.
MatchingCriteria elements are included in the MatchingCriteriaColleciton element on the
ImportMetaData elements as shown following.
<ImportMetaData>
<Instruction>UpdateAndInsertIfNotFound</Instruction>
<MatchingCriteriaCollection>
<MatchingCriteria>
<FieldName>ChargeCode</FieldName>
<Value>FSC</Value>
</MatchingCriteria>
</MatchingCriteriaCollection>
</ImportMetaData>

Each MatchingCriteria element contains a single FieldName and Value that must match to an
existing row for it to be considered a match. Where there are multiple MatchingCriteria elements
provided, all criteria must be met to obtain a match to a target row.

eAdaptor - Developer’s Guide | 197

• ChargeCode
• Creditor
• CostAPInvoiceNumber
• SupplierReference
• CostOSCurrency
• CostOSAmount
• CostLocalAmount
• CostInvoiceDate
• CostDueDate
• CostExchangeRate
• ApportionmentMethod *
• PrepaidCollectFilter *

*Applicable to ConsolCosts Only.

When using the Update Instruction, it’s important to include a set of criteria that will uniquely
identify the row you want to update. Where multiple matches exist for Update Instructions
provided, an error will result looking like "Error - whilst importing ... multiple charges found when
updating charge line. No changes were made due to the above errors. Please fix the errors and try
again." For Delete Instructions, all rows matching will be considered a match.

For this reason, sometimes it’s best to include separate Delete and Insert instructions. A common
case is where all charge lines containing costs from a particular supplier are Deleted, then Insert
Instructions are used to add replacement lines from that supplier. Be aware that in this case, any
other changes made to the rows being deleted between updates will be lost as you are throwing
away the rows when you replace them.

5.4.3.3.3 Using the Insert instruction

The Insert instruction can be used to insert a new charge line/consol cost. It does not require any
MatchingCriteria as no matching is performed.
<ImportMetaData>
<Instruction>Insert</Instruction>
</ImportMetaData>

eAdaptor - Developer’s Guide | 198

The Update instruction can be used to update an existing matching charge line/consol cost.

In this case, one or more matching criteria can be specified for the system to locate the charge
line consol cost to be updated.
<ImportMetaData>
<Instruction>Update</Instruction>
<MatchingCriteriaCollection>
<MatchingCriteria>
<FieldName>ChargeCode</FieldName>
<Value>FRT</Value>
</MatchingCriteria>
<MatchingCriteria>
<FieldName>CostOSCurrency</FieldName>
<Value>AUD</Value>
</MatchingCriteria>
</MatchingCriteriaCollection>
</ImportMetaData>

In the above example, the first line with a Charge Code of FRT and a Cost OS Currency of AUD
would be updated. If no matching line was found, the message would be rejected as the update
could not be made.

5.4.3.3.5 Using the UpdateAndInsertIfNotFound instruction

The UpdateAndInsertIfNotFound instruction can be used to update an existing matching charge

line/consol cost. In the event where a matching charge line/consol cost cannot be found, a new
line will be added.

In this case, one or more matching criteria can be specified for the system to locate the charge
line/consol cost to be updated.
<ImportMetaData>
<Instruction>UpdateAndInsertIfNotFound</Instruction>
<MatchingCriteriaCollection>
<MatchingCriteria>
<FieldName>ChargeCode</FieldName>
<Value>FRT</Value>
</MatchingCriteria>
<MatchingCriteria>
<FieldName>Creditor</FieldName>
<Value>FREAIRCMH</Value>
</MatchingCriteria>
</MatchingCriteriaCollection>
</ImportMetaData>

In the above example, the first line with a Charge Code of FRT and a Creditor Code of FREAIRCMH
would be updated. If no matching line was found, a new charge line would be added.

eAdaptor - Developer’s Guide | 199

The Delete instruction can be used to delete an existing matching charge line/consol cost.

In this case, one or more matching criteria can be specified for the system to locate the charge
line/consol cost to be updated.
<ImportMetaData>
<MatchingCriteriaCollection>
<Instruction>Delete</Instruction>
<MatchingCriteria>
<FieldName>Creditor</FieldName>
<Value>FREAIRCMH</Value>
</MatchingCriteria>
</MatchingCriteriaCollection>
</ImportMetaData>

In the above example, any lines with a Creditor Code of FREAIRCMH would be deleted. If no
matching lines were found, an error will be logged in the Data Import Log for the message as
shown below, and the message will be discarded.

Figure 105 View Message > Notes tab

eAdaptor - Developer’s Guide | 200

Example 1: Single Matching Criteria

<ImportMetaData>
<Instruction>UpdateAndInsertIfNotFound</Instruction>
<MatchingCriteriaCollection>
<MatchingCriteria>
<FieldName>ChargeCode</FieldName>
<Value>FSC</Value>
</MatchingCriteria>
</MatchingCriteriaCollection>
</ImportMetaData>

With the above matching criteria, the system will locate existing charge line with Charge code =
FSC and update it if found, add a new charge if not found.

Figure 106 Shipment > Billing tab

eAdaptor - Developer’s Guide | 201

© 2024 WiseTech Global 11 March 2024
Example 2: Multiple matching criteria
<ImportMetaData>
<Instruction>Update</Instruction>
<MatchingCriteriaCollection>
<MatchingCriteria>
<FieldName>Creditor</FieldName>
<Value>QANCARSYD</Value>
</MatchingCriteria>
<MatchingCriteria>
<FieldName>CostAPInvoiceNumber</FieldName>
<Value>MET1101</Value>
</MatchingCriteria>
<MatchingCriteria>
<FieldName>ChargeCode</FieldName>
<Value>FSC</Value>
</MatchingCriteria>
</MatchingCriteriaCollection>
</ImportMetaData>

With the above matching criteria, the system will locate existing charge line with Creditor =
QANCARSYD Invoice number = MET1101 and Charge code = FSC. If the charge line exists, it will
update.

Figure 107 Shipment > Billing tab

If a matching charge line is not found, an error will be logged in the Data Import Log for the
message, and the message will be discarded. For this reason, when using Update, it’s important to
know what the current state of the data is.

eAdaptor - Developer’s Guide | 202

The previous samples demonstrate the use of the ImportMetaData element only. Following is a
complete and more complicated sample including the Universal Shipment and multiple charge
lines at both the Consol and Shipment levels.
<UniversalShipment xmlns="http://www.cargowise.com/Schemas/Universal/2011/11" version="1.1">
<Shipment>
<DataContext>
<DataTargetCollection>
<DataTarget>
<Type>ForwardingConsol</Type>
<Key>C300001703</Key>
</DataTarget>
</DataTargetCollection>
<Company>
<Code>DAU</Code>
</Company>
<EnterpriseID>WTG</EnterpriseID>
<ServerID>XX1</ServerID>
</DataContext>

<ConsolCosts>
<ConsolCostLineCollection>
<ConsolCostLine>
<ImportMetaData>
<Instruction>Insert</Instruction>
</ImportMetaData>
<ApportionmentMethod>CHG</ApportionmentMethod>
<ApportionToSubShipments>false</ApportionToSubShipments>
<ChargeCode>
<Code>FRT</Code>
<Description>International Freight</Description>
</ChargeCode>
<ChargeCodeGroup>
<Code>FRT</Code>
<Description>Freight</Description>
</ChargeCodeGroup>
<CostExchangeRate>1</CostExchangeRate>
<CostLocalAmount>1555</CostLocalAmount>
<CostOSAmount>1555</CostOSAmount>
<CostOSCurrency>
<Code>AUD</Code>
<Description>Australian Dollar</Description>
</CostOSCurrency>
<Creditor>
<Type>Organization</Type>
<Key>QANCARSYD</Key>
</Creditor>
</ConsolCostLine>
</ConsolCostLineCollection>
</ConsolCosts>

<SubShipmentCollection>
<SubShipment>
<DataContext>
<DataTargetCollection>
<DataTarget>
<Type>ForwardingShipment</Type>
<Key>S54623816</Key>
</DataTarget>
</DataTargetCollection>
</DataContext>
<JobCosting>
<ChargeLineCollection>
<ChargeLine>
<ImportMetaData>

eAdaptor - Developer’s Guide | 203

© 2024 WiseTech Global 11 March 2024
<Instruction>Update</Instruction>
<MatchingCriteriaCollection>
<MatchingCriteria>
<FieldName>ChargeCode</FieldName>
<Value>FSC</Value>
</MatchingCriteria>
<MatchingCriteria>
<FieldName>Creditor</FieldName>
<Value>KELTRASYD</Value>
</MatchingCriteria>
</MatchingCriteriaCollection>
</ImportMetaData>
<Branch>
<Code>SYD</Code>
<Name>Cargowise EDI - Sydney (AU)</Name>
</Branch>
<ChargeCode>
<Code>FSC</Code>
<Description>Fuel Surcharge</Description>
</ChargeCode>
<CostLocalAmount>112.5000</CostLocalAmount>
<CostOSAmount>112.5000</CostOSAmount>
<CostOSCurrency>
<Code>AUD</Code>
<Description>Australian Dollar</Description>
</CostOSCurrency>
<Creditor>
<Type>Organization</Type>
<Key>KELTRASYD</Key>
</Creditor>
<Debtor>
<Type>Organization</Type>
<Key>AAASHISYD</Key>
</Debtor>
<Department>
<Code>FEA</Code>
<Name>Forwarding Export Air</Name>
</Department>
<Description>Fuel Surcharge</Description>
<SellLocalAmount>135.0000</SellLocalAmount>
<SellOSAmount>135.0000</SellOSAmount>
<SellOSCurrency>
<Code>AUD</Code>
<Description>Australian Dollar</Description>
</SellOSCurrency>
</ChargeLine>
<ChargeLine>
<ImportMetaData>
<Instruction>UpdateAndInsertIfNotFound</Instruction>
<MatchingCriteriaCollection>
<MatchingCriteria>
<FieldName>ChargeCode</FieldName>
<Value>ODOC</Value>
</MatchingCriteria>
</MatchingCriteriaCollection>
</ImportMetaData>
<Branch>
<Code>SYD</Code>
<Name>Cargowise EDI - Sydney (AU)</Name>
</Branch>
<ChargeCode>
<Code>ODOC</Code>
<Description>Origin Documentation Fee</Description>
</ChargeCode>
<CostLocalAmount>15.0000</CostLocalAmount>
<CostOSAmount>15.0000</CostOSAmount>
<CostOSCurrency>
<Code>AUD</Code>
<Description>Australian Dollar</Description>

eAdaptor - Developer’s Guide | 204

© 2024 WiseTech Global 11 March 2024
</CostOSCurrency>
<Debtor>
<Type>Organization</Type>
<Key>AAASHISYD</Key>
</Debtor>
<Department>
<Code>FEA</Code>
<Name>Forwarding Export Air</Name>
</Department>
<Description>Origin Documentation Fee</Description>
<SellLocalAmount>25.0000</SellLocalAmount>
<SellOSAmount>25.0000</SellOSAmount>
<SellOSCurrency>
<Code>AUD</Code>
<Description>Australian Dollar</Description>
</SellOSCurrency>
</ChargeLine>
<ChargeLine>
<ImportMetaData>
<Instruction>Delete</Instruction>
<MatchingCriteriaCollection>
<MatchingCriteria>
<FieldName>ChargeCode</FieldName>
<Value>OCART</Value>
</MatchingCriteria>
<MatchingCriteria>
<FieldName>Creditor</FieldName>
<Value>KELTRASYD</Value>
</MatchingCriteria>
<MatchingCriteria>
<FieldName>SupplierReference</FieldName>
<Value>REF1101</Value>
</MatchingCriteria>
</MatchingCriteriaCollection>
</ImportMetaData>
<Branch>
<Code>SYD</Code>
<Name>Cargowise EDI - Sydney (AU)</Name>
</Branch>
<ChargeCode>
<Code>OCART</Code>
<Description>Pick Up Cartage</Description>
</ChargeCode>
<CostLocalAmount>128.0000</CostLocalAmount>
<CostOSAmount>128.0000</CostOSAmount>
<CostOSCurrency>
<Code>AUD</Code>
<Description>Australian Dollar</Description>
</CostOSCurrency>
<Debtor>
<Type>Organization</Type>
<Key>AAASHISYD</Key>
</Debtor>
<Department>
<Code>FEA</Code>
<Name>Forwarding Export Air</Name>
</Department>
<Description>Pick Up Cartage</Description>
<SellLocalAmount>138.0000</SellLocalAmount>
<SellOSAmount>138.0000</SellOSAmount>
<SellOSCurrency>
<Code>AUD</Code>
<Description>Australian Dollar</Description>
</SellOSCurrency>
</ChargeLine>
</ChargeLineCollection>
</JobCosting>
</SubShipment>
</SubShipmentCollection>

eAdaptor - Developer’s Guide | 205

The preceding sample will target Forwarding Consol C300001703 and Forwarding Shipment
S54623816 then:

• Insert a new “FRT” Consol Cost to Consol C30001703 and apportion to the shipments
based on CHG – Chargeable Units
• Update “FSC” Shipment S54623816 Job Charge using matching criteria: ChargeCode ‘FSC’
and Creditor ‘KELTRASYD’
• UpdateAndInsertIfNotFound “ODOC” Shipment S54623816 Job Charge using matching
criteria: ChargeCode ‘ODOC’
• Delete “OCART” Shipment S54623816 Job Charge using matching criteria: ChargeCode
‘OCART’, Creditor ‘KELTRASYD’ and SupplierReference ‘REF1101’

The sample above was imported into a system where the Forwarding Consol C300001703 had
no charges on the Consol Costs tab and Forwarding Shipment S54623816 had charges on the
Billing tab as shown below.

Figure 108 Shipment > Billing tab

eAdaptor - Developer’s Guide | 206

Figure 109 Consol > Consol Costing tab

Forwarding Shipment S54623816 is updated as follows:

• FSC Charge Line was updated as a match was found

• ODOC Charge Line was inserted as no match was found
• OCART Charge Line was deleted as a match was found

Figure 110 Shipment > Billing tab

eAdaptor - Developer’s Guide | 207

© 2024 WiseTech Global 11 March 2024
5.4.4 SendersLocalClient and LocalClient Organization
elements
Most operational modules within CargoWise show a Billing Tab. This tab contains charge lines
used for billing, along with the Branch, Department, Exchange Rates, Local Client and sometimes a
secondary billing party like the Overseas Agent in the case of a Forwarding Shipment.

Figure 111 Shipment > Billing tab

This information is included in the Universal Shipment XML under the JobCosting element except
for the Organizations. The Local Client Organization often shows on the main job tab (as shown
following on the Forwarding Shipment), so to keep things consistent the Local Client Organization
was included directly under the main Universal Shipment.

eAdaptor - Developer’s Guide | 208

5.4.4.1 Exporting the Local Client

Organizations on a Universal Shipment are found within the OrganizationAddressCollection as
OrganizationAddress elements. Each OrganizationAddress has an AddressType. When you send a
Universal Shipment, the AddressType used for the Local Client is SendersLocalClient as shown in
the sample following.
<OrganizationAddress>
<AddressType>SendersLocalClient</AddressType>
<Address1>8770 W BRYN MAWR AVE STE 1300</Address1>
<AddressShortCode>8770 WEST BRYN MAWR AVE,</AddressShortCode>
<City>CHICAGO</City>
<CompanyName>UNITED ENTERPRISES (US) CORPORATION</CompanyName>
<Country>
<Code>US</Code>
<Name>United States</Name>
</Country>
<Email>[email protected]</Email>
<Fax>+18736412232</Fax>
<OrganizationCode>UNIENTORD</OrganizationCode>
<Phone>+18736412122</Phone>
<Port>
<Code>USORD</Code>
<Name>O'Hare Apt/Chicago</Name>
</Port>
<Postcode>60631</Postcode>
<State>IL</State>
</OrganizationAddress>

eAdaptor - Developer’s Guide | 209

© 2024 WiseTech Global 11 March 2024
5.4.4.2 Importing the Local Client
When importing a Universal Shipment, OrganizationAddress elements with an AddressType of
SendersLocalClient are ignored. If you want to set the Local Client when importing Universal
Shipment XML, you can use the AddressType LocalClient to do so. This means that when
Universal Shipments are exported/sent, they use an AddressType of SendersLocalClient, but use
LocalClient when they are imported/received.

5.4.4.3 Local Clients are Different in Different Business Contexts

When using Universal Shipments to transfer job data from one CargoWise system to another, it is
very rare that the Local Client in one system will end up being the same as the Local Client in the
other system. For the Sending Forwarder the client will be the Consignor, for the Receiving
Forwarder, the client will be the Consignee. Where domestic transport is involved, the client may
be a Forwarder, Consignor, Consignee, or even a Customs Broker.

These Organizations are already included in the Universal Shipment XML and are used by the
receiving system to set the Local Client upon XML Import using the context of the sent Shipment
and target module/recipient role. The Sender’s Local Client is included in case it is of interest to
the receiving system but is not used to set the Local Client in the target system.

5.4.4.4 Setting the Local Client Directly

Some integrations within house business management systems require the ability to set the
Local Client directly. To meet this requirement, you can include an OrganizationAddress with an
AddressType of LocalClient which will be stored directly in the Local Client field.

When you do this, you must make sure that you provide a Branch, or that the Branch on the
Billing tab has already been set. You must also have the Department provided, or enough
information in the incoming XML to be able to default the Department. The reason for this is that
the Branch and Department fields are mandatory and must be filled in before any fields on the
Billing tab can be set.

If there is not enough information provided to save the Billing/Job Costing information, you will
see an error in the Message Processing Log like the following.

Error - Could not save Local Client Organization - Must have an Origin, Destination and Transport Mode
to be able to calculate a Department for a Job Costing record, as the Local Client is saved on the Job
Costing record.

eAdaptor - Developer’s Guide | 210

© 2024 WiseTech Global 11 March 2024
5.4.5 Additional References
Many modules in CargoWise have a list of Additional References where users can pre-define a
list of reference types, they want to be able to track, and enter as many of these references as
they like. In modules where these are available, they are included in the
AdditionalReferenceCollection when exporting a Universal Shipment. One example of Additional
References is the Reference Numbers grid on the Additional Detail tab on a Forwarding Shipment.

Figure 113 Shipment > Additional Details tab

eAdaptor - Developer’s Guide | 211

© 2024 WiseTech Global 11 March 2024
5.4.5.1 Exporting
When a Universal Shipment is sent from an entity with Additional References, the Additional
Reference Code is sent in the Type.Code element, and the description associated with that code
is sent in the Type.Description element. The reference number itself is included in the
ReferenceNumber element.

This means that if a Universal Shipment was sent from the Forwarding Shipment shown above in
the previous sample, the AMS Number and Customs Office Code Override would be included as
shown:

<UniversalShipment xmlns="http://www.cargowise.com/Schemas/Universal/2011/11" version="1.1">

<Shipment>
<DataContext>
<DataSourceCollection>
<DataSource>
<Type>ForwardingShipment</Type>
<Key>S00043996</Key>
</DataSource>
</DataSourceCollection>

<EnterpriseID>CWE</EnterpriseID>
<ServerID>PRD</ServerID>
<Company>
<Code>CWS</Code>
<Name>WiseTech Global edi Pty Ltd</Name>
</Company>
</DataContext>

<AdditionalReferenceCollection>
<AdditionalReference>
<Type>
<Code>AMS</Code>
<Description>AMS Number</Description>
</Type>
<ReferenceNumber>34217-812349</ReferenceNumber>
</AdditionalReference>
<AdditionalReference>
<Type>
<Code>COC</Code>
<Description>Customs Office Code Override</Description>
</Type>
<ReferenceNumber>FFG3278197</ReferenceNumber>
</AdditionalReference>
</AdditionalReferenceCollection>

</Shipment>
</UniversalShipment>

eAdaptor - Developer’s Guide | 212

© 2024 WiseTech Global 11 March 2024
5.4.5.2 Importing
When Universal Shipments come back into CargoWise, any AdditionalReference elements with a
Type.Code value matching a valid Additional Reference Type as defined in the registry are
imported as Additional Reference Numbers.

If Additional References are sent with Type.Code values that are not present in the registry, these
are recorded in a read-only Note against the updated entity with the description, ’Unrecognised
Additional Reference Types‘. Users can then see these references and decide whether they need
to be entered in another place or can be safely ignored.

Figure 114 Shipment > Notes tab

eAdaptor - Developer’s Guide | 213

© 2024 WiseTech Global 11 March 2024
5.4.5.3 Registry settings
Additional Reference Types are defined in the CargoWise registry with a Code and Description as
shown below:

Figure 115 Registry setting Freight > Customs Numbers

The registry item shown above is used to define the Additional Reference Types available on a
Forwarding Shipment. For more information on how to setup Additional Reference Types in a
given module you should refer to the documentation for that module. For modules where the
Registry settings are company specific, the Company from the DataContext element is used to
load the right set of Additional Reference Types from the registry.

5.4.5.4 Matching on Import

If an appropriate set of Additional Reference Types is loaded from the registry, any Context
Values where the Type matches one of the existing Additional Reference Types may be used for
matching as part of the Combination Key Match for that module if Combination Key Matching is
enabled.

Information on which modules implement Additional References, where they appear in those
modules and how they are used for matching is available in the Module Mapping Guides.

If the Additional Reference code provided cannot be found in the appropriate registry item, the
Context Value will not be used for Additional Reference matching.

Module Mapping Guides describe the keys used for matching, give an overview of how the
schema is mapped, and provide a list of element level mappings describing each field’s
location in the GUI. They can be found under Integration Options – Mapping Guides

eAdaptor - Developer’s Guide | 214

© 2024 WiseTech Global 11 March 2024
5.4.6 Importing and Exporting Notes
Notes in Universal XML are represented by Content attribute within a NoteCollection. They
appear within a number of datasets as they are commonly implemented within CargoWise.

5.4.6.1 Collection Content Attribute

All notes that are input through a universal XML are by default merged with pre-existing notes.
However, the Collection Content attribute within the NoteCollection, allows for the specification
of either:

• Partial – where the changes to matching notes are updated, changes to new notes are
added and unmatched notes are left unchanged. A sample can be seen below:
• <NoteCollection Content="Partial">
• Complete – where the changes to matching notes are updated, changes to new notes are
added and unmatched notes are deleted’. A sample can be seen below:
• <NoteCollection Content="Complete">

When importing universal XMLs the default, where not specified, is “Partial”.

5.4.6.2 Note Types In The GUI

Looking at the Notes tab on the Organizations form following you can see examples of three
different Note Types. The first one is Goods Handling Instructions.

eAdaptor - Developer’s Guide | 215

© 2024 WiseTech Global 11 March 2024
When that is selected, you will see that above the text box where you type your note, it says the
note is Text Only. This is the simplest way to tell which Note Types/Descriptions are Text Only.
You will see that there is no formatting available, and all you can enter is plain text.

When you select the Internal Work Notes note, the text entry section at the bottom of the form
changes to allow you to select fonts, colors, styles, and insert pictures.

This means that Internal Work Notes is a Rich Text note type. Both of these note types are pre-
defined system note types, the last type of notes are Custom notes.

5.4.6.3 Note types Registry setting

The Note Types for each module are configured in the Custom Defined Note Types registry item

Go to Maintain > System > Registry then open up the sub-tree System > Custom Defined Note
Types.

eAdaptor - Developer’s Guide | 216

© 2024 WiseTech Global 11 March 2024
When a note is imported via Universal XML, the <Description> element is used to define the Note
type, which then attempts to get matched against a Custom Defined Note Types registry item, or
a pre-existing system defined note type.

5.4.6.4 Importing and Exporting Plain and Rich Text Notes via
Universal XML
There are two types of notes you can have in CargoWise, Text Only and Rich Text Notes.
Universal XMLs do not support Rich Text Notes. Rich text notes cannot be imported through a
Universal XML and when exported they do not retain their original formatting.

eAdaptor - Developer’s Guide | 217

© 2024 WiseTech Global 11 March 2024
An example of a Universal XML export of a Rich Text Note containing “Bold”, “Italic” and
“Underlined” characters can be seen in the sample below.
<NoteCollection Content="Partial">
<Note>
<Description>Note test</Description>
<IsCustomDescription>false</IsCustomDescription>
<NoteText>The Bold
The Italic
The Underline</NoteText>
<NoteContext>
<Code>AAA</Code>
<Description>Module: A - All, Direction: A - All, Freight: A -
All</Description>
</NoteContext>
<Visibility>
<Code>PUB</Code>
<Description>CLIENT-VISIBLE</Description>
</Visibility>
</Note>
</NoteCollection>

As seen in this sample the “Bold”, “Italic” and “Underlined” characters have been reformatted into
plain text and the pre-existing formatting from the job notes is not retained.

5.5 Universal Events

5.5.1 Overview
Universal Events are an XML representation of a single Event that you can see on the Events sub
tab of any Workflow & Tracking tab in most operational modules throughout CargoWise. Universal
Events can be sent to a CargoWise installation via the eAdaptor Web Service Interface and will
cause Event logs to be added on any entity that the incoming Universal Event is matched to.

The eHub Gateway service can be used to send Universal Events to your CargoWise installation
via the eAdaptor interface. This enables you to create your own Web Service based Service Bus
using a tool like Microsoft BizTalk to communicate directly with the eAdaptor interface.

As Universal Events come in, they trip any Milestones and Triggers configured on the Workflow
tab of the entity they are linked to and can update dates and other fields with data specified in
the Universal Event on that entity.

You can also push events out via the eAdaptor Interface using Workflow Triggers. In all areas
where the Workflow & Tracking tab appears, you can configure Workflow to export Universal
Events by configuring a trigger action with an Action Type of XUE Send XML Universal Event.
These Universal Events are sent from CargoWise via the eAdaptor interface to either our eHub
Gateway or your own internal Web Service.

Only field attached to the Business Object Schema can be updated via an XUE. Any other fields
that need to be updated (For example. Customs fields) should be done via an XUS.

eAdaptor - Developer’s Guide | 218

© 2024 WiseTech Global 11 March 2024
Refer to our Workflow learning units for more information on the Workflow entities mentioned
above.

5.5.2 Universal Event Schema

You can obtain a current XSD Schema for the Universal Event using the functionality described in
Section 3.1 Obtaining Current XML Schemas earlier in this document.

5.5.3 Common implementation aspects

5.5.3.1 Overview
Following is a description of what you should expect to see in each element in a Universal Event
when populated:

• EventType (mandatory) -This is the Three-character event code. Describes what the
nature of the event. You will have seen some of these already on the Workflow & Tracking
> Events tab on various Business Entities (Shipment, Consol, Declaration etcetera.)
throughout CargoWise
• EventDescription (optional) - Human readable description of the event. May contain
supplementary information to clarify the scope of the event, but this will not affect how the
event is processed. Is imported ‘as is’ upon consumption so the user can identify the event
easily
• EventTime (mandatory) - This is the time the event occurred, or in the case of ‘Estimate’
events, the time at which the event is estimated to occur. Please note that this is taken
from the Event Time, not the Posted Time in CargoWise
• There is no time zone directly associated with the Event Time; it is seen as the Local Time
for the location at which the event occurred. For a Departure event it would be the time
zone at the original, for an Arrival event, it would be the time zone at the destination and so
on. This is how most industry systems supply event data, so this is how we work with it
ourselves
• CreatedTime (optional) - This is the time at which the event information was generated or
supplied. Only used in the case where the Event Time is different from the time the event
was generated. In most cases, the event should be generated at the same time the event
occurred so this field will not be included, but for cases like Estimate events, this would be
used so that you can tell when the estimate was made
• DataProvider (mandatory) - Describes the Communications Service Providers (CSP)
providing the event information
• IsEstimate – Set to indicate an event is an estimate for a future event

eAdaptor - Developer’s Guide | 219

© 2024 WiseTech Global 11 March 2024
• IsPartial – Set when the event only relates to part of the Business Entity identified by the
collection of Keys. Used for things like split masters where the airlines split one master
across two flights to meet loading constraints. For example, a partial delivery would have
the ‘IsPartial’ flag set on it, and the last and final partial delivery would not have the flag set
showing that the event is fully complete
• IsCancelled – Not implemented
• ContextCollection (conditional) - Contexts have a Type and Value. These are used to
narrow down the context in which the event applies to the Business Entity identified by the
Keys above, and to provide additional information about the Event itself where a field for
the information does not already exist on the Universal Event. The Type may optionally
have a Description attribute where the Type is an abbreviation or short code representing
the Type of information being sent
• AddtionalFieldsToUpdateCollection (optional) – Contains a list of Field Names to update
(Type) along with values to update those fields with. Field Names are expected in the form
of TableName.FieldName. Whenever a Universal Event is linked to an entity, if the
underlying table name of that entity matches the table name specified in an
AdditionalFieldToUpdate and the Field identified by name exists, that field will be updated
with the Value specified. This means that things like critical dates and signatory names on
PODs can be updated using Events

5.5.3.2 Context Values

Context Values in the ContextCollection are used by CargoWise to work out where the event
should be applied throughout the system. The combination of Values provided determines what
type or types of Business Entity the Event will be applied. For example, where an event had:

• Master Bill only – Link to a Consolidation with that Master Bill

• Master Bill and Flight Number– Link to a Consolidation Transport Leg. with that Flight
Number
• Master Bill and House Bill – Link to a Shipment or Declaration with both matching
• Master Bill and Container Number – Link to a Container against a Consolidation. Event
shown on the Consolidation
• Master Bill, House Bill and Container Number – Link to a Container against a Shipment or
Declaration. Event shown on the Shipment or Declaration

Context Values are only sent where they are required to uniquely identify the entity a given event
applies. This means that something like a Flight Number would only be included where the Event
related to that flight, or a particular Transport Leg. If the Event related to the entire
Consolidation, the Flight Number will not be included.

Another common usage of a Context Values is to specify the place the event occurred. A
Departure event might apply to the ‘first’ or ‘second leg.’ on a Consolidation where multiple legs
exist. A location based Context Value then allows us to identify which leg. has just been
embarked on.

eAdaptor - Developer’s Guide | 220

© 2024 WiseTech Global 11 March 2024
These are the Context Value Type codes we currently use for identifying entities within
CargoWise:

Air Only Multi-Modal Other Mode Specific

MAWBNumber MBOLNumber VesselName (Sea)

MAWBOriginIATAAirportCode MBOLOriginUNLOCO VoyageNumber

(Sea, Road, Rail)

MAWBDestinationIATAAirportCode MBOLDestinationUNLOCO

IATAAirportCode UNLOCO

FlightDate LegDepartureDate

FlightNumber LegArrivalDate

ULDIdentification ContainerNumber

HAWBNumber HBOLNumber

HAWBOriginIATAAirportCode HBOLOriginUNLOCO

HAWBDestinationIATAAirportCode HBOLDestinationUNLOCO

CarriersBookingReference

ShippersReference

OrderNumber

InterimReceipt

eAdaptor - Developer’s Guide | 221

CFSReference

These may or may not be used in each module depending on the information available within
that module. For more information on which Context Value Types are included in each module
when exporting and importing Universal Events, refer to the Module Mapping Guides.

Module Mapping Guides describe the keys used for matching, give an overview of how the
schema is mapped, and provide a list of element level mappings describing each field’s
location in the GUI. They can be found in Integration Options – Mapping Guides

You can also include any additional information you like in the ContextCollection by making up
your own Context Value Type codes. Although CargoWise will only use the list above to work out
which entities the Event applies to, you can add any Context Type and Value you like using
Pascal Casing on the Type.

When you do this, CargoWise will show every Type and Value provided in a human readable form
by inserting spaces into the key where indicated by the Pascal Naming capitalizations. There is a
screenshot of how this appears in CargoWise in section 5.5.4 Events Showing in CargoWise .

Context Value Type elements can optionally include a Description attribute. This is used where
either a short code or abbreviation has been used in the Type value so that a full human readable
description can be specified. This description is used instead of the description generated from
Pascal Naming wherever it is used. One place the Description attribute is used is where modules
in CargoWise allow users to enter a list of Additional References.

5.5.3.3 Additional References

Many modules in CargoWise have a list of Additional References where users can pre-define a
list of reference types, they want to be able to track, and enter as many of these references as
they like. In modules where these are available, they are included in the Context Values when
exporting a Universal Event. One example of Additional References is the Reference Numbers grid
on the Additional Detail tab on a Forwarding Shipment.

eAdaptor - Developer’s Guide | 222

When a Universal Event is sent from an entity with Additional References, the Additional
Reference Code is sent in the Type element, and the description associated with that code is
sent in the Description attribute on the Type element. The reference number itself is included in
the Value element of the Context item.

This means that if a Universal Event was sent from the Forwarding Shipment shown above in the
previous sample, the AMS Number and Customs Office Code Override would be included as
shown:

eAdaptor - Developer’s Guide | 223

© 2024 WiseTech Global 11 March 2024
<UniversalEvent xmlns="http://www.cargowise.com/Schemas/Universal/2011/11" version="1.0">
<Event>
<DataContext>
<EnterpriseID>CWE</EnterpriseID>
<ServerID>PRD</ServerID>
<Company>
<Code>CWS</Code>
<Name>WiseTech Global edi Pty Ltd</Name>
</Company>
</DataContext>
<EventTime>2011-06-08T19:26:18.96</EventTime>
<EventType>ATH</EventType>
<DataProvider>CW1</DataProvider>
<ContextCollection>
<Context>
<Type>MAWBNumber</Type>
<Value>081-11111111</Value>
</Context>
<Context>
<Type>HAWBNumber</Type>
<Value>HAF0003278137</Value>
</Context>
<Context>
<Type Description="AMS Number">AMS</Type>
<Value>34217-812349</Value>
</Context>
<Context>
<Type Description="Customs Office Code Override">COC</Type>
<Value>FFG3278197</Value>
</Context>
</ContextCollection>
</Event>
</UniversalEvent>

When Universal Events come back into CargoWise if the EnterpriseID and ServerID of the
incoming Universal Event match the Enterprise ID and Server ID of the CargoWise installation, any
Context Values with a three-character Type will used for matching to Additional References.

eAdaptor - Developer’s Guide | 224

© 2024 WiseTech Global 11 March 2024
Additional Reference Types are defined in the CargoWise registry with a Code and Description as
shown below:

Figure 117 Registry setting Freight > Customs Numbers

If an appropriate set of Additional Reference Types is loaded from the registry, any Context
Values where the Type matches one of the existing Additional Reference Types will be used for
matching as part of the Combination Key Match for that module. Information on which modules
implement Additional References, where they appear in those modules and how they are used
for matching is available in the Module Mapping Guides.

If the Additional Reference code provided cannot be found in the appropriate registry item, the
Context Value will not be used for Additional Reference matching.

Module Mapping Guides describe the keys used for matching, give an overview of how the
schema is mapped, and provide a list of element level mappings describing each field’s
location in the GUI. They can be found in Integration Options – Mapping Guides

eAdaptor - Developer’s Guide | 225

© 2024 WiseTech Global 11 March 2024
5.5.3.4 AdditionalFieldsToUpdate Collection
Sometimes when events occur, there is additional information used to supplement or
substantiate the event itself. Examples of this kind of information are the name of a signatory
when delivery is signed for, or a date related to the action that is being chronicled by the event.

This functionality is designed for small supplementary updates of fields directly related to the
entity the Event is being applied against. It has a simple syntax, which does not allow you to
update child entities by design. If you want to update more than one or two additional fields or
any information on child entities, it is recommended that you use the Universal Shipment instead.

Each AdditionalFieldsToUpdate element contains the following sub elements:

• Type: Identifies the Type and Field name you want to update using the value specified.
• Value: The value to store in the field identified by the Type element.

Following is an example of a Universal Event with an Event Type of DCF (Delivery Cartage
Finalised) including an Additional Field Update for the Delivery Cartage Completed Date:
<UniversalEvent xmlns="http://www.cargowise.com/Schemas/Universal/2011/11" version="1.1">
<Event>
<DataContext>
<DataTargetCollection>
<DataTarget>
<Type>ForwardingShipment</Type>
<Key>S00006294</Key>
</DataTarget>
</DataTargetCollection>
</DataContext>
<EventTime>2016-12-05T12:12:00</EventTime>
<EventType>DCF</EventType>
<AdditionalFieldsToUpdateCollection>
<AdditionalFieldsToUpdate>
<Type>ForwardingShipment.DocsAndCartage.JP_DeliveryCartageCompleted</Type>
<Value>2016-12-05T12:12:00</Value>
</AdditionalFieldsToUpdate>
</AdditionalFieldsToUpdateCollection>
</Event>
</UniversalEvent>

5.5.3.4.1 Component Parts of the Type

You will notice that the Type on the AdditionalFieldsToUpdate element has three parts to it with a
period (.) in between each component part:

• ForwardingShipment: The first part is the Entity Type that this update will apply. Universal
Events can be consumed by many modules, and the field names are different in each
module. When linking a Universal Event to an Entity, field updates will only be attempted
when the Entity Type matches the type of Entity the Event is being linked
• DocsAndCartage: The second part in this case identifies a related entity that the field
being updated actually sits. This is optional and can only be used where there is one and
only one related entity identified by the identifier specified. You cannot use this facility to
update a value in related child entities as there is no way to know which child row should
be updated. If you want to update information on child entities, it is recommended that
you use the Universal Shipment instead. If we were updating a field directly on the

eAdaptor - Developer’s Guide | 226

© 2024 WiseTech Global 11 March 2024
ForwardingShipment, this part and its separating period (.) would not be included
• JP_DeliveryCartageCompleted: The last part is always the name of the field being
updated

5.5.3.4.2 Discovering the Type for a field

Now that you know what component parts make up the Fields Update Type, you need to know
how to work out what those values are. You can work out what these are from existing samples
where they are available, or you can use some of the developer tools available from within
CargoWise itself.

For Universal Event sample files, see the eAdaptor Sample Interfaces Pack available from
Integration Options – eAdaptor Guides

You can calculate the Field Update Type from the binding information available from the
CargoWise GUI interface. To show the binding information for a field, first navigate to that field in
the GUI. For this example, we will open a Forwarding Shipment, then go to the Delivery tab, and
select the Actual Delivery field.

Figure 118 Shipment > Delivery tab

eAdaptor - Developer’s Guide | 227

© 2024 WiseTech Global 11 March 2024
Hold down the CTRL and SHIFT keys, then press R. A dialog will display showing the Binding
Information for the selected edit box.

Figure 119 Developer Information Dialogue Box

The last DataSource Type and BindingMember shows the Entity Type and field binding
information that is used to obtain the FieldToUpdate Type as follows.

DataSource type: Enterprise.Freight.Forwarding.Business.ForwardingShipment

BindingMember: DocsAndCartage+JP_DeliveryCartageCompleted

The first part of the AdditionalFieldsToUpdate Type is obtained from the last part of the
DataSource type. In this case, that’s ForwardingShipment. The rest of it comes from the
BindingMember using a period (.) delimiter between each part. In this case that means we insert a
period between the first part and the binding member, then replace the ‘+’ from the binding
member with a period. The result is then:

ForwardingShipment.DocsAndCartage.JP_DeliveryCartageCompleted

5.5.3.4.3 Formatting values for the Value element

The data you provide will be converted to the format required by the field you are trying to
update. Although the type of the Value element is a string in the XSD, you should provide the
content as though the Value element was actually defined as the XML type corresponding to the
type of the field you are updating. This means that if you are trying to update a date field, you
should use the XML Date format when formatting your content. The same applies for booleans,
integers and decimals.

eAdaptor - Developer’s Guide | 228

When field updates are successfully made using the AdditionalFieldsToUpdate elements, this is
logged in the Data Import Log Text note on the EDI Message itself.

Figure 120 View Message > Notes tab

You will see from the message in the example above that the field update was successful. If the
first part of the AdditionalFieldsToUpdate Type matches the module being targeted but the field
does not exist, or the content in the Value element is not of the right type to be stored in the
target field, an error will be shown.

If the first part of the AdditionalFieldsToUpdate Type does NOT match the module being
updated, no error will be shown as updates are only attempted when the module being updated
matches the type.

When the update is a success, go to the Forwarding Shipments module, open the Shipment being
updated (S00006294 in this case) and click on the Delivery tab. You will see the Actual Delivery
field has been updated with the date from the Value element in the AdditionalFieldsToUpdate
element.

eAdaptor - Developer’s Guide | 229

eAdaptor - Developer’s Guide | 230

© 2024 WiseTech Global 11 March 2024
5.5.4 Events Showing in CargoWise
After the initial configuration work is done, Events flow into the EDI Messages module via the
eAdaptor Interface from xHub or your own internal Gateway. CargoWise automatically parses
each incoming Universal Event and attempts to locate the appropriate Business Entity to link the
Event to.

If a matching Business Entity is found, the Event is added to the list of Events showing on the
Events sub tab under the Workflow and Tracking tab on that Business Entity. An example of this
is shown below for an FSU/RCS message translated to a CargoWise Universal Event with a type of
RCV – Received from Shipper:

Figure 122 Consol > Workflow & Tracking Events tab

You will note that when you select an Event that was created from an external Universal Event,
the Event Context Information grid appears showing all of the Context information that came
along with the Event from the Event Provider.

For Business Entities such as Containers that always reside on a parent Business Entity like a
Consolidation or a Declaration, the Event will appear on the Events sub tab of the parent Business
Entity with the Source column identifying the container the event relates.

eAdaptor - Developer’s Guide | 231

© 2024 WiseTech Global 11 March 2024
5.5.4.1 Effects an Event has
Once the event has been matched and added, it will be fired so that any Key Date Updates that
are supposed to respond to that event will be fired, and any Triggers or Milestones that have
been setup for that event will respond.

5.5.4.2 Event Cascading

When an Event is fired on a Parent Business Entity, the effect of that event on Milestones and
Triggers will cascade down to any Milestones and Triggers defined on any Child Business Entities
where the Workflow & Tracking tab appears. An example of this would be on the Forwarding
Consolidation where any Events raised on the Consolidation (parent job) will now trip Milestones
and Triggers on any Shipment (child job) related to that Consolidation. This is called Event
Cascading.

When you go to the Workflow & Tracking tab, Events sub tab within a Shipment linked to a
Consolidation, you would already have seen Events from the Consolidation showing up on the
Shipment. Previously these would not have tripped any Triggers or Milestones on the Shipment.
Now any events raised on the Consolidation will cascade down to trip Triggers and Milestones
defined on the Shipment so that as well as showing in the log, they can also trigger Actions and
complete Milestones on the Shipment.

This means that when a DEP - Departed event is raised on the Consolidation, each Shipment
linked to the Consolidation is checked for Triggers and Milestones, and if any of those are
configured to respond to the Departed event, they will be tripped and completed as is
appropriate. If there are events that you do not want to Cascade, you can apply a filter for that
Event Type as described above.

At this point Event Cascading only works with Consolidation Events cascading down to Shipment
level Workflow, and Shipment Events cascading down to Sub-Shipments, but this will be
implemented in other areas of CargoWise over time. Where applicable, Events will continue to
cascade down wherever there are more related child objects that have Workflow on them to
respond to cascaded events.

5.5.4.3 Event propagating

When an Event is fired on a Child Business Entity, the effect of that event on Milestones and
Triggers will propagate up to any Milestones and Triggers defined on any Parent Business Entities
where the Workflow & Tracking tab appears.

This is like the Event Cascading described above, but instead of the Events cascading down, they
are propagating up. The main difference is that when propagating up, Milestones and Triggers and
only tripped when ALL Child Business Entities on the Parent have raised that same event.

This means that if an Unpacked Event was raised on a Shipment, the Shipment will notify the
Consolidation to say that it has had the Unpacked event raised. The Consolidation will then check
all of the other Shipments linked to that Consolidation and if they ALL have the Unpacked event
on them, will raise an Unpacked event against the Consolidations with a description showing:

eAdaptor - Developer’s Guide | 232

© 2024 WiseTech Global 11 March 2024
• Internal Event: All Shipments: Unpacked
• Propagation will work in the following places:
• Shipment Events > Parent Consolidation
• Container Events > Parent Shipment
• Container Events > Parent Consolidation

At this point Event Propagation will only go one tier up from the place the Event is raised. This is
to stop Container level Events getting double propagated to Consolidations via the Shipments
and direct to the Consolidations as well.

Propagation will be implemented in other modules of CargoWise over time. In some of those
areas Events may propagate up multiple levels if there’s a business requirement to do so but at
this point there’s only been a need to propagate up one level.

5.5.4.4 Monitoring Events coming In

All incoming Universal Events show under Maintain > System > EDI Messages, so you can see an
overview of all Events coming in.

Figure 123 EDI Message Search Screen

There are also three registry items you can configure that turn on email notifications when xHub
XML events arrive in CargoWise. These would generally only be used for debugging purposes
while configuring your own Service Bus.

eAdaptor - Developer’s Guide | 233

© 2024 WiseTech Global 11 March 2024
eHub > Notifications > Incoming Event Matched Recipient will trigger an email to all parties
specified by this registry item when an Event is successfully Matched to a Business Entity.
Options are:

• None (default setting) – No email as long as the Event is Matched

• Operator – Email sent to the Operator of the Matched Business Entity
• Email Group – Email sent to a Specified Group
• Operator and Email Group – Email sent to a Specified Group and the Operator of the
Matched Business Entity

CargoWise determines who the Operator is by looking at the Business Entity to see if there’s an
explicit Operator field (e.g., Declaration has ‘Broker’) then falling back to the last person to edit
the Business Entity where nothing more explicit is available.

An Event Matched email contains:

• The Business Entity Types and Reference Numbers that the event was linked (e.g., “Consol
C00003427” or “Container CRXU9378472”)
• A URL Link to any Business Entities showing the event on the Workflow & Tracking tab
Events sub tab. For Containers this would be the parent Consol or Declaration
• Information from the XML Event itself including all Fields, Keys, and Contexts

eHub > Notifications > Incoming Event Matched Group

• Allows you to specify a Group, used when Group is one of the options selected in the
registry item above. The default setting is PMG - Post Masters

eHub > Notifications > Incoming Event Not Matched Group

• Will trigger an email to the Group specified by this registry item when an Event arrives from
eHub but is not matched to any known Business Entity. The default setting is PMG - Post
Masters
• If you want to turn off this notification, simply remove the group from the registry item

An Event Not Matched email contains all information from the XML Event itself including Fields,
Keys and Contexts, but no other information as no match was found.

Refer to 1COR192 - How can I get email notifications for Inbound Universal XML failures?

5.5.5 Sending eDocs to DocManager using Universal Event

XML
Documents can be uploaded to the eDocs of records by specifying “DocManager” as the
DataTarget type of a Universal Event. As with importing documents using the DocManager Import
Service task, documents can be allocated based on filename allocation details or barcodes within
the document.

eAdaptor - Developer’s Guide | 234

© 2024 WiseTech Global 11 March 2024
Universal Document Request supports functionality to upload documents to the eDocs tab using
type of DocManager. The document allocation details (i.e., Document Type, Job Number) for
DocManager can either be provided from barcodes within the base64 encoded document or
from the details provided in the <FileName> element. When using barcodes for allocation, the
barcodes can only be processed from TIF or PDF files. They must also be on separate pages and
scanned in the order of: Job Type barcode > Doc Type barcode > document to allocate.
It is possible to send multiple documents in a single UniversalEvent message. When sending
multiple documents, each document will reside within a separate <AttachedDocument> element in
the <AttachedDocumentCollection> element.
In below example below, there are two documents being sent in the UniversalEvent message. The
first document contains barcodes within the base64 encoded document that provide the
allocation details. The second document contains the allocation details in the filename.

<UniversalEvent xmlns="http://www.cargowise.com/Schemas/Universal/2011/11" version="1.1">

<Event>
<DataContext>
<DataTargetCollection>
<DataTarget>
<Type>DocManager</Type>
</DataTarget>
</DataTargetCollection>
<Company>
<Code>DAU</Code>
</Company>
<EnterpriseID>WUT</EnterpriseID>
<ServerID>UAT</ServerID>
</DataContext>
<EventTime>2016-12-05T12:12:00</EventTime>
<EventType>DDI</EventType>
<AttachedDocumentCollection>
<AttachedDocument>
<FileName>Client Agreement.tif</FileName>
<ImageData>SUkqAB5AAACAPe --- base64 encoded binary stream --- kKJSVFT0YK</ImageData>
<IsPublished>true</IsPublished>
<VisibleCompanyCode> </VisibleCompanyCode>
<VisibleBranchCode> </VisibleBranchCode>
<VisibleDepartmentCode> </VisibleDepartmentCode>
</AttachedDocument>
</AttachedDocumentCollection>
<AttachedDocumentCollection>
<AttachedDocument>
<FileName>[SHP BKC S00001493]Client Agreement.tif</FileName>
<ImageData>SUkqAB5AAACAPe --- base64 encoded binary stream --- kKJSVFT0YK</ImageData>
<IsPublished>true</IsPublished>
<VisibleCompanyCode> </VisibleCompanyCode>
<VisibleBranchCode> </VisibleBranchCode>
<VisibleDepartmentCode> </VisibleDepartmentCode>
</AttachedDocument>
</AttachedDocumentCollection>
</Event>
</UniversalEvent>

Document Attributes available are:

• FileName – Provide the Filename of the Document. Also, using filename, details for
allocation can be included within this element.
For example: <FileName>[SHP BKC S00001493]Client Agreement.tif</FileName>
This will allocate the document in Shipment # S00001493 as Document Type “BKC”.

eAdaptor - Developer’s Guide | 235

© 2024 WiseTech Global 11 March 2024
• ImageDate – base64 encoded document content.
• IsPublished – Flag the document as Published or not.
• VisibleCompanyCode – If the CompanyCode provided, the document will be allocated
Company Specific and will only be visible for Specified Company.
• VisibleBranchCode – If the BranchCode provided, the document will be allocated Branch
Specific and will only be visible for Specified Branch.
• VisibleDepartmentCode – If the DepartmentCode provided, the document will be
allocated Department Specific and will only be visible for Specified Department.

When a UniversalEvent message containing DataTarget Type as “DocManager” and attached

documents are received, imported documents will appear in the eDocs tab of the matching job if
Document Allocation details provided are matched.

Figure 124 Shipment eDocs tab

If the Document Allocation does not matched, the document will appear in the Allocate eDocs
module on the Unallocated eDocs tab. The Allocation Status column will contain the reason why
the document could not be allocated. Once the allocation details are provided, the document
can be allocated.

eAdaptor - Developer’s Guide | 236

For more information on how to send and retrieve documents using UniversalEvent messages
please refer to the Universal Document Request Update Note at Universal Document
Request.
When using barcodes, the barcodes must be in the same order as they would when
allocating via the DocManager Import service task. Job Type Coversheet > Doc Type
Coversheet > document.
When using filename details for allocation, add the details within the element, for example:
[SHP LTR S00001410]Client Agreement.tif.
For more information on using barcodes or filename allocation details, please refer to the
following Update Notes:
Enhancement to the allocation of documents via email
Enhancements To eDoc Allocation via a network folder

eAdaptor - Developer’s Guide | 237

© 2024 WiseTech Global 11 March 2024
5.6 Universal Activities
5.6.1 Overview
The modules making up the PAVE productivity tools built into CargoWise integrate their
operational data using the Universal Activity XML schema. These include the Customer Service
Ticket, Project and Work Item modules.

Just like the other Universal XML schemas, one schema is used across all PAVE modules making it
possible to transfer data across modules and systems seamlessly.

5.6.2 Module Mapping Guide

For further information on the Universal Activity schema, you can find the Universal Activity
Module Mapping Guide in WiseTech Academy under Integration Options – Mapping Guides. This
gives an overview of how the schema is mapped to all modules implemented and provides a list
of element level mappings describing each field’s location in the GUI.

5.7 Universal Transactions

5.7.1 Overview
If you are trying to interface using posted accounting transactions, then you can use the
Universal Transaction XML. As is common across all forms of Universal XML, there is only one
schema for all transaction types supported. AR and AP invoices use the same schema as Credit
Notes, Payments and Journals.

This is done by having all elements for all supported transaction types present in the one
schema. Where values are common across multiple transaction types like Posted Date, Local
Total and Currency, the same elements are used. Each transaction type uses elements relevant
to that transaction type and ignores those not relevant. As an example, you might have a Check
Number on a Payment, but not on an AR Invoice.

For unposted job related costs and revenue, you should use the JobCosting element in the
Universal Shipment XML mentioned in section 5.4.3 Job Costing (Billing) and Consol Costs .

eAdaptor - Developer’s Guide | 238

© 2024 WiseTech Global 11 March 2024
6. Module implementation overviews
When this guide was originally written, this section contained Module Mapping information for the
first four modules that were integrated with Universal XML. These were the Forwarding Consol,
Forwarding Shipment, Forwarding Booking, and Customs Brokerage modules.

The same information (and more) can now be found in the Module Mapping Guides published for
those modules. Each module that is mapped to a Universal or Native XML dataset will have a
Module Mapping Guide that covers that module’s specific implementation details.

The Module Mapping Guides describe the keys used for matching, give an overview of how the
schema is mapped, and provide a list of element level mappings describing each field’s location
in the GUI.

They can be found along with this document on WiseTech Academy under Integration Options –
Mapping Guides

At the time of writing this section, Module Mapping Guides exist for many modules across
CargoWise, and there are more that are still in progress. If you cannot find one for a module
you are working with, please raise an incident to register your interest.

eAdaptor - Developer’s Guide | 239

Integrating With CargoWise One
100% (2)
Integrating With CargoWise One
13 pages
Document Engine Reference Guide (CW1)
No ratings yet
Document Engine Reference Guide (CW1)
60 pages
CargoWise One Product Brochure
67% (3)
CargoWise One Product Brochure
24 pages
1ACC012 - Cargowise Learning Manual - Receivables Invoice
50% (2)
1ACC012 - Cargowise Learning Manual - Receivables Invoice
6 pages
602910-EdiEnterprise Account Operational Guide
100% (3)
602910-EdiEnterprise Account Operational Guide
363 pages
Applications of Blockchain Technology in Multi-Modal Transportation
No ratings yet
Applications of Blockchain Technology in Multi-Modal Transportation
20 pages
CargoWise One Strategy and Technology
0% (1)
CargoWise One Strategy and Technology
34 pages
Top MNC Companies in Coimbatore
100% (1)
Top MNC Companies in Coimbatore
8 pages
Cargowise Ocean Visibility Ebook
No ratings yet
Cargowise Ocean Visibility Ebook
13 pages
Eadaptor Product Sheet
No ratings yet
Eadaptor Product Sheet
1 page
IVS Cargowise Training Brochure
No ratings yet
IVS Cargowise Training Brochure
2 pages
Workflow & Tracking Overview
100% (1)
Workflow & Tracking Overview
14 pages
NaV 2009 Web Services
No ratings yet
NaV 2009 Web Services
42 pages
APAC Ocean Business Knowledge Training - VN Training
No ratings yet
APAC Ocean Business Knowledge Training - VN Training
100 pages
Capstone Project Test Script
No ratings yet
Capstone Project Test Script
11 pages
GLOW Installation Guide
No ratings yet
GLOW Installation Guide
51 pages
How-To Get Started With CargoWise Neo
No ratings yet
How-To Get Started With CargoWise Neo
15 pages
1COR063
No ratings yet
1COR063
4 pages
1COR CreateXMLMappingDocumentation
No ratings yet
1COR CreateXMLMappingDocumentation
10 pages
White Paper What Shippers Want
No ratings yet
White Paper What Shippers Want
22 pages
1FOR - How To Set Up Ocean Carrier Messaging
No ratings yet
1FOR - How To Set Up Ocean Carrier Messaging
9 pages
CargoWise One - All Diagrams 2022new
No ratings yet
CargoWise One - All Diagrams 2022new
84 pages
Cargowise One Software, Freight Forwarders & Logistics Providers
No ratings yet
Cargowise One Software, Freight Forwarders & Logistics Providers
6 pages
Global Sailing Schedules API Technical Guide
No ratings yet
Global Sailing Schedules API Technical Guide
14 pages
WiseCloud Connectivity and Troubleshooting Guide
No ratings yet
WiseCloud Connectivity and Troubleshooting Guide
23 pages
Universal XML Universal Activity Module Mapping Guide
No ratings yet
Universal XML Universal Activity Module Mapping Guide
17 pages
NTUC Club Brand Research
No ratings yet
NTUC Club Brand Research
16 pages
Maritime Software Overview Flier
No ratings yet
Maritime Software Overview Flier
2 pages
Best Freight Forwarding ERP Software - CargoNet PDF
No ratings yet
Best Freight Forwarding ERP Software - CargoNet PDF
19 pages
Expedock 1.7.22 White Paper
No ratings yet
Expedock 1.7.22 White Paper
10 pages
Deloitte NL Ths Airline Iot Passenger Experience Part 1
No ratings yet
Deloitte NL Ths Airline Iot Passenger Experience Part 1
8 pages
Program Guide: Server and Cloud Enrollment
No ratings yet
Program Guide: Server and Cloud Enrollment
15 pages
1BZA - How To Set Up CargoWise For Customs Messaging in South Africa
No ratings yet
1BZA - How To Set Up CargoWise For Customs Messaging in South Africa
13 pages
Vehicle Telematics Catalog July 2019
No ratings yet
Vehicle Telematics Catalog July 2019
40 pages
Microsoft Dynamics 365 For Operations On-Premises, Enterprise Edition Licensing Guide
100% (1)
Microsoft Dynamics 365 For Operations On-Premises, Enterprise Edition Licensing Guide
27 pages
Client Guide Mir Sal 2 en
No ratings yet
Client Guide Mir Sal 2 en
7 pages
Leveraging IoT For Logistics-1
No ratings yet
Leveraging IoT For Logistics-1
12 pages
KD3 Sahnewal
No ratings yet
KD3 Sahnewal
63 pages
Transportation Issues: Bypasses Will Help To Divert Traffic. Major Structural Change To The Existing Structure
No ratings yet
Transportation Issues: Bypasses Will Help To Divert Traffic. Major Structural Change To The Existing Structure
2 pages
Logistics Disruption
0% (1)
Logistics Disruption
15 pages
Invoice Now
No ratings yet
Invoice Now
6 pages
Blockchain Shipping and Logistics Presentation Sli
100% (3)
Blockchain Shipping and Logistics Presentation Sli
103 pages
E WaybillDemoScriptAX2012
No ratings yet
E WaybillDemoScriptAX2012
22 pages
Retail 17 07 32 PDF
No ratings yet
Retail 17 07 32 PDF
2,108 pages
Dynamics 365 Licensing Guide March 2024
100% (1)
Dynamics 365 Licensing Guide March 2024
63 pages
Sage X3 Discrete Manufacturing
No ratings yet
Sage X3 Discrete Manufacturing
7 pages
Jet Reports Installation Guide
No ratings yet
Jet Reports Installation Guide
27 pages
Ramco Logistics Suite - An Overview V1
No ratings yet
Ramco Logistics Suite - An Overview V1
44 pages
Guide To Oracle Cloud: 5 Steps To Ensure A Successful Move To The Cloud
No ratings yet
Guide To Oracle Cloud: 5 Steps To Ensure A Successful Move To The Cloud
13 pages
Business Intelligence Partner Program: Updated July 2020
No ratings yet
Business Intelligence Partner Program: Updated July 2020
7 pages
Incentives Partner Guide
No ratings yet
Incentives Partner Guide
38 pages
Things To Know About The IoT Platform Ecosystem
No ratings yet
Things To Know About The IoT Platform Ecosystem
7 pages
Blockchain Whitepaper PDF
No ratings yet
Blockchain Whitepaper PDF
16 pages
ENV BPP Group 2 - v2
No ratings yet
ENV BPP Group 2 - v2
18 pages
Project44 Final Paper
No ratings yet
Project44 Final Paper
22 pages
Wisetech Global Annual Report 2021
No ratings yet
Wisetech Global Annual Report 2021
160 pages
Dynamics 365 Licensing Guide - Dec 2023
No ratings yet
Dynamics 365 Licensing Guide - Dec 2023
62 pages
Introduction To CAL Programming
No ratings yet
Introduction To CAL Programming
198 pages
Microsoft Partner Incentives - FY14 Portfolio Overview
No ratings yet
Microsoft Partner Incentives - FY14 Portfolio Overview
25 pages
Penske - REPORT FINAL DIGITAL PDF
No ratings yet
Penske - REPORT FINAL DIGITAL PDF
16 pages
Cloud API A Clear and Concise Reference
From Everand
Cloud API A Clear and Concise Reference
Gerardus Blokdyk
No ratings yet
PC SDK: Application Manual
No ratings yet
PC SDK: Application Manual
136 pages
Google Translate - Google Search
No ratings yet
Google Translate - Google Search
1 page
Adani Supplier Login Guide
No ratings yet
Adani Supplier Login Guide
12 pages
Ed 83 Module 1 & 2
No ratings yet
Ed 83 Module 1 & 2
15 pages
Online Services Business Plan
0% (1)
Online Services Business Plan
38 pages
Online Appointment Scheduling System For Hospitals-An Analytical Study
No ratings yet
Online Appointment Scheduling System For Hospitals-An Analytical Study
7 pages
Reflection Paper To The Topic
100% (2)
Reflection Paper To The Topic
2 pages
Chapter 4
No ratings yet
Chapter 4
3 pages
Solutions 3rd Int WB Keys by Victoria - Issuu
No ratings yet
Solutions 3rd Int WB Keys by Victoria - Issuu
1 page
Messages
No ratings yet
Messages
39 pages
Netcast Digital Marketing & Advertising Portfolio Final
No ratings yet
Netcast Digital Marketing & Advertising Portfolio Final
27 pages
Kaspersky Lab Kaspersky Anti-Virus 7.0 User'S Guide
No ratings yet
Kaspersky Lab Kaspersky Anti-Virus 7.0 User'S Guide
77 pages
Social Media Evangelism - How To Effectively Use Social Media To Grow Your Ministry
No ratings yet
Social Media Evangelism - How To Effectively Use Social Media To Grow Your Ministry
14 pages
Credential Harvesting
No ratings yet
Credential Harvesting
18 pages
Introduction To HDFS PDF
No ratings yet
Introduction To HDFS PDF
27 pages
Sap Emarsys Tenant Configuration: Email Account Creation
No ratings yet
Sap Emarsys Tenant Configuration: Email Account Creation
3 pages
Module 3 TOUR121 For Students
No ratings yet
Module 3 TOUR121 For Students
31 pages
Front Page of Summer Vacation Homework
100% (1)
Front Page of Summer Vacation Homework
8 pages
ComputerNetworks mod3HTTP1 Q1 Etext
No ratings yet
ComputerNetworks mod3HTTP1 Q1 Etext
15 pages
Club Planner Victor Cruz
No ratings yet
Club Planner Victor Cruz
2 pages
Libra II Release Notes V 2.1.20
No ratings yet
Libra II Release Notes V 2.1.20
6 pages
Lesson 10 Empowerment Technology - Pau
No ratings yet
Lesson 10 Empowerment Technology - Pau
18 pages
Sonal Rathod: Address
No ratings yet
Sonal Rathod: Address
2 pages
NEWSL401 Set Up LAN PDF
No ratings yet
NEWSL401 Set Up LAN PDF
254 pages
The Dragons and The Snakes How The Rest Learned To Fight The West PDF
0% (3)
The Dragons and The Snakes How The Rest Learned To Fight The West PDF
1 page
NETWORKING
No ratings yet
NETWORKING
4 pages
Web Caching and Replication-0201615703
No ratings yet
Web Caching and Replication-0201615703
815 pages
Temas Controvertidos para Un Ensayo
100% (1)
Temas Controvertidos para Un Ensayo
8 pages
Day 1 Reviewer in Reading and Writing
No ratings yet
Day 1 Reviewer in Reading and Writing
3 pages