Publishing Containers for Tracing

Applications integrating Envase Trace will need to publish the containers they want to trace by sending an event to Envase Connect Data. Once the container is published, it will be traced at a predetermined intervals according to the business rules.

Note

Containers will be scheduled to be traced again based on the status retrieved on the previous trace. The business logic is implemented in the backend, so it can be adjusted as we learn more about the “behavior” of those containers. The goal is to notify client applications of changes as soon as they happen minimizing the overhead caused by tracing on the system and the provider services.

Applications can publish the same container more than once. This will not cause an error and will force the trace of the container. This, however, it is not recommended. Applications should be implemented to receive the notifications when they happen and not to force containers to be traced again.

Note

The ability to force a trace on a container has been provided to help during testing. When testing the implementation, it is desired to get results immediately without having to wait for the next trace cycle, which may happen days later depending on the container status. Still, client applications should not force the trace during normal operation.

Warning

A forced trace only make sense for containers traced through a Real-Time Workflow. Containers traced through providers that support other workflows will not be forced to trace.

Sending A Trace Request

Publishing a container requires the TMS application to send a request to Envase Connect Data with the information about the container to be traced. This request includes information about the container, the TMS, and the provider to be used for tracing:

POST https://events.envaseconnect.cloud/api/events

The body will have the following structure:

{
    "orgId": "3b42ff39-d731-43f6-a8a2-1b257f87469e",
    "svcId": "7cd437c3-f25a-4e22-b221-47b6485f140d",
    "type": "CONTAINER",
    "action": "TRACE_REQUESTED",
    "origin":  "profit-tools-web-services-trace-requested",
    "payload": {
        "id": "CONT123456",
        "siteId": "urn:site",
        "providerId": "up",
        "data": {

        }
    }
}

The orgId property identifies the Envase customer sending the request. This id is issued when a new organization is registered with Envase Identity Manager. Similarly, the svcId property represents the concrete instance of the client application, which is also registered when the customer’s account is created.

The type and action properties will always have the same values to publish a container. The type property must be set to CONTAINER and the action must be set to TRACE_REQUESTED.

The origin property identifies the service that originated the request. The Envase Connect Data team can provide the value that this property should be set.

The payload property is the relevant part of the request, which will have the structure represented above. It should include the following properties:

The id property is the container reference number. It indicates which container should be traced.

The siteId and providerId are optional; however, one of them must be included. These properties are provided to identify the provider that should be used for tracing.

Warning

Currently, only the providerId property is supported. The siteId will be used in the future once a sites service that normalizes site identifiers is implemented by Envase.

The data property is a flexible JSON object that allows to provide additional data necessary to trace a container. If no additional data is provided, it should be set to an empty JSON object. The properties within the data object will vary by provider, and they are documented in the provider documentation.

Important

Provider specific information can be added to the data property. This doesn’t include credentials or any type of secret which they’ll be managed through Envase Vault.

Important

The data property could have flag called normalize defaulted to true which means it will do the container validation but if the value is set to false then it will skip the container validation.

Providers Information

This section will introduce specific provider information like credentials and data information with examples

Apm

Credentials are envase based and they require

{
    "clientId": "enter client id",
    "clientSecret": "enter client secret"
}

Data has to be provided in the request payload for location_code which represents terminal name

Possible values:

Terminal Name	Location Code
Los Angels terminal	USLAX
Port Elizabeth Terminal	USNWK
Mobile Terminal	USMOB
South Florida Container Terminal Miami	USMIA

Example:

{
    "orgId": "3b42ff39-d731-43f6-a8a2-1b257f87469e",
    "svcId": "7cd437c3-f25a-4e22-b221-47b6485f140d",
    "type": "CONTAINER",
    "action": "TRACE_REQUESTED",
    "origin":  "profit-tools-web-services-trace-requested",
    "payload": {
        "id": "CONT123456",
        "siteId": "urn:site",
        "providerId": "apm",
        "data": {
            "locationCode": "USNWK"
        }
    }
}

Blount Island Terminal

Credentials are customer based and they require

{
    "user": "enter user email",
    "password":     "enter password"
}

Doesn’t require any additional information in the data parameter of the request payload

BNSF

Doesn’t require credentials

Doesn’t require any additional information in the data parameter of the request payload

CN

Credentials are envase based and they require

{
    "key": "enter key",
    "secret": "enter secret"
}

Doesn’t require any additional information in the data parameter of the request payload

Conley

Credentials are customer based and they require

{
    "user": "enter user email",
    "password": "enter password"
}

Doesn’t require any additional information in the data parameter of the request payload

Eagle Marine

Credentials are envase based and they require

{
    "user": "enter user email",
    "password": "enter password"
}

Doesn’t require any additional information in the data parameter of the request payload

Emodal

Credentials are envase based and they require

{
    "apiKey": "enter api key",
    "senderCd": "enter sender cd",
    "signature": "enter signature"
}

Data has to be provided in the request payload for location_code which represents terminal name

Possible values:

Terminal Name	Location Code
Virginia International Terminals	POV
New York Container Terminal Global Container Terminal Bayonne	NYNJ
PCT (Pierce County Terminal) Evergreen	NWSA
Everport	LALB
Oakland	OAK

