Handling Container Trace Result Events 

As containers are traced, the system will notify the TMS through the registered Web-Hook. The results from the traced are sent from Envase Trace to Envase Connect Data, which in turn will notify the TMS.

The TMS application will receive this information and update their system to reflect the new status of the container. This guide describes the request payload and container status events that the TMS will receive, so that the results can be handled correctly based on the TMS business logic.

Container Results Event 

The Container Results Event is the information that the Envase Trace system will use to notify about changes in the status of a container. It will do so through Envase Connect Data, which will use the registered Web-Hook to send the information.

Envase Connect Data will send a request to the URL registered as Web-Hook with the following structure:

{
    "orgId": "3b42ff39-d731-43f6-a8a2-1b257f87469e",
    "tmsId": "7cd437c3-f25a-4e22-b221-47b6485f140d",
    "type": "CONTAINER",
    "action": "TRACE_RESULT",
    "payload": {
        "containerNumber": "CONT123456",
        "description": "TBD",
        "length": "20",
        "tracedAt": "2021-07-26T11:00",
        "nextTraceAt": "2021-07-26T11:30",
        "loaded": "laden",
        "steamshipBL": "bill-of-lading-number",
        "pickupNumber": "pick-up-number",
        "carrier": {
            "type": "vessel",
            "steamshipLine": "carrier-scac",
            "vessel": "the-id-of-the-vessel",
            "voyage": "the-id-of-the-voyage"
        },
        "providerId": "ictsi",
        "destination": {
            "type": "terminal",
            "siteId": "urn:site",
            "name":"Long Beach - Terminal"
        },
        "events": [
        ]
    }
}

The event payload contains information about the event. The orgId and tmsId will match those specified when the container was published and they represent the customer company and TMS instance receiving the event.

Note

Currently length property is returned only if the providerId is ictsi. If other providers supported it in the future, the length property will be returned for them as well.

Note

A TMS application can validate the orgId and tmsId to verify that the event was really intended for it.

The type property will always be set to CONTAINER indicating that the event is related to a specific container. Similarly, the action property will always be set to TRACE_RESULT to indicate that this event provides results for the status of a container trace.

The payload property is specific to the container result. The properties in it represent the current status of the container. The containerNumber contains the container reference number, which will match the Container Number used when the container was published.

The description property will contain provider specific information about the container. Different providers will set different descriptions. In general, this property should be used as feedback to the user.

The tracedAt is an ISO date/time string representing when the container was last traced. The nextTraceAt is also an ISO date/time string that represents when the next trace for that container has been scheduled.

The loaded property represents the status of the container and can have a value of laden (loaded) or empty.

The steamshipBL property will contain a string representing the Bill of Lading number provided during the trace. The pickupNumber property provides a string with the Pickup Number for the container.

The carrier property is an object that represents the current carrier in possession of the container. The structure of this object is documented below.

The providerId represents the system used to retrieve the information. Specific ids are documented in each of the providers documentation.

The destination is a location object that represents the location of the terminal or rail where the container will arrive. The structure of a location object is documented below.

The events property is an array of associated container status events that represent the current status of the container. The container status events are documented in this guide.

Carrier Object Structure 

A carrier object represents the carrier that is currently in possession of the container. This might be the carrier the TMS is expecting or a different carrier depending on where the container is in its transit.

The object has a type property that will indicate the carrier type.

Warning

The possible values of the type property have not been fully defined yet and will be documented here once fully defined.

Todo

Document carrier types.

The carrier object also contains a steamshipLine property representing the SCAC for the carrier. The vessel and voyage properties indicate information about how the container is currently transported.

Location Object Structure 

Location objects represent a specific location for an entity. This location can have different properties depending on the type of location. As an example, a location object may contain a normalized address if the location represents a physical land location, but it may only contain a set of coordinates if the location is provided by GPS information or the location of a vessel on the sea.

In the context of Envase Trace, the location object is closely related to a site. Since Envase does not provide a sites service yet, Envase Trace uses the information retrieved from the trace provider to represent these locations. A better representation will be provided in the future, with more information about the specific location.

The structure of a location object should be similar to the following:

{
    "type": "terminal",
    "siteId": "urn:site:...",
    "name": "Long Beach - Terminal"
}

