How to run $apply on Android

[f-odhiambo]

We would like to explore ways on which we can run the $apply operation natively on Android to be able to dynamically generate:

1. CarePlan - Describes the intention of how one or more practitioners intend to deliver care for a particular patient, group or community for a period of time, possibly limited to care for a specific condition or set of conditions.
2. Task - A task resource describes an activity that can be performed and tracks the state of completion of that activity. It is a representation that an activity should be or has been initiated, and eventually, represents the successful or unsuccessful completion of that activity.

From either a :

1. ActivityDefiniton - An ActivityDefinition is a shareable, consumable description of some activity to be performed. It may be used to specify actions to be taken as part of a workflow, order set, or protocol, or it may be used independently as part of a catalogof activities such as orderables.
2. PlanDefinition - A plan definition is a pre-defined group of actions to be taken in particular circumstances, often including conditional elements, options, and other decision points. The resource is flexible enough to be used to represent a variety of workflows, as well as clinical decision support and quality improvement assets, including order sets, protocols, and decision support rules.

For the above scenarios, we can have the following mechanisms supported from the FHIR spec
A. Operation $apply on ActivityDefinition can be run using the following on server side (HAPI FHIR) :

1. [base]/ActivityDefinition/$apply
2. [base]/ActivityDefinition/[id]/$apply

In Parameters:

Name	Cardinality	Type	Binding	Profile	Documentation
activityDefinition	0..1	ActivityDefinition			The activity definition to apply. If the operation is invoked on an instance, this parameter is not allowed. If the operation is invoked at the type level, this parameter is required
subject	1..*	string(reference)			The subject(s) that is/are the target of the activity definition to be applied. The subject may be a Patient, Practitioner, Organization, Location, Device, or Group. Subjects provided in this parameter will be resolved as the subject of the PlanDefinition based on the type of the subject. If multiple subjects of the same type are provided, the behavior is implementation-defined
encounter	0..1	string(reference)			The encounter in context, if any
practitioner	0..1	string(reference)			The practitioner in context
organization	0..1	string(reference)			The organization in context
userType	0..1	CodeableConcept			The type of user initiating the request, e.g. patient, healthcare provider, or specific type of healthcare provider (physician, nurse, etc.)
userLanguage	0..1	CodeableConcept			Preferred language of the person using the system
userTaskContext	0..1	CodeableConcept			The task the system user is performing, e.g. laboratory results review, medication list review, etc. This information can be used to tailor decision support outputs, such as recommended information resources
setting	0..1	CodeableConcept			The current setting of the request (inpatient, outpatient, etc.)
settingContext	0..1	CodeableConcept			Additional detail about the setting of the request, if any

Out Parameters:

Name	Cardinality	Type	Binding	Profile	Documentation
return	1..1	Any			The resource that is the result of applying the definitionNote: as this is the only out parameter, it is a resource, and it has the name 'return', the result of this operation is returned directly as a resource

The result of invoking this operation is a resource of the type specified by the activity definition, with all the definitions resolved as appropriate for the type of resource. Any dynamicValue elements will be evaluated (in the order in which they appear in the resource) and the results applied to the returned resource. If the ActivityDefinition includes library references, those libraries will be available to the evaluated expressions. If those libraries have parameters, those parameters will be bound by name to the parameters given to the operation. In addition, parameters to the $apply operation are available within dynamicValue expressions as context variables, accessible by the name of the parameter, prefixed with a percent (%) symbol. For a more detailed description, refer to the ActivityDefinition resource

B. Operation $apply on PlanDefinition can be run using the following urls on server side (HAPI FHIR):

1. [base]/PlanDefinition/$apply
2. [base]/PlanDefinition/[id]/$apply

In Parameters:

