Aidbox Built-in Tasks

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 that will be in progress until a resource with the specified attributes would be persisted in the database. It is used for some workflow cases when the workflow should wait for resource creation.

Params

Parameter	Type	Required	Description
select-by	string	true	Rule written on subscription trigger rule DSL.

Result

Parameter	Type	Description
resource	object	The resource that triggered the task completion.

Example

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

method: awf.task/create-and-execute
params:
  definition: awf.task/subscribe
  params:
    select-by: 
      - get-in: 
        - resourceType
        comparator: eq
        value: Patient

result:
  resource:
    params:
      select-by:
        - value: Patient
          get-in:
            - resourceType
          comparator: eq
    status: in-progress
    definition: awf.task/subscribe
    retryCount: 1
    id: >-
      ce39265f-3ab0-40c4-b407-b75a45dc2f26
    resourceType: AidboxTask
    meta:
      lastUpdated: '2023-05-24T13:54:04.444841Z'
      createdAt: '2023-05-24T13:54:04.444841Z'
      versionId: '38277'

result:
  resource:
    definition: awf.task/subscribe
    meta:
      lastUpdated: '2023-05-24T13:55:21.134679Z'
      createdAt: '2023-05-24T13:54:04.444841Z'
      versionId: '38406'
    params:
      select-by:
        - value: Patient
          get-in:
            - resourceType
          comparator: eq
    retryCount: 1
    outcome: succeeded
    resourceType: AidboxTask
    status: done
    result:
      resource:
        id: >-
          asdasd
        meta:
          createdAt: '2023-05-24T13:55:21.131777Z'
          versionId: '38405'
          lastUpdated: '2023-05-24T13:55:21.131777Z'
        resourceType: Patient
    id: >-
      ce39265f-3ab0-40c4-b407-b75a45dc2f26

awf.task/wait

Task that will wait for the indicated duration or until the indicated datetime. Used in workflow when need to be paused for some purposes.

Either duration or until parameter SHOULD be specified.

Params

Parameter	Type	Required	Description
duration	object	false	The task will wait for this duration
duration.hours	integer	false	duration value in hours
duration.minutes	integer	false	duration value in minutes
duration.seconds	integer	false	duration value in seconds
until	datetime	false	The task will wait for until this datetime. Need to indicate in string of valid FHIR datetime - `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss+zz:zz` Example: "1905-08-23", "2015-02-07T13:28:17-05:00" or "2017-01-01T00:00:00.000Z"

Result

No result

Example

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

method: awf.task/create-and-execute
params:
  definition: awf.task/wait
  params:
    duration:
      hours: 4
      minutes: 30

result:
  resource:
    params:
      duration:
        hours: 4
        minutes: 30
    status: in-progress
    definition: awf.task/wait
    retryCount: 1
    id: >-
      41ab6e83-fa01-4a25-be56-beafd3ee5744
    resourceType: AidboxTask
    meta:
      lastUpdated: '2023-06-15T12:44:02.740779Z'
      createdAt: '2023-06-15T12:44:02.740779Z'
      versionId: '400'

{1 {:class "text-tint-12"}}

awf.workflow/decision-task

Decision tasks - special tasks that form the body of the workflow and partially execute it in certain iterations. Decision tasks are created when a workflow is started or as a response on another event to decide what action should be taken. Actions are predefined in task execution operations that are used as a response to a completed decision task. Actions are used in certain cases, such as starting a new task.

Decision tasks should also include an event that should represent the purpose of that task as a parameter.

Params

Parameter	Type	Required	Description
event	string	true	Type of event. Example: `awf.workflow.event/workflow-init`
workflow-id	string	false	Id of completed workflow instance. Required only if event type is `awf.workflow.event/workflow-completed`
task-id	string	false	Id of completed task instance. Required only if event type is `awf.workflow.event/task-completed`

Event types

