Tracking
Successful Request and message injection results in message(s) being queued internally for further processing, as a result of this approach the Response to a Request is limited to a confirmation that the message has been accepted and queued. Third parties may wish to obtain progress information during or after the processing of a Request. They can do this by calling the Gateway Tracking API.
As with all Gateway APIs and endpoints, the caller must present a valid authentication token (JWT) and have authority to use the tracking endpoint. Calls to the Tracking endpoint will return results based on the Client ID associated with the authenticated token, only.
The tracking HTTP POST message has its own Request and Response body. The Request provide the ability to input advanced search criteria and faciliates the controlling of paging and the size of the results returned. The Response as well as echoing back the search criteria, provides a header (for each matching result) detailing the caller’s Client ID, the Request’s unique identifer and date, as well as a sum of all the messages and their status. The main payload provides the details of each message, its type, status, processed date, as well as details of any issues or errors that occurred.
Unlike other POST Requests, the Tracking endpoint is processed synchronously providing an immediate Response back to the caller.
Request
search - The Tracker API allows the selection of five different filter criteria. Results are only returned if all conditions as met. The default search criteria ( if none provided) is ReceivedDate = today. The tracker Endpoint allow the caller to search based on:
messageType – search for a particular message type code ( Order, Vehicle for example). This can be a collection of different message types
messageStatus – search for messages with a paricular status code ( Failed, Complete for example). This can be a collection of different message status
receivedDate - search for messages received on a particular date or between a date range
id – search for a messages by Request ID. This is the ID generatd by Gateway and delivered in a Response. An ID seach does not require additional search criteria.
externalReference - search for a batch reference provided by the caller in a Request. An externalReference seach does not require additional search criteria.
paging – The Tracker API allows a caller to receive information in a particular order and filter by page. Page filtering is optional, if not provided all found rows will be returned.
sorting – Sorting is optional, with the default sorting for receivedDate = decending
Other sort attributes are processedDate and batchReference
Example – Search by Id with paging of 10 results per page and sorting asending by receivedDate
{
"search": [
{
"by": "id",
"value": [
"78452e72-0fcb-4455-afc3-68fadb22646f"
]
}
],
"paging": {
"number": "1",
"size": "10"
},
"sorts": [
{
"by": "receivedDate",
"order": "78452e72-0fcb-4455-afc3-68fadb22646f"
}
]
}
Example – Search by messageType = Estimate AND messageStatus=Failed OR messageStatus=Complete AND receivedDate BETWEEN 2018-10-01T00:00:00+00:00 AND 2018-10-02T00:00:00+00:00, with paging of 10 results per page, and sorting asending by receivedDate
{
"search": [
{
"by": "messageType",
"value": [ "Estimate" ]
},
{
"by": "messageStatus",
"value": ["Failed", "Complete"]
},
{
"by": "recievedDate",
"value": ["2018-10-01T00:00:00+00:00", "2018-10-02T00:00:00+00:00"]
},
]
}
Response
The tracker response has the same default root elements of; Data, Error and Success as other POST 200 responses. However, the Data attribute differs somewhat in structure, it contains the attributes:
Search – An echo of the search criteria supplied in the request itself
Requests – A collection of individual requests that meet the search criteria identified by
feedId – The caller’s unique B2B identifier in Gateway
clientName - The friendly name assocaited with the caller’s account
id – Gateway’s unique identifier for the request returned in the response of the original request.
batchReference – The caller’s request unique identifer supplied by the caller in the original request
RecievedDate - A date and time when the request was send to Gateway
Each request itself may have multiple messages contained within it. A summary providing totals for each status.
Total – The overall total number of message in a request
Queued – the number of message that are still queued
Processed – the number of message that are processed
Cancelled – the number of messages that are cancelled
Failed – the number of message that failed the import process
Invalid – The number of messages that did not pass validation
Complete – the number of message that have successfully load in to the Gateway platform
Finally, a collection of the found messages inside the request detailing :
ID – The Gateway unique identifier for the message
External Reference – the caller unique identifier for the message
messageStatus – the current status of the message
messageType – the type of gateway entity the message represents ( customer, estimate)
Processed Time – A date and time when the message was process by the Gateway Service
Example - Search for failed Opportunity messages received between 1st and 3rd of Oct 2018. In this case the search found 2 requests, one containing 5 messages, 4 of which completed successfully and one failed. The second request contained 10 messages, 9 of which completed successfully and one failed.