Clinical Practice Guidelines, published by HL7 International / Clinical Decision Support. This guide is not an authorized publication; it is the continuous build for version 3.0.0-ballot built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/cqf-recommendations/ and changes regularly. See the Directory of published versions
| Page standards status: Informative |
This page was reorganized from the single Methodology page of the previous version of this guide, and its guidance was expanded (see the change log).
Use the reviewed specification from the Represent step to author the FHIR R4 content and its computable logic. The knowledge engineer carries each criterion, input, and proposed response into the artifacts. The terminology owner reviews the coded meaning, and the clinical reviewer decides questions about interpretation that surface during authoring. The Content IG Walkthrough illustrates tooling for authoring a package. Check its compatibility with the project's selected versions.
The translate step involves using the narrative (L1) and semi-structured (L2) outputs from the select and represent steps to create formal, computable, standards-based representations of guideline content: specifically, FHIR profiles (i.e. case features), CPG activities, CQL logic, and CPG recommendations, strategies, and pathways (structured, L3 content). This step is typically performed by a team consisting of at least:
Record which guideline passages and journal articles (L1) inform the reviewed data, criteria, and activities from Represent (L2), and which FHIR and CQL artifacts (L3) implement them. These relationships can be one-to-one or many-to-many.
Start with content identity and dependencies, then define the data profiles, terminology, and logic. Describe the activities and assemble them into recommendations, strategies, and pathways. Define any patient-level metrics needed to evaluate progress.
The content steward establishes the repository, canonical base URL, intended realm, publication route, and dependency versions. Use a canonical base controlled by the steward so the identities used in definitions and dependencies can persist across releases. Sample Content IG · FHIR Community Process
A computable Clinical Practice Guideline (CPG) following this methodology is delivered as a FHIR Implementation Guide, and the first step to developing the content is to establish the content IG. This typically takes the form of a Github repository, similar to the Sample Content IG.
Pay particular attention at this step to the selection of the canonical URL for the computable guideline, as it will determine the base of the URLs for all the artifacts published by the IG, as well as enable resolution of artifacts when the IG is published at its canonical URL.
Many FHIR implementation guides are Health Level 7 (HL7) balloted specifications, and as such are published on the HL7 FHIR website. For example, the US Core implementation guide is published at http://hl7.org/fhir/us/core. However, for content IGs, the steward of the content will typically be the publisher, so the canonical base URL for the IG should be selected using a domain that the steward controls.
For open-source content with a commitment to maintain it, the fhir.org site can provide a publication alternative by following the FHIR Community Process.
Map each data dictionary entry to the FHIR data the logic will read. Two observations distinguished only by code may share an interoperability profile. Use a separate profile when a distinct set of constraints needs to be validated. A CPGCaseFeatureDefinition describes a reusable feature. A corresponding patient observation can carry the patient-specific value and timing. Preserve the provenance of each result and distinguish asserted facts from calculated inferences when persisting them. CPGCaseFeatureDefinition
Broadly, data elements defined in the data dictionary result in case features, or profiles that use the CPGCaseFeatureDefinition profile. Case features fall into two categories:
Note that an inferred case feature may be recorded as part of the patient record, so that it effectively becomes an asserted case feature. And it may also be the case that asserted case features can also be calculated based on other values in the patient record.
Because case features are aspects of the patient's record (or typically events that have occurred, as opposed to are planned), case features will typically be event resources.
Content conforming to this implementation guide SHOULD use the CPG Event Activity Profiles as the basis for case feature definitions.§data-1
In addition, content implementation guides will typically select a target realm for deployment, and select interoperability profiles appropriate for that realm (statement prof-2).
Identify or author the code systems, value sets, and mappings needed by each decision. Carry over the mapping qualifications agreed during representation and record versions and responsibility for maintaining expansions. Take meaning that cannot be expressed with the selected codes back to the clinical and terminology reviewers. Terminology requirements and maintenance guidance
This step is typically performed by the terminologist with help from the knowledge engineering role to assist in creating FHIR representations. For terminology servers that already support authoring and distribution of FHIR ValueSet resources, this is less of an issue, but often there are not complete solutions available, and additional tooling is required to support the terminology publishing needs. For more discussion on the creation and distribution of value sets, see the Terminology page.
Express the reviewed criteria and calculations in a supported logic language. If you use CQL, follow the conformance requirements for CQL content. Publish the logic through Library resources with its dependencies and data requirements. Connect the expressions to the source criteria and expected cases so reviewers can test how the logic handles timing, missing information, and exceptions. Libraries · Using CQL With FHIR
IG Publisher can attach the authored CQL to its Library resources through the binary adjunct loader and generate ELM. Check the resulting Library attachments, dependencies, and data requirements before packaging.
Across guideline-based care, there are many different types of recommendations that may be given, such as the recommendation to conduct a specific test, to prescribe a specific medication, recommendation for a particular procedure, and many others. Following the general workflow pattern established in FHIR, the activities within these recommendations are represented by the following patterns:
Choose resources based on what each artifact represents. A definition describes what can occur. A request describes what is proposed or intended for a patient. An event records what is occurring or has occurred. For example, a medication proposal and a later record of dispensing describe different stages of care. FHIR R4 definition, request, and event patterns · Activity flow
Readers of this implementation guide should refer to the Definitional Artifacts topic in the FHIR specification for general information on how ActivityDefinition resources are used to describe the activities that can be performed.
An ActivityDefinition is a patient-independent template. Applying it in context can produce patient-specific values and requests. Acceptance, authorization, and fulfillment occur through the receiving workflow. Consult each artifact for the exact context and parameters it accepts.
| Name | Description |
|---|---|
| Patient | The current Patient in context |
| Practitioner | The current Practitioner interacting with the clinical system |
| Encounter | The Encounter in progress, if one is currently in progress |
These generic ActivityDefinitions illustrate inputs and target fields. Their dynamicValue expressions require review and testing before reuse. See Activity Examples for worked definitions, libraries, and scenario resources.
| Activity | Parameters |
|---|---|
| AdministerMedication | MedicationRequest: The detailed medication request to be administered. This may be an existing order, or it may be produced as part of the administer medication activity |
| CollectInformation | QuestionnaireCanonical: The canonical URL of the questionnaire to be used to collect the information |
| CommunicationRequest | CategoryCodeableConcept: The category of communication |
| DispenseMedication | MedicationRequest: The detailed medication request to be dispensed. This may be an existing order, or it may be produced as part of the dispense medication activity |
| DocumentMedication | MedicationRequest: The detailed medication request to be documented. This may be an existing order, or it may be produced as part of the document medication activity |
| Enrollment | PathwayCanonical: The canonical URL of the pathway or strategy in which the patient is enrolled/unenrolled |
| GenerateReport | DefinitionCanonical: The canonical URL of the metric, case report, or profile to use to generate the report |
| ImmunizationRequest | VaccineCodeableConcept: The vaccine being recommended |
| MedicationRequest | MedicationCodeableConcept: The medication being proposed, as a CodeableConcept DoseQuantity: The quantity of medication DosesPerDay: The intended number of doses per day. The generic timing expression uses this value as the period and needs correction before use. |
| ProposeDiagnosisTask | DiagnosisCodeableConcept: The diagnosis being proposed |
| RecordDetectedIssueTask | IssueCodeableConcept: The issue being recorded |
| RecordInferenceTask | InferenceCodeableConcept: The type of inference being recorded InferenceValue: The value of the inference being recorded. Construct the result according to the selected inference profile. |
| ReportFlagTask | IssueCodeableConcept: The issue being flagged |
| ServiceRequest | ServiceCodeableConcept: The type of service being proposed |
Proposed activities are represented with request resources, and for each type of activity, this implementation guide defines a proposal profile. These are effectively the recommended action to be taken as part of a guideline recommendation, and in general they each specify:
These profiles are intended to be used for proposals, and so are modeled with the proposal intent. Note that some implementations may go further and use the plan or even order intents of a request, depending on the capabilities of the systems involved.
Choose the recommendation instance profile that represents the action proposed.
The applicable profile and the local authorized workflow determine whether the activity can also be represented with plan or order intent. Recommendation instances and care plans
Content conforming to this implementation guide SHALL use one of the recommendation instance profiles described above to ensure supporting information related to the recommendation is preserved through the recommendation instance.§act-1
Specific guideline content MAY define derived profiles for recommendation instances establishing additional constraints.§act-3
For each of the activity types, this implementation guide defines an event profile for modeling when the activities have actually occurred. Each event profile typically describes:
instantiatesCanonical element, referring back to the guideline (definitional) contentbasedOn element, referring back to the request the event is fulfillingUse the elements supported by the event's profile to link it to its definition, request, and pertinent patient information. The event resource describes the evidence actually recorded. For example, a dispense, administration, and medication statement each tell a reviewer something different about a medication order. When an event is also a case feature, instantiatesCaseFeature identifies the feature definition and caseFeatureType records whether the fact is asserted or inferred.
| Activity | Event |
|---|---|
| Send a message | CPGCommunication |
| Administer medication | CPGMedicationAdministration |
| Collect information | CPGQuestionnaireResponse |
| Dispense medication | CPGMedicationDispense |
| Document medication | CPGMedicationStatement |
| Enrollment | CPGCase |
| Generate report | CPGMetricReport CPGCaseSummary CPGCasePlanSummary CPGCasePlanProgressingNote |
| Order a medication | CPGMedicationDispense CPGMedicationAdministration CPGMedicationStatement |
| Recommend an immunization | CPGImmunization |
| Order a service | CPGProcedure CPGObservation |
| Propose a diagnosis | CPGCondition |
| Record a detected issue | CPGDetectedIssue |
| Record an inference | CPGObservation |
| Report a flag | CPGFlag |
Content conforming to this implementation guide SHALL use the event profiles defined above to ensure guideline supporting and tracking information is available for activities delivered in the context of a computable guideline.§act-2
Requests can also be case features. A current order may be the first or only recorded signal of an intervention, so the request profiles support the same case-feature extensions.
Pertinence describes how facts such as signs, symptoms, and lab values contribute to a specific clinical finding, such as a condition or physiological state. Check the applicable instance profile for extension support. Examples include request and event profiles, case-feature profiles such as CPGCondition, and the CPGCaseSummary and CPGCasePlanSummary profiles.
pertinent links a finding or recommendation to the patient information relevant to it.pertinentTo links a patient fact to the higher-level finding it is pertinent to.caseFeaturePertinence qualifies how a fact bears on the particular finding. The pertinence value set includes weakly positive, strongly positive, weakly negative, strongly negative, and pathognomonic codes.pertinenceRating expresses the weight of a fact for inferring the finding as an integer from 0 (no weight) to 10 (greatest weight). Use it alone or alongside the coded pertinence.The two link directions let a system document the relationship when it manages only one of the records. To qualify the fact on a supported instance resource, use the resource's extension element. To qualify a specific pertinent or pertinentTo link, put the coded pertinence or rating on that link's Reference using valueReference.extension.
In the synthetic CHF case, jugular venous pressure observation 4 uses pertinentTo to link to observation 5 and gives that reference an illustrative weight of 8. Observation 5 uses pertinent to link back to observation 4 and records strongly-positive on the Observation itself.
Represent a recommendation as a PlanDefinition event-condition-action rule. The trigger identifies when evaluation is relevant, the condition expresses applicability, and the action describes the proposed response. Reference the expressions and activity definitions that implement the reviewed criteria and proposed action. Carry the citation and recommendation ratings from Select into the definition. Guideline supporting information
Content conforming to this implementation guide SHALL use the cpg-recommendationdefinition profile to represent recommendation definitions.§rec-5
The recommendation used in this way specifies:
Readers of this implementation guide should refer to the Applying a PlanDefinition topic for details on how an event-condition-action rule can be applied to a particular patient to produce guidance appropriate to that patient.
When the guideline expresses how it regards alternative options, author that stance on each PlanDefinition.action using the cpg-preferenceBehavior extension, with a code from the CPG Preference Behavior value set: preferred, recommended, neutral, or not-recommended. See Preference among Options for the meaning of each code and how preference differs from applicability, direction, and strength. CPGComputablePlanDefinition supports the extension on its actions, and CPGStrategy supports it on the actions of a patient-specific strategy.
The extension conveys the guideline's intended stance for an action at design time. When $apply produces a RequestGroup, the value is realized on the corresponding RequestGroup.action, so that a client can present the options with the guideline's stance on each.
For example, the illustrative CKD Hypertension Therapy Options recommendation offers three alternative initial therapies under a single action with a selectionBehavior of at-most-one. The ACE inhibitor option is preferred, the angiotensin receptor blocker is recommended, and the dihydropyridine calcium channel blocker is not-recommended. The ACE inhibitor option also has its own applicability condition, so for a patient with a history of ACE inhibitor angioedema it is excluded by applicability, not marked down by preference. The result of applying it to a patient without that history is a RequestGroup whose actions carry the copied preference values, with child requests of intent option.
Content conforming to this implementation guide SHALL express applicability through action conditions of kind applicability, and SHALL NOT express applicability through the preference behavior extension.§rec-8
Content conforming to this implementation guide SHALL NOT use the preference behavior extension to override applicability.§rec-9
The $apply operation SHOULD copy the preference behavior extension from each PlanDefinition.action to the corresponding RequestGroup.action.§rec-10
Implementations SHOULD treat any conflict between applicability and preference behavior as a modeling error.§rec-11
Content conforming to this implementation guide MAY use a dynamicValue to compute or override preference behavior at runtime, for example for patient-specific ranking, payer-specific preferences, or guideline branching.§rec-12
Use a strategy definition to group related recommendation definitions for a clinical issue. The reusable strategy definition is a PlanDefinition. A patient-specific strategy can be represented as a CPGStrategy RequestGroup.
Content conforming to this implementation guide SHALL use the cpg-strategydefinition profile to represent strategy definitions.§rec-6
A strategy can express how related recommendations are intended to work together, so the team can review their sequencing and dependencies. Specify when each recommendation can be evaluated and whether it depends on a Case Feature, a prior proposal, an authorized request, or a documented event. For example, if guidance calls for reassessment after an intervention, establish which event starts the interval and what happens if fulfillment is partial or unknown. A source recommendation, decision table, or flow diagram may describe the relationships. When the source leaves sequencing or a conflict unresolved, record the interpretation with the guideline team before encoding it. Use the PlanDefinition processing semantics to express the agreed dependencies.
Use a pathway definition to organize strategies and describe the scope of the guideline. Specify clinical eligibility separately from local enrollment or activation. Decisions can be reevaluated as information changes. If a pathway calls for a fixed sequence, have clinical reviewers confirm the rationale and local implementers confirm that the workflow can support it. CPG plans
Content conforming to this implementation guide SHALL use the cpg-pathwaydefinition profile to represent pathway definitions.§rec-7
For example, the WHO antenatal care guideline recommends an overall contact schedule consisting of eight contacts at specific points during the pregnancy. This is represented using a pathway with actions for each of the contacts, where each action defines an applicability criteria that identifies the recommended timing of the encounter. The activities in a pathway used in this way are references to other strategies, rather than particular activities to be performed.
The choice between representation using recommendations, strategies, and pathways depends on a variety of factors, largely driven by:
We use the term pathway in this methodology for a more flexible representation of the guidance, as opposed to a protocol which would typically be a more rigid description of a particular process. Depending on the guideline, there may be aspects of the pathway that are expected to be more rigid (i.e. closer to protocols), depending on the clinical specification.
This implementation guide uses the Measure resource to represent metrics, patient-level indicators of how care delivered compares with the guideline. Content conforming to this implementation guide SHALL use the CPGComputableMetric profile to represent metrics, and the CPGMetricReport profile to record the result of evaluating a metric for a patient.§metric-1
The type of a metric is identified by Measure.type, using the CPG Measure Type value set. In addition to the base measure types (such as process, outcome, and composite), this value set includes compliance and adherence. Their type descriptions also discuss goal and pathway scopes. The coded result sets currently defined by this guide cover two combinations of type and scope:
Result codes for metrics scoped to pathways and goals are not yet defined, and are expected in a future version of this implementation guide. This project is actively seeking feedback on the compliance and adherence result codes below.
A metric is a patient-level indicator. It can express progress toward a goal or elapsed time from a proposal to documented care. Specify the facts it uses, the event that starts the interval, the scoring rule, and what a result means. Explain how unavailable or stale data affect the result. For example, a missing administration record may leave fulfillment unknown. Preserve the distinction between a recommendation that was inapplicable, a proposal that was declined, and care explicitly documented as not done.
Both value sets draw their codes from the hierarchical CPG Metric Result code system. For example, compliant-with-prior-non-compliance is a kind of compliant. Use a terminology operation that supports hierarchy when querying for a parent and its descendants. The ballot defines the result codes and their meanings. The CPGMetricReport profile does not specify an element or extension for those codes, so agree on the exchange representation before sharing coded results.
| Compliance result | Adherence result | Meaning |
|---|---|---|
| compliant | adherent | The expectation is met |
| compliant-with-prior-non-compliance | adherent-with-prior-non-adherence | The expectation is met, but a prior evaluation within the metric's lookback was not |
| partially-adherent | Some, but not all, of the strategy's requirements are met | |
| non-compliant | non-adherent | The expectation is not met |
| at-risk-for-non-compliance | at-risk-for-non-adherence | The expectation is not yet failed, but the metric predicts it will fail without intervention |
Both value sets also include six shared operational states, which describe why no success or failure result is reported:
| Code | Meaning |
|---|---|
| pending | The expectation applies and its fulfillment window is still open |
| on-hold | The expectation is temporarily suspended under the metric's policy |
| exempted | The recommendation or strategy applies, but an exemption accepted by the metric's policy removes the expectation |
| not-applicable | The recommendation or strategy does not apply to the patient |
| not-yet-evaluated | The metric has not yet been evaluated for the patient |
| unknown | The metric was evaluated, but the result cannot be determined from the available data |
See the code system for the full definition of each code. A metric reports one code per evaluation, chosen as follows:
MeasureReport.status, not with the unknown code.Several codes depend on the metric's policy. A metric that reports these codes SHOULD document, in its definition, the following policy elements.§metric-4
State whose care a summary view covers, which recommendation, strategy, or pathway defines its scope, and whether it describes the current state or a prior point in time. Show the source and time of important facts. Readers need to see which activities were proposed, authorized, or documented as performed, and where information is unavailable.
Take the authored definitions, profiles, terminology, libraries, and their dependency versions into Validate with the reviewed cases. Keep the source-to-artifact links and any unresolved decisions with the work so reviewers can trace a discrepancy to the relevant criterion, mapping, or activity. Use the L3 checklist to review the artifacts and documentation you hand off.