Event type	Description
`awf.workflow.event/workflow-init`	First task execution in the context of the current workflow instance. The decision task contains this event if it was started using the `awf.workflow/create-and-execute` method.
`awf.workflow.event/task-completed`	Reaction to a completed task started by the current workflow. Includes the ID of the completed task instance in the decision task parameters.
`awf.workflow.event/workflow-completed`	Reaction to a completed workflow started by the current workflow. Includes the ID of the completed workflow instance in the decision task parameters.

Result

Parameter	Type	Required	Description
action	string	true	Type of action. Example: `awf.workflow.action/schedule-task`
task-request	object	false	Object with task execution request. Required only if action type is `awf.workflow.action/schedule-task` or `awf.workflow.action/schedule-workflow`
task-request. definition	string	false	Definition of predefined task or custom-defined task. Example: `aidbox.archive/create-archive`
task-request. label	string	false	Human- or machine-readable description of task instance. Should be unique in the context of single workflow. Example: `Import Patient resources`
task-request. params	object	false	The input parameters described in the task or workflow definition.

Action types

Action type	Description
`awf.workflow.action/schedule-task`	Used to schedule the execution of a new task from current workflow. Requires task request object in the response.
`awf.workflow.action/schedule-workflow`	Used to schedule the execution of a new workflow from current workflow. Requires workflow request object in the response.
`awf.workflow.action/do-nothing`	Used to wait until the next event occurs when multiple tasks have been started in parallel, but when some tasks are completed, other tasks are still in progress.
`awf.workflow.action/complete-workflow`	Used when all tasks have been completed to change the status of the workflow instance to `done` with outcome `succeeded`.
`awf.workflow.action/fail`	Used when some tasks have failed to change the status of the workflow instance to `done` with outcome `failed` with handled error.
`awf.workflow.action/unknown-error`	Used when some tasks have failed to change the status of the workflow instance to `done` with outcome `failed` with unknown error.

{1 {:class "text-tint-12"}}

Import resource task

Loading resource in specified format (.gzip or .ndjson) from specified url and persists it into Aidbox database.

Params

Parameter	Type	Required	Description
id	string	false	Identifier of the import. If you don't provide this, the id will be auto-generated. You can check it on `Content-Location` header in the response
contentEncoding	string	false	Supports `gzip` or `plain` (non-gzipped .ndjson files)
input	object	true	Resource to import
input.url	string	true	URL from which load resources
input.resourceType	string	true	Resource type to be loaded
type	string	false	Type of persisted resource Possible values: `fhir`, `aidbox`

Example

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

method: awf.task/create-and-execute
params:
  definition: aidbox.bulk/import-resource-task
  params:
    type: aidbox
    input:
      url: https://storage.googleapis.com/aidbox-public/synthea/100/Organization.ndjson.gz
      resourceType: Organization

result:
  resource:
    params:
      type: aidbox
      input:
        url: >-
          https://storage.googleapis.com/aidbox-public/synthea/100/Organization.ndjson.gz
        resourceType: Organization
    status: ready
    definition: aidbox.bulk/import-resource-task
    id: >-
      102fe9a4-386e-4b66-a01a-7f6c2661e9bd
    resourceType: AidboxTask
    meta:
      lastUpdated: '2023-05-24T13:37:49.615506Z'
      createdAt: '2023-05-24T13:37:49.615506Z'
      versionId: '37424'

result:
  resource:
    definition: aidbox.bulk/import-resource-task
    meta:
      lastUpdated: '2023-05-24T13:37:49.828022Z'
      createdAt: '2023-05-24T13:37:49.615506Z'
      versionId: '37433'
    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
    result:
      imported-resources: 0
    execId: 2748c559-cd78-4005-abc8-b85e5e94b3a4
    id: >-
      102fe9a4-386e-4b66-a01a-7f6c2661e9bd

{1 {:class "text-tint-12"}}

ingestion/map-to-fhir-bundle-task