Name	Cardinality	Type	Binding	Profile	Documentation
planDefinition	0..1	PlanDefinition			The plan definition to be applied. If the operation is invoked at the instance level, this parameter is not allowed; if the operation is invoked at the type level, this parameter is required
subject	1..*	string(reference)			The subject(s) that is/are the target of the plan to be applied. The subject may be a Patient, Practitioner, Organization, Location, Device, or Group. Subjects provided in this parameter will be resolved as the subject of the PlanDefinition based on the type of the subject. If multiple subjects of the same type are provided, the behavior is implementation-defined
encounter	0..1	string(reference)			The encounter in context, if any
practitioner	0..1	string(reference)			The practitioner applying the plan definition
organization	0..1	string(reference)			The organization applying the plan definition
userType	0..1	CodeableConcept			The type of user initiating the request, e.g. patient, healthcare provider, or specific type of healthcare provider (physician, nurse, etc.)
userLanguage	0..1	CodeableConcept			Preferred language of the person using the system
userTaskContext	0..1	CodeableConcept			The task the system user is performing, e.g. laboratory results review, medication list review, etc. This information can be used to tailor decision support outputs, such as recommended information resources
setting	0..1	CodeableConcept			The current setting of the request (inpatient, outpatient, etc.)
settingContext	0..1	CodeableConcept			Additional detail about the setting of the request, if any

Out Parameters:

Name	Cardinality	Type	Binding	Profile	Documentation
return	1..1	CarePlan			The CarePlan that is the result of applying the plan definitionNote: as this is the only out parameter, it is a resource, and it has the name 'return', the result of this operation is returned directly as a resource

The result of this operation is a CarePlan resource with a single activity represented by a RequestGroup. The RequestGroup will have actions for each of the applicable actions in the plan based on evaluating the applicability condition in context. For each applicable action, the definition is applied as described in the $apply operation of the ActivityDefinition resource, and the resulting resource is added as an activity to the CarePlan. If the ActivityDefinition includes library references, those libraries will be available to the evaluated expressions. If those libraries have parameters, those parameters will be bound by name to the parameters given to the operation. In addition, parameters to the $apply operation are available within dynamicValue expressions as context variables, accessible by the name of the parameter, prefixed with a percent (%) symbol.

[mwkhan1983]

(copied from Francis post on #fhir slack channel)

Prospective CarePlan
A complete view of all of the proposed Activities (Tasks) to be completed for a given patient across all of the pathways they are enrolled in
Is generated by calling $apply on the Pathway (highest level) PlanDefinition

By default would include workflow steps and guideline recommendations => API to filter out workflow tasks (process steps)
Currently not persisted - would be up to implementers to decide
Could be generated at any time and would reflect the Happy Pathway for that patient given all of the known information about the patient

CarePlan of Record
Maintains what has been done and what is proposed between the current and next encounter (in the immediate future i.e. next scheduled and anything in-between)
Has an Activity representing the schedule of the next encounter
May have Activities that are completed between the current and the next encounter (e.g. unscheduled CHW activities)
API to update the single CarePlan of record
Should be able to reflect Activities across different Care Pathways (i.e. single CarePlan for a patient)
As care is delivered over time, the CarePlan of Record builds up .. provides complete history of what happened over the course of the Pathway…
Up to the implementation to decide whether to store workflow tasks OR just recommendation Activities

Intermediate [transient] CarePlan
Point in time next set of proposed Activities in the current encounter. Returns both workflow tasks and recommendation activities
Based on the Activity PlanDefinitions for the current step on the cpg-common-process
Generated at each encounter. Currently based on iterative ‘next step’ model.
Discussed extension to return all of the proposed Tasks for an encounter with relationships defined (for ordering)
User interacts with this (via the app) to consolidate proposals to the CarePlan of Record
In-memory? Representation
Up to implementation to determine what to store

[f-odhiambo]

More on the CarePlan generation is discussed here

From the preliminary research, the CarePlan generation can take two approaches

1. Manual approach - Not advised
2. Automated approach using the $apply operation - run the operation $apply with params $appy(subject) = CarePlan for a patient. The subject(s) that is/are the target of the plan to be applied. The subject may be a Patient, Practitioner, Organization, Location, Device, or Group. Subjects provided in this parameter will be resolved as the subject of the PlanDefinition based on the type of the subject. If multiple subjects of the same type are provided, the behaviour is implementation-defined

The result of this operation is a CarePlan resource with a single activity represented by a RequestGroup. The RequestGroup will have actions for each of the applicable actions in the plan based on evaluating the applicability condition in context. More on this operation as currently implemented here