Task Planning Model Overview

This section and the following one describe the Task Planning model in technical detail. Most of the emphasis is on the 'definition' level of expression, with most details of the 'materialised' and 'runtime' expressions left to implementers. Throughout these sections, a version of the Task Planning Visual Modelling Language (TP-VML) is used to illustrate instance structures. This visual language is designed to be formally aligned to the semantics of the model.

The following UML diagram shows the rm.task_planning package in overview form, showing the constituent packages, definition, materialised, and history. The first of these packages contains the class model for the definition model expression of a Work Plan, i.e. the workflow structure intentionally designed to achive a goal.

The materialised package contains the class model of the materialised form of the definition, which is created prior to its use in execution. The materialised model is presented in outline only, as a way of indicating some of the general features of the materialised form, and is not intended to be normative. (At some point in the future, a skeleton materialised model may be declared normative, based on implementation experience).

The history package contains the model of audit events that have occurred to each Task Plan in a Work Plan during execution.

PROC task planning overview
Figure 1. proc.task_planning package overview

The following instance diagram illustrates the relationships among these models for one Task Plan. On the left is a Task Plan definition, consisting of a Task Group and various Defined Actions. Each of these Tasks may have a prototype Entry attached, which represents the intended data of an Action, Observation or other Entry that the Task defines.

In the centre is a materialised Task Plan, which is an execution-time structure used to maintain state for an executing Plan. This structure allows the representation of all state to do with Plan execution, including instances of variables, timing information and so on. The materialised structure is not owned by the definition structure, but rather is created at run time, and points back to its definition via various references. The right hand side of the diagram shows a part of the materialised structure that is currently instantiated within a user-application session.

At the lower right is a Task Plan Execution History, which is a record of all events that were made during the execution of the original Task Plan.

task planning overview
Figure 2. Task planning overview

Identification and Referencing

With a Task Plan, various elements need to be referenceable at runtime. Tasks and Task Groups are identified via the uid attribute inherited from LOCATABLE via PLAN_ITEM, and which is populated with a Guid. References to a Task or Task Group are thus achieved with UID_BASED_ID instances carrying a Guid.

Plan Data Context

TBD: this section needs to be upgraded to latest EL and BMM model. The type EXPR_TYPE_DEF will be replaced by a BMM equivalent.

A Task Plan may contain logical symbolic values of various kinds, including constants, variable references and expressions, which are used in within the Plan structure. These are globally collated and tracked at runtime at the Work Plan level, i.e. in common to all Task Plans. Each context value has a symbolic name (CONTEXT_VALUE.name), a type from within the openEHR type system (EXPR_TYPE_DEF). The following UML diagram illustrates.

PROC task planning.definition context
Figure 3. Task planning - context values

An instance of PLAN_DATA_CONTEXT represents the full set of tracked variables and expressions used in a Work Plan, which are either atomic variables or constants, or else expressions that reference such variables, respectively represented by the classes CONTEXT_VARIABLE<T>, CONTEXT_CONSTANT<T> and CONTEXT_EXPRESSION<T>. These classes and the abstract parent are generic, with the parameter being the formal type of variable or expression.

Context variables are typically related to subject state, such as patient vital signs, key demographic characteristics and so on, or the clinical care process, such as the 'time since stroke event', while expressions are used to represent logical expressions such as $bp_systolic - $bp_diastolic, where $bp_systolic and $bp_diastolic are defined as single variables. The syntax of expressions is defined by the openEHR Expression language.

Two types of context variable are distinguished: external and local, represented by EXTERNAL_VARIABLE<t> and LOCAL_VARIABLE<T>. The former represent values of entities outside the task planning environment, and are written to via a populating_request which uses some method (such as EHR querying, API calls) to obtain the relevant external value. They are accordingly not writable from within the Work Plan.

There are two types of external variables - 'event' and 'state', which distinguish the update basis. An Event variable is 'watched' by some technical means, and its value is updated whenever it changes. The CONTINUOUS_EVENT_VARIABLE specialised type can be used for managing updates of continuous valued variables (i.e. real values) such that changes below a certain threshold, say 2% do not register.