Example:

{
    "orgId": "3b42ff39-d731-43f6-a8a2-1b257f87469e",
    "svcId": "7cd437c3-f25a-4e22-b221-47b6485f140d",
    "type": "CONTAINER",
    "action": "TRACE_REQUESTED",
    "origin":  "profit-tools-web-services-trace-requested",
    "payload": {
        "id": "CONT123456",
        "siteId": "urn:site",
        "providerId": "emodal",
        "data": {
            "locationCode": "OAK"
        }
    }
}

Everglades Terminal

Credentials are customer based and they require

{
    "user": "enter user email",
    "password": "enter password"
}

Doesn’t require any additional information in the data parameter of the request payload

Florida International Terminal

Credentials are customer based and they require

{
    "user": "enter user email",
    "password": "enter password"
}

Doesn’t require any additional information in the data parameter of the request payload

ICTSI

Credentials are evnvase based and they require

{
    "subscriptionId": "enter subscription id",
    "subscriptionKey": "enter subscription key",
}

Data have to be provided in the request payload for locationCode which represents terminal name

Possible values:

Terminal Name	Location Code
Marine International Container Terminal	MICT
Sub Bay International Terminal Corp.	SBITC

Also data must have a property called steamshipBL which represents the steamship bill of lading.

Example of publishing an import container:

{
    "orgId": "3b42ff39-d731-43f6-a8a2-1b257f87469e",
    "svcId": "7cd437c3-f25a-4e22-b221-47b6485f140d",
    "type": "CONTAINER",
    "action": "TRACE_REQUESTED",
    "origin":  "profit-tools-web-services-trace-requested",
    "payload": {
        "id": "CONT123456",
        "siteId": "urn:site",
        "providerId": "ictsi",
        "data": {
            "locationCode": "MICT",
            "steamshipBL": "599221769"
        }
    }
}

Its

Credentials are customer based and they require

{
    "user": "enter user email",
    "password": "enter password"
}

Data has to be provided in the request payload for location_code which represents terminal name

Possible values:

Terminal Name	Location Code
ITS Long Beach	ITS
Husky Tacoma	HUSKY

Example:

{
    "orgId": "3b42ff39-d731-43f6-a8a2-1b257f87469e",
    "svcId": "7cd437c3-f25a-4e22-b221-47b6485f140d",
    "type": "CONTAINER",
    "action": "TRACE_REQUESTED",
    "origin":  "profit-tools-web-services-trace-requested",
    "payload": {
        "id": "CONT123456",
        "siteId": "urn:site",
        "providerId": "its",
        "data": {
            "locationCode": "ITS"
        }
    }
}

LBCT

Credentials are customer based and they require

{
    "apiKey": "enter api key"
}

Doesn’t require any additional information in the data parameter of the request payload

Maher

Credentials are customer based and they require

{
    "authorization": "enter authorization",
    "sid": "enter sid"
}

Doesn’t require any additional information in the data parameter of the request payload

Matson C60

Doesn’t require credentials

Doesn’t require any additional information in the data parameter of the request payload

MGT

Credentials are customer based and they require

{
    "user": "enter user email",
    "password": "enter password"
}

Doesn’t require any additional information in the data parameter of the request payload

NWCS

Credentials are customer based and they require

{
    "user": "enter username",
    "password": "enter password"
}

Doesn’t require any additional information in the data parameter of the request payload

Oakland B58

Credentials are customer based and they require

{
    "user": "enter user email",
    "password": "enter password"
}

Doesn’t require any additional information in the data parameter of the request payload

Pacific coast terminal

Credentials are customer based and they require

{
    "user": "enter user email",
    "password": "enter password"
}

Doesn’t require any additional information in the data parameter of the request payload

Packer

Doesn’t require credentials

Doesn’t require any additional information in the data parameter of the request payload

Pier A

Credentials are customer based and they require

{
    "user": "enter user email",
    "password": "enter password"
}

Doesn’t require any additional information in the data parameter of the request payload

Pomtoc

Credentials are customer based and they require

{
    "user": "enter user email",
    "password": "enter password"
}

Doesn’t require any additional information in the data parameter of the request payload

Port of Houston

Credentials are customer based and they require

{
    "user": "enter user email",
    "password": "enter password"
}

Note

Provider <port_houston> is customer based and customers must request API access from Port of Houston

Data has to be provided in the request payload for locationCode which represents terminal name and truckCompany which is a 4 character company code

Possible values:

Terminal Name	Location Code
Barbours Cut	PHABC
Bayport	PHA

Example:

{
    "orgId": "3b42ff39-d731-43f6-a8a2-1b257f87469e",
    "svcId": "7cd437c3-f25a-4e22-b221-47b6485f140d",
    "type": "CONTAINER",
    "action": "TRACE_REQUESTED",
    "origin":  "profit-tools-web-services-trace-requested",
    "payload": {
        "id": "CONT123456",
        "siteId": "urn:site",
        "providerId": "port_houston",
        "data": {
            "locationCode": "PHABC",
            "truckCompany": "SCAC"
        }
    }
}

