Track and Trace Data Requirements
This page provides detailed information on the data that is needed within InterSystems Supply Chain Orchestrator™ in order to use the Track and Trace cloud service.
Overview
To use the Track and Trace service, Supply Chain Orchestrator must contain data about the tracking service and the service level agreement with the tracking service. In addition, Supply Chain Orchestrator must contain specific shipment information; the details are different for truck, ocean, air, and rail shipments.
When Supply Chain Orchestrator has the appropriate information, the Track and Trace cloud service creates shipment tracking requests and sends them to the tracking service.
Also note:
-
For successful shipment tracking, all the required information about the shipment must be provided in the Supply Chain Orchestrator data model.
If any information is missing, then the tracking request will not be created and the information that is missing will be provided in the statusMessage attribute of the shipment object (SupplyShipment or SalesShipment). Once the missing information is updated, then the tracking request will be automatically created for the shipment.
-
All the updates regarding status of the shipment and tracking updates must be received from Descartes MacroPoint, via the Track and Trace cloud service. That is, do not update these fields via other mechanisms.
-
To track a shipment which goes through multiple modes, it is necessary to create a separate shipment object (SupplyShipment or SalesShipment) for each mode.
For example, if the first part of the shipment goes by truck and then the second part goes by ocean, this must be two shipment objects.
Tracking Service Object
The TrackingService object represents the tracking service (or more specifically, the contract with the tracking service). Currently, there is one tracking service (MacroPoint), so just create a single TrackingService object. This object has the following properties:
|
Property |
Description |
Required |
|---|---|---|
|
serviceProviderId |
The Descartes MacroPoint generated ID that denotes the account(s) that will receive notifications from the tracking session. This is provided by MacroPoint during the onboarding process. |
Yes |
|
stopSequencingRequired |
If True, requires Descartes MacroPoint to capture Trip Events and report Schedule Alerts in sequential order of stops on the tracking session. If not passed, MacroPoint Company Preferences default will be used. For more details, please refer to your contract with MacroPoint. |
No |
|
maximumAllowableDrivingHoursPerDay |
Alters the ETA calculation for the shipment. This is typically utilized for team shipments by MacroPoint. If not provided, MacroPoint company preference default will apply. For more details, please refer to your contract with MacroPoint. |
No |
|
startDate |
Start date of the MacroPoint contract. |
Yes |
|
endDate |
End date of the MacroPoint contract. |
Yes |
|
trackingServiceProvider |
Name of the tracking service provider. Use MacroPoint |
Yes |
|
uid |
Unique ID to identify each row uniquely. Use T&T_MacroPoint |
Yes |
Service SLA Object
The ServiceSLA object represents a detail within a service level agreement (SLA) of the associated tracking service. First, consider the contents of an SLA with a shipment tracking service. Such an SLA contains agreement terms about the tracking interval and tracking duration for different kinds of shipments. For example:
-
For truckload shipments, updates will be provided every 15 minutes. (The tracking interval is 15 minutes for these shipments.)
-
For truckload shipments, a given shipment will be tracked for 24 hours. (The tracking duration is 24 hours for these shipments.)
-
For ocean shipments, updates will be provided every 30 minutes. (The tracking interval is 30 minutes for these shipments.)
-
For ocean shipments, a given shipment will be tracked for 96 hours. (The tracking duration is 96 hours for these shipments.)
Each of these agreement terms is represented by a single ServiceSLA object, which has the following properties:
|
Property |
Description |
Required |
|---|---|---|
|
serviceId |
Refers to the UID of the tracking service to which this information belongs. |
Yes |
|
termName |
Specifies the agreement term to be stored. Specify either
|
Yes |
|
termValue |
Specifies the numeric value for the corresponding termName in the SLA. |
Yes |
|
termValueUOM |
The unit of measure for the termValue attribute, for informational purposes. |
No |
|
type |
Shipment type to which the termName and termValue refer. Use Truckload, LTL, Ocean, Rail, or Air. |
Yes |
|
serviceObject |
Specifies the type of the service object for which the SLA belongs. Specify TrackingService. |
Yes |
|
uid |
Unique ID to identify each row uniquely. |
Yes |
To continue the example given before this table, those agreement terms would be represented by the following ServiceSLA objects (omitting the serviceObject and uid properties, for reasons of space):
|
serviceId |
termName |
termValue |
termValueUOM |
type |
|---|---|---|---|---|
|
T&T_MacroPoint |
trackingIntervalinMinutes |
15 |
minutes |
Truckload |
|
T&T_MacroPoint |
trackingDurationinHrs |
24 |
hours |
Truckload |
|
T&T_MacroPoint |
trackingIntervalinMinutes |
30 |
minutes |
Ocean |
|
T&T_MacroPoint |
trackingDurationinHrs |
96 |
hours |
Ocean |
Data Needed for Truck Shipments
For truck shipments, the following objects must contain data about the shipments:
-
The Shipment object contains data about the vehicle and the carrier.
-
The ShipmentStop object contains information about the shipment stops, like pick up or drop off. For each stop, it should have details regarding the stop like name, type of stop (pick up or drop off), location details, and so on Each shipment stop is linked to a shipment through field. For each stop there should be an entry made in the shipment stop data object. If no information regarding the shipment stop is provided, then the Track & Trace cloud service will create shipment stops based on location information provided in the shipment object. It will create shipment stops based on origin location ID and destination location ID provided in the shipment object.
-
The Location object contains data about the location of the stop. This contains the details regarding the address of the shipment stop.
-
The Carrier object contains information about carriers such as names and IDs. The UID of the carrier should be populated in the carrierId of the shipment object.
Shipment Object (Truck Shipments)
For truck shipments, specify values for the following properties of the SupplyShipment or SalesShipment object:
|
Property |
Description |
Required |
|---|---|---|
|
vehicleId |
Truck number. Carrier must have Electronic Logging Devices integrated to be supported. |
No |
|
trailerId |
Trailer number. Carrier must have trailer GPS units integrated to be supported. |
No |
|
externalShipmentId |
The ShipmentID is a unique ID generated by a Carrier’s TMS, this identifier can be provided by Carriers to Customers. The ShipmentID should only be provided in the Create Order request if the Carrier is supplying tracking updates to Descartes MacroPoint via a TMS Integration. Note: If the ShipmentID sent in the Create Order request and does not match what the carrier provides to MacroPoint, the tracking updates cannot be applied to the tracking session. |
No |
|
parcelTrackingNumber |
LTL Carrier PRO number. This field can be used for parcel tracking (UPS for example). |
No |
|
carrierContainer |
Container number. |
No |
|
trackStartDateTime |
The date/time to start the tracking session, in the format used within Supply Chain Orchestrator. |
Yes |
|
carrierBookingNumber |
Unique customer reference number shared between customer and carrier. |
Yes |
|
vehicleType |
Type of vehicle used on the load. Use DryVan, Refrigerated, Flatbed, Tanker, StraightTruck, or Drayage. |
Yes |
|
transportMode |
Specifies the mode of this truck shipment: Truckload or LTL. |
Yes |
|
emailCopiesOfUpdatesTo |
A comma-separated list of email addresses that should receive updates about this shipment. |
No |
|
notes |
Notes assigned to a shipment. |
No |
|
trackingServiceProvider |
Tracking service provider name. Use MacroPoint. |
Yes |
Shipment Stop Object (Truck Shipments)
For truck shipments, specify values for the following properties of the ShipmentStop object:
|
Property |
Description |
Required |
|---|---|---|
|
name |
Name assigned to the stop. |
Yes |
|
stopType |
Type of stop; either Pickup or DropOff. |
Yes |
|
earliestDateTime |
Earliest date/time permitted to arrive at a stop. This can be an appointment time or window if EndDateTime differs. Use the date/time format recognized within Supply Chain Orchestrator. |
Yes |
|
latestDateTime |
Latest date/time permitted to arrive at a stop. This can be an appointment time or window if EndDateTime differs. Use the date/time format recognized within Supply Chain Orchestrator. |
Yes |
|
geofence |
Allows clients to pass in by stop the radius geofence in miles. If not provided, MacroPoint will use their default value. Please check contract for more details. Geofence radius will determine if the shipment has arrived or departed a shipment stop. Shipment within a geofence radius of the stop is considered to be arrived at a stop. Similarly, once the shipment has left the geofence radius of the stop is considered to be departed the shipment stop. |
No |
|
stopNumber |
If StopSequencingRequired in Tracking Service object is True, this field is required and used as the stop sequence number. |
No |
|
uid |
Unique identifier assigned to a stop. |
Yes |
|
notes |
Notes assigned to a stop. |
No |
|
locationId |
UID of the associated location object for this stop. |
Yes |
Location Object (Truck Shipments)
For truck shipments, specify values for the following properties of the Location object:
|
Property |
Description |
Required |
|---|---|---|
|
street |
Address line 1 details. |
Yes |
|
street2 |
Address line 2 details. |
No |
|
city |
City name of address. |
Yes |
|
stateProvinceIso2 |
State name of address. Acceptable formatting: state abbreviation. |
Yes |
|
postalCode |
Postal code of address. 5 and 9 digit postal codes accepted. |
Yes |
|
countryIso3 |
Country of address. Use country codes (alpha codes)Opens in a new tab recognized by MacroPoint. |
Yes |
|
latitude |
Latitude decimal degrees of stop. If provided, the latitude and longitude override the geofence of the address provided. |
No |
|
longitude |
Longitude decimal degrees of stop. If provided, the latitude and longitude override the geofence of the address provided. |
No |
Carrier Object (Truck Shipments)
For truck shipments, specify values for the following properties of the Carrier object:
|
Property |
Description |
Required |
|---|---|---|
|
scac |
Truck carrier SCAC. |
No |
|
name |
Name of the carrier. |
Yes |
|
uid |
Unique code to identify carrier. |
Yes |
Data Needed for Ocean Shipments
For ocean shipments, the following objects must contain data about the shipments:
-
The Shipment object contains data about the ocean container.
-
The ShipmentStop object contains data about stops made by the vessel.
-
The Carrier object contains information about the ocean carrier.
Shipment Object (Ocean Shipments)
For ocean shipments, specify values for the following properties of the SupplyShipment or SalesShipment object:
|
Property |
Description |
Required |
|---|---|---|
|
carrierContainer |
Ocean container number. |
Yes |
|
trackStartDateTime |
The date/time to start the tracking session, in the format used within Supply Chain Orchestrator. |
Yes |
|
billOfLadingNumber |
Ocean bill of lading number. |
Yes - if Carrier Booking Number and Carrier SCAC are not provided |
|
carrierBookingNumber |
Ocean carrier booking number. |
Yes - Along with SCAC if Bill of Lading Number not provided |
|
carrierBookingNumber |
Unique shipment level identifier. Customer reference number shared between customer and carrier |
Yes |
|
transportMode |
Specify Ocean. |
Yes |
|
emailCopiesOfUpdatesTo |
A comma-separated list of email addresses that should receive updates about this shipment. |
No |
|
notes |
Notes assigned to a shipment. |
No |
|
trackingServiceProvider |
Tracking service provider name. Use MacroPoint. |
Yes |
Shipment Stop (Ocean Shipments)
For ocean shipments, specify values for the following properties of the ShipmentStop object:
|
Property |
Description |
Required |
|---|---|---|
|
name |
Captures the stop name for each event. Use the same value as you use for stopType. |
No |
|
stopType |
Specifies the stop type, one of the following: PlaceOfReceipt, PortOfLoading, PortOfDischarge, or Delivery |
No |
|
earliestDateTime |
Earliest date/time permitted to arrive at a stop. This can be an appointment time or window if EndDateTime differs. Use the date/time format recognized within Supply Chain Orchestrator. |
No |
|
latestDateTime |
Latest date/time permitted to arrive at a stop. This can be an appointment time or window if EndDateTime differs. Use the date/time format recognized within Supply Chain Orchestrator. |
No |
|
uid |
Unique identifier to assign to a stop. |
Carrier Object (Ocean Shipments)
For ocean shipments, specify values for the following properties of the Carrier object:
|
Property |
Description |
Required |
|---|---|---|
|
scac |
Ocean carrier SCAC. |
Yes - Along with carrier booking number if bill of lading number not provided |
|
name |
Name of the carrier on the load. |
Yes |
|
uid |
Internal code to identify carrier. |
Yes |
Data Needed for Air Shipments
For air shipments, specify values for the following properties of the SupplyShipment or SalesShipment object:
|
Property |
Description |
Required |
|---|---|---|
|
masterAirWaybillNumber |
Air waybill number. |
Yes |
|
trackStartDateTime |
The date/time to start the tracking session, in the format used within Supply Chain Orchestrator. |
Yes |
|
carrierBookingNumber |
Unique shipment level identifier. Customer reference number shared between customer and carrier. |
Yes |
|
transportMode |
Use the value Air. |
Yes |
|
emailCopiesOfUpdatesTo |
A comma-separated list of email addresses that should receive updates about this shipment. |
No |
|
notes |
Notes assigned to a shipment. |
No |
|
trackingServiceProvider |
Tracking service provider name. Use MacroPoint. |
Yes |
Data Needed for Rail Shipments
For rail shipments, the following objects must contain data about the shipments:
-
The Shipment object contains data about the rail container.
-
The ShipmentStop object contains data about stops made by the carrier.
-
The Location object contains information about the stop locations.
Shipment Object (Rail Shipments)
For rail shipments, specify values for the following properties of the SupplyShipment or SalesShipment object:
|
Property |
Description |
Required |
|---|---|---|
|
railCar |
Rail container number. |
Yes |
|
trackStartDateTime |
The date/time to start the tracking session, in the format used within Supply Chain Orchestrator. |
Yes |
|
carrierBookingNumber |
Unique shipment level identifier. Customer reference number shared between customer and carrier |
Yes |
|
transportMode |
Use the value Rail. |
Yes |
|
emailCopiesOfUpdatesTo |
A comma-separated list of email addresses that should receive updates about this shipment. |
No |
|
notes |
Notes assigned to a shipment. |
No |
|
trackingServiceProvider |
Tracking service provider name. Use MacroPoint. |
Yes |
Shipment Stop Object (Rail Shipments)
For rail shipments, specify values for the following properties of the ShipmentStop object:
|
Property |
Description |
Required |
|---|---|---|
|
name |
Name assigned to the stop. |
Yes |
|
stopType |
Type of stop, either Pickup or DropOff. |
Yes |
|
earliestDateTime |
Earliest date/time permitted to should arrive at a stop. This can be an appointment time or window if EndDateTime differs. Use the date/time format recognized within Supply Chain Orchestrator. |
Yes |
|
latestDateTime |
Latest date/time permitted to arrive at a stop. This can be an appointment time or window if EndDateTime differs. Use the date/time format recognized within Supply Chain Orchestrator. |
Yes |
|
geofence |
Allows clients to pass in by stop the radius geofence in miles. If not provided, MacroPoint will use their default value. Please check contract for more details. Geofence radius will determine if the shipment has arrived or departed a shipment stop. Shipment within a geofence radius of the stop is considered to be arrived at a stop. Similarly, once the shipment has left the geofence radius of the stop is considered to be departed the shipment stop. |
No |
|
stopNumber |
If StopSequencingRequired in Tracking Service object is True, this field is required and used as the stop sequence number. |
No |
|
uid |
Unique identifier to assign a stop, typically a customer ID/Number. |
Yes |
|
notes |
Notes assigned to a stop. |
No |
|
locationId |
UID of the associated location object for this stop. |
Yes |
Location Object (Rail Shipments)
For rail shipments, specify values for the following properties of the Location object:
|
Property |
Description |
Required |
|---|---|---|
|
street |
Address line 1 details. |
Yes |
|
street2 |
Address line 2 details. |
No |
|
city |
City name of address. |
Yes |
|
stateProvinceIso2 |
State name of address. Acceptable formatting: state abbreviation. |
Yes |
|
postalCode |
Postal code of address. 5 and 9 digit postal codes accepted. |
Yes |
|
countryIso3 |
Country of address. Acceptable formatting: country abbreviations (US, USA). |
Yes |
|
latitude |
Latitude decimal degrees of stop. If provided, the latitude and longitude override the geofence of the address provided. |
No |
|
longitude |
Longitude decimal degrees of stop. If provided, the latitude and longitude override the geofence of the address provided. |
No |