Local variables are internal to the Work Plan, and can be read and written to by expressions used within Tasks in the Plan.

Class Descriptions

PLAN_DATA_CONTEXT Class

  • Definition

Class

PLAN_DATA_CONTEXT

Description

Container for all variable definitions used in the Task Plan.

Attributes

Signature

Meaning

0..1

variables: List<CONTEXT_VARIABLE>

List of all variables tracked by this Plan.

0..1

expressions: List<CONTEXT_EXPRESSION>

List of all expressions used in the Plan, based on tracked variables.

0..1

constants: List<CONTEXT_CONSTANT>

List of all constants used in the Plan.

CONTEXT_VALUE Class

  • Definition

Class

CONTEXT_VALUE<T> (abstract)

Description

Any kind of value used in the Plan definition. Typed by the formal type of the value, i.e. Boolean, Integer etc. The types are represented by EXPR_TYPE_DEF descendants.

Attributes

Signature

Meaning

1..1

name: String

Name of variable, as used in precondition and decision expressions.

1..1

type: T

Type of this variable.

CONTEXT_CONSTANT Class

  • Definition

Class

CONTEXT_CONSTANT<TT>

Description

Definition of a symbolic constant value that can be used in Context Expressions.

Inherit

CONTEXT_VALUE

Attributes

Signature

Meaning

1..1

value: Any

Value of the constant.

CONTEXT_VARIABLE Class

  • Definition

Class

CONTEXT_VARIABLE<TT> (abstract)

Description

Any kind of symbolic variable that can be used within Expressions in the Task Plan, including in pre-conditions and decision pathways.

Inherit

CONTEXT_VALUE

EXTERNAL_VARIABLE Class

  • Definition

Class

EXTERNAL_VARIABLE<TT> (abstract)

Description

A variable that carries a value from the external environment, including patient variables, and has a method of being populated. Cannot be written to from within the TP environment.

Inherit

CONTEXT_VARIABLE

Attributes

Signature

Meaning

0..1

populating_request: SYSTEM_CALL

Optional specification of a system request that would populate a context variable.

LOCAL_VARIABLE Class

  • Definition

Class

LOCAL_VARIABLE<TT>

Description

Variable that is used locally within the Work Plan, and can be used to transmit information to sub-plans.

Inherit

CONTEXT_VARIABLE

EVENT_VARIABLE Class

  • Definition

Class

EVENT_VARIABLE<TT>

Description

Variable whose value is required to be the latest; ideally, updating would be implemented by listener model.

Inherit

EXTERNAL_VARIABLE

CONTINUOUS_EVENT_VARIABLE Class

  • Definition

Class

CONTINUOUS_EVENT_VARIABLE<TT>

Description

Dynamically updated variable of any continuous type whose value may change by arbitrarily small amounts. The update_variation attribute may be used to control updating frequency.

Inherit

EVENT_VARIABLE

Attributes

Signature

Meaning

0..1

update_variation: Real

Minimum percentage variation from current value to be considered a change that should cause an update.

STATE_VARIABLE Class

  • Definition

Class

STATE_VARIABLE<T>

Description

Abstraction of a real-world variable that represents a quality of a subject, e.g. patient diabetic status, date of birth etc.

The generic parameter is a model type from an accessible model.

Attributes

Signature

Meaning

0..1

history: Hash<String,VALUE_SNAPSHOT>

Local history of values.

1..1

name: String

Name of variable.

Functions

Signature

Meaning

1..1

is_available (): Boolean

Return True if there is a value in history.

0..1

unavailable_reason (): String

If is_available is False, potentially provide a reason.

0..1

value (): T

Retrieve latest value, or null if none.

CONTEXT_EXPRESSION Class

  • Definition

Class

CONTEXT_EXPRESSION<TT>

Description

An expression that references one or more context variables. At run time, Context Expressions are updated when changes to their dependent variables are detected.

Inherit

CONTEXT_VALUE

Attributes

Signature

Meaning

1..1

expression: String

Expression, in openEHR Expression syntax.

