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[]		An array of task definitions to include.
workflowDefinitions	string[]		An array of workflow definitions to include. In response, decision tasks will be returned for specified workflow if available.
maxBatchSize	integer		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.

Request

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

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

Response

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[]		An array of task definitions to include.
workflowDefinitions	string[]		An array of workflow definitions to include. In response, decision tasks will be returned for specified workflow if available.
maxBatchSize	integer		The number of tasks that can be polled from the queue simultaneously. Default value: 1
timeout	integer		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.

Request

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

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

Response

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		Identifier of the Task resource.
execId	string		Execution id of the task. Used to avoid duplicate task executions.

Result:

Parameter	Type	Description
resource	object	Started AidboxTask resource.

Request

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

Response

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		Identifier of the Task resource.
execId	string		Execution id of the task. Used to avoid duplicate task executions.
notification	string		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		A string message about any additional information.

For progress Notification Type :

Parameter	Type	Required	Description
progress-current	integer		The current value of progress in an integer (The numerator of current / total).
progress-total	integer		The total value of progress in an integer (The dominator of current / total).
progress-unit	string		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.

Request

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"

Response

result:
  inProgressTimeoutAt: '2023-05-05T14:07:27.831585Z'

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		Identifier of the Task resource.
execId	string		Execution id of the task. Used to avoid duplicate task executions.
result	object		Result with which task was succeeded.

Result:

Parameter	Type	Description
resource	object	Succeeded AidboxTask resource.

Request

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

Response

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		Identifier of the Task resource.
execId	string		Execution id of the task. Used to avoid duplicate task executions.
error	object		Error with which task was failed.

Result:

Parameter	Type	Description
resource	object	Failed AidboxTask resource.

Request

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

Response

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