Technical guide

Universal XML - Universal Activity Module

Mapping Guide
6 December 2021

Contents
1. Terms of use ...................................................................................................................................................... 4
2. Introduction ...................................................................................................................................................... 4
2.1 DataSource/DataTarget Type .......................................................................................................................................... 4
3. Universal events .............................................................................................................................................. 5
3.1 Data export .................................................................................................................................................................................... 5
3.2 Data import .................................................................................................................................................................................... 5
3.2.1 Matching and special update logic ..............................................................................................................5
4. Universal Activity ............................................................................................................................................ 6
4.1 Data export .................................................................................................................................................................................... 6
4.1.1 Exporting related items ........................................................................................................................................6
4.1.2 Exporting Workflow items ...................................................................................................................................6
4.1.3 Exporting eConversation ..................................................................................................................................... 7
4.1.4 Exporting Job Costing data ............................................................................................................................... 7
4.1.5 Exporting Custom Fields ......................................................................................................................................8
4.2 Data import .................................................................................................................................................................................... 8
4.2.1 Matching and special update logic ..............................................................................................................8
4.2.2 Client matching...........................................................................................................................................................8
4.2.3 Importing related items ........................................................................................................................................9
4.3 Element mappings .................................................................................................................................................................... 9
4.3.1 Universal Activity .......................................................................................................................................................9
4.3.2 Task.................................................................................................................................................................................... 12
4.3.3 TaskSet............................................................................................................................................................................ 14
5. Universal Activity Request ........................................................................................................................ 16
5.1 UniversalActivityRequest ................................................................................................................................................... 16

CargoWise Technical Guide | 1

© 2021 WiseTech Global 6 December 2021
 5.2 Targeting a Data Source Entity using DataContext ........................................................................................ 16
5.3 UniversalResponse .................................................................................................................................................................. 17
6. Sample files ...................................................................................................................................................... 17

CargoWise Technical Guide | 2

© 2021 WiseTech Global 6 December 2021
 Date Version Description of Change

6/12/2021 2 Update 4.3.1 Universal Activity eConversation element

CargoWise Technical Guide | 3

© 2021 WiseTech Global 6 December 2021
1. Terms of use
WiseTech Global (WTG) grants you access to this Universal Activity Mapping Guide for the
following purpose(s):

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 Universal Activity Module Mapping Guide
(irrespective of how it is accessed) may only do so only for the Permitted Purpose. All intellectual
property rights in this Universal Activity Module Mapping 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 Universal Activity Module
Mapping Guide is permitted to copy or distribute, forward or publicly display the contents of this
Universal Activity Module Mapping Guide (or any part of it) to any third party without first
obtaining the written consent of WTG.

2. Introduction
CargoWise features a number of modules that facilitate the creation of jobs representing generic
work. These modules support Universal XML by adhering to the Universal Activity schema for
importing and exporting data. The following modules are currently supported:
• Customer Service Tickets
• Projects
• Work Items

2.1 DataSource/DataTarget Type

A Universal Activity targeted for import into a specified module becomes a job in that module.
You target a module by including a DataContext > DataTargetCollection > DataTarget element
within the Universal Activity. You must include a DataTarget Type and can optionally include a
DataTarget Key.

Data target type Targeted module Matching key (job number)

Customer Service
CustomerServiceTicket Ticket Number
Ticket

CargoWise Technical Guide | 4

© 2021 WiseTech Global 6 December 2021
 Project Project Project Number

WorkItem Work Item Work Item Number

When a Key element is included, if a matching job (with the same module and job number) is
found in the recipient system, this job will be updated. If no match is found, the message is
rejected. If no Key element is included, a new Job is created in the target module.

For more information refer to:

• eRequest Management Portal module
• Workflow & Productivity module

