API - Batch Processing
Transaction Support
In a business context it is sometimes necessary to perform several actions in order to complete a single business function - e.g. creating a job, creating a shipment and linking the two entities together.
The Sequoia API service exposes each of the above steps (actions) as a specific request/response in order to provide developers with complete flexibility and therefore relies on the external application to choreograph the complete business function.
In the previous example, you can create a Job without specifying a job reference (whereby Sequoia will automatically allocate a job reference for you and return this in the response).
However, to link the job to the shipment you will need this job reference from the CreateJob
response and the Shipment reference from the CreateShipment
response in order to link the two in the LinkJobToShipment
request.
In order to allow complex business functions to be performed in a single request/response the API service has been extended to include batch processing, whereby a user can invoke a sequence of service requests using a single call to the API.
See BatchProcess
and BatchProcessResponse
for schema details.
In addition, the result (response) of one of these service requests which has been successfully completed can be used (by using XPath to retrieve the data from the response) to replace details of a subsequent service request in the batch.
Therefore, again in the above example, you can retrieve both the job and shipment references from the responses to CreateJob
and CreateShipment
respectively and use the information in the LinkJobToShipment
request.
The following should be noted:
- This batch processing functionality is not restricted to linked service requests; any number of individual unrelated service requests can be included in a batch request.
- A batch is processed from top to bottom, in the order in which individual service requests are specified in the batch.
- Responses to individual service requests within the batch are returned in the
BatchProcessResponse
, in the order in which individual service requests were specified in the batch. - Transaction processing of a batch is supported by specifying a TransactionId in the batch envelope.
- However, although individual service requests which themselves support transaction processing are supported within a batch, you cannot specify an individual TransactionId for these requests.
- For the above reason, the following service requests are not supported directly within a batch:
BeginTransaction
CommitTransaction
RollbackTransaction
- The following service requests are also not supported within a batch:
SendGbDeclaration
SendGbDeclarationCancellation
ProcessBatch