View raw Markdown
type: resourceresource: PlanDefinition

PlanDefinition

Introduction

Scope and Usage

This resource is a definition resource from a FHIR workflow perspective - see Workflow, specifically Definition.

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.

PlanDefinitions can contain hierarchical groups of action definitions, where each action definition describes an activity to be performed (often in terms of an ActivityDefinition resource), and each group defines additional behavior, relationships, and applicable conditions between the actions in the overall definition.

In addition to describing what should take place, each action in a plan definition can specify when and whether the action should take place. For when the action should be taken, the trigger element specifies the action should be taken in response to some trigger occurring (such as a particular point in a workflow being reached, or as the result of a prescription being ordered). For whether the action should be taken, the condition element can be used to provide an expression that evaluates to true or false to indicate the applicability of the action to the specific context.

The process of applying a PlanDefinition to a particular context typically produces request resources representing the actions that should be performed, grouped within a RequestOrchestration to capture relationships between the resulting request resources.

Each ActivityDefinition is used to construct a specific resource, based on the definition of the activity and combined with contextual information for the particular patient that the plan definition is being applied to.

As with the ActivityDefinition, a PlanDefinition may provide information about how to transform the activity to a specific intent resource, either by specifying a StructureMap that can be used to perform the transformation completely, or by specifying values for specific elements of the resulting resource using dynamicValue elements in the action.

Note that these mechanisms are provided on both the ActivityDefinition and the PlanDefinition to allow both reusable transformation descriptions, as well as customization of those descriptions within specific contexts. As such, the transform descriptions specified on the PlanDefinition override transform descriptions defined on the ActivityDefinition.

Dynamic values within the definitions can be provided by specifying the expression directly, or by referencing an expression defined within a library. For more information on how to reference expressions within resources, refer to the Using Expressions topic.

As an example, the Low Suicide Risk example order set from the Clinical Decision Support Knowledge Artifact Specification can be represented using the PlanDefinition and ActivityDefinition structures: Low Suicide Risk Example Order Set.

In addition to the representation of PlanDefinitions, the $apply operation allows PlanDefinitions to be applied to a specific context such as a patient, practitioner, or institution. For Order Sets specifically, this operation is expected to place the orders defined by the order set, consistent with the service functional requirements defined by the Order Set specification.

Plan definitions also allow for the definition of goals. Actions in the plan definition can then reference these goals in order to indicate that the action should be taken in fulfillment of the goal. Note that the goal-relationship extension can be used to describe relationships between goal definitions, and the satisfies-requirement extension can be used to indicate that the goal satisfies a particular requirement.

Boundaries and Relationships

The PlanDefinition resource is used to describe series, sequences, or groups of actions to be taken, while the ActivityDefinition resource is used to define each specific step or activity to be performed.

As the name implies, the PlanDefinition resource is strictly definitional. It does not represent the intention to take any action, nor does it represent that any actions have been taken. Rather, the resource provides a definition that can be applied in the appropriate circumstances. When the plan definition is applied, the result will in general be a set of actions that should be (or potentially even have been) performed.

Note that the PlanDefinition still has action-level information, as well as a reference to an ActivityDefinition. The action-level information defined in the PlanDefinition itself is used to describe how the actions are related to each other within the plan, where the ActivityDefinition contains only information about the activity itself. In addition, there is some overlapping information that allows the resources to be used independently, or in combination. See the Applying a PlanDefinition section for more information.

Background and Context

Provides additional detail on exactly how the resource is to be used

Notes

Applying a PlanDefinition

The following diagram illustrates the relationship between the PlanDefinition and ActivityDefinition resources, as well as a typical realization to RequestOrchestration and Request-pattern resources. The resources depicted on the left side of the arrow are definition resources, while the ones on the right side of the arrow are request resources, with the arrow representing the $apply operation:

relationship-between-action-and-activity-definition

The PlanDefinition and ActivityDefinition resources support the representation of a broad range of use cases including order sets, documentation templates, event-condition-action rules, clinical protocols, and research trials. To support this range of use cases, as well as the variability in capabilities of systems that use these types of artifacts, this specification is not prescriptive about exactly how these definitions are applied to produce request and event resources. However, the approach depicted above provides a general framework for the process, and the following steps provide more detail on the potential approach:

  1. Create a Bundle resource to contain the overall results of the realization.
  2. Create a RequestOrchestration resource focused on the Patient in context and linked to the PlanDefinition using the instantiatesCanonical element
  3. Set the first entry of the Bundle to the newly created RequestOrchestration resource
  4. Create Goal resources based on the goal definitions in the PlanDefinition
  5. Process each action element of the PlanDefinition, in order