3. Universal events
3.1 Data export
When you export a Universal Event from a supporting job, only the module name and job number
will be extracted and included in DataSource element of the xml. The job number for any job can
be found in CargoWise in the title bar of the job’s form. The Universal Event also contains
information about the Event and Workflow configuration that caused the Universal Event to be
sent.
The Universal Event is designed to be a notification of an event occurring during the life of a job. If
you want the full details of the Job, you should send a Universal Activity instead.

3.2 Data import

3.2.1 Matching and special update logic
• Job Number Matching: in this business context, this is the only matching strategy the system
will use when importing Universal Event XML. You can see from the XML snippet below,
DataContext contains DataTargetCollection describing the importing target. A DataTarget
contains both Type and Key to indicate the type of the target this event is importing to
(Customer Service Ticket, Project, or Work Item) and the job number of the parent. The
system will look for the data target and try to load the event parent with this information.

CargoWise Technical Guide | 5

© 2021 WiseTech Global 6 December 2021
 <Event>
<DataContext>
<DataTargetCollection>
<DataTarget>
<Type>CustomerServiceTicket</Type>
<Key>CST00001003</Key>
</DataTarget>
</DataTargetCollection>

• Combination Key Match: not currently available for UniversalActivity modules, as these
modules do not offer any reference number other than job numbers. Combination Key
matching may be implemented in the future as business cases arise.

4. Universal Activity
4.1 Data export
The data included in a Universal Activity export includes summary, description, client, selection
criteria, custom field values, notes, workflow items, eConversation, job costing data, and a
collection of related items.

4.1.1 Exporting related items

Each of the job types that are compatible with Universal Activity XML can have a collection of
related items, listed on the Related Items tab of the job’s form. This functionality allows jobs to
be attached to other jobs. For example, a customer service ticket may have a work item
attached.

In Universal Activity XML, these related items are exported and listed in the
RelatedActivityCollection element. Each related item of an activity is written as an activity itself
(with a root element of <RelatedActivity>). These related activities contain all the detail that a
top-level Universal Activity would, with one exception. The related activity’s own
RelatedActivityCollection is omitted in order to prevent the recursive listing of related activities,
and to ensure the dataset is kept at a reasonable size.

4.1.2 Exporting Workflow items

Every module currently supported by Universal Activity XML also supports workflow. When a job
is exported as a Universal Activity, that job’s tasks, task sets, and milestones are included in the
exported XML. Element mappings for tasks and task sets can be found in the Element Mappings
section below.

Workflow items 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.
Tasks, task sets, and milestones from Universal Activity XML are never imported. Workflow is

CargoWise Technical Guide | 6

© 2021 WiseTech Global 6 December 2021
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.

For more information about the way workflow items are handled by Universal XML, refer to
the Milestones section of the eAdaptor Developer’s Guide.

4.1.3 Exporting eConversation

Jobs that support eConversation will export the details of their conversations in any Universal
Activity export. A Conversation element consists of the following collections:

• ConversationMessageCollection: the ConversationMessageCollection element contains child

elements for every eConversation message associated with jobs that support eConversation.
Message elements include details regarding the sender of the message, whether the message
is an internal message or system message, the message’s creation time, and the message
text. Currently, messages cannot be imported using Universal Activity XML.

Note: the internal messages will only be exported if Organization Proxy is the selected
recipient of the Universal Activity export.

• ParticipantStaffCollection: all staff participants involved in an eConversation are included in

the ParticipantStaffCollection. Details of each participant include the staff code, name,
location, job title, active status, and subscription status.
• ParticipantGroupCollection: all Group participants involved in an eConversation are included
in the ParticipantGroupCollection. Details of each participant include the group code, name,
location, active status, and subscription status.
• ParticipantRelatedPartyCollection: all related party participants involved in an
eConversation are included in the ParticipantRelatedPartyCollection. Details of each
participant include the organization address details, location, relation, active status, and
subscription status. RelatedPartyType denotes whether the participant represents an
organization or a contact.

4.1.4 Exporting Job Costing data

