Callback processing - advanced

Callback options

The callback step provides a few additional options.

  • callbackRetention can be used to control the cleanup process. By default, callback information can automatically be removed one hour after the process is inactive. Set retention to true to keep the callback indefinitely, or to an ISO 8601 duration (such as "PT24H" for one day). Do not set to true for permanent reused processes (such as a group or control process) as the callbacks will not be cleaned up.

Output attributes

The callback step creates multiple attributes, the names of which can be overridden. These are described below.

Attribute

Descriptions

 Config option to override name
callbackToken

For create, the callback token that has been created.

In other cases, the callback token passed into the step.

 tokenAttribute
callbackParentToken

The callback token of the parent.

 parentTokenAttribute
callbackData

The response data. This is a merge of the following, where the later items override the earlier ones.

  • The createData option set when the callback was created.
  • When called as callback, the data propery of the data parameter.
 dataAttribute
callbackId

The internal id used to identify the callback. This can be useful to managing other data associated with the callback.

 idAttribute
callbackStatus

The status of the current callback.

 statusAttribute
n/a

The full response object, which is of the form:

{
  "status": "status",
  "token": "token",
  "data": {
    // Callback data
  }
}

This follows the same pattern as other steps (such as evaluate) which use attributeReference for the full callback response, but only if the configuration option attributeReference is set.

 attributeReference

State mapping

You can use the next states active and error as a default for other states.

  • active can be used in place of create, accept, start, progress and exists
  • error can be used in place of timeout, orphan, notFound and cancel (as well as for error).

This means that you can just use the three states - error, active and cancel - in place of the detailed status-based states, but use the more detailed states where required.

Multi-threading

Multiple calls may be made to the same process worker (or group), and these calls (or the background executions they initiate) may be active at the same time. Some care is required where this may be the case:

  • Do not use specific data area for callbacks that might be multi-threaded. The response store provides a suitable storage area for each callback.
  • You may use parameters and attributes, as these are per-thread, and not global to the worker.
  • The store of callback information is held in the worker node's user data. For very intensive use, there is a possibility of contention, i.e. one call might overwrite the updates of another. However, the chances of this are very small indeed and should not pose a problem to most solutions.

Integrating with external services

It is possible for external services to integrate with the asynchronous processing. It most cases it will be easiest to have a stub process that is passed a token and which can perform the next action. However, for direct integration, it is possible to call the callback step (i.e. the step that performed the prepare) directly.

To do this, you need to know what node and action to perform, and to format a response appropriately. The token is a base64-encoded JSON object, with node and anchor properties, where anchor the process step to invoke on callback (i.e. the action parameter).

To find the node and anchor step to which to send the callback, extract the node and anchor from the token.

You can then execute the node, passing in the data parameter a structure of the form:

{
  "type": "CALLBACK",
  "callbackToken": "token",
  "callbackStatus": "status",
  "callbackData": {
    // Response data
  }
}

status must be one of start, progress, complete, cancel or error.

The response will be returned in the <return> element from the call. It will have the same format, without the "type" property, though it may be been modified by following steps in the process.

You can also query the current state of the callback by using a callbackAction of "getCallback".

{
  "type": "CALLBACK",
  "callbackToken": "token",
  "callbackAction": "getCallback"
}

This will return an object with token, status and data, like the other callback.

The Dispatch Callback Service provides a simplified, call-in point for external services.