Processing for each action proceeds according to the following steps:

  1. Determine applicability by evaluating the applicability conditions defined for the element
  2. If the action is applicable, determine whether the action is a group or a single, atomic activity (does the action have child actions?)
  3. If the action is atomic, process according to the following steps:
    • Create an action element in the RequestOrchestration. If the element has a linkId, set the linkId> element of the new action to the same value. Note that for legacy PlanDefinitions, this action linking was accomplished with the id element, so for backwards compatibility, implementations may set the id element of the newly created action as well.
    • Apply the elements of the action to the corresponding elements of the newly created action in the RequestOrchestration such as title, description, textEquivalent, timing, and so on
    • Carry any start and stop conditions defined in the plan action forward to the request group action.
    • There are multiple possibilities for the definition element:
      • ActivityDefinition:
        1. Create the target resource as described in the Applying an ActivityDefinition topic
        2. Reference the resulting resource in the resource element of the action and add the resource as an entry in the overall result Bundle.
        3. Set the intent of the target resource to option so that it is clearly indicated as part of a RequestOrchestration. Note that the ActivityDefinition/$apply operation will not necessarily produce the resource with this status, so this is an important step.
        4. Apply any overrides based on the elements of the action (see the section on Overlap below for details)
      • PlanDefinition:
        1. Create a RequestOrchestration by applying the target PlanDefinition
        2. Reference the resulting resource in the resource element of the action and add it as an entry in the overall result Bundle.
        3. Set the intent of the RequestOrchestration to option so that it is clearly indicated as part of a RequestOrchestration.
        4. Apply any overrides based on the elements of the action such as title, description, and dynamicValue.
      • Other definitional resource types:
        1. Create a Task resource
        2. Reference the task resource in the resource element of the action and add the resource as an entry in the overall result Bundle.
        3. Set the focus element of the task to the definitional resource.
        4. Set the code element of the task to an appropriate code, such as fulfill.
  4. If the action is a group, determine which actions to process based on the behaviors specified in the group. Note that this aspect of the process may require input from a user. In these cases, either the choices made by the user can be provided as input to the process, or the process can be performed as part of a user-entry workflow that enables user input to be provided as necessary. If no behaviors are specified, default behavior for each behavior element is assumed (i.e. logical-group, all actions apply and are optional, no action is pre-selected, and all actions are assumed singular).

Note that if there is no optionality in the resulting resources, systems may choose to return the request resources directly, rather than organizing them within an overall RequestOrchestration. This means that the result of the operation may be any combination of request Resources, including CarePlan, RequestOrchestration, and individual request resources such as ServiceRequest and MedicationRequest.

The parameters to the $apply operation are available within dynamicValue CQL and FHIRPath expressions as context variables, accessible by the name of the parameter prefixed with a percent (%) symbol. For example, to access the subject given to the apply, use the expression %subject. The value of the %subject context variable in a dynamicValue expression is determined using the current subject, as specified by the subject element on the PlanDefinition, current PlanDefinition.action, or ActivityDefinition.

In addition to the $apply operation parameters, the context variable %action can be used within the path element of a dynamicValue to specify the current action target. For example, to specify the path to the description element of the current action, use %action.description.

In addition, the subject element establishes the context for CQL expressions evaluated during the operation, as discussed in the Evaluation Context discussion in the Using Expressions topic.

Note that result of this operation is transient (i.e. none of the resources created by the operation are persisted in the server, they are all returned as contained resources in the result). The result effectively represents a proposed set of activities, and it is up to the caller to determine whether and how those activities are actually carried out.

Event Resources

The ActivityDefinition resource may only specify Request resource types to facilitate considering user input as part of processing the result of any automated clinical reasoning processes. To support creation of event resources, such as Observations, RiskAssessments, and DetectedIssues, use a Task resource with the focus of the task set to the event resource to be created.

Overlap with ActivityDefinition

As noted in the Boundaries section, there is some overlap between the content that can be represented within the action element of a PlanDefinition, and the elements of the ActivityDefinition resource. This overlap allows for both resources to be used independently, as well as in combination. For example, a PlanDefinition may be used without any supporting ActivityDefinitions to describe a particular workflow, where it is sufficient to describe the actions simply as textual descriptions of what needs to take place. On the other hand, the PlanDefinition may be used together with ActivityDefinition to provide a detailed structural representation of the activities to be performed.

