Data Exchange For Quality Measures Implementation Guide, published by HL7 International / Clinical Quality Information. This guide is not an authorized publication; it is the continuous build for version 1.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/davinci-deqm/ and changes regularly. See the Directory of published versions
| Official URL: http://hl7.org/fhir/uv/deqm/OperationDefinition/evaluate | Version: 1.0.0-ballot | ||||
| Standards status: Trial-use Active as of 2026-03-23 | Maturity Level: 4 | Computable Name: Evaluate | |||
The evaluate operation is used to calculate an eMeasure and obtain the results.
It is often the case that the operation should not be performed from the server's timezone, rather the client's timezone is typically a more correct option. Note that even this isn't always correct because the evaluation may be running over data from multiple sources in different timezones. Providing guidance to the measure evaluator with the timezone header can facilitate consistent behavior.
The type of the return parameter of this $evaluate is Bundle.
Language: en
URL: [base]/Measure/$evaluate
| Use | Name | Scope | Cardinality | Type | Binding | Documentation |
| IN | measureUrl | 1..* | canonical | The URL of the measure to be evaluated. A measure URL is specified in the url element of the Measure resource. The measure URL remains the same when the measure is stored on different servers. | ||
| IN | periodStart | 1..1 | date | The start of the measurement period. In keeping with the semantics of the date parameter used in the FHIR search operation, the period will start at the beginning of the period implied by the supplied timestamp. E.g. a value of 2014 would set the period start to be 2014-01-01T00:00:00 inclusive | ||
| IN | periodEnd | 1..1 | date | The end of the measurement period. The period will end at the end of the period implied by the supplied timestamp. E.g. a value of 2014 would set the period end to be 2014-12-31T23:59:59 inclusive | ||
| IN | reportType | 0..1 | code | The type of measure report: | ||
| IN | subject | 0..1 | string (reference) | Subject(s) for which the measure will be calculated. Subjects provided in this parameter SHALL match the subjectType of the measure being evaluated (e.g. if the Measure.group.subjectType is Patient, the subject SHALL be a reference to a Patient or a Group of Patients). This parameter cannot be used with the subjectGroup parameter. If no subject or subjectGroup is provided, what subjects are evaluated is up to the server. | ||
| IN | subjectGroup | 0..1 | Group | Subjects for which the measure will be evaluated, provided as a Group resource. Subjects provided in this parameter SHALL match the subjectType of the measure being evaluated. (e.g. if the Measure.group.subjectType is Patient, the subject SHALL be a reference to a Patient or a Group of Patients). This parameter cannot be used with the subject parameter. If no subject or subjectGroup is provided, what subjects are evaluated is up to the server. | ||
| IN | reporter | 0..1 | string (Practitioner, PractitionerRole, Organization) (reference) | The provider for which the report will be run. This may be a reference to a Practitioner, PractitionerRole, or Organization. If specified, systems MAY use this information to determine subjects for which the measure will be calculated, but how subjects are determined is implementation-specific. This parameter is reflected in the reporter element of the resulting MeasureReport(s). This parameter cannot be used with the reporterResource parameter. | ||
| IN | reporterResource | 0..1 | Practitioner | PractitionerRole | Organization | The provider for which the report will be run, provided as a Practitioner, PractitionerRole, or Organization resource. This is intended to support the use case in which the organization information is not on the server performing the evaluation, for example an ad-hoc group of practitioners that are part of a provider group. This parameter is reflected in the reporter element of the resulting MeasureReport(s). This parameter cannot be used with the reporter parameter. | ||
| IN | location | 0..* | string (reference) | The location(s) for which the report will be run. This parameter is reflected in the location element of the resulting MeasureReport(s). | ||
| IN | parameters | 0..1 | Parameters | Any input parameters for the Measure evaluation. If the measure uses CQL, the parameter types are mapped to CQL as specified in the Parameters and Data Requirements section of the Using CQL with FHIR Implementation Guide. Any parameters defined in this input will be bound by name to parameters defined in the logic library referenced from library element of the Measure. If a parameter appears more than once in the input Parameters resource, it is represented with a List in the input CQL. If a parameter has parts, it is represented as a Tuple in the input CQL. | ||
| IN | manifest | 0..1 | canonical (CRMI Manifest Library) | Specifies an asset-collection library that provides dependency version resolution and expansion rules for the operation. See the description of manifest in the Canonical Resource Management Infrastructure IG for a complete description of how manifest values are used to provide defaults for dependency version resolution and expansion parameters. Parameters specified directly in the operation override behaviors specified by the manifest parameter. In general, if this parameter is supplied, it is expected to be used in nested operation calls. For example, in evaluating a measure, if the expansion of a value set is required, this parameter SHALL be supplied to that expansion. | ||
| IN | lastReceivedOn | 0..1 | dateTime | The date the results of this measure were last received. This parameter is only valid for patient-level reports and is used to indicate when the last time a result for this patient was received. This information can be used to limit the set of resources returned for a patient-level report | ||
| IN | excludeEvaluatedResources | 0..1 | boolean | Indicates that evaluated resources and supplemental data referenced by the MeasureReport(s) should not be included in the resulting bundles. The default for this parameter is false, so that evaluated resources are NOT included. Note that this parameter does not apply to the contained resources that are created by evaluation to communicate the results of stratification or supplemental data counts. | ||
| IN | stratifier | 0..* | Additional stratifier criteria for the measure. The resulting MeasureReport will contain this additional stratifier information as well as any stratifiers defined in the Measure being reported. | |||
| IN | stratifier.measureUrl | 0..* | canonical | If the evaluate operation is for multiple measures, this parameter may be used to specify which measures the additional stratifier should be reported on. If not specified, the stratifier will be reported on all the measures. Note that if this results in a stratifier definition that cannot be interpreted correctly for the measure being reported, the behavior is at server discretion; it may throw an error, or simply ignore the additional stratifier definition. | ||
| IN | stratifier.groupId | 0..* | string | If the measure being evaluated has multiple groups, this parameter may be used to specify which groups the additional stratifier should be reported on. If not specified, the stratifier will be reported on all groups in the measure being reported. Note that if this results in a stratifier definition that cannot be interpreted correctly for the measure group being reported, the behavior is at server discretion; it may throw an error, or simply ignore the additional stratifier definition. | ||
| IN | stratifier.component | 1..* | One or more components of the stratifier definition. Additional stratifiers are reported in the MeasureReport in the same way as stratifiers defined in the Measure. | |||
| IN | stratifier.component.code | 0..1 | code | http://hl7.org/fhir/ValueSet/measure-stratifier-example (Example) | Meaning of the stratifier component. | |
| IN | stratifier.component.description | 0..1 | markdown | Human readable description of the stratifier component | ||
| IN | stratifier.component.criteria | 1..1 | Expression | An expression that returns the value of this component of the stratifier for a member of the population. This is typically the name of an expression defined within a referenced library, but it may also be a path to a stratifier element, evaluated from the perspective of the measure subject. If this is a non-subject-based measure, the expression may be a reference to a function that takes an argument of the type of the measure basis, allowing the stratifier value to be determined for each member of the population. | ||
| IN | stratifier.component.valueSet | 0..1 | canonical (ValueSet) | A value set defining possible stratifier values. If both expression and valueset are specified, they SHALL be consistent (i.e. the expression SHALL evaluate to a code that is a member of the specified valueset). | ||
| IN | stratifier.component.unit | 0..1 | string | Indicates what units, if any, stratifier values are expected to be expressed in. This element SHOULD be specified in UCUM units or calendar units. This information SHOULD be provided if it cannot be inferred from the stsratifier expression directly. | ||
| IN | supplementalData | 0..* | What additional supplemental data should be reported with the measure. This additional data is specified in the same was as supplemental data in the Measure resource, and is reported in the same way in the MeasureReport. | |||
| IN | supplementalData.measureUrl | 0..* | canonical | If the evaluate operation is for multiple measures, this parameter may be used to specify which measures the additional supplemental data should be reported on. If not specified, the stratifier will be reported on all the measures. Note that if this results in a stratifier definition that cannot be interpreted correctly for the measure being reported, the behavior is at server discretion; it may throw an error, or simply ignore the additional stratifier definition. | ||
| IN | supplementalData.code | 0..1 | CodeableConcept | http://hl7.org/fhir/ValueSet/measure-supplemental-data-example (Example) | Meaning of the supplemental data. | |
| IN | supplementalData.usage | 0..* | CodeableConcept | MeasureDataUsage (Extensible) | supplemental-data | risk-adjustment | factor | |
| IN | supplementalData.description | 0..1 | markdown | Human readable description of this supplemental data element | ||
| IN | supplementalData.criteria | 1..1 | Expression | Expression describing the additional data to be reported. This may be the name of an expression in a library, or it may be a path to a specific data element, reachable from the subject being evaluated. | ||
| OUT | return | 0..* | Bundle | The result of this operation is a Bundle for each input subject. These Bundles SHALL contain 1..* DEQM MeasureReport resources conforming to the appropriate MeasureReport profile for the type of report, one for each measure evaluated by the operation. Subsequent entries in the bundle are evaluated resources referenced by the MeasureReport(s). See the guidance on Bundle structure for discussion about the Bundle content and organization. Note that even though there is a single parameter named return of type Bundle, it is a multi-cardinality parameter, and so will still be returned using a Parameters resource, as described in the general operations framework. |