BOOLEAN_CONTEXT_EXPRESSION Class

  • Definition

Class

BOOLEAN_CONTEXT_EXPRESSION

Description

Boolean-valued form of CONTEXT_EXPRESSION.

Inherit

CONTEXT_EXPRESSION

System Calls

The SYSTEM_CALL class and its descendants provide a way to represent a call to any service or interface available within the computing environment. The class attributes are designed to carry sufficient meta-data such that a call invocation module or plug-in in the Task Planning execution environment can convert the call to a concrete form (e.g. a REST or RPC call) and then execute it.

Generic API calls

The representation of a generic API call is via the API_CALL class, while the QUERY_CALL class provides a way to represent a call to a query service.

For generic API calls, the assumed model of calling is as follows: when the call is invoked, all required parameters are passed; these are obtained from two sources:

  • context values: context values, Work Plan built-in variables (see below);

  • fixed parameters: parameters whose value is fixed from the point of view of the Plan definition.

The first is specified via the parameter_map attribute, which defines the mapping between the external call parameter names and the names of variables that will be used to populate them at invocation. For example, assume there is an API call in a clinical decision support service with the following signature, which is to be used in a Task Plan:

    cds_calc_risk (
        riskType:    String;
        sex:         CodedText;
        dateOfBirth: Iso8601Date;
        isSmoker:    Boolean;
    ): Real

The parameter_map attribute of the SYSTEM_CALL instance will contain the following, where the left hand item in each case is the name of a Work Plan context value (i.e. variable, expression or constant):

    {
        "parameter_map": [
            {"context_name": "subject_sex",        "name": "sex"},
            {"context_name": "subject_dob",        "name": "dateOfBirth"},
            {"context_name": "tobacco_use_status", "name": "isSmoker"}
        ]
    }

This tells the Task Plan execution system to inject the current value of the context variable subject_sex into the location where the sex parameter is expected and so on.

TBD: we may need to allow functions, so that data type/structure conversions can be managed.

The second type of parameter is a fixed value, which enables the System call to represent the external call in a preferred way. An example of this is a general API call such as cds_check (type: String, other_args, …​) might be used from within the Task Plan with the first argument fixed in each case, to form specific invocations, e.g. cds_check ("hypertension risk", other_args, …​), cds_check ("diabetes type 2 risk", other_args, …​) etc. Fixed parameters are represented in the bound_parameters attribute of a SYSTEM_CALL instance.

The total set of parameters for any System call is provided by the combination of the contents of the parameter_map and bound_parameters attributes, where either may be empty.

Query Calls

The above provides for API calls whose signature definition may be more or less anything. For the case of query invocation, some simplifying assumptions can be made, and in the interests of clarity, the QUERY_CALL class is defined for this purpose. A QUERY_CALL instance represents a query invocation which is assumed to take the form of either an ad hoc query or a stored query, with substitutable parameters. accordingly, the external API calls are therefore assumed to take one of the two forms:

    // ad hoc query call
    execute_ad_hoc_query (
        query_text: String;
        parameters: Hash<String, String>;
    ): Result

    // stored query call
    execute_stored_query (
        query_id: String;
        parameters: Hash<String, String>;
    ): Result

In the first case, a query string is supplied; in the second, the registered identifier of a stored query is supplied. In both cases, the substitutable parameters are supplied though the args attribute, which is a keyed list of String values that can be substituted into the replaceable parameters found in the query.

In order to represent an invocation of either of these calls, the parameter_map attribute is used to represent the map between the names of the substitutable parameters in the query and variables from the Work Plan context. Since these are often likely to be the same (almost certainly the case for ad hoc queries), mappings are only required for substitutable variables whose names differ in the query and in the Plan context variable set.

The bound_parameters may be used in a similar fashion, to represent fixed-value substitutable parameters.

As a consequence of this scheme, the total set of replaceable query parameters is specified by the combination of the parameter_map, the bound_parameters and the context variables. In many cases, only the latter may be used.

Class Descriptions

SYSTEM_CALL Class

  • Definition

Class

SYSTEM_CALL (abstract)

Description

