Use the FHIR $apply operation on a PlanDefinition to generate a CarePlan and RequestGroup for a patient enrolled in a chronic disease management protocol
POST a Parameters resource to the PlanDefinition's $apply endpoint carrying the required subject parameter referencing the Patient, the encounter parameter if applying within an active encounter context, and the practitioner parameter identifying the applying clinician
Confirm that the PlanDefinition has action elements with condition elements specifying applicability conditions in CQL or FHIRPath; the $apply operation evaluates these conditions against the patient context to determine which actions generate Request resources and which are skipped
Parse the returned CarePlan resource to identify which actions were instantiated into activity elements; each activity will reference a RequestOrchestration (formerly RequestGroup in R4) containing the generated ServiceRequest, MedicationRequest, or Task resources
For actions that require a questionnaire to be completed before the activity is applicable, follow the relationship between the CarePlan activity and the linked Questionnaire and use $populate to pre-fill the Questionnaire from existing patient data before presenting it for completion
POST the returned CarePlan to the FHIR server to persist it; then POST any generated Request resources that were returned as contained resources or as separate resource references in the CarePlan activity elements
If the PlanDefinition version changes after initial application, call $apply again with the same patient context and compare the resulting RequestOrchestration to the existing one to identify new actions that must be added to the patient's active care plan
Known gotchas
The $apply operation is defined in the FHIR Clinical Reasoning module but is not uniformly implemented; many FHIR servers return a 404 on PlanDefinition/$apply or return a CarePlan without evaluating the CQL applicability conditions, silently applying all actions regardless of patient eligibility
The $apply response may return a CarePlan with contained Request resources rather than persisting those resources independently; the returned resources must be extracted from the contained array and POSTed separately before they are accessible via standard FHIR search
PlanDefinition actions with a timing element specifying an offset from enrollment need a reference date to compute the scheduled timing; if the enrollment date is not passed as a parameter, the engine may default to the current date, generating incorrectly scheduled activities
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp