Situational Awareness for Novel Epidemic Response, published by HL7 International / Public Health. This guide is not an authorized publication; it is the continuous build for version 1.0.1 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/fhir-saner/ and changes regularly. See the Directory of published versions

Query Measure Definition

This section describes the PULL-MX of this guide. This transaction is used by the Measure Definition Source and Measure Definition Consumer actors.

Scope

The Query Measure Definition transaction allows a Measure Definition Consumer to periodically query about the availability of a resource from an Measure Definition Source.

This transaction enables a MeasureDefinition Consumer actor to access Measure resources from a MeasureDefinitionSource actor. It defines the query parameters that the actors shall and should support for search and read operations that shall be supported.

Actors Roles

Table 2.3-1: Actor Roles

Actor	Role
Measure Definition Source	Reports on available measures in response to a query.
Measure Consumer	Queries for available measures and components.

Referenced Standards

Table 3.71.3-1: Referenced Standards |Standard|Name| |—|—| |FHIR-R4|HL7 FHIR Release 4.0| |RFC-7230|Hypertext Transfer Protocol - HTTP/1.1| |NDJSON|Newline Delimited JSON|

Interactions

Search Request

Trigger Event - A Query is Initiated by User/System

Message Semantics

The Measure Definition Consumer sends a query using an HTTP GET or POST transaction to the Measure Definition Source requesting information on available measures.

The following are general requirements of the interaction.

1. Formats. All servers shall support the _format parameter for any read or search and the standard values defined by FHIR for JSON and XML output. This value shall override the Accept: header when present in an exchange. Servers shall also support the Accept: header, and shall support any value in Accept: that can be given to _format for consistency. Servers are also free to support other output formats (e.g. turtle as defined in the base FHIR specifications, or other formats such as CSV which might be easier for clients to present or use). Servers should support other commonly used expressions representing JSON or XML outputs without complaint, including those specified in prior releases (e.g., the DSTU2 application/xml+fhir or application/json+fhir types that have since changed in R4).

Parameter	Cardinality	Measure Definition Source Expectation	Measure Definition Consumer Expectation
_format=application/fhir+xml|application/fhir+json	0..1	shall	shall
_format=xml|json|text/xml|application/json|application/xml|application/xml+fhir|application/json+fhir	0..1	should	should not
Accept:=application/fhir+xml|application/fhir+json	0..1	shall	shall
Accept:=xml|json|text/xml|application/json|application/xml|application/xml+fhir|application/json+fhir	0..1	should	should not

1. Include Support. To reduce transaction overhead, a client system may wish to retrieve all the resources referenced by the selected resource when obtaining it. This can be accomplished by using a search with an _id parameter, combined with _include=*. This guide does not further specify specify resource includes beyond required support for . Systems that support _include generally handle _include=, in fact, in some ways it is easier to implement than more selective _include operations. Recursive includes can be a source of server loading issues, as an incorrectly implemented include with recursive includes could wind up retrieving far more data than the client expected. Thus, these are not recommended.

Parameter	Cardinality	Measure Definition Source Expectation	Measure Definition Consumer Expectation
_include=*	0..1	shall	shall
_include:iterate		should not	should not

1. The server shall support the _count parameter for queries. Servers should use a default value for _count if no value is provided to avoid server overloading. This guide recommends a default value of 100 based on existing implementation experience.

Parameter	Cardinality	Measure Definition Source Expectation	Measure Definition Consumer Expectation
_count	0..1	shall	shall

Read on Required Resources

A client shall be able to read individual Measure and Library resources that are returned by a query.

The server shall demonstrate the FHIR read operation on the Measure, Library, ValueSet, CodeSystem and ConceptMap resources.

Search by _id on Measure and Library Resources

A client shouldsupport the FHIR search operation on the Measure, Library, ValueSet, CodeSystem and ConceptMap resources with the following parameters. The server shalldemonstrate the FHIR search operation on the Measure, Library, ValueSet, CodeSystem and ConceptMap resources with the following parameters.

1. Search by _id.
   A client shall be able to read individual resources that are returned or referenced within resources returned by a query. Client systems may save resource references for future use, retrieving them later as needed. To reduce overhead, a client system may also wish to retrieve the resources referenced by the selected resource. This can be accomplished by using a search with an _id parameter, combined with _include=*

Parameter	Cardinality	Measure Definition Source Expectation	Measure Definition Consumer Expectation
_id	1..*	shall	shall

1. Search by _url.
   A client shall be able to read individual resources that are returned or referenced within a measure by the canonical url that is used to identify them. Client systems may save resource references for future use, retrieving them later as needed.

Parameter	Cardinality	Measure Definition Source Expectation	Measure Definition Consumer Expectation
url	1..*	shall	shall

Search on Measure Definition Resources

Systems shall be able to retrieve measures needed for automation.

Measures can be identified by codes used in the measure, or by the measure title, its canonical URL, or by something easier for a user to recall, such as the text of the measure or a code within it. Multiple measures may report on the same kind of thing (e.g., beds), so retrieval by code, or by code within a value set should be supported. There may be multiple measures which identify the kind of thing that the client system is interested in learning more about. Search by code should be met by implementing the SearchParameter-code search parameter.

However, search by code is not supported by default by many off-the-shelf systems, and so this is not a strict requirement for implementers. Also, chained searching is also not always readily available, and so search by measure title is also not a hard requirement. At the very least, a server shall be able to search by measure, and a client shall also to ensure the greatest interoperability between systems with differing capabilities.

A client should support the FHIR search operation on the Measure resource with the following parameters. The server shall demonstrate the FHIR search operation on the Measure resource with the following parameters.

1. Search by Text or Code. A client system should be able to search for Measure definitions. This requirement can be met through support of the _text or _content search parameters, or by implementation of the definition-text SearchParameter.

Parameter	Cardinality	Measure Definition Source Expectation	Measure Definition Consumer Expectation
_text	0..*	SHOULD	SHOULD
_content	0..*	SHOULD	SHOULD
definition-text	0..*	SHOULD	SHOULD
code	0..*	SHOULD	SHOULD
code:in	0..*	SHOULD	SHOULD

Expected Actions

Search for Measure

The Measure Definition Consumer performs a FHIR Search operation to retrieve the selected measures.

Search Response

The Measure Definition Source returns the requested results results.

Trigger Event - Resources have been requested by a Measure Definition Consumer.

Message Semantics

The Measure Definition Source responds with requested resources.

The resources will conform to the profile for the Public Health Measure described elsewhere in this Implementation Guide

Expected Actions

Returns Matching Measure Resources

The Measure Definition Source returns the requested resource.

Conformance

See the following CapabilityStatement resources for conformance requirements:

• CapabilityStatement-MeasureDefinitionSource-QueryMeasureDefinition Defines the requirements for the Measure Definition Source implementing the Query Measure Definition transaction.
• CapabilityStatement-MeasureDefinitionConsumer-QueryMeasureDefinition Defines the requirements for the Measure Definition Consumer implementing the Query Measure Definition transaction.