Task Executor API

Workflow engine is configured by zen. We do not support it and do not recommend to use it anymore. Please, use any other workflow engine e.g. Temporal .

Since the 2405 release, using Aidbox in FHIR schema validation engine is recommended, which is incompatible with zen or Entity/Attribute options.

Setup Aidbox with FHIR Schema validation engine

Task Executor API is designed to allow implement task executor in any programming language and use it in Aidbox via REST requests with RPC calls.

`awf.task/poll`

Fetches a task in the status ready from the queue and changes its status to requested.

Immediately returns an empty array if there are no tasks in the queue.

Either taskDefinitions or workflowDefinitions parameter SHOULD be specified.

Params:

Parameter	Type	Required	Description
taskDefinitions	string[]	false	An array of task definitions to include.
workflowDefinitions	string[]	false	An array of workflow definitions to include. In response, decision tasks will be returned for specified workflow if available.
maxBatchSize	integer	false	The number of tasks that can be polled from the queue simultaneously. Default value: 1

Result:

Parameter	Type	Description
resources	object[]	AidboxTask resources with `execId`.

POST /rpc
content-type: text/yaml
accept: text/yaml

method: awf.task/poll
params:
    taskDefinitions: [aidbox.bulk/import-resource-task]

result:
  resources:
    - execId: ea5c0022-c1e7-4f3c-b1ed-7e9b2428b7d2
      params:
        type: aidbox
        input:
          url: >-
            https://storage.googleapis.com/aidbox-public/synthea/100/Organization.ndjson.gz
          resourceType: Organization
      status: requested
      executeAt: '2023-05-04T15:30:43'
      definition: aidbox.bulk/import-resource-task
      id: >-
        819c2499-1303-4c0e-bf1e-bcca761bfbde
      resourceType: AidboxTask
      meta:
        lastUpdated: '2023-05-04T16:33:14.682354Z'
        createdAt: '2023-05-04T16:33:12.056223Z'
        versionId: '17633'

`awf.task/long-poll`

Fetches a task in the status ready from the queue and changes its status to requested.

Waits for a timeout unless a new task is received. In case of timeout, returns an empty array.

Either taskDefinitions or workflowDefinitions parameter SHOULD be specified.

Params:

Parameter	Type	Required	Description
taskDefinitions	string[]	false	An array of task definitions to include.
workflowDefinitions	string[]	false	An array of workflow definitions to include. In response, decision tasks will be returned for specified workflow if available.
maxBatchSize	integer	false	The number of tasks that can be polled from the queue simultaneously. Default value: 1
timeout	integer	false	A period of time in ms, the period of time during which the tasks can be polled. Default value: 60000 (equal to 1 minute)

Result:

Parameter	Type	Description
resources	object[]	AidboxTask resources with `execId`.

POST /rpc
content-type: text/yaml
accept: text/yaml

method: awf.task/long-poll
params:
    timeout: 50000
    taskDefinitions: [aidbox.bulk/import-resource-task]

result:
  resources:
    - execId: ea5c0022-c1e7-4f3c-b1ed-7e9b2428b7d2
      params:
        type: aidbox
        input:
          url: >-
            https://storage.googleapis.com/aidbox-public/synthea/100/Organization.ndjson.gz
          resourceType: Organization
      status: requested
      executeAt: '2023-05-04T15:30:43'
      definition: aidbox.bulk/import-resource-task
      id: >-
        819c2499-1303-4c0e-bf1e-bcca761bfbde
      resourceType: AidboxTask
      meta:
        lastUpdated: '2023-05-04T16:33:14.682354Z'
        createdAt: '2023-05-04T16:33:12.056223Z'
        versionId: '17633'

`awf.task/start`

Changes the status of a task from requested to in-progress and start its execution.

The required param of execId is supposed to be received from the requestawf.task/poll or awf.task/long-poll.

Params:

Parameter	Type	Required	Description
id	string	true	Identifier of the Task resource.
execId	string	true	Execution id of the task. Used to avoid duplicate task executions.

Result:

Parameter	Type	Description
resource	object	Started AidboxTask resource.

POST /rpc
content-type: text/yaml
accept: text/yaml

method: awf.task/start
params:
    id: c578a224-c1fa-44c1-bc7a-9d2e624b872b
    execId: aac4c869-daa4-45fb-917a-46fe14359ed4

result:
  resource:
    definition: aidbox.bulk/import-resource-task
    meta:
      lastUpdated: '2023-05-05T13:40:38.088195Z'
      createdAt: '2023-05-05T09:37:41.786909Z'
      versionId: '128518'
    params:
      type: aidbox
      input:
        url: >-
          https://storage.googleapis.com/aidbox-public/synthea/100/Organization.ndjson.gz
        resourceType: Organization
    retryCount: 1
    resourceType: AidboxTask
    status: in-progress
    execId: aac4c869-daa4-45fb-917a-46fe14359ed4
    id: >-
      c578a224-c1fa-44c1-bc7a-9d2e624b872b

`awf.task/notify`