In general, where there is overlap, the elements from the PlanDefinition provide overriding behavior. Specifically, the following elements of action overlap with ActivityDefinition:

ElementBehavior
titleThe title element in ActivityDefinition is the title of the activity "as defined", where the title element in PlanDefinition reflects the title in the scope of the plan.
descriptionThe description element in ActivityDefinition is the description of the activity "as defined", where the description element in PlanDefinition reflects the description in the scope of the plan.
codeThe code element in ActivityDefinition represents the meaning of the activity "as defined", where the code element in PlanDefinition represents the meaning in the scope of the plan.
documentationThe documentation element in PlanDefinition represents additional documentation for the action specific to the scope of the plan, where the relatedArtifact element in ActivityDefinition provides documentation specific to the activity itself.
timingThe timing element in ActivityDefinition represents timings associated within the activity itself, where the timing element in PlanDefinition represents the timing of the activity with respect to the plan and its other actions. When a timing is provided on both, the timing defined in the plan generally takes precedence.
asNeededThe asNeeded element allows pre-conditions to be associated with an action or activity. When asNeeded is specified on both, the value specified in the plan generally takes precedence.
participantThe participant element in ActivityDefinition represents what type of actor is expected to perform the activity generally, where the participant element in PlanDefinition represents the type of actor that is expected to perform the activity in the context of the plan.
transformThe transform element in ActivityDefinition describes the transformation of the definition to a request or event resource in general, where the transform element in PlanDefinition describes the transformation within the scope of the plan. When a transform is present in both, the transform in the plan takes precedence.
dynamicValueThe dynamicValue element in ActivityDefinition defines values for elements of the target request or event resource in general, where the dynamicValue element in PlanDefinition defines values within the scope of the plan. When dynamic values are present in both, the dynamic values from the ActivityDefinition are applied first (in the order in which they appear on the ActivityDefinition), followed by the dynamic values from the PlanDefinition (in the order in which they appear on the PlanDefinition).

StructureDefinition

Elements (Simplified)

Mappings

Operations

Full Operations

Resource Packs

list-PlanDefinition-packs.xml

<?xml version="1.0" encoding="UTF-8"?>

<List xmlns="http://hl7.org/fhir">
  <id value="PlanDefinition-packs"/>
  <status value="current"/>
  <mode value="working"/>
</List>

Search Parameters

Full Search Parameters

Examples

Full Examples

Mapping Exceptions

plandefinition-definition-mapping-exceptions.xml

Divergent Elements

The determination of when to create a new version of a resource (same url, new version) vs. defining a new artifact is up to the author. Considerations for making this decision are found in Technical and Business Versions.

In some cases, the resource can no longer be found at the stated url, but the url itself cannot change. Implementations can use the meta.source element to indicate where the current master source of the resource can be found. | resource=Can be a urn:uuid: or a urn:oid: but real http: addresses are preferred. Multiple instances may share the same URL if they have a distinct version.

The determination of when to create a new version of a resource (same url, new version) vs. defining a new artifact is up to the author. Considerations for making this decision are found in Technical and Business Versions.

In some cases, the resource can no longer be found at the stated url, but the url itself cannot change. Implementations can use the meta.source element to indicate where the current master source of the resource can be found.

Unknown does not represent 'other' - one of the defined statuses must apply. Unknown is used when the authoring system is not sure what the current status is. | resource=Allows filtering of plan definitions that are appropriate for use versus not.

See guidance around (not) making local changes to elements here.

DEPRECATION NOTE: For consistency, implementations are encouraged to migrate to using the new 'jurisdiction' code in the useContext element. (I.e. useContext.code indicating http://terminology.hl7.org/CodeSystem/usage-context-type#jurisdiction and useContext.valueCodeableConcept indicating the jurisdiction.). | resource=It may be possible for the plan definition to be used in jurisdictions other than those for which it was originally designed or intended.

DEPRECATION NOTE: For consistency, implementations are encouraged to migrate to using the new 'jurisdiction' code in the useContext element. (I.e. useContext.code indicating http://terminology.hl7.org/CodeSystem/usage-context-type#jurisdiction and useContext.valueCodeableConcept indicating the jurisdiction.)

See guidance around (not) making local changes to elements here.

Unmapped Elements

plandefinition-fivews-mapping-exceptions.xml

Unmapped Elements