Asynchronous Mutator Transaction Status Callback

When using the API parameter nowait=true, the service requester can submit optional request meta data - containing a callback URL - with any mutator request by appending the request_meta tag to the normal payload of the request.

In order to receive asynchronous transaction status notifications, the requesting system needs to publish an HTTP service to service requests made by the callback URL. An example of a simple http service is provided in a separate section.

The callback operation supports an optional username and password that VOSS-4-UC uses to perform HTTP basic authentication on requests made to the callback service. The optional elements external_id and external_reference are explained in the section on correlation identifiers.

{
   <Actual request data goes here>,
   "request_meta": {
        "external_id": "3x4mpl3-3xtern4l-FF",
        "external_reference": "Example External Reference-FF",
        "callback_url": "http://my.callbackservice:8080",
        "callback_username": "username",
        "callback_password": "password"
     }
}

The following details should be noted here:

• The schema of system resources or system tools do not include reference to the request meta data in the schema definition of each resource in the system.

• The <Actual request data goes here> request data needed to for example add a country_name instance for data/Countries would be similar to: "country_name": "South Africa".

• The request data for deleting two countries for example would be

  "hrefs":[
     "/api/data/Countries/534fdf190dd19012066433ce",
     "/api/data/Countries/534fda1d0dd1901206643397"
  ]
  

• For the callback service to function, the callback service needs to be accessible from the fulfillment server.

Upon completion of the asynchronous mutator transaction posted with a callback URL, VOSS-4-UC POSTs an HTTP request (asynchronous transaction status callback) to the callback service specified by the callback URL. The callback service needs to respond with a HTTP 200 ACK before internal processing of the callback. The callback includes the transaction ID sent to the requesting system as part of the synchronous response. To correlate the asynchronous transaction status callbacks with the original request, the requesting system would need to record the transaction_id returned in the synchronous response.

The HTTP headers and the payload of the asynchronous transaction status callback includes the following information:

HTTP headers:

{
    'accept-encoding': 'identity',
    'authorization': 'BasicdXNlcm5hbWU6cGFzc3dvcmQ=',
    'content-length': '275',
    'content-type': 'application/json',
    'host': 'localhost: 8080'
}

Payload:

{
    "external_id": "3x4mpl3-3xtern4l-FF",
    "external_reference": "ExampleExternalReference",
    "status": "Success",
    "transaction": {
        "href":
          "http: //my.fulfillmentserver/api/tool/
            Transaction/e6ac7c1e-c63a-11e3-9af5-08002791605b/",
        "id": "e6ac7c1e-c63a-11e3-9af5-08002791605b"
    }
}

The following details should be noted here:

• Correlation identifiers (see correlation identifiers) are included in the payload if they are present.
• The status of the transaction is as in the transaction log: Fail or Success.

The transaction status in VOSS-4-UC is not affected by the response of the HTTP service published by the requesting system. The transaction log information includes the callback request and the response returned by the callback service published by the external system.

For transactions with multiple sub-transactions, a single transaction status callback request is made upon the completion of the parent transaction. Transaction status callbacks are not supported for the parent transactions tool/BulkLoad and tool/DataImport.

In the event that the transaction status callback is not received by the external system due to for example a network outage, the external system can poll to retrieve the transaction status. For example:

GET /api/tool/Transaction/e6ac7c1e-c63a-11e3-9af5-08002791605b

Callbacks for failing transactions include error data as part of the callback body/payload. For example:

{u'authorization': 'Basic dXNlcm5hbWU6cGFzc3dvcmQ=',
 u'error': {u'code': 4001,
            u'http_code': 400,
            u'message': u'Error, Duplicate Resource Found.
             data/CallbackDataModel already exists with the following
              unique data - (name = "CallbackDataModel Name 2")'},
 u'external_id': u'3x4mpl3-3xt3rn4l-7d',
 u'external_reference': u'External Ref',
 u'resource': {u'hierarchy': u'542a7347c952703e3646a4c5',
               u'model_type': u'data/CallbackDataModel',
               u'pkid': u'542a7357c952703e3646a4da'},
 u'status': u'Fail',
 u'transaction': {u'href':
  u'http://django.testserver/api/tool/Transaction/844344ee-4881-11e4-a4f9-0800279e955b/',
                   u'id': u'844344ee-4881-11e4-a4f9-0800279e955b'}}

The error data as show in the example, includes:

• the exception code: 4001
• http error code: 400
• error message:

'Error, Duplicate Resource Found. data/CallbackDataModel already
exists with the following unique data - (name = "CallbackDataModel Name 2")'

This is the same error message structure as returned by the API for failing requests.