Services

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

Scheduler

The Scheduler is a task-related service. It provides the ability to execute tasks and workflows at defined time intervals. The scheduler is managed by rules that have to determine which and when the activity will be executed, whether it should be forbidden if the same activity is already in progress, and the time for which it should be executed before the execution time comes.

To use the scheduler, you need to describe your rules in zen format and list them in the scheduler service definition.

Rule params

Parameter	Type	Required	Description
schedule	string		A string in cron format that describes how often an activity is executed. Example: ***** (Every minute)
execute-on-setup	boolean		If true, the task will always be started immediately on the first Aidbox start with the new rule. The rule will adhere to the schedule after this. Default: false
concurrency-policy	string		Prohibits the scheduler to start an activity if a similar activity already started has not yet ended when value is forbid. Allows this behavior if the value is allow. Default: forbid
start-deadline-seconds	number		The period of time in which the task can be started after the assigned time in seconds. Default: 60
task-request	map		Definition of the task-request to be performed. Exclusive with workflow-request.
workflow-request	map		Definition of the workflow-request to be performed. Exclusive with task-request.

Rule definition

 archive-every-day
 {:zen/tags #{awf.scheduler/rule}
  :schedule "10 14 * * *"
  :execute-on-setup true
  :concurrency-policy "forbid"
  :start-deadline-seconds 60
  :task-request {:definition aidbox.archive/create-archive
                 :params {:targetResourceType    "AuditEvent"
                          :history               false
                          :criteriaPaths         ["recorded"]
                          :retentionPeriod       {:value  1
                                                  :unit   "day"}
                          :storageBackend        "gcp"
                          :serviceAccount        {:id "my-account"
                                                  :resourceType "GcpServiceAccount"}
                          :bucket                "aidbox-archive-test"
                          :pruneArchivedData     false}}}
 scheduler-service
 {:zen/tags #{aidbox/service}
  :engine awf.scheduler/task-scheduler-service-engine
  :rules #{archive-every-minute}}

This rule describes how to run the audit-events archiving task every day at 14:10. For a full example of how to use the scheduler, see the tutorialautomatically-archive-auditevent-resources-in-gcp-storage-guide.md

Another example of rule definition is automatically delete AidboxTask, AidboxTaskLog and AidboxWrokflow resources with awf.task/clean-up-activities task.

Cleanup rule definition

  cleanup-tasks
  {:schedule "10 14 * * *"
   :concurrency-policy "forbid"
   :start-deadline-seconds 60
   :task-request {:definition awf.task/task-clean-up
                  :params {:rules [{:retentionPolicy {:unit "days" :value 1}}]}}}
  scheduler-service
  {:zen/tags #{aidbox/service}
   :engine awf.scheduler/task-scheduler-service-engine
   :rules #{cleanup-tasks}}

This rule describes how to run the cleanup task that deletes all AidboxTask, AidboxTaskLog, and AidboxWorkflow resources that are older than 1 day every day at 14:10.

Subscription trigger

Subscription trigger is a service that allows you to subscribe to changes in the Aidbox database and perform tasks or workflows described in the rule when the conditions are met.

To use the subscription trigger, you need to describe your rules in zen format and list them in the subscription trigger service definition.

Subscription trigger rule DSL

Subscription trigger rules

Subscription trigger rules use their own DSL to describe subscriptions. A select-by part of the rule may include several expressions and will be considered fulfilled if all expressions are true.

In general every expression is divided into three parts with specified keys:

1. :get-in - describes the path in the modified resource where the left-hand operation argument will be taken. The value must be a vector and contain the path to the value in the nested structure. &#xNAN;Example: :get-in [:name :given]

2. :comparator - the logical operation performed on the arguments. &#xNAN;Possible values: :eq, :gt, :lt, :ge, :le

3. :value - the right-hand argument of the expression. Should be the same type with left argument.

Rule params

Parameter	Type	Required	Description
select-by	vector		Vector of instructions written in the subscription trigger rule DSL. Example: [{:get-in [:resourceType] :comparator :eq :value "Encounter"}]
task-request	map		Definition of the task-request to be performed. Exclusive with workflow-request.
workflow-request	map		Definition of the workflow-request to be performed. Exclusive with task-request.

Rule definition

{ns     my-trigger
 import #{aidbox awf.subscription-trigger ingestion.core lisp}

 observation-bundle-mapping
 {:zen/tags #{lisp/mapping}
  :mapping   {:resourceType "Bundle"
              :type "transaction"
              :entry [{:resource {:resourceType "Encounter"
                                  :subject (get-in [:subject])
                                  :participant (for [p (get-in [:performer])]
                                                       {:individual {:resourceType (get p :resourceType)
                                                                     :id (get p :id)}})
                                  :status "planned"
                                  :class  {:display "Encounter"}}
                                  :request {:method "PUT"
                                            :url "/Encounter"}}]}}

 trigger-on-observation-registered
 {:zen/tags    #{awf.subscription-trigger/rule}
  :select-by    [{:get-in [:resourceType] :comparator :eq :value "Observation"}
                 {:get-in [:status] :comparator :eq :value "registered"}]
  :task-request {:definition ingestion.core/map-to-fhir-bundle-task
                 :params {;; mapping should be a string representation of schema symbol with namespace
                          :mapping "my-trigger/observation-bundle-mapping"
                          :context {:resourceId (get-in [:id])
                          :subject (get-in [:subject])
                          :performer (get-in [:performer])}
  :format "fhir"}}}

subscription-trigger-service
{:zen/tags #{aidbox/service}
 :engine   awf.subscription-trigger/subscription-trigger-service-engine
 :rules    #{trigger-on-observation-registred}}}

This example uses a subscription trigger with ingestion/map-to-fhir-bundle-task. It means that every time an Observation resource is updated with status registered, an Encounter resource is created with the same subject and performer as the participant.