Asynchronous Processing

There are many use cases where having the client process wait for a response from the server is not an effective way to operate; e.g. where the server processing can take a long time and potentially cause timeouts somewhere along the HTTP transport network path or where the client wants to schedule tasks to be processed during off hours when the server is most likely to be less busy.

You are able to request that a POST, PATCH or DELETE message should be processed asynchronously. If the resource supports asynchronous processing for the chosen HTTP method, then it will be queued for later processing. If not, it will be processed immediately as per default synchronous processing capabilities. Support for the capability to schedule processing for an arbitrary future time can be managed via Integration Data Queues.

Note:

Only asynchronous deletion of both OrderRelease and OrderBases has been enabled and can be achieved by setting a header parameter "Prefer : respond-async".

Note:

Support for asynchronous operations will be indicated on a resource by resource basis in the Tasks section of this documentation for each release. The resource will show optional support for the "Prefer" HTTP request header parameter containing the value "respond-async".

Note:

Some resources use automatic "recalculation" logic to ensure consistency of certain data. This will be the default logic used for asynchronous messages and so it may appear that the values of some persisted properties are not as they were populated in the inbound message. Synchronous message properties will always be saved as entered and it is the API client's responsibility to ensure data consistency (i.e. functional consistency as opposed to data integrity which is a database schema constraint and is always guaranteed).

For example, the shipments resource has the following calculated properties:
  • "totalActualCost"
  • "numStops"
  • "startTime"
  • "endTime"
  • "sourceLocationGid"
  • "destLocationGid"
  • "dimWeight"
  • "totalPackagingUnitCount"
  • "totalItemPackageCount"
  • "totalNumReferenceUnits"
  • "firstEquipmentGroupGid"
  • "weightUtilization"
  • "volumeUtilization"

To force the values on the inbound message to be used, the "isRecalcTotals" property in the same inbound message must be "false".

There are two main models for how an asynchronous message exchange can take place: Asynchronous with Polling and Asynchronous with Callback. This release currently implements the first of these but both models are described below.

Both models follow a similar basic pattern (assume that the target resource supports asynchronous processing):
  • Processing preference is indicated in a "Prefer" HTTP Header sent to the server.
  • Message body is sent and contains a single resource (See Resource Types).
  • The server stages the message in the transmission tables and raises an internal event to trigger, at some time later, the actual processing of the message. The eventual time of triggering the event depends on the configuration of Integration Data Queues (see the Integration Guide) and on the volume of integration messages handle by the internal event queues.
  • Server responds with a 202 "Accepted" HTTP Status Code.
  • Server returns a "transmissionStatus" resource message body (See Resource Types) and a Location HTTP Header also containing a link to the same status resource.

Once a status resource is returned for a completed message it may contain error details if the process was not successful. The status message also contains a related link (rel="related") to a "transmissionReports" resource which can be used to retrieve any error messages logged by the integration application which was unable to process the message.

Asynchronous REST API messages are processed by the same integration application which handles requests from SOAP web services and the HTTP servlets (see Integration Guide for details). This also means that the Agent Workflow Datasource for the events will be "INTEGRATION" and so any agents listening for asynchronous REST API events should specify this Datasource. Synchronous REST API processing will continue to use the "REST" Datasource and therefore allows agent workflow to be configurable depending on how the event was raised.

Note:

Synchronous REST messages do not publish pre-persist events.

The ID of the transmissionStatus and transmissionReports resource is the Transmission number assigned when staging the message in the transmission tables.

Therefore, the Transmission Manager user interface can also be used to monitor and inspect any asynchronous REST API messages. Synchronous messages are not staged to the transmission tables.

The resource specific Asynchronous processing i.e. targeted to a specific root resource name, only supports a single resource message at present and so only the Transaction record "raw" JSON can be viewed in the Transmission Manager. The Transmission record "raw" JSON is not populated in these cases. See Batch Processing for a description on support for sending a collection of the same or different singular resources in one message.

Asynchronous with Polling

The client requests this model by setting the following HTTP Header: 

Prefer : "respond-async"

In this model the URL for the Status Resource returned in the original request must be polled intermittently to determine if the process is still pending or whether it has completed. Each poll may return an updated Status Resource or if the process is still pending the content will essentially not change.

Asynchronous with Callback

The client requests this model by setting the following HTTP Header:

Prefer : "async-callback; url=https://..."

In this model the "Prefer" Header sent by the client to the server contains a URL that the server should POST a Status Resource back to when the internal processing has completed. The client process also has the option to poll the Status Resource if needed but the main advantage of the Callback is to avoid having to continually poll.