Abstract definition of a request to make to a system (i.e. information system or device) via its API, that reads or writes information specific to the Task to which it is attached in an actual Plan.

This could include OS calls, e.g. to launch an application for a certain user.

The formal signature of the call may be referenced via the definition attribute.

Attributes

Signature

Meaning

0..1

parameter_map: List<PARAMETER_MAPPING>

Map of parameter names from system call definition (i.e. argument names) to Work Plan context variable names. This may be partial if there are bound parameters.

1..1

system_id: String

Identifier of target system, typically a domain name.

1..1

call_name: String

Name of call in API.

0..1

definition: @@

Signature definition of call.

TODO: to be defined.

0..1

bound_parameters: List<PARAMETER_DEF>

Parameter values fixed for any invocation of the call. For example, a general call such as cds_check (type: String, other_args, …​) might be used from within the Task Plan in the form cds_check ("hypertension risk", other_args, …​), i.e. the first argument is always fixed.

PARAMETER_DEF Class

  • Definition

Class

PARAMETER_DEF

Description

Specifies a parameter with a name and type from an external API, and a value to be passed for this parameter on call invocation.

Attributes

Signature

Meaning

1..1

name: String

Name of parameter in external API call.

1..1

type: EL_TYPE_DEF

Type of parameter in external API call.

1..1

value: Any

Fixed value to pass on call invocation.

PARAMETER_MAPPING Class

  • Definition

Class

PARAMETER_MAPPING

Description

Mapping of an internal context value name to an external API call parameter name.

Attributes

Signature

Meaning

1..1

name: String

Name of parameter in external API call definition.

1..1

context_name: String

Name of context value definition (i.e. variable, expression, constant, including built-ins) whose value should be passed through as the named parameter on call invocation.

API_CALL Class

  • Definition

Class

API_CALL

Description

Type of System call targetted to a general API, which may by via any concrete technology or protocol. The parameters list will normally consist of heterogeneous types.

Inherit

SYSTEM_CALL

QUERY_CALL Class

  • Definition

Class

QUERY_CALL

Description

Type of System Call that is to a query service, where calls are available for executing ad hoc queries and stored queries. For the ad hoc case, the parameters are of the form:

  • query_text: String

  • query_parameters: Hash<String, String>

while for the stored query case, a query_id would be supplied instead of the query_text: String.

In the context of a Work Plan / Task Plan, query parameters supplied from three places:

  • for substitutable parameters having the same name as context variables, by implicit substitution;

  • for parameters with different names, parameter_map defines the mapping;

  • for fixed parameters, bound_parameters contains the values.

Inherit

SYSTEM_CALL

Attributes

Signature

Meaning

0..1

query_id: String

Identifier of a stored query.

0..1

query_text: String

Ad hoc query text.

Variable Referencing

Within the expressions and System calls used in Task definitions, various variables may be used. These include the context variables described above and built-in variables defined for any Work Plan context, enabling the current Plan, current Task etc to be referred to, for example in a System call. The 'camel-case' and 'snake-case' variants of a variable name are treated as equivalents, i.e. $var_name and $varName refer to the same thing. Among the context variables, some standard defaults are recommended in order to maximise reusability of Task Plan definitions.

Within expressions, defined variables are referenced using the '$' syntax, i.e. $var_name or $varName. Within System calls there are two places where variable references may appear:

  • within the parameters list, to indicate the mapping of a call parameter to a variable defined in the Work Plan context;

  • as lexical inline replaceable parameters within a call parameter that represents an ad hoc query string or similar.

For the first case, the '$' name form is used. In the second case, variables usually appear within query strings in a lexical form that depends on the particular kind of query syntax, i.e. forms such as:

  • $var_name - openEHR AQL;

  • @varName - SQL Server, Oracle, PostGres 9 or later;

  • $[varName] - some SQL implementations.

TBD: do we need another property to record the type of query syntax, e.g. 'aql', 'oracle-sql', or variable syntax, since it is not a SQL standard?

The following table describes the variables available within a typical Work Plan.

Name Type Status Description

Work plan-defined variables

$work_plan_id / $workPlanId

String

Standard