Job Costing data from the Billing tab of the exported job will be included in the JobCosting
element in each Universal Activity.

For more information, please refer to the Job Costing (Billing) and Consol Costs section of
the eAdaptor Developer’s Guide.

CargoWise Technical Guide | 7

© 2021 WiseTech Global 6 December 2021
4.1.5 Exporting Custom Fields
Custom fields can be defined in the workflow templates for job types that are currently
supported by Universal Activity. When you export a job as a Universal Activity, any data stored in
custom fields will be included in the CustomizedFieldCollection element.

For more information, please refer to the Customized Fields section of the eAdaptor
Developer’s Guide.

4.2 Data import

4.2.1 Matching and special update logic
• Context Key Matching: this is the only matching strategy the system will use when importing
Universal Activity XML. As you can see from the XML snippet below, DataContext contains
DataTargetCollection describing the importing target. A DataTarget contains both type and
key to indicate the target job to be imported. The system will use the key in DataTarget, which
is the job number, to try to load the job. If the Key element is omitted, the system will create a

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

<Activity>
<DataContext>
<DataTargetCollection>
<DataTarget>
<Type>WorkItem</Type>
<Key>WI00001003</Key>
</DataTarget>
</DataTargetCollection>

new job for the Universal Activity provided.

• Combination Key Match: not currently available for UniversalActivity modules, as these
modules do not offer any reference number other than job numbers. Combination Key
matching may be implemented in the future as business cases arise.

4.2.2 Client matching

Some Universal Activity jobs are associated with a contact at a particular organization. In order to
uniquely identify the correct contact in Universal Activity XML, an OrganizationAddressCollection
element is included in the schema, featuring address and contact information. The address
details are used to identify the correct organization, and the contact element is used to find the
correct contact within that organization. Address matching uses the same logic as all other
Universal XML modules. Contact matching simply uses the contact name to match, as contact
names must be unique in each organization.

CargoWise Technical Guide | 8

© 2021 WiseTech Global 6 December 2021
4.2.3 Importing related items
When a RelatedActivityCollection element is present, each RelatedActivity listed will be read and
imported into the system. Any RelatedActivity that contains a DataTarget with a key element will
attempt to find the matching job in the system. If a matching job is found, it will be attached to
the imported top-level business object. If no job is found, nothing will be attached.

New business objects can be created and attached simply by omitting the DataTarget Key
element on the RelatedActivity. A new business object will be created and attached to the
imported top-level business object.

Any RelatedActivity that does not include a DataTarget with a valid type element specified will be
ignored.

Note: the RelatedActivityCollection cannot be used to update the data of a related job.
Additionally, related jobs cannot be detached from a job using a Universal Activity import.
Any listed RelatedActivity will only be used to attach a job to the top-level business object.

4.3 Element mappings

4.3.1 Universal Activity
Elements in Universal Activity modules are be mapped to various user controls on the respective
job’s form. All fields included in a Universal Activity export are found on the respective job’s
Details tab. Please see the table below:

Customer service
Element name Project Work item Notes
ticket

SelectionCriterion1 SelectionCriterion1 Project Type Type

The labels for
these fields
Project Sub can be
SelectionCriterion2 SelectionCriterion2 Product Area customized by
Type
modifying the
registry. The
SelectionCriterion3 SelectionCriterion3 Project Module Activity Type fields may
appear with
different
Activity Sub
SelectionCriterion4 SelectionCriterion4 Priority captions in
Type
your job form if

CargoWise Technical Guide | 9

© 2021 WiseTech Global 6 December 2021
 Customer service
Element name Project Work item Notes
ticket

these registry
items have
SelectionCriterion5 SelectionCriterion5 Priority been
customized.

Summary Summary Description Summary

Large text box Large text box

Large text box
Description below below
below Summary
Description Summary

Branch Branch

Department Department Department

Location Country Country / Port

Company Company