Task that applies lisp/mapping to the given context and applies the result to the database as a bundle in either fhir or aidbox formats.

Params

Parameter	Type	Required	Description
mapping	string	true	Reference to a defined lisp/mapping.
context	object	true	Initial data.
format	string	true	Bundle format. Possible values: `fhir`, `aidbox`

Example

{ns     my-mappings
 import #{lisp}
 
 my-mapping
 {:zen/tags #{lisp/mapping}
  :mapping  {:resourceType "Bundle"
             :type "transaction"
             :entry [{:resource {:resourceType "Patient"}
                      :request {:method "PUT"
                                :url "/Patient/zero"}}

                     {:resource {:resourceType "Observation"
                                 :status (get :status)
                                 :code {:coding [{:system "http://loinc.org"
                                                  :code "8867-4"
                                                  :display "Respiratory rate"}]
                                        :text "Breathing Rate"}
                                 :subject {:reference "Patient/zero"}
                                 :effectiveDateTime (get-in [:br 0 :dateTime]),
                                 :valueQuantity   {
                                                   :value (get-in [:br 0 :value :breathingRate]),
                                                   :unit "breaths/minute",
                                                   :system "http://unitsofmeasure.org",
                                                   :code "/min"}}
                      :request {:method "POST"
                                :url "/Observation"}}]}}}

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

method: awf.task/create-and-execute
params:
  definition: ingestion.core/map-to-fhir-bundle-task
  params:
    format: fhir
    mapping: my-mappings/my-mapping
    context: 
      br: 
        - value: 
            breathingRate: 17.8
        - dateTime: 2021-10-25
      status: final

result:
  resource:
    params:
      format: fhir
      context:
        br:
          - value:
              breathingRate: 17.8
          - dateTime: '2021-10-25T00:00:00Z'
        status: final
      mapping: aidbox-with-task/my-mapping
    status: ready
    definition: ingestion.core/map-to-fhir-bundle-task
    id: >-
      fd9808c9-29c5-409b-a10f-96d3e28d0039
    resourceType: AidboxTask
    meta:
      lastUpdated: '2023-05-24T12:17:32.528315Z'
      createdAt: '2023-05-24T12:17:32.528315Z'
      versionId: '33349'

result:
  resource:
    definition: ingestion.core/map-to-fhir-bundle-task
    meta:
      lastUpdated: '2023-05-24T12:20:45.742574Z'
      createdAt: '2023-05-24T12:20:45.072825Z'
      versionId: '33546'
    params:
      format: fhir
      context:
        br:
          - value:
              breathingRate: 17.8
          - dateTime: '2021-10-25T00:00:00Z'
        status: final
      mapping: my-mappings/my-mapping
    retryCount: 1
    outcome: succeeded
    resourceType: AidboxTask
    status: done
    result:
      id: >-
        33545
      type: transaction-response
      entry:
        - resource:
            id: >-
              zero
            meta:
              extension:
                - url: http://example.com/createdat
                  valueInstant: '2023-05-24T12:20:45.110149Z'
              versionId: '33542'
              lastUpdated: '2023-05-24T12:20:45.110149Z'
            resourceType: Patient
          response:
            etag: '33542'
            status: '201'
            location: /Patient/zero/_history/33542
            lastModified: '2023-05-24T12:20:45.110149Z'
        - resource:
            id: >-
              8f21674f-e03c-47b4-b952-1e237db99b04
            code:
              text: Breathing Rate
              coding:
                - code: 8867-4
                  system: http://loinc.org
                  display: Respiratory rate
            meta:
              extension:
                - url: http://example.com/createdat
                  valueInstant: '2023-05-24T12:20:45.110149Z'
              versionId: '33544'
              lastUpdated: '2023-05-24T12:20:45.110149Z'
            status: final
            subject:
              reference: Patient/zero
            resourceType: Observation
            valueQuantity:
              code: /min
              unit: breaths/minute
              value: 17.8
              system: http://unitsofmeasure.org
          response:
            etag: '33544'
            status: '201'
            location: /Observation/8f21674f-e03c-47b4-b952-1e237db99b04/_history/33544
            lastModified: '2023-05-24T12:20:45.110149Z'
      resourceType: Bundle
    execId: ae747dd9-6cda-477f-8a83-5f6b18cee94e
    id: >-
      fd9808c9-29c5-409b-a10f-96d3e28d0039

