STU3 Candidate

This page is part of the FHIR Specification (v1.8.0: STU 3 Draft). The current version which supercedes this version is 5.0.0. For a full list of available versions, see the Directory of published versions

This section of the clinical reasoning module discusses the evaluation use case for clinical decision support and how the various knowledge artifacts can be integrated into clinical workflow.

The ServiceDefinition resource provides a mechanism for describing the functionality made available by a particular service. For example, a service may provide an immunization forecasting module or a drug-drug interaction checking module. From the perspective of the consumer, how this functionality is performed is irrelevant; the only aspect of interest is a description of what the service module does, the required inputs and the outputs it produces.

As such, this resource uses the same metadata elements to define the common information relevant to all knowledge artifacts, and then defines the input and output parameters as well as any data requirements for the service module in the same way that parameters and data requirements are defined for expression logic in general.

As an example, the functionality defined by the Guideline Appropriate Ordering IG can be expressed as a ServiceDefinition: Service Definition Example.

<ServiceDefinition>
  <id value="example"/>
  <text>
  <status value="generated" />
  <div xmlns="http://www.w3.org/1999/xhtml">Guideline Appropriate Ordering Module</div>
  </text>
    
  <identifier>
    <use value="official"/>
    <value value="guideline-appropriate-ordering"/>
  </identifier>
  <version value="1.0.0"/>
  <title value="Guideline Appropriate Ordering Module"/>
  <status value="draft"/>
  <description value="Guideline appropriate ordering is used to assess appropriateness of an order given a patient, a proposed order, and a set of clinical indications."/>
  <publicationDate value="2015-07-22"/>
  <topic>
    <text value="Guideline Appropriate Ordering"/>
  </topic>
  <topic>
    <text value="Appropriate Use Criteria"/>
  </topic>
    
  <!-- Patient Parameter -->
  <parameter>
    <name value="patient"/>
    <use value="in"/>
    <type value="Patient"/>
    <profile>
      <reference value="http://hl7.org/fhir/StructureDefinition/gao-patient"/>
    </profile>
  </parameter>

  <!-- Order Parameter -->
  <parameter>
    <name value="order"/>
    <use value="in"/>
    <type value="Order"/>
    <profile>
      <reference value="http://hl7.org/fhir/StructureDefinition/gao-order"/>
    </profile>
  </parameter>
  
  <!-- Order Output -->
  <parameter>
    <name value="order"/>
    <use value="out"/>
    <type value="Order"/>
    <profile>
      <reference value="http://hl7.org/fhir/StructureDefinition/gao-order"/>
    </profile>
  </parameter>
  
  <!-- Result -->
  <parameter>
    <name value="result"/>
    <use value="out"/>
    <type value="Basic"/>
    <profile>
      <reference value="http://hl7.org/fhir/StructureDefinition/gao-result"/>
    </profile>
  </parameter>
    
</ServiceDefinition>

The ServiceDefinition resource defines an $evaluate operation that allows for consistent invocation of decision support functionality across a broad range of decision support artifacts. This consistency enables consumers to implement the request/response pipeline once to enable access to any decision support functionality provided by the service.

The GuidanceResponse structure provides a general mechanism for representing the actions to be performed in response to a guidance evaluation request.

The $evaluate operation provides a complete example of a request and response using the Guideline Appropriate Ordering decision support service module: $evaluate operation example.

In the simplest case, an application requests guidance from a decision support service as part of a particular trigger, usually a specific point in a clinical workflow.

Synchronous, Direct Guidance Request

For example, on the placement of an order for a specific imaging study, the application performs an $evaluate on the Guideline Appropriate Ordering service module:

EHR Radiology Workflow Example
POST [base]/ServiceDefinition/example/$evaluate
  