The Status field

is calculated
for most job
types;
Status Status Status Status therefore jobs
will not be
updated by
Universal XML
for this field.

Organization Client
Address (Type: Client Information >
Client) Client/Contact

CargoWise Technical Guide | 10

© 2021 WiseTech Global 6 December 2021
 Customer service
Element name Project Work item Notes
ticket

Organization Technician
Address (Type: Information >
TechnicalClient) Client/Contact

NoteCollection Notes tab Notes tab Notes tab

Each row in the

Related Items
grid will be
RelatedActivity exported as a
Related Items Related Items
Related Items tab RelatedActivity.
tab tab
Collection See Exporting
Related Items
for more
information.

Not shown on form

CreatedBy but included in Created By Created By
Activity

Project
ProjectManager
Manager

eConversation eConversation
eConversation + + +
Conversation eConversation eConversation eConversation
Participants tab Participants Participants
tab tab

Custom fields
CustomizedField will appear on
Details tab Details tab Details tab the Details tab
Collection if they have
been defined
for the

CargoWise Technical Guide | 11

© 2021 WiseTech Global 6 December 2021
 Customer service
Element name Project Work item Notes
ticket

selected
workflow
template.

Task Sets
appear in the
Workflows grid
on the
Management
tab for job
Workflow & Workflow & Workflow & types
TaskSetCollection
Tracking tab Tracking tab Tracking tab associated
with a Buffer
Management
System. All
Tasks can be
seen on the
Tasks tab.

Workflow &
Milestone Workflow & Workflow &
Tracking tab,
Tracking tab, Tracking tab,
Milestones
Collection Milestones grid Milestones grid
grid

JobCosting Billing Tab Billing Tab Billing Tab

4.3.2 Task
A Universal Activity job’s tasks can be found on the job’s form under Workflow & Tracking >
Tasks tab. If Buffer Management is enabled for the job type, tasks will also appear under
Workflow & Tracking > Management tab in the Tasks grid, along with information about their
associated task set. All fields included in a task export are found in these grids. Please see the
table below:

CargoWise Technical Guide | 12

© 2021 WiseTech Global 6 December 2021
 Element name (XML) Value mapped from Note

TaskID Tasks grid, Task ID field

Tasks grid, Task

Sequence
Sequence field

Tasks grid, Description

Description
field

TaskNotes Task Notes box

Tasks grid, Card Note Appears on the Management tab only

CardNote
field when Buffer Management is enabled.

Tasks grid, Task Type

Type
field

Tasks grid, Task Status

Status
field

Tasks grid, Task

AssignedStaff
Assigned To field

Tasks grid, Required

AssignedCapability
Capability field

Tasks grid, Assigned

AssignedGroup
Group field

Tasks grid, Low

EstimatedDuration Estimated Duration
field

CargoWise Technical Guide | 13

© 2021 WiseTech Global 6 December 2021
 Element name (XML) Value mapped from Note

Tasks grid, Estimate

EstimatedVariationFactor
Variation Factor field

Tasks grid, Completed Appears on the Management tab only

Time (Offset) field when Buffer Management is enabled.
Tasks > Advanced For job types where Buffer
CompletedTimeUTC
View tab, Schedule Management is not enabled, refer to
section, Completed the Advanced View tab on the Tasks
Time (Offset) field tab to see this value.

Tasks grid, Actual

ActualDuration
Duration field

Tasks grid, Estimated

EstimatedStartTimeUTC
field

Tasks grid, Actual Start

ActualStartTimeUTC
field

4.3.3 TaskSet
When Buffer Management is enabled for a particular job type, task sets can be found on the job’s
form under Workflow & Tracking > Management tab. Each job has one job-level task set and
zero or more regular task sets. Each regular task set can have zero or more tasks. Task sets are
more than simple containers for tasks—they govern how work moves through a Buffer
Management System and is released into buffers. All fields included in a Task Set export are
found in the Workflows grid on the Management tab.

