Asynchronous Mutator Transaction Status Callback
------------------------------------------------

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

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 Automate|
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"
         }
    }

Note the following details:

* 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 Automate| 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"
        }
    }




Note the following details:

* 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 Automate| 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'}}

Error data, as shown 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.




.. |VOSS Automate| replace:: VOSS Automate
.. |Unified CM| replace:: Unified CM