The object will provide a type property indicating the type of location it represents. It will also provide a siteId that uniquely identifies the location.

Warning

Since there is no sites service implemented currently, the siteId is not a reliable value; therefore, TMS applications should try to avoid this property in their business logic if possible.

A name property will be provided with a friendly name for the location that can be displayed to the user.

Container Status Events 

A Trace Result event will provide an array of Container Status Events that represent the current status of the container when traced. The design of these events has been made flexible, so other status events can be provided in the future.

These events represent the container status life-time over time. When a container is traced, the results represent the current status of the container, and they will not include information about previous states.

All events have a basic structure:

{
    "code": "event-code",
    "eventDate": "2021-07-26T10:56:22.240572",
    "location": {
        "type": "site-type",
        "siteId": "site-id-when-ready",
        "name": "friendly-name-for-site"
    },
    "data": {

    }
}

All events will provide a normalized code that represents the type of container status event. They will also provide an eventDate, which is an ISO date/time string indicating when the event happened, and a location property representing the location of the event (see the Location Object documentation).

Each individual event type, indicated by the code property, will include additional data related to the event. The following sections document each of the supported container status events.

ETA Event 

Provided that containers are traced early in their life cycle, the ETA event should be one of the first states in which a container will be. It indicates that the container is in transit and has not arrived yet to the terminal or rail destination.

This event provides information about when the container is expected to arrive (Estimated Time of Arrival). This event also indicates that the provider is aware of the container, and at some point, they will provide further status information.

The ETA event follows the structure of all container status events and provides additional data:

{
    "code": "eta",
    "eventDate": "2021-07-26T10:56:22.240572",
    "location": {
        "type": "site-type",
        "siteId": "site-id-when-ready",
        "name": "friendly-name-for-site"
    },
    "data": {
        "eta": "2021-07-27T10:56"
    }
}

The event code will be set to eta. The data object provides an eta property, which is an ISO date/time string representation of when the container is estimated to arrive.

Arrived Event 

The Arrived event is included when the container has arrived at its destination. The event provides the same properties as other events and includes some additional data.

{
    "code": "arrived",
    "eventDate": "2021-07-26T10:56:22",
    "location": {
        "type": "site-type",
        "siteId": "site-id-when-ready",
        "name": "friendly-name-for-site"
    },
    "data": {
        "arrived": "2021-07-26T10:56:22"
    }
}

The event code will be set to arrived. The data object provides an arrived property, which is an ISO date/time string representation of when the container arrived at the terminal or rail.

Grounded Event 

The Grounded event represents when the container has been removed from the vessel and place on a yard. The event provides information about when this happened.

{
    "code": "grounded",
    "eventDate": "2021-07-26T10:56:22",
    "location": {
        "type": "site-type",
        "siteId": "site-id-when-ready",
        "name": "friendly-name-for-site"
    },
    "data": {
        "grounded": "2021-07-26T10:56:22",
        "lot": "SP1258"
    }
}

The event code will be set to grounded. The data object provides a grounded property, which is an ISO date/time string representation of when the container was grounded.The data also provides a lot which represents where the container has been grounded.

Lfd Event 

The Lfd event represents the last free date for a container to be picked up, Additional information is provided in the data object.

{
    "code": "lfd",
    "eventDate": "2021-07-26T10:56:22.240572",
    "location": {
        "type": "site-type",
        "siteId": "site-id-when-ready",
        "name": "friendly-name-for-site"
    },
    "data": {
        "lfd": "2021-07-26"
    }
}

The event code will be set to lfd. The data provides lfd property, which is an ISO date string representation of the last free date when the container can be picked up.

Released Event 

The Released event represents that the container has been released by the terminal or rail, and it should be ready to be picked up provided that no holds are active on the container (see hold event below). Additional information is provided in the data object.

{
    "code": "released",
    "eventDate": "2021-07-26T10:56:22.240572",
    "location": {
        "type": "site-type",
        "siteId": "site-id-when-ready",
        "name": "friendly-name-for-site"
    },
    "data": {
        "release": "2021-07-26T10:56:22"
    }
}

The event code will be set to released. The data provides a released, which is an ISO date/time string representation of when the container was released. The data also provides lfd an lineLfd properties, which is an ISO date string representation of the last free date when the container can be picked up.

