Links

Task Executor API

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
Response
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[]
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
Response
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
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
Response
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
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
Response
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"
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
Response
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
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
Response
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 modified 5mo ago