Handling Booking Trace Results

Client applications will be notified of the trace results through the registered web-hooks with Envase Connect Data. The booking trace event will provide the information about the status of the booking, which has the following structure:

{
    "orgId": "organizationId",
    "svcId": "serviceId",
    "type": "BOOKING",
    "action": "TRACE_RESULTS",
    "origin": "trace-booking-<environment>-notify-results",
    "payload": {
        "id": "2139165390",
        "providerId": "lbct",
        "locationCode": "LAX",
        "steamshipLine": "OOLU",
        "vessel": "EVER FRANK",
        "vesselNumber": "9622588",
        "voyage": "1054W",
        "earliestLoading": "2023-03-21T07:00:00.000-07:00",
        "arrived": "2023-02-28T04:48:00.000-08:00",
        "etd": "2023-03-04T05:00:05.000-08:00",
        "eta": "2023-03-03T05:00:05.000-08:00",
        "departed": "2023-03-04T04:18:00.000-08:00",
        "cutoff": "2023-03-28T16:00:00.000-07:00",
        "reeferCutoff": "2023-03-30T02:00:00.000-07:00",
        "oogCutoff": "2023-03-28T12:00:00.000-07:00",
        "hazmatCutoff": "2023-03-27T16:00:00.000-07:00",
        "hazmat": true,
        "reefer": true,
        "oogAllowed": false,
        "totalContainers": 2,
        "loadedContainers": 1,
        "emptyContainers": 1,
        "tracedAt": "2023-03-27T16:00:00.000-07:00",
        "lastProviderUpdate": "2023-02-22T15:31:54.861-08:00",
        "bookingDetails": [
            {
                "temperatureRequired": "-18",
                "containerIso": "22G1",
                "containerDescription": "20ft general",
                "totalContainers": 2,
                "loadedContainers": 1,
                "hazmat": true,
                "reefer": true,
                "oogAllowed": false
            }
        ]
    }
}

The root properties orgId and svcId identify the client application and are used by Envase Connect Data to determine which web-hook will be notified. The type property will be set to BOOKING indicating that is a booking event, and the action will be set to TRACE_RESULT indicating that is a new result for the booking number being traced. As with other events, the origin property is provided by Envase Connect Data and client applications do not need to process that information.

The payload property contains a JSON object with the results of the trace with the following properties:

Name	Type	Description
id	string	The booking number being traced.
providerId	string	Identifier of the provider providing the data.
locationCode	string	Terminal/Rail specific identifier of the location.
steamshipLine	string	Steamship line identifier/SCAC.
vessel	string	Identifier of the vessel.
vesselNumber	string	Reference number for the vessel.
voyage	string	Reference number for the voyage.
earliestLoading	ISO Date/Time	Date/Time when loading starts.
arrived	ISO Date/Time	Date/Time the vessel arrived.
etd	ISO Date/Time	Estimated time to departure.
eta	ISO Date/Time	Estimated time to arrival.
departed	ISO Date/Time	Date/Time the vessel departed.
cutoff	ISO Date/Time	General cargo cutoff date/time.
reeferCutoff	ISO Date/Time	Refrigerated cargo cutoff date/time.
oogCutoff	ISO Date/Time	Out-of-gage cargo cutoff date/time.
hazmatCutoff	ISO Date/Time	Hazmat cargo cutoff date/time.
hazmat	bool	Allows hazardous materials, default is false.
reefer	bool	Allows refrigerated cargo, default is false.
oogAllowed	bool	Allows out of guage freight, default is false.
totalContainers	number	Total number of containers in the booking reservation, default is -1 which means its not provided.
loadedContainers	number	Number of containers that are loaded, default is -1 which means its not provided.
emptyContainers	number	Number of containers that are empty, default is -1 which means its not provided.
tracedAt	ISO Date/Time	Time where the booking was traced.
lastProviderUpdate	ISO Date/Time	Date/Time the provider updated the data.
bookingDetails[n].temperatureRequired	sting	Required temperature for a group of containers.
bookingDetails[n].containerIso	string	Container iso id.
bookingDetails[n].containerDescription	string	Container description.
bookingDetails[n].totalContainers	number	Total number of containers, default is -1 which means its not provided.
bookingDetails[n].loadedContainers	number	Number of loaded containers, default is -1 which means its not provided.
bookingDetails[n].hazmat	bool	Containers has hazardous material, default is false.
bookingDetails[n].reefer	bool	Containers are refrigerated, default is false.
bookingDetails[n].oogAllowed	bool	Containers are out of guage, default is false.

Handling Errors

Client applications will be notified when errors happen. Those errors fall into a couple of categories: trace errors and job failures. The structure of the events for those errors is similar, but client applications might want to handle them differently and take different actions.

Error indicating a job failure will have an action of JOB_FAILED. These errors represent a problem that will prevent all traces through a specific provider or for a specific customer.

As an example, imagine one of the provider APIs is down. Every booking traced through that API will fail because the site is down. A client application might want to notify the user that all their bookings through that site will not be traced because of problems with the provider.

Another example is an invalid credentials problem. Some sites require our customers to provide credentials to log into the provider site. When those credential expire, or are entered wrong, traces will fail until the problem is fixed. A client application will want to notify their users that the credential need to be reset or fixed.

The following is the structure of a JOB_FAILED event:

{
    "orgId":"organizationId",
    "svcId":"serviceId",
    "type":"BOOKING",
    "action":"JOB_FAILED",
    "origin":"trace-booking-etbm-<environment>-send-job-error-event",
    "payload":{
        "siteId":"urn:site",
        "providerId":"providerId",
        "data":{
            "message": "error message"
            //Any additional info we need to add related to the error
            // could be providerId, status_code or any other info
        }
    }
}

Errors that affect a specific booking are represented as trace errors events, and the action property will be set to TRACE_FAILED. These errors represents a problem with a specific booking at a specific trace time and client applications will want to handle them in different ways.

An example will be an error caused by an invalid or incorrect booking number. Client applications will want to notify the user that they should fix the problem and republish the booking for tracing.

The following shows the structure of a TRACE_FAILED event:

{
    "orgId":"organizationId",
    "svcId":"serviceId",
    "type":"BOOKING",
    "action":"TRACE_FAILED",
    "origin":"trace-booking-etbm-<environment>-send-job-error-event",
    "payload":{
        "siteId":"urn:site",
        "providerId":"providerId",
        "id": "bookingId",
        "data":{
            "message": "error message"
            //Any additional info we need to add related to the error
            // could be providerId, status_code or any other info
        }
    }
}