Handling Container Export and Empty Results

Handling Container Export Results

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

{
     "orgId": "3b42ff39-d731-43f6-a8a2-1b257f87469e",
     "svcId": "7cd437c3-f25a-4e22-b221-47b6485f140d",
     "type": "CONTAINER",
     "action": "TRACE_EXPORT_RESULT",
     "payload": {
         "id": "CONT123456",
         "description": "TBD",
         "length": "40",
         "tracedAt": "2021-07-26T11:00",
         "events": [
             {
                 "code": "appointment-ready",
                 "eventDate": "2021-07-26T10:56:22.240572",
                 "location": {
                     "type": "site-type",
                     "siteId": "site-id-when-ready",
                     "name": "friendly-name-for-site"
                 },
                 "data": {
                     "readyForAppointment": true
                 }
             },
             {
                 "code": "completed",
                 "eventDate": "2021-07-26T10:56:22.240572",
                 "location": {
                     "type": "site-type",
                     "siteId": "site-id-when-ready",
                     "name": "friendly-name-for-site"
                 },
                 "data": {}
             }
         ]
     }
 }

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 CONTAINER indicating that is a container event, and the action will be set to TRACE_EXPORT_RESULT indicating that is a new result for the container 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 structure is similar to container availibility trace results, but the event that will only ever appear on the payload will be the appointment-ready and completed event.

Handling Container Empty Results

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

{
    "orgId": "3b42ff39-d731-43f6-a8a2-1b257f87469e",
    "svcId": "7cd437c3-f25a-4e22-b221-47b6485f140d",
    "type": "CONTAINER",
    "action": "TRACE_EMPTY_RESULT",
    "payload": {
        "id": "CONT123456",
        "description": "TBD",
        "length": "40",
        "tracedAt": "2021-07-26T11:00",
        "events": [
            {
                "code": "appointment-ready",
                "eventDate": "2021-07-26T10:56:22.240572",
                "location": {
                    "type": "site-type",
                    "siteId": "site-id-when-ready",
                    "name": "friendly-name-for-site"
                },
                "data": {
                    "readyForAppointment": true
                }
            },
            {
                "code": "completed",
                "eventDate": "2021-07-26T10:56:22.240572",
                "location": {
                    "type": "site-type",
                    "siteId": "site-id-when-ready",
                    "name": "friendly-name-for-site"
                },
                "data": {}
            }
        ]
    }
}

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 CONTAINER indicating that is a container event, and the action will be set to TRACE_EMPTY_RESULT indicating that is a new result for the container 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 structure is similar to container availibility trace results, but the event that will only ever appear on the payload will be the appointment-ready and completed event.

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_EXPORT_FAILED or JOB_EMPTY_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 container traced through that API will fail because the site is down. A client application might want to notify the user that all their containers 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_EXPORT_FAILED event:

{
    "orgId": "3b42ff39-d731-43f6-a8a2-1b257f87469e",
    "svcId": "7cd437c3-f25a-4e22-b221-47b6485f140d",
    "type":"CONTAINER",
    "action":"JOB_EXPORT_FAILED",
    "origin":"trace-container-etbm-<environment>-send-job-error-event",
    "payload":{
        "siteId":"urn:site",
        "providerId":"ictsi",
        "data":{
            "message": "error message"
            //Any additional info we need to add related to the error
            // could be providerId, status_code or any other info
        }
    }
}

The following is the structure of a JOB_EMPTY_FAILED event:

{
    "orgId": "3b42ff39-d731-43f6-a8a2-1b257f87469e",
    "svcId": "7cd437c3-f25a-4e22-b221-47b6485f140d",
    "type":"CONTAINER",
    "action":"JOB_EMPTY_FAILED",
    "origin":"trace-container-etbm-<environment>-send-job-error-event",
    "payload":{
        "siteId":"urn:site",
        "providerId":"ictsi",
        "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 container tracer are represented as trace errors events, and the action property will be set to TRACE_EXPORT_FAILED or TRACE_EMPTY_FAILED. These errors represents a problem with a specific container 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 container number. Client applications will want to notify the user that they should fix the problem and republish the container for tracing.

The following shows the structure of a TRACE_EXPORT_FAILED event:

{
    "orgId": "3b42ff39-d731-43f6-a8a2-1b257f87469e",
    "svcId": "7cd437c3-f25a-4e22-b221-47b6485f140d",
    "type": "CONTAINER",
    "action": "TRACE_EXPORT_FAILED",
    "origin": "ett-<environment>-send-job-error-event",
    "payload":{
        "siteId":"urn:site",
        "providerId":"ictsi",
        "id": "123456789",
        "data":{
            "message": "Container not found"
        }
    }
}

The following shows the structure of a TRACE_EMPTY_FAILED event:

{
    "orgId": "3b42ff39-d731-43f6-a8a2-1b257f87469e",
    "svcId": "7cd437c3-f25a-4e22-b221-47b6485f140d",
    "type": "CONTAINER",
    "action": "TRACE_EMPTY_FAILED",
    "origin": "ett-<environment>-send-job-error-event",
    "payload":{
        "siteId":"urn:site",
        "providerId":"ictsi",
        "id": "123456789",
        "data":{
            "message": "Container not found"
        }
    }
}