Notifies Task Service that a task is still alive.

After receiving notification, Task Service creates AidboxTaskLog resource with values of extra params fields below.

Notification Types:

Notification Type	Description
`heartbeat`	Prolongs the `inProgressTimeout` property of the task and sends a string message.
`progress`	Prolongs the `inProgressTimeout` property of the task and sends information about its progress.

Params:

Parameter	Type	Required	Description
id	string	true	Identifier of the Task resource.
execId	string	true	Execution id of the task. Used to avoid duplicate task executions.
notification	string	true	The type of notification depends on which extra parameters may be required. Possible values: `heartbeat`, `progress`

Extra Params

Depending on the #notification-types, the following params are needed.

These parameters with notification type will be recorded in AidboxTaskLog resource after handling API request.

For `heartbeat` Notification Type :

Parameter	Type	Required	Description
message	string	false	A string message about any additional information.

For `progress` Notification Type :

Parameter	Type	Required	Description
progress-current	integer	true	The current value of progress in an integer (The numerator of `current / total`).
progress-total	integer	false	The total value of progress in an integer (The dominator of `current / total`).
progress-unit	string	false	The unit for the values of `progress-total` and `progress-current`. Example: `rows`

Result:

Parameter	Type	Description
inProgressTimeoutAt	integer	The renewed `inProgressTimeout` property of the task.

POST /rpc
content-type: text/yaml
accept: text/yaml

method: awf.task/notify
params:
    id: 3abf82be-ec63-4fb4-908a-21d91b2d4af9
    execId:   292e9f34-c275-4cd3-840f-b4c39d0512e4
    notification: awf.task/heartbeat
    message: "task is alive"

`awf.task/success`

Changes the status of a task from in-progress to done, setting the outcome to succeeded.

Params:

Parameter	Type	Required	Description
id	string	true	Identifier of the Task resource.
execId	string	true	Execution id of the task. Used to avoid duplicate task executions.
result	object	false	Result with which task was succeeded.

Result:

Parameter	Type	Description
resource	object	Succeeded AidboxTask resource.

POST /rpc
content-type: text/yaml
accept: text/yaml

method: awf.task/success
params:
    id: c578a224-c1fa-44c1-bc7a-9d2e624b872b
    execId: aac4c869-daa4-45fb-917a-46fe14359ed4

result:
  resource:
    definition: aidbox.bulk/import-resource-task
    pool: awf.executor/aidbox-long-tasks-pool2
    meta:
      lastUpdated: '2023-05-05T13:41:20.628857Z'
      createdAt: '2023-05-05T09:37:41.786909Z'
      versionId: '128521'
    params:
      type: aidbox
      input:
        url: >-
          https://storage.googleapis.com/aidbox-public/synthea/100/Organization.ndjson.gz
        resourceType: Organization
    retryCount: 1
    outcome: succeeded
    resourceType: AidboxTask
    status: done
    execId: aac4c869-daa4-45fb-917a-46fe14359ed4
    id: >-
      c578a224-c1fa-44c1-bc7a-9d2e624b872b

`awf.task/fail`

Changes the status of a task from in-progress to done, setting the outcome to failed.

Params:

Parameter	Type	Required	Description
id	string	true	Identifier of the Task resource.
execId	string	true	Execution id of the task. Used to avoid duplicate task executions.
error	object	false	Error with which task was failed.

Result:

Parameter	Type	Description
resource	object	Failed AidboxTask resource.

POST /rpc
content-type: text/yaml
accept: text/yaml

method: awf.task/fail
params:
    id: 7572b48b-7196-4887-bab7-a78bf09bdd83
    execId: d9bdbaa7-35ee-4234-a603-990a6a5dd559

result:
  resource:
    definition: aidbox.bulk/import-resource-task
    meta:
      lastUpdated: '2023-05-05T14:15:49.658083Z'
      createdAt: '2023-05-05T14:12:52.899952Z'
      versionId: '128620'
    params:
      type: aidbox
      input:
        url: >-
          https://storage.googleapis.com/aidbox-public/synthea/100/Organization.ndjson.gz
        resourceType: Organization
    retryCount: 2
    outcome: failed
    resourceType: AidboxTask
    status: done
    execId: d9bdbaa7-35ee-4234-a603-990a6a5dd559
    id: >-
      7572b48b-7196-4887-bab7-a78bf09bdd83
    outcomeReason:
      type: awf.task/failed-by-executor
      message: Failed by executor

Last updated: 2025-05-12T17:04:33Z

awf.task/poll

Params:

Result:

awf.task/long-poll

Params:

Result:

awf.task/start

Params:

Result:

awf.task/notify

Notification Types:

Params:

Extra Params

For heartbeat Notification Type :

For progress Notification Type :

Result:

awf.task/success

Params:

Result:

awf.task/fail

Params:

Result:

`awf.task/poll`

`awf.task/long-poll`

`awf.task/start`

`awf.task/notify`

For `heartbeat` Notification Type :

For `progress` Notification Type :

`awf.task/success`

`awf.task/fail`