awf.task/clean-up-activities

Deletes AidboxTask, AidboxTaskLog and AidboxWorkflow resources that are in done state according to specified rules.

When the workflow is matched by the rule, all activities requested by that workflow as AidboxTask and AidboxWorkflow would also be deleted. If task is matched by the rule, all it's AidboxTaskLog resources would also be deleted.

When includeDefinitions is specified, only activities with listed definitions will be deleted.
When excludeDefinitions is specified, all activities are deleted except for activities with the listed definitions.
If both includeDefinitions and excludeDefinitions are not specified, deletes all resources that match retentionPolicy.

If multiple rules are listed, all rules are applied.
Can be used with the Scheduler service to automatically clean up old tasks and workflows.

Params

Parameter	Type	Required	Description
rules	object[]	true	Array of cleanup rules. At least 1 rule is required.
rules[].retentionPolicy	object	true	Policy that manages the length of time resources are kept. Resources that are not within this time period will be deleted. Example: `{"unit": "hour", "value": 1}` - means that any resource updated more than 1 hour ago will be deleted.
rules[].retentionPolicy.unit	string	true	Time units. Possible values: `minute`, `hour`, `day`, `week`, `month`, `year`
rules[].retentionPolicy.value	integer	true	Number of time units.
rules[].includeDefinitions	string[]	false	List of task/workflow definitions that would be affected by this rule. Example: `["aidbox.bulk/import-resource-task"]` Exclusive with rules.excludeDefinitions
rules[].excludeDefinitions	string[]	false	List of task/workflow definitions that would be ignored by this rule. In this case, the rule would be applied to all AidboxTask, AidboxTaskLog and AidboxWorkflow resources except the listed definitions. Example: `["aidbox.bulk/import-resource-task"]` Exclusive with rules.includeDefinitions

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

method: awf.task/create-and-execute
params: 
  definition: awf.task/clean-up-activities
  params: 
    rules:
      - retentionPolicy:
          unit: minute
          value: 1
        includeDefinitions:
          - aidbox.bulk/import-resources-workflow

Status: 200

result:
  resource:
    params:
      rules:
        - retentionPolicy:
            unit: minute
            value: 1
          includeDefinitions:
            - aidbox.bulk/import-resources-workflow
    status: ready
    definition: awf.task/clean-up-activities
    id: >-
      e0f2d92d-92eb-4e12-9da8-ef619596fbb9
    resourceType: AidboxTask
    meta:
      lastUpdated: '2023-10-30T13:40:01.071987Z'
      createdAt: '2023-10-30T13:40:01.071987Z'
      versionId: '73542'

definition: awf.task/clean-up-activities
meta:
  lastUpdated: '2023-10-30T13:40:01.097386Z'
  createdAt: '2023-10-30T13:40:01.071987Z'
  versionId: '73549'
params:
  rules:
    - retentionPolicy:
        unit: minute
        value: 1
      includeDefinitions:
        - aidbox.bulk/import-resources-workflow
retryCount: 1
outcome: succeeded
resourceType: AidboxTask
status: done
result:
  deletedRowsCount:
    AidboxTask: 23
    AidboxTaskLog: 124
    AidboxWorkflow: 3
execId: 746092c9-aa5e-43b4-ba8c-baa9d8c288d2
id: >-
  e0f2d92d-92eb-4e12-9da8-ef619596fbb9

aidbox.task/run-sql

