Platform Event Model
Copyright IBM Corporation and GTD Solution Inc. 2018, 2021
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 five main groups of events to consider:
- Consignment events
- Transport Equipment events
- Shipment events
- Transport Plan events
- Generic 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 Publish API in Swagger. You can see the input that each API can accept and what is returned. For the latest information, see the API User Guide section for the Swagger URLs.
Consignment, Transport Equipment, and Shipment events
The platform is based on a simple logical data model with three related classes: Consignments, Transport Equipment, and Shipments. The main purpose of the platform’s events model is essentially to start and track consignments, transport equipment (containers), and shipments while managing the IDs and relationships between the three. 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. Shipments and consignments can also have a many-to-many relationship.
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 and bill of lading 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.
Notes for table 1: The events below are not a complete list of available APIs. For the latest information, see the API User Guide section for the Swagger URLs. The Ennn is a reference to a previous API structure and not all APIs have an Ennn reference.
Table 1 - Consignment, Transport Equipment, and Shipment events
|Consignments||POST .../consignments - Start consignment tracking (E468)|
|POST .../consignments/consignmentSubcontracted - Consignment subcontract added (E705)|
|POST .../consignments/partyAdded - Consignment visibility added (E001)|
|POST .../consignments/partyListUpdated - Consignment visibility updated (E002)|
|POST .../consignments/partyRemoved - Consignment visibility removed (E003)|
|POST .../consignments/referenceAdded - Consignment reference added (E422)|
|POST .../consignments/referenceListUpdated - Consignment reference list updated|
|POST .../consignments/referenceRemoved - Consignment reference removed|
|POST .../consignments/statusUpdated - Consignment status updated (E707)|
|POST .../consignments/transportEquipmentRemoved - Transport Equipment Removed|
|Consignments - Transport Equipment association||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/partyAdded - Transport equipment visibility added (E550)|
|POST .../transportEquipment/partyListUpdated - Transport equipment visibility updated (E551)|
|POST .../transportEquipment/partyRemoved - Transport equipment visibility removed (E552)|
|POST .../transportEquipment/referenceAdded - Transport equipment reference added (E469)|
|POST .../transportEquipment/referenceListUpdated - Transport equipment reference list updated|
|POST .../transportEquipment/referenceRemoved - Transport equipment reference removed|
|Shipments||POST .../shipments - Shipment created|
|POST .../shipments/consignmentAdded - Shipment consignment added|
|POST .../shipments/partyAdded - Shipment party added|
|POST .../shipments/partyListUpdated - Shipment party list updated|
|POST .../shipments/partyRemoved - Shipment party removed|
|POST .../shipments/referenceAdded - Shipment reference added|
|POST .../shipments/referenceListUpdated - Shipment reference list updated|
|POST .../shipments/referenceRemoved - Shipment reference removed|
|Shipments - Consignments association||POST .../shipments - Shipment created (if consignmentIdentifier is included)|
|POST .../shipments/consignmentAdded - Shipment consignment added|
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 User Guide 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 User Guide 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 same physical container participates in multiple transport equipment over time, but can (by definition) only be part of one transport equipment at a time.
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 from.
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.
A few other commonly used events for transport equipment are detailed here. For a complete list, see the API User Guide section for more information and a link to the Swagger URLs.
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/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. Equipment number is the preferred identifier for a 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 business partners. This API grants the organization the ability to view the transport equipment, its events, and any documents associated with the TE based on the permissions for the partyRole. Permissions for documents are detailed in the TradeLens Data Sharing Specification and in the Document Sharing topic.
A consignment represents the linkage between what is transported 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 some events that are sent to a consignment, and are relevant to the containers, will result in the platform sending that event to all of the transport equipment 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 User Guide 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 User Guide 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.
billOfLadingNumber is the bill of lading number for the consignment. The combination of a carrier booking number and a bill of lading number uniquely identifies a consignment. For example, you can have two consignments with the same carrier booking number but different bill of lading numbers; this is a split consignment.
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.
A few other commonly used events for consignments are detailed here. For a complete list, see the API User Guide section for more information and a link to the Swagger URLs.
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 (or carrier booking number and bill of lading number if the consignment has been split). Warning: As with TERef, the TradeLens platform cannot guarantee uniqueness of CRefs.
POST .../consignments/partyAdded - consignment visibility added associates a consignment with another organization. Carriers can use this to grant visibility of a consignment to their business partners. This API grants the organization the ability to view the consignment, its events, and any documents associated with the consignment based on the permissions for the partyRole. Permissions for documents are detailed in the TradeLens Data Sharing Specification and in the Document Sharing topic.
Consignment Association With Transport Equipment
To associate a transport equipment with a consignment, use the POST .../transportEquipment - Start transport equipment tracking to 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. If an organization needs visibility to a consignment, the organization can be added as a party to the consignment using the POST .../consignments/partyAdded - consignment visibility added event to associate a consignment and its transport equipment with an organization or business partner. This grants the organization the ability to view the consignment, its transport equipment, and documents (associated with the consignment) that they have permission to upload, download, edit, and view, based on their partyRole. Permissions for documents are detailed in the TradeLens Data Sharing Specification and in the Document Sharing topic. If an organization needs visibility to a transport equipment, the organization can be added as a party to the transport equipment using the POST .../transportEquipment/partyAdded - Transport equipment visibility added. This API grants the organization the ability to view the transport equipment, its events, and any documents associated with the TE based on the permissions for the partyRole.
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. The API requires either a subcontractId, or a subcontractCBN and subcontractBOL 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.
The shipment trade object represents the delivery of traded goods from seller to buyer. Shipments serve as a pouch of trade documents, provide visibility to the progress of the transport, and enable a way to track relevant references to the shipment.
In correspondence with the UN/CEFACT model, shipments are the TradeLens’ fundamental object for trade aspects, mirroring the consignment which is the foundational object for transport and logistics.
Official UN/CEFACT definition: A shipment is an identifiable collection of one or more Trade Items (available to be) transported together from the Seller (Original Consignor/Shipper) to the Buyer (Final/Ultimate Consignee):
- A shipment can only be destined for one Buyer.
- A shipment can be made up of some or all Trade Items from one or more Sales Orders.
- A shipment can have only one Customs UCR.
- A shipment may form part or all of a consignment or may be transported in different consignments.
TradeLens is not intended to be a purchase order management system. TradeLens does not support detailed cargo management (at PO/SKU line level). However, the shipment trade object does support tracking based on PO/SKU reference numbers (and many other types of references) for a shipment. This makes the data searchable and facilitates ingestion of TradeLens data into ERP (Enterprise Resource Planning) and SCM (Supply Chain Management) platforms.
Organizations of the types Cargo Interest and 3PL Agent can create shipments using the POST .../shipments - shipment created Event Publish API. The caller must specify a shipment reference that includes a reference and a type. The reference and type must be unique within the scope of a given reference owner. The list of allowable types can be found using the GET .../referenceTypes - Get all reference types Platform Constants API. See the API User Guide section for more information on the APIs. If the consignmentIdentifier is supplied on the POST .../shipments - shipment created Event Publish API, then the shipment will be associated with the consignment(s).
Shipment Association With Consignment
The logistical movement of the traded goods are handled through one or multiple consignments. In the most simple scenario, the shipment is just moved by a single consignment. However, in many cases a many-to-many relationship exists between shipments and consignments reflecting how goods are consolidated in LCL (Less than Container Load) scenarios. Shipments can span multiple consignments, such as inland and ocean consignments in merchant haulage scenarios. In this way, shipments can group “sibling” consignments (merchant haulage scenarios), that are otherwise not directly related. If the consignmentIdentifier is supplied on the POST .../shipments - shipment created Event Publish API, then the shipment will be associated with the consignment(s). Otherwise, the POST .../shipments/consignmentAdded - Shipment consignment added Event Publish API will associate a shipment with a consignment. If an organization needs visibility to a consignment, the organization can be added as a party to the consignment using the POST .../consignments/partyAdded - Consignment visibility added Event Publish API.
Data Sharing Among Shipment Parties
Trade and transport parties often differ, so from a data sharing perspective it is important to make this distinction. The shipment trade object provides an object that trade partners, particularly the Seller and Buyer, can use to share data and documents. The POST .../shipments/partyAdded - Shipment party added and POST .../shipments/partyListUpdated - Shipment party list updated Event Publish APIs can be used to add parties to a shipment. Permissions for documents are detailed in the TradeLens Data Sharing Specification and in the Document Sharing topic.
Data Sharing With Customs Authorities
Shipment data, especially certain documents, is relevant for sharing with customs authorities. In the transport (consignment-based) space, TradeLens determines the relevant customs authorities from the transport plan. This is not applicable for shipments, given the loose coupling with the transport layer. Rather, customs authorities are associated to shipments through two attributes on the Shipment:
- originCountry - the country of origin, from where the shipment is lodged.
- destinationCountry - the country of final destination for this shipment.
This approach allows shipment parties to prepare a full set of documents before sharing with relevant authorities.
See the Shipment Manager section for an example of a shipment in the Shipment Manager UI.
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.
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). Since the stuffing or stripping work begins and ends at the same location, they do not generate arrival and departure events (see tables 3, 4, and 5 below). 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 (or consignment). 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 (transport service provider) 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 relocated 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 entire transport plan. This allows carriers and other transport service providers 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 (or the other TE within 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. If the TE already has a TE specific plan, new plans sent to the consignment are not forwarded down to the TE. 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 User Guide for details on the Trade Object APIs and what is returned.
Event Priority Matrix
An Event Priority (eventPriority) is applied by TradeLens to Transport Events (Estimated and Actual) and to Generic Events. This allows TradeLens to group events of the same type that are happening at the same location and display (or return) the highest priority event that is available at that time. This ensures that the most reliable data for milestone events is provided, based on who the provider of the data is and the availability of the events at the time when the events are sent to subscription webhooks or when they are queried through the Trade Object APIs or displayed on the Current Progress view of the UI.
For example, assuming the same location is used and the fullStatus is the same (Full or Empty): If an Ocean Carrier publishes an Actual Gate In, the event would have the Event Priority set to 5. If a Terminal Operator publishes an Actual Gate In, the Event Priority would be set to 1. If a Truck Operator publishes an Actual Gate In, the Event Priority would be set to 3. The highest priority event from the Ocean Carrier will be displayed in the Current Progress view of the UI for the Transport Equipment. The additional sources for the events from the Terminal Operator and Truck Operator are hidden, but are available by clicking the Additional Sources link in the Current Progress view.
To view the priority matrix, you can download the Event_Priority_Matrix.xlsx spreadsheet. The spreadsheet has two tabs: The first one has the events broken down by the same event type/category and the second tab is the consolidated list for all events.
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||grouped by location - highest priority Actual and/or Estimated, latest Planned||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 API in the API User Guide section.
(Note: The Ennn is a reference to a previous API structure and not all APIs have an Ennn reference.)
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, unless the transport equipment has an existing plan that was sent to just the transport equipment.
Generic events are other events for either the transport equipment or the consignment. They represent events that can happen to a transport equipment or consignment, beyond the transport events, for example POST .../genericEvents/packedContainerSealed - Packed transport equipment sealed. See the API User Guide section for Swagger URLs for the generic events in the Event Publish API.
TradeLens uses matching logic to associate incoming events with a consignment, transport equipment, or shipment trade object. 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 the trade object if additional information is received by the platform that enables a match.
If there is only one consignment with the carrierBookingNumber and an event specifies a consignment identifier (consignmentId or carrierBookingNumber) then the event will be matched with the consignment. If there is more than one consignment with the same carrierBookingNumber (like in a split consignment case), then either the consignmentId, or the carrierBookingNumber and billOfLadingNumber, are required to uniquely identify the consignment.
If an event specifies a transport equipment identifier (transportEquipmentId, transportEquipmentRef, equipmentNumber) and a transport equipment exists that matches the identifier, then the event will be matched.
If an event specifies a shipment reference (both the reference and the type) and a shipment exists that matches the shipment reference, then the event will be matched.
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 is one exception to this rule: POST .../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.