Track and Trace Data Outputs
This page provides detailed information on the data that is automatically available within InterSystems Supply Chain Orchestrator™ when you use the Track and Trace cloud service.
Overview
Throughout the lifecycle of a shipment, Descartes MacroPoint sends updates to the Track and Trace cloud service, which in turn immediately pushes the data to Supply Chain Orchestrator. Then Supply Chain Orchestrator does the following:
-
Creates or updates a ShipmentTracking object. (The object is created upon the first update and is modified by later updates from the Track and Trace service.) The ShipmentTracking object is linked to the original SupplyShipment or SalesShipment object, as applicable.
-
Creates a Location object that records the current location. The ShipmentTracking object is linked to this.
-
If the update describes a shipment milestone, Supply Chain Orchestrator does the following:
-
Creates a ShipmentMilestone object that describes the milestone and that is linked to the shipment.
-
Creates a ShipmentStop object with information on this stop within the lifecycle. This object is linked to the ShipmentMilestone object and to the Location object.
-
Via the Track and Trace service, Supply Chain Orchestrator also receives the following other kinds of updates from MacroPoint:
-
Schedule alerts. An update results in a new ShipmentMilestone object that describes the schedule alert.
-
Enhanced shipment status updates. Upon receiving an update of this type, Supply Chain Orchestrator updates the ShipmentTracking object and creates a new Location object.
The following diagram shows the relationship of these objects with each other, connecting them to the original Shipment object (either SupplyShipment or SalesShipment).
The rest of this page examines the available data in these objects.
Current Location
For a given shipment, the ShipmentTracking object contains current location information as follows:
|
Property |
Description |
|---|---|
|
uncertainty |
Approximate uncertainty radius, in miles. |
|
trackingServiceLastUpdatedTimeUTC |
Date and time in ISO 8601 that location was obtained. |
|
trackingServiceLastUpdatedTimeLocal |
The date and time that this location was obtained, in the local time zone. |
|
datasource |
Source the data was received from. |
|
locator |
TMS ID, truck number, trailer number, or cell phone number. |
|
latestLocationId |
The UID of the Location object that was created with the latest update. |
In turn, the Location object provides the following properties:
|
Property |
Description |
|---|---|
|
latitude |
Latitude, in decimal degrees. The location object stored will be referred in the shipment tracking via the latestLocationId attribute. The UID of the new location object will be stored in the latestLocationId attribute of the ShipmentTracking object. |
|
longitude |
Longitude, in decimal degrees. |
|
street |
Street address, if available. |
|
street2 |
Second street address line, if available. |
|
neighborhood |
Neighborhood name, if available. |
|
city |
City name, if available. |
|
stateProvinceIso2 |
State name, if available. |
|
postalCode |
Postal code, if available. |
|
countryIso3 |
Country, if available. |
Shipment Tracking Status
For a given shipment, the ShipmentTracking object contains current shipment tracking status data as follows:
|
Property |
Description |
|---|---|
|
trackingServiceShipmentStatus |
The MacroPoint order status code |
|
trackingServiceShipmentMessage |
The MacroPoint order status message |
For convenience, the following table lists the MacroPoint tracking statuses and their descriptions, but always consult the official MacroPoint documentation for the latest information:
|
Status Code |
Order Status Message |
Order Status Description |
|---|---|---|
|
1002 |
Requesting+App+Install |
Tracking is pending the driver download of the Descartes MacroPoint app for tracking to take place. |
|
1020 |
Ready+To+Track |
Tracking session is awaiting the track start time. |
|
1021 |
Tracking+Now |
Tracking is actively taking place. |
|
1022 |
Tracking+Completed+Successfully |
Tracking is completed and the session yielded location data. |
|
1050 |
Stopped+By+Creator |
Tracking session was cancelled before completion by creator. |
|
1053 |
Location+Hidden+By+Driver |
Driver disabled or limited location services on the app. |
|
1060 |
Tracking+-+Waiting+For+Update |
A scheduled ping has not yet been acquired. |
|
1061 |
Incompatable+Phone |
Phone does not support Descartes MacroPoint mobile app. |
|
1065 |
Invalid+Truck+Number |
Truck # is determined to be invalid. |
|
1066 |
Invalid+Trailer+Number |
Trailer # is determined to be invalid. |
|
1067 |
Expired+With+Location+Hidden+By+Driver |
Tracking session expired without a location due to location setting restrictions at the mobile device level. |
|
1068 |
Driver+Phone+Unresponsive |
Mobile device is not responding to Descartes MacroPoint request for a ping. |
|
1069 |
Expired+With+Driver+Phone+Unresponsive |
Tracking session expired without a location due to no response from the mobile device. |
|
1070 |
Expired+Without+Installation |
Tracking session expired without the installation of the Descartes MacroPoint app. |
|
1071 |
Expired+Without+Location |
Tracking session expired without a ping. |
|
1072 |
Invalid+Bill+Of+Lading |
Ocean bill of lading is invalid. |
|
1073 |
Invalid+PRO+Number |
LTL PRO is invalid. |
|
1074 |
Invalid+Air+Waybill |
Air waybill is invalid. |
Trip Events
A shipment can have multiple ShipmentMilestone objects, each of which provides information about events of the trip. With respect to those events, the ShipmentMilestone object provides the following properties:
|
Property |
Description |
|---|---|
|
shipmentId |
Shipment ID. |
|
shipmentType |
Type of the shipment (Supply, Sales). |
|
stopId |
Customer internal reference ID for stop. |
|
statusCode |
Event code, as provided by the shipping tracker; see details after this table. |
|
lastUpdatedTimeUTC |
Time in ISO8601 and in UTC. |
|
lastUpdatedTimeLocal |
The date and time that this event occurred in the local time zone. |
|
updatedBy |
Method event was captured. Values include: Customer (via API or Control Tower), Carrier (via integration), Driver (via mobile app), MacroPoint (via geofence). |
|
unLocode |
Code for the associated terminal. Ocean tracking only. |
|
milestone |
The event name regarding the status code. |
For reference, here are the MacroPoint standard event codes (used as statusCode in the ShipmentMilestone object):
|
Event Name |
Event Code |
|---|---|
|
Arrived - Pickup |
X3 |
|
Departed - Pickup |
AF |
|
Arrived - DropOff |
X1 |
|
Departed - DropOff |
D1 |
MacroPoint uses a different set of event codes for ocean shipping; these are as follows:
|
Event Name |
Event Code |
|---|---|
|
EmptyOut |
E1 |
|
Arrived |
G1 |
|
ContainerLoaded |
LB |
|
VesselDeparted |
DP |
|
VesselArrival |
AD |
|
ContainerUnloaded |
D1 |
|
Departed |
G2 |
|
EmptyReturn |
E2 |
|
Departed – Delivery |
UR |
Schedule Alerts
When MacroPoint sends a schedule alert, Supply Chain Orchestrator creates a new ShipmentMilestone object with information about the alert, as follows:
|
Property |
Description |
|---|---|
|
shipmentId |
Shipment ID. |
|
shipmentType |
Type of the shipment (Supply, Sales). |
|
stopType |
The type of stop that is expected to occur next: Pickup or Dropoff. |
|
stopId |
Customer internal reference ID for stop. |
|
statusCode |
A numeric code that represents the current status of the order. |
|
milestone |
A brief description of current schedule status for the order (i.e.: 2 Hours Behind). |
|
distanceToStop |
Distance to stop in miles from last known location. |
|
estimatedTime |
Estimated time to the stop based on the last known location in UTC. |
|
estimatedTimeLocal |
Local time zone offset from UTC. |
For reference, here are the MacroPoint schedule alert codes (used as statusCode in the ShipmentMilestone object, in the case of schedule alerts):
|
Schedule Alert Name |
Schedule Alert Code |
|---|---|
|
Cannot Determine |
0 |
|
On Time or Ahead of Schedule |
1 |
|
Behind Schedule |
2 |
|
Cannot Make It |
3 |
|
Past Appointment Time |
4 |
Enhanced Shipment Status
MacroPoint can also send enhanced shipment status updates. For these updates, a new Location object is created, with details as follows:
|
Property |
Description |
|---|---|
|
city |
City where the status change occurred if available. The location object stored will be referred in the shipment tracking via the latestLocationId attribute. The UID of the new location object will be stored in the latestLocationId attribute of the Shipment Tracking. |
|
stateProvinceIso2 |
State where the status change occurred if available |
|
countryIso3 |
Country where the status change occurred if available |
The ShipmentTracking object is also updated. Updates for Air and Rail are always provided. The updates for LTL and Ocean depend on the carrier. Below are the details for ShipmentTracking:
|
Property |
Description |
|---|---|
|
trackingServiceShipmentStatus |
The order status code. |
|
trackingServiceShipmentMessage |
Text explaining the status code. |
|
trackingServiceLastUpdatedTimeUTC |
Date and time in UTC that the status update occurred. |
|
trackingServiceLastUpdatedTimeLocal |
Event ETA for the final stop in local time. |
|
trackingServiceLastUpdatedTimeUTC |
Event ETA for the final stop in UTC time. |
|
unLocode |
Code for the associated terminal. Ocean tracking only. |
|
latestLocationId |
The UID of the Location object that was created with the latest update. |
For reference, here are the MacroPoint air status codes:
|
Status Code |
Status Description |
|---|---|
|
ARR |
Consignment arrived on a given flight or surface transport of the given airline. |
|
AWD |
Consignment where arrival documents have been delivered to the consignee or his agent. |
|
BKD |
Consignment booked on a specific flight. |
|
CCD |
Consignment cleared by customs. |
|
CRC |
Consignment reported to customs authorities. |
|
DDL |
Consignment has been delivered to consignee door. |
|
DEP |
Consignment departed on a specific flight. |
|
DIS |
Consignment with a discrepancy. |
|
DLV |
Consignment has been delivered to consignee or his agent. |
|
FOH |
Consignment is on hand pending “ready for carriage” determination. |
|
MAN |
Consignment manifested on a specific flight. |
|
NFD |
Consignment where consignee or his agent has been informed of its arrival at destination. |
|
PRE |
Consignment prepared for loading. |
|
RCF |
Consignment physically received from a given flight or surface transport of the given airline. |
|
RCS |
Consignment physically received (“ready for carriage”) from a shipper or an agent. |
|
RCT |
Consignment received from another airline. |
|
TFD |
Consignment which has been transferred to another airline. |
|
TGC |
Consignment has been transferred to customs/government control. |
|
TRM |
Consignment which is to be transferred to another airline. |
Also, here are the MacroPoint rail status codes:
|
Status Code |
Status Description |
|---|---|
|
4040, 4041, 4042, 4043, 4045, 4046, 4049 |
Interchange delivery. |
|
4048, 4050, 4051, 4053, 4055 |
Interchange receipt. |
|
6001 |
Released load. |
|
6002 |
Pull from patron siding. |
|
6005 |
Arrival at final destination. |
|
6006 |
Arrival in transit. |
|
6007 |
Placement actual. |
|
6009 |
Placement constructive. |
|
6010 |
Bad order with hours to repair. |
|
6011 |
Bad order repair > 20 hours. |
|
6013 |
Bad order repair < 20 hours. |
|
6014 |
Bad order hours to repair unknown. |
|
6015 |
Unit released from bad order. |
|
6016 |
Departed from location. |
|
6024 |
Held for billing or disposition. |
|
6026 |
Unit held - no billing. |
|
6030 |
ETA. |
|
6036 |
Arrival at initial rail facility. |
|
6037 |
Departure en route to non-rail facility. |
|
6038 |
Intermodal ingate. |
|
6039 |
Intermodal outgate. |
|
6044 |
Notified destination party. |
|
6064 |
TOFC/COFC onto rail-controlled truck. |
|
6065 |
Rail controlled arrival on motor. |
|
6067 |
Ramped. |
|
6068 |
Deramped. |