<Parameters>
  <id value="evaluate-operation-request-example"/>
  <!--  This example demonstrates the $evaluate operation against a ServiceDefinition resource. -->
  <parameter>
    <name value="requestId"/>
    <valueString value="guidanceRequest1"/>
  </parameter>
  <parameter>
    <name value="setting"/>
    <valueCoding>
      <system value="http://hl7.org/fhir/encounter-class"/>
      <code value="inpatient"/>
    </valueCoding>
  </parameter>
  <parameter>
    <name value="patient"/>
    <resource>
      <Patient>
        <id value="example"/>
        <meta>
          <profile value="http://hl7.org/fhir/StructureDefinition/qicore-patient"/>
          <profile value="http://hl7.org/fhir/StructureDefinition/gao-patient"/>
        </meta>
        ... <!-- Excluded for brevity -->
      </Patient>
    </resource>
  </parameter>
  <parameter>
    <name value="order"/>
    <resource>
      <Order>
        <id value="order1"/>
        <meta>
          <profile value="http://hl7.org/fhir/StructureDefinition/gao-order"/>
        </meta>
        <contained>
          <DiagnosticRequest>
            <id value="DiagnosticRequest1"/>
            <meta>
              <profile value="http://hl7.org/fhir/StructureDefinition/gao-diagnosticrequest"/>
            </meta>
            <subject>
              <reference value="Patient/example"/>
            </subject>
            <item>
              <code>
                <coding>
                  <system value="http://www.ama-assn.org/go/cpt"/>
                  <code value="70450"/>
                  <display value="CT, head, wo iv contrast"/>
                </coding>
              </code>
            </item>
          </DiagnosticRequest>
        </contained>
        <date value="2012-12-28T09:03:04+11:00"/>
        <subject>
          <reference value="Patient/example"/>
        </subject>
        <source>
          <reference value="Practitioner/example"/>
        </source>
        <reasonCodeableConcept>
          <coding>
            <system value="http://hl7.org/fhir/sid/icd-9"/>
            <code value="70450"/>
            <display value="Headache, Chronic, no new features"/>
          </coding>
        </reasonCodeableConcept>
        <detail>
          <reference value="#DiagnosticRequest1"/>
        </detail>
      </Order>
    </resource>
  </parameter>
</Parameters>

The above example uses the profiles defined in the Guideline Appropriate Ordering IG. In this specific case, the request includes the patient information, and the order being assessed includes the indication and the procedure.

The decision support service processes the request and determines whether the order is appropriate given the patient information and indication for the requested procedure. The result is returned as a GuidanceResponse resource with a status of success, and the calling application examines the appropriateness score and determines the appropriate action to take: either proceed with placing the order, or prompt the user that the requested procedure is not appropriate based on the guidelines returned in the response. An example response is shown below.

<GuidanceResponse>
  <!-- This example demonstrates the response to an $evaluate operation using the GuidanceResponse resource. -->
  <contained>
    <Parameters>
      <id value="outputParameters1"/>
      <parameter>
        <name value="order"/>
        <valueReference>
          <reference value="#order1"/>
        </valueReference>
      </parameter>
      <parameter>
        <name value="result"/>
        <resource>
          <!-- GAO Result, profile of Basic -->
          <Basic>
            <id value="result1"/>
            <meta>
              <profile value="http://hl7.org/fhir/StructureDefinition/result-gao-gao-result"/>
            </meta>
            <extension url="http://hl7.org/fhir/StructureDefinition/result-gao-score">
              <valueDecimal value="7"/>
            </extension>
            <extension url="http://hl7.org/fhir/StructureDefinition/result-gao-item">
              <extension url="http://hl7.org/fhir/StructureDefinition/result-gao-item#code">
                <valueCodeableConcept>
                  <coding>
                    <system value="http://www.ama-assn.org/go/cpt"/>
                    <code value="70450"/>
                    <display value="CT, head, wo iv contrast"/>
                  </coding>  
                </valueCodeableConcept>
              </extension>
            </extension>
            <!-- Appropriate Use Criteria Identifier -->
            <extension url="http://hl7.org/fhir/StructureDefinition/result-gao-guideline">
              <valueUri value="http://someguidelineprovider.org/radiology-appropriateness-guidelines.html"/>
            </extension>
            <!-- Certified HealthCare Information Technology Identifier -->
            <extension url="http://hl7.org/fhir/StructureDefinition/result-gao-device">
              <valueReference>
                <reference value="#device1"/>
              </valueReference>
            </extension>
            <!-- Provider NPI -->
            <extension url="http://hl7.org/fhir/StructureDefinition/result-gao-practitioner">
              <valueIdentifier>
                <value value="exampleNPI"/>
              </valueIdentifier>
            </extension>
            <identifier>
              <value value="result1"/>
            </identifier>
            <code>
              <coding>
                <code value="within"/>
                <display value="Order is within identified guidelines"/>
              </coding>
            </code>
            <subject>
              <reference value="#order1"/>
            </subject>
          </Basic>
        </resource>
      </parameter>
    </Parameters>
  </contained>
  <requestId value="guidanceRequest1"/>
  <module>
    <reference value="ServiceDefinition/example"/>
  </module>
  <status value="success"/>
  <outputParameters>
    <reference value="#outputParameters1"/>
  </outputParameters>
</GuidanceResponse>

Note that this example is incomplete and reproduced here for illustration purposes only. Refer to the Guideline Appropriate Ordering Implementation Guide for a more complete description of GAO.

