Platform Event Model
Copyright IBM Corporation and Maersk GTD Inc. 2018, 2020
To properly map an organization’s internal system’s events, triggers, actions, and data, it is important to understand the TradeLens platform event model. There are four main groups of events to consider:
Transport Equipment events
Transport Plan events
Note: Events for document actions are sent to the platform automatically and internally by the document sharing service.
These groups can be found in the event publishing API in Swagger. You can also see the input that each API can accept and what is returned. For the latest information, see the Event Publish Swagger UI in the API Documentation section.
Consignments and Transport Equipment events
The platform is based on a simple logical data model with two related classes: Consignments and Transport Equipment. The main purpose of the platform’s Consignments and Transport Equipment events is essentially to start and track consignments (shipments) and transport equipment (containers), while managing the IDs and relationships between the two. The TradeLens platform is flexible and allows a consignment to be in multiple transport equipment (along with other consignments), and for a transport equipment to be part of multiple consignments. For example a consignment of shoes_from_company1 could be split among multiple transport equipment, and there could also be shoes_from_company2 in some of the transport equipment.
All of the events listed in table 1 below are POST events and if multiple posts are done for the same event (with the same identifiers, for example carrier booking number for a consignment, or carrier booking number and equipmentNumber for a transport equipment), the information will be updated. For example, if a POST .../consignments is done with partial bookingData, another POST .../consignments can be done with the complete bookingData once it is available, or new bookingData if it has changed. This provides an advantage since providers are not required to maintain state for the data since the POST results in an update of existing data if an event is submitted that matches a previous event's identifier(s). An update to a consignment does not replace everything, some attributes are preserved like: parties added, references added, relationships with transport equipment, and relationships with consignments.
Table 1 - Consignments and Transport Equipment events
(Note: The Ennn is a reference to the old API structure before GA)
|Consignments||POST .../consignments - Start consignment tracking (E468)|
|POST .../consignments/referenceAdded - Consignment reference added (E422)|
|POST .../consignments/consignmentSubcontracted - Consignment subcontract added (E705)|
|Consignments - Transport Equipment association||POST .../consignments/partyAdded - Consignment visibility added (E001)|
|POST .../transportEquipment - Start transport equipment tracking (E278),
the carrier booking number is a required field and establishes the linkage between the consignment and transport equipment.
|Transport Equipment||POST .../transportEquipment - Start transport equipment tracking (E278)|
|POST .../transportEquipment/cargoTypeUpdated - Transport equipment cargo type updated (E314)|
|POST .../transportEquipment/equipmentNumberUpdated - Transport equipment number updated (E417)|
|POST .../transportEquipment/locationsUpdated - Transport equipment locations updated (E704)|
|POST .../transportEquipment/referenceAdded - Transport equipment reference added (E469)|
|POST .../transportEquipment/partyAdded - Transport equipment visibility added (E550)|
Containers are the units being moved, and the vast majority of events occur at the container level (such as “actualContainerStuffed”, “actualGateIn”, “actualDischargeFromVessel”, etc). The TradeLens platform uses Transport Equipment (TE) to track the movement of a container’s goods from one place to another. It is important to note that the term “container” is meant quite generically, and along with intermodal shipping containers of all sizes, encompasses single-unit cardboard boxes, and anything in-between.
The physical container participates in multiple transport equipment operations over time. Importantly, the transport equipment can be created before the exact physical container is known. Consignment, or shipment, planning most often occurs in advance of the physical container getting picked from the depot stack.
Tracking a transport equipment is initiated by event POST .../transportEquipment - start transport equipment tracking. The transport equipment should be created only after the actual physical ID (PID) is known, since the equipmentNumber is a required field and represents the PID. When this event is called, a transportEquipmentId (TEID) is created, but not returned. The TEID is a unique identifier that the platform assigns for the transport equipment that can be used (like the equipmentNumber) to publish or query events for the container. The TEID can be retrieved by using the queries (like POST .../tradeObjectIds) in the Trade Object APIs, see the API Documentation section.
POST .../transportEquipment - start transport equipment tracking also takes some required and optional fields as input, that can be conveniently used during tracking. Note: Not all input fields are described below. Refer to the API Documentation section.
carrierBookingNumber is the booking number from the carrier. When a consignment carriage is contracted with a carrier (ocean, truck, barge, rail or otherwise), a Booking Number reference is assigned to the consignment; this is the carrier booking number. The carrier booking number is used to match incoming events with a consignment and transport equipment. The carrier booking number must be a unique identifier across the entire shipping industry. The carrier booking number is a required field and establishes the linkage between the consignment and transport equipment.
equipmentNumber is the actual ID that is printed on the transport equipment. Thus, this value can only be set after the box has been selected. The equipmentNumber can be updated with POST .../transportEquipment/equipmentNumberUpdated - transport equipment number updated.
Warning: The same physical container participates in multiple transport equipment over time, but can (by definition) always only be part of one transport equipment at a time. Thus, if a equipmentNumber is already registered on an active transport equipment “A” (TE-A), and the same equipmentNumber is provided to another TE-B, then the TradeLens platform will deactivate TE-A.
transferFromConsignment allows the publisher the ability to move a transport equipment from one consignment to another. The identifiers contained in the field specify the consignment that the transport equipment is being transferred from. The identifiers specified in the main body of the event describe the consignment that the transport equipment is being transferred to.
correlationId is an additional identifier that can be passed with events. The correlationId can be used as needed, for example, to establish traceability. Note that all subscribers will receive the correlationId too. All platform events can be provided with correlationIds, so we will not repeat its description for the remainder of this document.
POST .../transportEquipment/cargoTypeUpdated - transport equipment cargo type updated sets or replaces a cargo type. The value is a Harmonized System 6 Code (HS6).
POST .../transportEquipment/equipmentNumberUpdated - transport equipment number updated similarly corresponds to adding an equipmentNumber as part of start transport equipment tracking. But a transport equipment can (by definition) only be delivered by use of a single physical container, and thus a TE can always only carry a single equipmentNumber. If the equipmentNumber had already been set, a /transportEquipment/equipmentNumberUpdated will replace the transport equipment information with the new equipmentNumber. Often the actual physical container is not known at the time of booking, and thus /transportEquipment/equipmentNumberUpdated is called when the container is picked from the empty stack. Note: Because a physical container can only participate in a single TE at a time, if an already in use equipmentNumber is submitted again, any previous TE will be ended.
POST .../transportEquipment/locationsUpdated - transport equipment locations updated sets or replaces the list of port and country fields of the transport equipment.
POST .../transportEquipment/referenceAdded - transport equipment reference added sets or replaces the transport equipment reference(s) (TERef) to the transport equipment. The TERef is meant to represent your internal system’s representation of this particular transport equipment (note the distinction from the physical container, which may also take place internally in your system). If a TERef is provided, then the transport equipment might be subsequently identified by the TEID or the TERef interchangeably. Note that multiple TERefs can be added if practical, allowing the same TE to be referenced by different foreign IDs, for example, a Non Vessel Owning Common Carrier's (NVOCC) internal reference for the shipment. Carrier booking number is the preferred identifier for a consignment and transport equipment. Warning: There is no way for the TradeLens platform to ensure the uniqueness of TERefs, so use them with caution. It is advised that you prefix your actual ID with some odd static string in order to avoid collisions with other platform participants’ use of TERef.
POST .../transportEquipment/partyAdded - Transport equipment visibility added associates a transport equipment with another organization. Carriers can use this to grant visibility of a transport equipment to their onboarded parties. This API grants the organization the ability to view the transport equipment and its events.
A shipment represents the linkage between what is transported (consignment) and how it is transported (partial, full, or multiple containers).
From the TradeLens platform perspective, a consignment carries a few essential attributes, and also functions as an aggregator for transport equipment, meaning that events can be posted to a consignment, and the platform will then delegate that event to all of the transport equipment containers involved with the consignment. Similarly, subscribing to a consignment will route all the transport equipment events related to that consignment to the subscription endpoint. This is a convenience, both in terms of the amount of API calls that are required, and by allowing participants to operate with a commonly shared identifier.
Consignments are established in the platform by event POST .../consignments - start consignment tracking. When this event is called, a consignmentId (CID) is created, but not returned. The CID is a unique identifier that the platform assigns for the consignment that can be used to publish or query events for the consignment. The CID can be retrieved by using the queries in the Trade Object APIs (like POST .../tradeObjectIds or GET .../consignments), see the API Documentation section.
POST .../consignments - start consignment tracking also takes some required and optional fields as input, that can be conveniently used during tracking. Note: Not all input fields are described below. Refer to the API Documentation section.
carrierBookingNumber is the booking number from the carrier. When a consignment carriage is contracted with a carrier (ocean, truck, barge, rail or otherwise), a Booking Number reference is assigned to the consignment; this is the carrier booking number. The carrier booking number is used to match incoming events with a consignment and transport equipment. The carrier booking number must be a unique identifier across the entire shipping industry.
bookingData is optional and contains information about the booking for the consignment. Additional posts for the same carrier booking number replace the bookingData. The complete set of bookingData must be provided every time the POST is sent. There is no merging of information from a previous POST to a new POST.
POST .../consignments/referenceAdded - consignment reference added sets or replaces the consignment reference(s) (CRef). It also allows you to add multiple consignmentRefs if practical, so the same consignment can be referenced by different foreign IDs. CRef can be used to establish an identifier between parties (such as shipper and carrier), and this attribute is meant to enable the use of this already known identifier for tracking the consignment in the platform. Carrier booking number is the preferred identifier for a consignment and transport equipment. Warning: As with TERef, the TradeLens platform cannot guarantee uniqueness of CRefs.
A consignment can be part of a consignment hierarchy. A consignment can have multiple subconsignments (child consignments) and a subconsignment can have multiple parent consignments. There is no limit on the number of levels in the consignment hierarchy. A consignment and subconsignment are connected by using the POST .../consignments/consignmentSubcontracted Consignment subcontract added API, and this creates the hierarchy.
POST .../consignments/consignmentSubcontracted Consignment subcontract added can be used to associate a subcontracted consignment as a child of another consignment. The API requires either a consignmentId or a carrierBookingNumber to identify the parent consignment and a subcontractId or subcontractCBN to identify the child consignment.
Each consignment has its own list of parties and roles that control the visibility to a consignment and the permissions for documents. There are no derived parties from parent or child consignments. Access to a consignment, its data, events, and documents is defined by its own parties. The creator of the consignment needs to call POST .../consignments/partyAdded - Consignment visibility added. You might have access to a consignment in a specific level of the hierarchy, but that does not give you access to parent or child consignments in the hierarchy unless you have been added as a party by the creator of the parent or child consignments. Access must be explicitly given using partyAdded.
Access to events from other levels of the hierarchy is available based on the following rules:
- All events from transport equipment (TE) go to all consignments that are associated with the TE; for example, an actual discharge from vessel event from a TE is also visible at its associated consignments.
- Only Planned events from a child consignment go to a parent consignment. Generic events, documentation events, and admin events do not go to parent consignments.
Note: The consignment hierarchy feature will continue to be enhanced. For now, some limitations exist, like the need to establish a hierarchy before associating transport equipment.
See the Consignment Hierarchy view section for an example of a consignment hierarchy on the Shipment Manager UI.
Consignments and Transport Equipment association
POST .../consignments/partyAdded - consignment visibility added can be used to associate a consignment and its transport equipment with the UUID of an onboarded organization. This grants the organization the ability to view the consignment (shipment), its transport equipment (containers), and documents that they have permission to upload, download, edit, and view, based on their partyRole (see the Data Provisioning Obligations and the Data Access Rights sections in the TradeLens Data Sharing Specification and the Document Sharing topic).
POST .../transportEquipment - Start transport equipment tracking can be used to create the transport equipment and establish the relationship between the consignment and transport equipment. The carrier booking number is a required field and establishes the linkage between the consignment and transport equipment.
Transport events are designed to communicate the planned operational route, and how it progresses to completion. Each event represents a significant step that has to occur in order for the transport equipment to get from origin to destination.
The transport event model is based around a logical model, that aims to:
- Be generic, broadly applicable throughout the supply chain. It is not meant to cover particular domains in full detail.
- Enable software developers to easily comprehend, map to and from, and code against.
- Embrace industry terms when such exist.
Thus, the transport event model follows this pattern:
- Each type of leg consists of four distinct events: Load, Departure, Arrival, and Discharge
- These four are mirrored in planned, estimated, and actual
- There are four leg types represented: Truck, Rail, Barge, and Ocean Vessel
The only exception to the above logic is stuffing (loading the transport equipment) and stripping (unloading the transport equipment) that starts and ends at the same location, and thus does not generate arrival and departure events. Stuffing and stripping events are still included as transport events, since they represent physical, time-consuming tasks, that must be factored into the planning of a consignment.
The transport events consist of three categories of events:
Planned events provide the planned route of a transport equipment. Estimated events provide the estimated time things will occur to the transport equipment. Actual events indicate things that have occurred to the transport equipment.
The transport owner of the consignment publishes the transport plan (planned events). Other participants can provide updated estimated and actual events. Consider for example the case where the transport plan published by the carrier includes a truck leg with planned departure and arrival. The trucker uses a GPS device to calculate the fastest route to the terminal as well as continuously updated ETAs (estimated time of arrival). These ETAs are estimated events, and can be published to the platform indicating to the terminal when the truck will arrive. These estimates do not change the transport plan that is owned by the transport owner (carrier). Conversely, if the trucker arrives late at the terminal, the transport equipment might have to be reallocated to a different vessel or voyage, and this would require a change to the transport plan by the carrier.
Planned events can be published by the transport owner without the need to analyze differences with previously published planned events, meaning that the transport owner does not need to maintain state data for the transport plan. The planned events must include the field "transportPlanIssuanceTime8601" which is the transport plan time stamp. The "transportPlanIssuanceTime8601" is used to group together planned events that make up the transport plan. This allows carriers and other transport owners to easily publish the most current transport plan. Subscribers can group the planned events by the transport plan time stamp "transportPlanIssuanceTime8601" and only consider the group with the newest time stamp to be valid. Similarly, the TradeLens Query API will consider the newest group of planned events with the same "transportPlanIssuanceTime8601" to be the new plan.
The TradeLens platform calculates a dynamic route for the transport equipment (TE) or consignment based on the submitted planned events. Using the planned events, the platform identifies the location of the event. The dynamically calculated route is used to determine which port and country subscribers receive events for the TE. As mentioned earlier, planned events can be submitted to consignments and they will define the transport plan for the consignment. The transport plan of a consignment can differ from the transport plan of its TE. This is because planned events published to a consignment are forwarded down to its TE, but planned events published to a TE are not forwarded up to its consignment, since a single TE within a consignment could take a different path than the rest of the consignment. If the plan for an entire consignment changes, then the carrier (or owner of the consignment) should submit a new set of planned events to the consignment. Since these events are forwarded down to the TE, the transport plan (and the route) of the TE is updated. Note that the transport plan is different than the route. The transport plan is the list of locations (in order) that the consignment or TE will pass through. The route is the list of port and country subscriptions that should receive events for the consignment or TE. The route of a consignment is the sum of the routes of all of its TE. That is, if you have a consignment with two TE, one going to ports A and B, and the second going to ports A and C, the events for the consignment will go to port subscriptions A, B, and C. The platform uses the sum of the routes of the TE because different TE in a consignment can have a different set of planned events, but all subscribers need to receive consignment-level events, like the consignmentCreated event.
The transport plan summary is a construct that the queries from the Trade Object API creates (and can also be viewed through the Shipment Manager UI), based on the events received. It includes a list of transport events, ordered by when they occur "eventOccurrenceTime8601". Together these events indicate the series of locations that each transport equipment will move, or has moved, on its journey and everything that happened to it along the way. See API Documentation for details on the Trade Object APIs and what is returned.
If you view the transport plan from the Shipment Manager UI, table 2 can help you understand the filtering. Note: Table 2 only shows the selections (Current Progress/Transport Plan/All Event Types) that relate to the transport plan.
Table 2 - Current Progress/Transport Plan/All Event Types with Latest Events/All Events
|Current Progress||latest Planned, up to latest Actual or latest Estimated without an Actual for current progress leg - associated events are grouped by their planned, estimated, and actual events if available. Note that Planned events for a transportation leg will not appear until at least an Estimated or an Actual event is available for that leg||n/a|
|Transport Plan||only Planned events (no Estimated or Actuals), grouped by Current Version of transport plan and any previous versions (Version 1, Version 2, etc.) of transport plan||n/a|
|All Event Types||latest Planned, latest Estimated, all Actuals, latest other non-tp events||all events submitted|
This logic corresponds to the events listed in table 3, 4, and 5 below. For the latest information, see the Event Publish Swagger UI in the API Documentation section.
(Note: The Ennn is a reference to the old API structure, if applicable, before GA)
Table 3 - Transport events – planned
|Truck||plannedLoadedOnTruck (E427)||plannedGateOut (E302)||plannedGateIn (E246)||plannedDischargeFromTruck (E450)|
|Train||plannedLoadedOnRail (E451)||plannedRailDeparture (E455)||plannedRailArrival (E403)||plannedDischargeFromRail (E459)|
|Barge||plannedLoadedOnBarge (E458)||plannedBargeDeparture (E440)||plannedBargeArrival (E410)||plannedDischargeFromBarge (E420)|
|Ocean||plannedLoadedOnVessel (E457)||plannedVesselDeparture (E034)||plannedVesselArrival (E310)||plannedDischargeFromVessel (E456)|
|Stuffing||plannedStuffingStarted (E423)||-||-||plannedContainerStuffed (E428)|
|Stripping||plannedStrippingStarted (E418)||-||-||plannedContainerStripped (E406)|
Table 4 - Transport events – estimated
Table 5 - Transport events – actuals
|Truck||actualLoadedOnTruck (E212)||actualGateOut (E268)||actualGateIn (E217)||actualDischargeFromTruck (E461)|
|Train||actualLoadedOnRail (E308)||actualRailDeparture (E421)||actualRailArrival (E405)||actualDischargeFromRail (E432)|
|Barge||actualLoadedOnBarge (E460)||actualBargeDeparture (E404)||actualBargeArrival (E414)||actualDischargeFromBarge (E454)|
|Ocean||actualLoadedOnVessel (E452)||actualVesselDeparture (E025)||actualVesselArrival (E280)||actualDischargeFromVessel (E453)|
|Stuffing||actualStuffingStarted (E416)||-||-||actualContainerStuffed (E229)|
|Stripping||actualStrippingStarted (E411)||-||-||actualContainerStripped (E021)|
Note that all transport plan events relate to transport equipment, not consignments. This is because the transport equipment is what get stuffed, loaded, discharged, etc. Shipment plans are made at the transport equipment level, but individual containers can often deviate from that plan. Managing at the transport equipment level allows for transport owners to have nuanced understandings of their shipment status.
For convenience, the TradeLens platform does allow a way to submit planned events against a consignment. This can save some event publishing calls. But it is important to understand that the platform will translate all these into individual transport equipment events for all the containers of the consignment.
TradeLens uses matching logic to associate incoming events with a consignment or with transport equipment. There are some cases where an event can not be matched, and if this occurs, the event is kept in a special area by the platform and will be associated with a consignment or to transport equipment if additional information is received by the platform that enables a match.
An event will be matched:
If an event specifies a Consignment Identifier (consignmentId or carrierBookingNumber) and a consignment exists that matches the identifier.
If an event specifies a Transport Equipment Identifier (transportEquipmentId, transportEquipmentRef, equipmentNumber) and a transport equipment exists that matches the identifier.
Note: For an event that was submitted with a transportEquipmentRef or an equipmentNumber, a carrierBookingNumber can also be specified. The event will only be matched if a transport equipment that matches the Transport Equipment Identifier exists and is associated with a consignment that matches the carrierBookingNumber.
There are two exceptions to this rule:
- POST .../api/v1/transportEquipment/referenceAdded - Transport equipment reference added (E469)
You can not use the transportEquipmentRef as the identifier for matching since it is the value being updated.
- POST .../api/v1/transportEquipment/equipmentNumberUpdated - Transport equipment number updated (E417)
You can not use the equipmentNumber as the identifier for matching since it is the value being updated.