PlanDefinition $apply | Medplum

On this page

Medplum implements the FHIR $apply operation for PlanDefinition resources.

The $apply operation converts a PlanDefinition into a set of actionable resources for a specific patient. It creates a CarePlan containing a RequestGroup with Tasks based on the actions defined in the PlanDefinition.

For a detailed explanation of how Medplum processes PlanDefinitions, resolves ActivityDefinitions, and handles custom Task extensions, see our guide on Authoring Clinical Protocols.

Use Cases

Care Protocols: Apply standardized care protocols to patients
Clinical Guidelines: Implement evidence-based treatment guidelines
Care Coordination: Generate care plans with assigned tasks
Workflow Automation: Create structured workflows from templates

Invoke the `$apply` operation

[base]/PlanDefinition/[id]/$apply

For example:

curl -X POST 'https://api.medplum.com/fhir/R4/PlanDefinition/example-id/$apply' \

-H "Content-Type: application/fhir+json" \

-H "Authorization: Bearer MY_ACCESS_TOKEN" \

-d '{

"resourceType": "Parameters",

"parameter": [\
\
      {\
\
        "name": "subject",\
\
        "valueString": "Patient/patient-123"\
\
      }\
\
    ]

}'

Parameters

Name	Type	Description	Required
`subject`	`string[]`	Reference to the Patient the plan applies to	Yes
`encounter`	`string`	Reference to the Encounter for context	No
`practitioner`	`string`	Reference to the Practitioner applying the plan	No
`organization`	`string`	Reference to the Organization context	No

Example with All Parameters

curl -X POST 'https://api.medplum.com/fhir/R4/PlanDefinition/example-id/$apply' \

-H "Content-Type: application/fhir+json" \

-H "Authorization: Bearer MY_ACCESS_TOKEN" \

-d '{

"resourceType": "Parameters",

"parameter": [\
\
      {\
\
        "name": "subject",\
\
        "valueString": "Patient/patient-123"\
\
      },\
\
      {\
\
        "name": "encounter",\
\
        "valueString": "Encounter/encounter-456"\
\
      },\
\
      {\
\
        "name": "practitioner",\
\
        "valueString": "Practitioner/dr-smith"\
\
      },\
\
      {\
\
        "name": "organization",\
\
        "valueString": "Organization/clinic-abc"\
\
      }\
\
    ]

}'

Output

The operation returns a CarePlan resource that references a RequestGroup containing the generated Tasks.

Example Response

{

"resourceType": "CarePlan",

"id": "generated-careplan-id",

"status": "active",

"intent": "plan",

"subject": {

"reference": "Patient/patient-123"

},

"instantiatesCanonical": [\
\
    "http://example.org/PlanDefinition/diabetes-management"\
\
  ],

"activity": [\
\
    {\
\
      "reference": {\
\
        "reference": "RequestGroup/generated-requestgroup-id"\
\
      }\
\
    }\
\
  ]

}

Example PlanDefinition

At its most basic level, a PlanDefinition is a list of sequential tasks. The $apply operation converts these actions into a RequestGroup and individual Task resources.

{

"resourceType": "PlanDefinition",

"id": "example-plan",

"url": "http://example.org/PlanDefinition/diabetes-screening",

"title": "Diabetes Screening Protocol",

"status": "active",

"action": [\
\
    {\
\
      "title": "Order HbA1c Test",\
\
      "definitionCanonical": "http://example.org/ActivityDefinition/hba1c-order"\
\
    },\
\
    {\
\
      "title": "Complete Risk Assessment",\
\
      "definitionCanonical": "http://example.org/Questionnaire/diabetes-risk"\
\
    },\
\
    {\
\
      "title": "Schedule Follow-up",\
\
      "description": "Schedule a follow-up appointment in 3 months"\
\
    }\
\
  ]

}

For more advanced examples of modeling workflows (including hierarchical actions, conditional logic, timing dependencies, and dynamic values), see our guide on Authoring Clinical Protocols.