Executes the given SQL query. If given is array, executes given as prepared statement.
If the query result is greater than 1000 rows, an error is returned.

Params

Parameter	Type	Required	Description
sql	string or string[]	true	SQL query or prepared statement.

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

method: awf.task/create-and-execute
params: 
  definition: aidbox.task/run-sql
  params: 
    sql:
      - SELECT id FROM Patient WHERE id=? LIMIT 1;
      - 'pt-1'

result:
  resource:
    params:
      sql:
        - SELECT id FROM Patient WHERE id=? LIMIT 1;
        - pt-1
    status: ready
    definition: aidbox.task/run-sql
    id: >-
      ee56dfe3-5853-4da1-bbb2-2405b1d8b0a9
    resourceType: AidboxTask
    meta:
      lastUpdated: '2023-10-31T08:02:05.399463Z'
      createdAt: '2023-10-31T08:02:05.399463Z'
      versionId: '73560'

definition: aidbox.task/run-sql
meta:
  lastUpdated: '2023-10-31T08:02:05.449732Z'
  createdAt: '2023-10-31T08:02:05.399463Z'
  versionId: '73566'
params:
  sql:
    - SELECT id FROM Patient WHERE id=? LIMIT 1;
    - pt-1
retryCount: 1
outcome: succeeded
resourceType: AidboxTask
status: done
result:
  - id: pt-1
execId: 86cb0940-75a1-4d2f-89ca-0a5fe4cbf497
id: >-
  ee56dfe3-5853-4da1-bbb2-2405b1d8b0a9

aidbox.task/run-rpc

Executes the given Aidbox RPC-method with params.

Params

Parameter	Type	Required	Description
method	string	true	Definition of the RPC-method.
params	object	false	Params of the RPC-method.

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

method: awf.task/create-and-execute
params: 
  definition: aidbox.task/run-rpc
  params: 
    method: aidbox.pg/vacuum-table
    params:
      table: patient
      analyze: true

result:
  resource:
    params:
      method: aidbox.pg/vacuum-table
      params:
        table: patient
        analyze: true
    status: ready
    definition: aidbox.task/run-rpc
    id: >-
      374a188d-3f71-4910-82db-c993f174c501
    resourceType: AidboxTask
    meta:
      lastUpdated: '2023-10-31T08:27:11.072779Z'
      createdAt: '2023-10-31T08:27:11.072779Z'
      versionId: '73604'

definition: aidbox.task/run-rpc
meta:
  lastUpdated: '2023-10-31T08:27:11.099924Z'
  createdAt: '2023-10-31T08:27:11.072779Z'
  versionId: '73610'
params:
  method: aidbox.pg/vacuum-table
  params:
    table: patient
    analyze: true
retryCount: 1
outcome: succeeded
resourceType: AidboxTask
status: done
result:
  res:
    - 0
execId: 3a9fdddb-17e2-49a7-ba95-0924cbf96cc6
id: >-
  374a188d-3f71-4910-82db-c993f174c501

aidbox.validation/resource-types-bath-validation-workflow

Executes validation on given table names. Creates a task for every table.

Note: for every broken target resource creates a BatchValidationError resource.

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

method: awf.workflow/create-and-execute
params: 
  definition: aidbox.validation/resource-types-batch-validation-workflow
  params: 
    tables: ['patient', 'observation']

result:
  resource:
    params:
      tables:
        - patient
        - observation
    status: in-progress
    definition: aidbox.validation/resource-types-batch-validation-workflow
    id: >-
      c36e0665-0fe2-4cec-972f-2112716f9233
    resourceType: AidboxWorkflow

result:
  resource:
    params:
      tables:
        - patient
        - observation
    result: Finished
    status: done
    outcome: succeeded
    definition: aidbox.validation/resource-types-batch-validation-workflow
    id: >-
      c36e0665-0fe2-4cec-972f-2112716f9233
    resourceType: AidboxWorkflow

PreviousTask

NextTask Executor API