Each task set has a TaskCollection and TaskSetCollection. The TaskCollection contains all of the
tasks directly associated with that task set. The TaskSetCollection contains any child task sets.
For example, the job-level task set will often have regular task sets in its TaskSetCollection.
Similarly, task sets that have a quality iteration task set will have a populated TaskSetCollection.
Tasks exported from jobs where Buffer Management is not enabled will appear in a default task
set element which will be included in the TaskSetCollection of a job-level task set in the Activity’s
TaskSetCollection.

CargoWise Technical Guide | 14

© 2021 WiseTech Global 6 December 2021
 Note: task sets are currently referred to as Workflows in CargoWise and ProductivityWise. An
Update Note will be released when the renaming of Workflows to Task Sets is complete.

Element name (XML) Value mapped from Note

Workflows grid,
Description
Description field

Type values are:

JOB – Job
Workflows grid, Type
Type TKS – Workflow (will be renamed to
field
Task Set in the future. The code will
remain TKS).

Workflows grid, Current

CurrentStatus
Status field

Notes Workflow Notes tab

Workflows grid, Active

IsActive
field

Workflows grid, Earliest

EarliestStartDateUTC
Start Date field

Workflows grid, Agreed

AgreedDeliveryDateUTC
Delivery Date field

Workflows grid, Date

DateAcceptability
Acceptability field

Workflows grid, Release

ReleaseGroup
Group field

CargoWise Technical Guide | 15

© 2021 WiseTech Global 6 December 2021
 Workflows grid,
TaskSetStatus
Workflow Status field

5. Universal Activity Request

To use the Universal Activity Request component, send a UniversalActivityRequest XML message
via the eAdaptor HTTP+XML interface, and you will get a UniversalResponse XML message in
response. The UniversalResponse will either contain the requested UniversalActivity, or a failure
status and a reason why a UniversalActivity could not be returned.

5.1 UniversalActivityRequest
The UniversalActivityRequest is designed to query for and return a single UniversalActivity
matching the parameters enclosed in the message. Every module that supports exporting
UniversalActivity XML works with the UniversalActivityRequest interface. Each ‘well formed’
UniversalActivityRequest 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 Work

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

<ActivityRequest>
<DataContext>
<DataTargetCollection>
<DataTarget>
<Type>WorkItem</Type>
<Key>WI00001003</Key>
</DataTarget>
</DataTargetCollection>

<Company>
<Code>BEN</Code>
</Company>
<EnterpriseID>HYE</EnterpriseID>
<ServerID>BEN</ServerID>
</DataContext>
</ActivityRequest>
</UniversalActivityRequest>

Item:

The UniversalActivityRequest content is used to target a particular data source entity in a

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

5.2 Targeting a Data Source Entity using

DataContext
The DataTarget Type (WorkItem, in the above example) 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. The DataTarget Key is used to
identify the job within the module you are querying.

CargoWise Technical Guide | 16

© 2021 WiseTech Global 6 December 2021
Each module has a job number field that uniquely identify rows within that module. The
DataTarget Type and Key contains the same values you see in the DataSource of a
UniversalActivity or UniversalEvent exported from any module supporting the
UniversalActivityRequest.

5.3 UniversalResponse
Each ‘well formed’ UniversalActivityRequest 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.

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

6. Sample files
• UniversalActivity_CustomerServiceTicket_DataSource.xml: customer service ticket
exported data
• UniversalActivity_Project_DataTarget.xml: project with rich text in description element
• UniversalActivity_WorkItem_DataTarget.xml: work Item with related items

Refer to the eAdaptor Sample Interfaces Pack under My Account Technical Guides >
Integration Options > eAdaptor.

Support: Press the F1 key from anywhere within CargoWise to raise an eRequest.

CargoWise Technical Guide | 17

© 2021 WiseTech Global 6 December 2021