Hold Event 

The Hold event represents some blocker for which a container cannot be picked up yet. The container can be in a Released status and have that event, but because of the hold, the container is not available for pick up.

There are many different types of holds, and the list increases when new providers are added. The types might also differ on the data they provide. The design of the Hold event allows the necessary extensibility, so that TMS applications can process the holds in a consistent manner, which ignoring the details they don’t care about.

{
    "code": "hold",
    "eventDate": "2021-07-26T10:56:22.240572",
    "location": {
        "type": "site-type",
        "siteId": "site-id-when-ready",
        "name": "friendly-name-for-site"
    },
    "data": {
        "holdType": "type-of-hold",
        "code": "code-provided-by-provider"
    }
}

The event code will be set to hold. The data provides a holdType property that identifies the type of hold. It also provides a code property that refers to the provider specific code to represent the hold. Depending on the provider, this value will be different, but it helps legacy TMS systems on identifying the type of hold.

The following table shows the known holds for the existing providers:

Name	Type	Description
Customs	customs	Represents a hold in Customs.
CTF	ctf	Represents a CTF hold.
Demurrage	demurrage	Represents a demurrage hold.
Exam	exam	Represents an exam hold.
Freight	freight	Represents a freight hold.
Line	line	Represents a line hold.
OBL	obl	Represents an obl hold.
TMF	tmf	Represents a tmf hold.
USDA	usda	Represents a USDA hold.

Outgated Event 

The Outgated event represents the container has been picked up and has left the facilities. When this event is received, Envase Trace will stop tracing that container. Additional data is provided for the Outgated event.

{
    "code": "outgated",
    "eventDate": "2021-07-26T10:56:22.240572",
    "location": {
        "type": "site-type",
        "siteId": "site-id-when-ready",
        "name": "friendly-name-for-site"
    },
    "data": {
        "outgated": "2021-07-26T10:56:22.240572",
        "outgateScac": "scac-of-trucking-company",
        "outgateConfirmed": true
    }
}

The event code will be set to outgated. The data will contain an outgated property, which is an ISO date/time representation of when the container was outgated.

Some providers will include the outgateScac of the trucking company that picked the container.

The outgateConfirmed property is a Boolean that represents whether the Outgated is confirmed or not. Some providers make the outgated information available when the container is picked. In those cases, the confirmed property will have a value of true. Other providers do not indicate when the container is Outgated, in which case, we will use other logic to create an Outgated event to stop tracing the container. In these other cases, the confirmed property will be set to false.

No Data Event 

The No Data event indicates that there is not information about the specified container. This can be caused by many reasons, but the most likely reason is that the container was published way ahead in advance, and the provider doesn’t have the information yet. The container will be traced again after some time to see if it makes it through the system.

{
    "code": "no-data",
    "eventDate": "2021-07-26T10:56:22.240572",
    "location": {
        "type": "site-type",
        "siteId": "site-id-when-ready",
        "name": "friendly-name-for-site"
    },
    "data": {

    }
}

Container Trace Failure Events 

There is the possibility that a trace job may fail completely. This can be cause by many reasons, in which case the TMS application will be notified of the failure.

Some of the problems are caused by the provider service itself. The web-site or API might be down for some reason, or the web-site has changed and the tracer fails. Other reasons can be changes to the API, but this happens less frequently.

Other problems might be caused by the customer; for example, the case where they entered the wrong credentials to log into one of the provider web-sites. The customer needs to be notified to fix that problem.

When this job level errors happen, a notification to the TMS will be sent so that the application can take action. The structure of the event is as follows:

{
    "orgId": "3b42ff39-d731-43f6-a8a2-1b257f87469e",
    "tmsId": "7cd437c3-f25a-4e22-b221-47b6485f140d",
    "type": "TRACE",
    "action": "FAILED",
    "origin": "trace-entm-dev-send-job-error-event",
    "payload": {
        "siteId": "urn:site",
        "providerId": "up",
        "data": {
            "message": "description of the error"
        }
    }
}

The event has the usual properties at the root level orgId, tmsId, origin, type always set to TRACE, and action set to FAILED.

The payload property contains information about the error. Within it, the data property will have a message describing the error, and other information about the problem.