Publish Booking for Tracing
Applications integrating Envase Trace will need to publish the booking numbers they want to trace by sending an event to Envase Connect Data. Once the booking number is published, it will be traced at a predetermined intervals according to the business rules.
Note
Booking numbers 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 bookings. 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 booking number more than once. This will not cause an error and will force the trace of the booking number. This, however, it is not recommended. Applications should be implemented to receive the notifications when they happen and not to force bookings to be traced again.
Note
The ability to force a trace on a booking number 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 booking status. Still, client applications should not force the trace during normal operation.
Warning
A forced trace only make sense for bookings traced through a Real-Time Workflow. Booking numbers traced through providers that support other workflows will not be forced to trace.
Sending A Trace Request
Publishing a booking requires the client application to send a request to Envase Connect Data with the information about the booking number to be traced. This request includes information about the booking, the service, 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": "BOOKING",
"action": "TRACE_REQUESTED",
"origin": "provided-by-connect-data",
"payload": {
"id": "the-booking-id",
"siteId": "urn:site",
"providerId": "ictsi",
"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 booking number. The type property must be set to BOOKING 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 booking reference number. It indicates which booking 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 booking. 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.
APM
Publishing a booking id for APM requires the client application to send a request with the information about the booking to be traced. This request should include information about the booking like orgId, svcId, payload.id which represents booking id, the provider id as apm, and terminal code in data.locationCode.
{
"orgId": "3b42ff39-d731-43f6-a8a2-1b257f87469e",
"svcId": "7cd437c3-f25a-4e22-b221-47b6485f140d",
"type": "BOOKING",
"action": "TRACE_REQUESTED",
"origin": "provided-by-connect-data",
"payload": {
"id": "the-booking-id",
"siteId": "urn:site",
"providerId": "apm",
"data": {
"locationCode": "USNWK"
}
}
}
Terminal Name |
Facility Code |
|---|---|
Los Angels terminal |
USLAX |
Port Elizabeth Terminal |
USNWK |
Mobile Terminal |
USMOB |
South Florida Container Terminal Miami |
USMIA |
Important
Credentials are envase based and they are required.
{
"client_id": "enter subscription id",
"client_secret": "enter subscription key",
}
ICTSI
Publishing a booking id for ictsi requires the client application to send a request with the information about the booking to be traced. This request should include information about the booking like orgId, svcId, payload.id which represents booking id, the provider id as ictsi, and terminal code in data.locationCode.
{
"orgId": "3b42ff39-d731-43f6-a8a2-1b257f87469e",
"svcId": "7cd437c3-f25a-4e22-b221-47b6485f140d",
"type": "BOOKING",
"action": "TRACE_REQUESTED",
"origin": "provided-by-connect-data",
"payload": {
"id": "the-booking-id",
"siteId": "urn:site",
"providerId": "ictsi",
"data": {
"locationCode": "SBITC"
}
}
}
Terminal |
Code |
|---|---|
Sub Bay International Terminal Corp. |
SBITC |
Important
Credentials are customer based and they are required.
{
"subscriptionId": "enter subscription id",
"subscriptionKey": "enter subscription key",
}
LBCT
Publishing a booking id for lbct requires the client application to send a request with the information about the booking to be traced. This request should include information about the booking like orgId, svcId, payload.id which represents booking id, and the provider id as lbct.
{
"orgId": "3b42ff39-d731-43f6-a8a2-1b257f87469e",
"svcId": "7cd437c3-f25a-4e22-b221-47b6485f140d",
"type": "BOOKING",
"action": "TRACE_REQUESTED",
"origin": "profit-tools-booking-trace-requested",
"payload": {
"id": "6353167170",
"siteId": "",
"providerId": "lbct",
"data": {}
}
}
Note
Payload doesn’t require any additional information in the data parameter.
Important
Credentials are customer based and they required.
{
"apiKey": "enter api key"
}
Port of Houston
Publishing a booking id for port_houston requires the client application to send a request with the information about the booking to be traced. This request should include information about the booking like orgId, svcId, payload.id which represents booking id, the provider id as port_houston, and terminal code in data.locationCode.
Important
Credentials are customer based and they require
{
"user": "enter user email",
"password": "enter password"
}
Data has to be provided in the request payload for locationCode which represents terminal name.
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": "BOOKING",
"action": "TRACE_REQUESTED",
"origin": "provided-by-connect-data",
"payload": {
"id": "the-booking-id",
"siteId": "urn:site",
"providerId": "port_houston",
"data": {
"locationCode": "PHABC"
}
}
}
Cancel Booking Trace
Client applications might need to cancel a booking number from being traced. To cancel a booking 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": "BOOKING",
"action": "TRACE_CANCELLED",
"origin": "provided-by-connect-data",
"payload": {
"id": "the-booking-id",
"siteId": "urn:site",
"providerId": "ictsi",
}
}
The event structure is similar to the event to publish a booking number, and it uses most of the same properties. The difference is in the action property that will be set to TRACE_CANCELLED.