Clinical Protocols
In FHIR, care workflows and clinical protocols are primarily modeled using the PlanDefinition resource.
While a CarePlan represents a concrete plan for a specific patient, a PlanDefinition represents the abstract protocol that can be applied to any patient.
At its core, a PlanDefinition contains a list of action elements, where each action represents a specific step in the workflow. The action element is extremely expressive and allows for incredibly rich workflow logic.
Basic Sequential Tasks
At its most basic level, a PlanDefinition is just a simple list of sequential tasks. You can define the task details directly inline:
{
"resourceType": "PlanDefinition",
"status": "active",
"title": "Basic Onboarding Protocol",
"action": [
{
"title": "Schedule Initial Consult",
"description": "Call patient to schedule their first appointment."
},
{
"title": "Send Welcome Packet",
"description": "Email the welcome packet and intake forms."
}
]
}
Reusable Definitions (ActivityDefinition & Questionnaire)
Instead of defining all task details inline, actions often reference standalone, reusable definition resources using the definitionCanonical element. This allows you to maintain a single source of truth for common clinical activities across multiple protocols.
ActivityDefinition
An ActivityDefinition is a template for a specific clinical act, such as ordering a lab test, prescribing a medication, or performing a procedure.
When an action references an ActivityDefinition, the protocol inherits its properties. Furthermore, the ActivityDefinition.kind element tells the system what type of resource to generate when the protocol is executed:
- If
kindis set toServiceRequest, executing the protocol will generate a draftServiceRequestresource (copying over thecode,intent, etc.) alongside theTask, and link them together. - If
kindis set toTask(or left blank), it will simply generate aTask.
// The PlanDefinition represents the overall protocol
{
"resourceType": "PlanDefinition",
"status": "active",
"action": [
{
"title": "Order HbA1c Test",
// This canonical URL links the action to the ActivityDefinition below
"definitionCanonical": "http://example.org/ActivityDefinition/hba1c-order"
}
]
}
// The ActivityDefinition is a reusable template for the specific lab order
{
"resourceType": "ActivityDefinition",
"url": "http://example.org/ActivityDefinition/hba1c-order",
"status": "active",
"kind": "ServiceRequest",
"code": {
"coding": [
{
"system": "http://loinc.org",
"code": "4548-4",
"display": "HbA1c"
}
]
}
}
Questionnaire
If an action requires collecting structured data from a patient or provider, it can reference a Questionnaire. When executed, the system generates a Task whose input references the Questionnaire, signaling to your application that this specific form needs to be completed to fulfill the task.
{
"resourceType": "PlanDefinition",
"status": "active",
"action": [
{
"title": "Complete Risk Assessment",
"definitionCanonical": "http://example.org/Questionnaire/diabetes-risk"
}
]
}
Advanced Workflow Logic
The FHIR standard supports highly complex workflow orchestration.
Hierarchical Actions & Grouping
You can nest actions to create phases or groups, and define rules for how users select from them using groupingBehavior (e.g., logical-group, visual-group) and selectionBehavior (e.g., any, all, exactly-one).
{
"resourceType": "PlanDefinition",
"status": "active",
"action": [{
"title": "Initial Lab Orders",
"groupingBehavior": "logical-group",
"selectionBehavior": "any",
"action": [
{ "title": "Order CBC" },
{ "title": "Order CMP" }
]
}]
}
Conditional Actions
You can define if/else logic or prerequisites using expressions (like CQL or FHIRPath) to determine if a step should occur.
{
"resourceType": "PlanDefinition",
"status": "active",
"action": [{
"title": "Administer Medication",
"condition": [{
"kind": "applicability",
"expression": {
"language": "text/fhirpath",
"expression": "%patient.birthDate <= today() - 18 years"
}
}]
}]
}
Action Timing & Dependencies
You can trigger actions based on the completion of other actions, including time delays.
{
"resourceType": "PlanDefinition",
"status": "active",
"action": [
{
"id": "step1",
"title": "Initial Assessment"
},
{
"title": "Follow-up Assessment",
"relatedAction": [{
"actionId": "step1",
"relationship": "after-end",
"offsetDuration": {
"value": 7,
"unit": "days",
"system": "http://unitsofmeasure.org",
"code": "d"
}
}]
}
]
}
Dynamic Values
You can dynamically inject values into the resulting resources based on the context (like the patient's name) when the protocol is applied.
{
"resourceType": "PlanDefinition",
"status": "active",
"action": [{
"title": "Create Follow-up Task",
"dynamicValue": [{
"path": "Task.description",
"expression": {
"language": "text/fhirpath",
"expression": "'Follow up with ' + %patient.name.first().given.first()"
}
}]
}]
}
Executing Protocols
To actually start a workflow for a specific patient, you instantiate the PlanDefinition using the $apply operation.
When you invoke the $apply operation, Medplum processes the PlanDefinition and:
- Creates Tasks for each action in the PlanDefinition
- Resolves ActivityDefinitions & Questionnaires to generate the appropriate underlying resources (like
ServiceRequest). - Creates a RequestGroup containing all the generated actions.
- Creates a CarePlan that wraps the RequestGroup.
The FHIR standard allows for very complex workflow modeling, including hierarchical actions, conditional logic, and dynamic values. While you can author and store these complex PlanDefinition resources in Medplum today, the Medplum $apply operation currently implements a focused subset of these capabilities (primarily generating sequential Tasks and resolving ActivityDefinitions). Full execution support for hierarchical and conditional logic is under active development.
Action Definition Processing
| Definition Type | Generated Resources |
|---|---|
Questionnaire | Task with Questionnaire input reference |
ActivityDefinition | Task + ServiceRequest (if kind is ServiceRequest) |
| None | Task only |
Task Extensions
Medplum supports a custom extension to assign Task parameters when $apply is run. It can be placed on a PlanDefinition.action or on an ActivityDefinition.
https://medplum.com/fhir/StructureDefinition/task-elements- Configure TaskownerandperformerType:ownerwithvalueReferenceassigns every Task to a fixedPractitioner,PractitionerRole,Organization,CareTeam,HealthcareService,Patient,Device, orRelatedPerson(for example, an intake care team). Any other resource type is rejected.ownerwithvalueExpressionresolves the owner from a FHIRPath expression based on the$applyparameters (e.g.,%subject,%practitioner,%organization).performerTypewithvalueCodeableConceptsets a fixed performer type.
The extension on the action applies to every action type, including Questionnaire actions and actions with no definition. When both the action and its ActivityDefinition carry the extension, each field on the action takes precedence and the ActivityDefinition fills in any field the action leaves unset. A field set on the action means the ActivityDefinition's value for that field is ignored.
An owner must be a literal ResourceType/id reference. If any action resolves to an invalid owner, the whole $apply fails with a 400 and no resources are created.
Placing task-elements on an ActivityDefinition is deprecated and will be removed in a future major release. An ActivityDefinition describes the resource it generates, such as a ServiceRequest, not the Task that tracks the action. Put task-elements on the PlanDefinition.action instead. To set fields on the generated resource itself, use ActivityDefinition.dynamicValue.
Example PlanDefinition action with Task Extensions:
{
"resourceType": "PlanDefinition",
"status": "active",
"action": [
{
"title": "Complete intake questionnaire",
"definitionCanonical": "http://example.com/Questionnaire/intake",
"extension": [{
"url": "https://medplum.com/fhir/StructureDefinition/task-elements",
"extension": [
{
"url": "owner",
"valueExpression": {
"language": "text/fhirpath",
"expression": "%practitioner"
}
}
]
}]
},
{
"title": "Verify insurance",
"extension": [{
"url": "https://medplum.com/fhir/StructureDefinition/task-elements",
"extension": [
{
"url": "owner",
"valueReference": { "reference": "CareTeam/intake-team" }
}
]
}]
}
]
}
Example ActivityDefinition with Task Extensions (deprecated):
{
"resourceType": "ActivityDefinition",
"status": "active",
"extension": [{
"url": "https://medplum.com/fhir/StructureDefinition/task-elements",
"extension": [
{
"url": "owner",
"valueExpression": {
"language": "text/fhirpath",
"expression": "%practitioner"
}
},
{
"url": "performerType",
"valueCodeableConcept": {
"coding": [{ "system": "http://snomed.info/sct", "code": "158965000", "display": "Medical practitioner" }]
}
}
]
}]
}
When the protocol is applied, Medplum evaluates these expressions to generate a concrete Task resource with the resolved values.
{
"resourceType": "Task",
"status": "requested",
"intent": "order",
"for": { "reference": "Patient/example" },
// The owner is resolved from the %practitioner FHIRPath expression
"owner": { "reference": "Practitioner/dr-alice-smith" },
// The performerType is resolved from the valueCodeableConcept in the extension
"performerType": [
{
"coding": [
// The coding is resolved from the extension's valueCodeableConcept
{ "system": "http://snomed.info/sct", "code": "158965000", "display": "Medical practitioner" }
]
}
]
}