Passing parameters to background executions and returning responses

You can pass parameters into a background process in the usual way, and use the callParams option in call in the normal way (this allows you to specify, for local calls, whether all the parameters are put into a single "data" parameter). The callbackToken is always passed in the data parameter, and will be merged into any other parameters put into this.

An asynchronous process can return a response in one of two ways:

  • If it uses start/complete, it can return a response by setting the response configuration option on the complete step.
  • If it does not use start/complete, a response written as JSON into the <return> element will be used as the response.

The response is then passed on to the steps following the complete branch of the prepare step.

The anchor step can also provide a callback data option, into which the call data is merged. This allows you to set key information that might be required on the response. data is only used when the callback is created - it will not pick up runtime values in subsequent calls.

[
  {
    "name": "anchor",
    "script": "stepTypeCallback",
    "config": {
      "callbackData": {
        "start": "%{now}",
        "callerRef": "A"
      }
    },
    "next": {
      "create": "call",
      "complete": "complete",
      "*": false
    }
  },
  {
    "name": "call",
    "script": "stepTypeCall",
    "config": {
      "callAction": "start",
      "background": true,
      "callback": true,
      "call": {
        "param1": "value1"
      }
    },
    "next": false
  },
  {
    "name": "complete",
    "script": "stepTypeSet",
    "config": {
      "show": false,
      "createEvent": true,
      "description": "Status %{attr:callbackStatus}",
      "eventOptions": "%{attr:callbackResponse}"
    },
    "next": false
  },
  {
    "name": "start",
    "script": "stepTypeCallback",
    "config": {
      "callbackAction": "start"
    },
    "next": false
  },
  {
    "name": "end",
    "script": "stepTypeCallback",
    "config": {
      "callbackAction": "complete",
      "callbackData": {
        "end": "%{now}",
        "calledRef": "B",
        "param1": "%{param:param1}"
      }
    },
    "next": false
  }
]

In this example:

  • The prepare sets callbackData to include a start timestamp (using the runtime placeholder %{now} and an additional callerRef property). These are just examples - you can put anything in callbackData. The callbackData is only used during callback creation, so the timestamp in this case will always be the start timestamp.
  • The call is passed a "param1" parameter.
  • The end step (within the asynchronous process) sets callback data with an end timestamp, and calledRef and the value of param1.
  • On return to the caller, this is merged with the data from the create. The returned values take precedence.
  • The complete step retrieves this using the callbackData attribute. In this case, the data will be something like 
    {
      "start":"2025-04-15T09:20:01.200",
      "callerRef":"A",
      "end": "2025-04-15T09:20:01.350",
      "calledRef": "B",
      "param1": "value1"
    }
  • The complete step also shows the callback status, using the callbackStatus attribute.

You can change the names of the attributes for the callback response and callback status by setting the dataAttribute and statusAttribute options on the prepare step.