Variable referring to current WORK_PLAN.uid

$task_plan_id / $taskPlanId

String

Standard

Variable referring to current TASK_PLAN.uid

$task_group_id / $taskGroupId

String

Standard

Variable referring to current TASK_GROUP.uid

$task_id / $taskId

String

Standard

Variable referring to current TASK.uid

$subject_id / $subjectId

String

Standard

Variable referring to current WORK_PLAN.subject.external_ref.id.value

Context variables and expressions

$var_name / $varName

Any

Standard

Any variable or expression, e.g. $heart_rate;

$ehr_id / $ehrId

String

Preferred

Variable referring to EHR id of EHR of the subject of the Task Plan

$bp_systolic / $bpSystolic

Real

Preferred

Variable referring to subject current systolic arterial blood pressure

$bp_diastolic / $bpDiastolic

Real

Preferred

Variable referring to subject current diastolic arterial blood pressure

$heart_rate / $heartRate

Real

Preferred

Variable referring to subject current heart rate

Specifying Time

Generic classes for specifying time formally and in customary form such as 'afternoon' are provided for use in the main model. These are shown bottom right of the above UML diagram: TIME_SPECIFIER and descendants.

Class Descriptions

TIME_SPECIFIER Class

  • Definition

Class

TIME_SPECIFIER (abstract)

Description

Abstract parent of types used to specify a point in time during a day.

CLOCK_TIME Class

  • Definition

Class

CLOCK_TIME

Description

A point in time within a day.

Inherit

TIME_SPECIFIER

Attributes

Signature

Meaning

1..1

time: Iso8601_time

Time expressed as a clock time within a day.

CUSTOMARY_TIME Class

  • Definition

Class

CUSTOMARY_TIME

Description

Time specified in some customary way, such as 'morning', 'afternoon', etc, that must be interpreted to determine an equivalent format time.

Resolution to computable times is assumed to be done via call to a service or resource available within the operational environment.

Inherit

TIME_SPECIFIER

Attributes

Signature

Meaning

1..1

time: DV_CODED_TEXT

A coded term expressing a customary time in natural language.

Enumerated Types

Various enumerated types are defined in the definitions package, for use by the definition, materialised and runtime models. The TASK_LIFECYCLE enumeration is included in Lifecycle State.

Class Descriptions

RESUME_TYPE Enumeration

  • Definition

Enumeration

RESUME_TYPE

Description

Enumeration of types of resume behaviour after a callback.

Attributes

Signature

Meaning

resume_specified

Resume at a specified Task in the same thread of control.

retry_current_group

Retry Tasks starting at the top of the current Group.

new_thread

Recommence as a new thread of execution at restart_location.

TEMPORAL_RELATION Enumeration

  • Definition

Enumeration

TEMPORAL_RELATION

Description

Enumeration of relative temporal relations.

Attributes

Signature

Meaning

before

Before a reference event.

with

At the same time as a reference event.

after

After a reference event.

EXECUTION_TYPE Enumeration

  • Definition

Enumeration

EXECUTION_TYPE

Description

Enumeration specifying types of execution for a set of Tasks.

Attributes

Signature

Meaning

sequential

Items execute in order, one after the other.

parallel

Items may be executed in parallel, with no regard to order in the representation.

PLAN_TIME_ORIGIN Enumeration

  • Definition

Enumeration

PLAN_TIME_ORIGIN

Description

Enumeration of types of origin for time offsets within a Work Plan.

Attributes

Signature

Meaning

current_work_plan

Time offset is relative to the moment of activation of the Work Plan within which the offset occurs.

Integer value = 0.

current_task_plan

Time offset is relative to the moment of activation of the Task Plan within which the offset occurs.

Integer value = 1.

inner_repeat_section

Time offset is relative to the moment of activation of the innermost Repeat Section (Task Group or Task with a REPEAT_SPEC) within which the offset occurs.

Integer value = 2.

outer_repeat_section

Time offset is relative to the moment of activation of the outermost Repeat Section (Task Group or Task with a REPEAT_SPEC) within which the offset occurs.

Integer value = 3.