There are three types of data that can be provided as part of a decision support service module evaluation request:

  • Context - Context information such as the patient and encounter in context.
  • Parameters - Service Module specific parameters.
  • Data Requirements - Service Module specific data, described using the DataRequirement structure.

In the same way that parameters and data requirements are both supported for expressions in general (see the Parameters and Data Requirements topics in the Using Expressions section), decision support service modules can describe data inputs as input parameters, or as data requirements.

Contextual information for every decision support service module is defined by the parameters on the base $evaluate operation. This contextual information includes the patient, the encounter, and workflow information.

The client provides this information using the normal mechanism for passing parameters using the Parameters resource.

Note that contextual information is defined as completely optional on the base $evaluate operation definition. However, specific service modules may override this behavior by redefining a contextual parameter, providing constraints on its use. This approach may only be used to apply cardinality and profile constraints. The type of a parameter may not be changed.

Input parameters allow the service module to declare specific data, usually patient-independent, such as configuration parameters. For example, a Diabetes Control service module may expose an A1C threshold as a parameter to allow for institutional and practitioner variance.

The client provides this information in the same way as the contextual parameters (i.e. additional parameter elements in the Parameters resource for the request), but these parameters are provided in addition to the ones defined by the $evaluate operation definition. This means that the set of parameters provided to the request may vary based on the service module being invoked.

Data requirements, on the other hand, allow the service module to declare input requirements in terms of the type of data involved, as well as constraints on that data. For example, a service module may declare that it requires A1C Observations for the past year in order to perform a successful evaluation.

Both options are provided to support a broad variety of service modules. However, note that declaring specific input parameters requires that a client build implementation logic specific to each service module. The data requirements approach allows for a generic data retrieval mechanism, independent of the specific service module being invoked.

Similar to the mechanism for any FHIR operation, evaluation results may be provided by defining specific output parameters on the service module. This is the approach taken by the GAO example provided above, where the results of the evaluation are provided as output parameters. However, as with the input parameters, defining specific output parameters on the service module requires that consumers build implementation logic specific to each service module.

In addition to results as output parameters, the GuidanceResponse resource allows actions to be described that indicate what actions should be performed. The action element of the GuidanceResponse mirrors the structure of the actionDefinition elements in a PlanDefinition, providing the ability to describe actions that should be performed in terms of creating, updating, or deleting a resource, or invoking a specific event.

Again, both options are provided to support a broad variety of service modules and implementation approaches.

To enable asynchronous request/response, the GuidanceResponse supports a status of in-progress. For this result, the HTTP response SHOULD include the Retry After header with an appropriate indication for the expected wait time.

In this case, the client is expected to reissue the request with the same requestId. To reduce bandwidth requirements, when reissuing a request the client need not send the input information. If the request is complete, a GuidanceResponse with an appropriate completion status (success, failure, or one of the data statuses) will be returned. If the request is still pending, a GuidanceResponse with a status of in-progress is returned.

In some cases, the decision support service may determine that additional information is required in order to continue processing, or that additional information may result in a more accurate or more appropriate result:

Synchronous, Direct Guidance Conversation

In these cases, the GuidanceResponse will be returned with a status of data-requested or data-required, to indicate the particular scenario. In these cases, the GuidanceResponse will contain additional information, stated in the form of additional DataRequirement specifications, to let the calling application know what data is needed. The calling application then repeats the request, providing the additional requested information, and the service continues processing.

The data-requested status is used to indicate that although the request was processed successfully and a result is provided, a more accurate or relevant result may be obtained by sending the additional requested information.

The data-required status is used to indicate that the request cannot be completed successfully without the additional required information.

Both these statuses may be used to coordinate conversational request/response.

To support the ability to issue multiple requests, use a Bundle of type batch. In this case, the input data is provided as resource entries in the bundle, with the operations specified as request entries.

The response to posting a batch Bundle containing $evaluate requests is a batch Bundle containing the GuidanceResponse resource results of each $evaluate, as though each request had been submitted independently. Note that this does not imply that the requests must be performed serially; the service is free to implement the requests in any order, including parallelizing the requests.

In addition to direct integration, the $evaluate operation can be used as a component within a larger infrastructure. For example:

Decision Support Service Scenario

In this scenario, the decision support service registers with an Event Publishing Service (EPS) to be notified when events of interest occur. An EHR subscribed to the same EPS system can then integrate with the decision support service without needing to know anything about the servicing system (or systems).

Note that whether the integration uses the direct or conversational approach is independent of whether the infrastructure used is direct through a synchronous call, or indirect through an EPS system or messaging bus. This is possible because from the perspective of the consumer, the service is stateless; conversational coordination is based on requests for additional information.