Portland

Credentials are customer based and they require

{
    "user": "enter user email",
    "password": "enter password"
}

Doesn’t require any additional information in the data parameter of the request payload

Ports America

Credentials are envase based and they require

{
    "user": "enter username",
    "password": "enter password"
}

Data has to be provided in the request payload for siteId which represents terminal name and truckingCompanyCode which is a 4 character company code

Possible values:

Terminal Name	Location Code
M.I.T. Seagirt Marine Terminal	SGT_BAL
OCT (Olympic Container Terminal)	OCT
PNCT (Port Newark Container Terminal)	PNCT_NJ
West Basin Container Terminal	WBCT_LA

Example:

{
    "orgId": "3b42ff39-d731-43f6-a8a2-1b257f87469e",
    "svcId": "7cd437c3-f25a-4e22-b221-47b6485f140d",
    "type": "CONTAINER",
    "action": "TRACE_REQUESTED",
    "origin":  "profit-tools-web-services-trace-requested",
    "payload": {
        "id": "CONT123456",
        "siteId": "urn:site",
        "providerId": "ports_america_api",
        "data": {
            "siteId": "WBCT_LA",
            "truckingCompanyCode": "PFCH"
        }
    }
}

Railsight

Credentials are envase based but Railsight sill needs a customer fleet code

Envase credentials

{
    "account": "enter account",
    "user": "enter username"
    "password": "enter password"
}

Customer credentials

{
    "fleet": "enter fleet"
}

Doesn’t require any additional information in the data parameter of the request payload

Red Hook Terminal

Credentials are customer based and they require

{
    "user": "enter user email",
    "password": "enter password"
}

Doesn’t require any additional information in the data parameter of the request payload

scspa

Doesn’t require credentials

Doesn’t require any additional information in the data parameter of the request payload

Shippers Alameda

Credentials are customer based and they require

{
    "user": "enter user email",
    "password": "enter password"
}

Doesn’t require any additional information in the data parameter of the request payload

Shippers Carson

Credentials are customer based and they require

{
    "user": "enter user email",
    "password": "enter password"
}

Doesn’t require any additional information in the data parameter of the request payload

Shippers Transport

Credentials are customer based and they require

{
    "user": "enter user email",
    "password": "enter password"
}

Doesn’t require any additional information in the data parameter of the request payload

Terminal 5

Credentials are customer based and they require

{
    "user": "enter user email",
    "password": "enter password"
}

Doesn’t require any additional information in the data parameter of the request payload

Terminal 6

Credentials are customer based and they require

{
    "user": "enter user email",
    "password": "enter password"
}

Doesn’t require any additional information in the data parameter of the request payload

Terminal 18

Credentials are customer based and they require

{
    "user": "enter user email",
    "password": "enter password"
}

Doesn’t require any additional information in the data parameter of the request payload

Terminal 30

Credentials are customer based and they require

{
    "user": "enter user email",
    "password": "enter password"
}

Doesn’t require any additional information in the data parameter of the request payload

Termont

Doesn’t require credentials

Doesn’t require any additional information in the data parameter of the request payload

Trapac

Doesn’t require credentials

Data has to be provided in the request payload for location_code which represents terminal name

Possible values:

Terminal Name	Location Code
B136 Los Angeles	LAX
B30 Oakland	OAK

Example:

{
    "orgId": "3b42ff39-d731-43f6-a8a2-1b257f87469e",
    "svcId": "7cd437c3-f25a-4e22-b221-47b6485f140d",
    "type": "CONTAINER",
    "action": "TRACE_REQUESTED",
    "origin":  "profit-tools-web-services-trace-requested",
    "payload": {
        "id": "CONT123456",
        "siteId": "urn:site",
        "providerId": "trapac",
        "data": {
            "locationCode": "OAK"
        }
    }
}

TTI

Credentials are customer based and they require

{
    "authorization": "enter authorization"
}

Doesn’t require any additional information in the data parameter of the request payload

UP

Credentials are envase based and they require

{
    "user": "enter username",
    "password": "enter password"
}

Doesn’t require any additional information in the data parameter of the request payload

Washington United

Credentials are customer based and they require

{
    "user": "enter username",
    "password": "enter password"
}

Doesn’t require any additional information in the data parameter of the request payload

YTI

Credentials are customer based and they require

{
    "user": "enter username",
    "password": "enter password"
}

Doesn’t require any additional information in the data parameter of the request payload

Cancel Container Trace

Client applications might need to cancel a container number from being traced. To cancel a container trace, the client application must send an event to Envase Connect Data with the following structure:

{
    "orgId": "3b42ff39-d731-43f6-a8a2-1b257f87469e",
    "svcId": "7cd437c3-f25a-4e22-b221-47b6485f140d",
    "type": "CONTAINER",
    "action": "TRACE_CANCELLED",
    "origin":  "provided-by-connect-data",
    "payload": {
        "id": "the-container-id",
        "siteId": "urn:site",
        "providerId": "apm",
    }
}

The event structure is similar to the event to publish a container number, and it uses most of the same properties. The difference is in the action property that will be set to TRACE_CANCELLED.