Publishing Containers for Export and Empty 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 Export 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_EXPORT_REQUESTED",
        "origin":  "profit-tools-web-services-trace-requested",
        "payload": {
            "id": "CONT123456",
            "siteId": "urn:site",
            "providerId": "ictsi",
            "data": {
                "locationCode": "MICT",
                "bookingNumber": "TASF883714"
            }
        }
}

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_EXPORT_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.

Important

The data property must have proprty called bookingNumber which represents booking number for this container.

Sending A Trace Empty 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_EMPTY_REQUESTED",
        "origin":  "profit-tools-web-services-trace-requested",
        "payload": {
            "id": "CONT123456",
            "siteId": "urn:site",
            "providerId": "ictsi",
            "data": {
                "locationCode": "MICT"
            }
        }
}

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_EMPTY_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

ICTSI

Credentials are envase based and they require

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

Data has 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

Important

For export container The data property must have proprty called bookingNumber which represents booking number related to this container.

Example of publishing an export container:

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

Note

For empty container, The data property does not require any addational keys beside locationCode.

Example of publishing an empty container:

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

Cancel Container Export 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_EXPORT_CANCELLED",
    "origin":  "provided-by-connect-data",
    "payload": {
        "id": "the-container-id",
        "siteId": "urn:site",
        "providerId": "ictsi",
    }
}

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_EXPORT_CANCELLED.

Cancel Container Empty 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_EMPTY_CANCELLED",
    "origin":  "provided-by-connect-data",
    "payload": {
        "id": "the-container-id",
        "siteId": "urn:site",
        "providerId": "ictsi",
    }
}

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_EMPTY_CANCELLED.