GuidanceResponse

Introduction

Scope and Usage

The GuidanceResponse resource is used to represent the result of invoking a decision support service. It provides a container for the status of the response, any warnings or messages returned by the service, as well as any output data from the service and any suggested actions to be performed.

Use cases for the GuidanceResponse resource include:

• Keeping a record of past service requests, including the ability to reference the context of the request such as the disease state
• Representing additional data requirements for subsequent service requests
• Representing Public Health case reporting and recording
• Sharing the results of decision support guidance and determination of reportability with clinicians and public health agencies

In addition, the GuidanceResponse resource is aligned with the CDS Hooks response structure and so provides a mechanism to record the results of CDS Hooks interactions. For a detailed discussion of how the GuidanceResponse resource can be used for this purpose, refer to the Evaluation topic in the Clinical Reasoning module.

Boundaries and Relationships

Explains how this resource relates to others. Particularly important is to differentiate between appropriate usages for related resources when an implementer might be confused about what to reference when.

Background and Context

Provides additional detail on exactly how the resource is to be used

Notes

GuidanceResponse Search

Although the GuidanceResponse resource does define search parameters, it is up to the individual decision support service whether or not historical records of guidance requests are preserved. A service might not support searching on GuidanceResponses at all, or it may support searching only for a pre-defined expiration period. The search parameters are defined to provide consumers with a consistent interface to searching if it is available for a specific service implementation. In any case, services should detail the support they do provide using a CapabilityStatement.

StructureDefinition

Elements (Simplified)

• GuidanceResponse [0..*]: - The formal response to a guidance request
• GuidanceResponse.requestIdentifier [0..1]: Identifier The identifier of the request associated with this response, if any
• GuidanceResponse.identifier [0..*]: Identifier Business identifier for guidance response
• GuidanceResponse.module[x] [1..1]: uri, canonical, CodeableConcept example:guidance-module-code What guidance was requested
• GuidanceResponse.status [1..1]: code required:guidance-response-status success | data-requested | data-required | in-progress | failure | entered-in-error
• GuidanceResponse.subject [0..1]: [Reference(Patient](/Reference(Patient), Group)) Individual service was done for/to
• GuidanceResponse.encounter [0..1]: Reference(Encounter) Encounter the guidance response is part of
• GuidanceResponse.occurrenceDateTime [0..1]: dateTime When the guidance response was processed
• GuidanceResponse.performer [0..1]: Reference(Device) Device returning the guidance
• GuidanceResponse.location [0..1]: Reference(Location) Where guidance response occurred
• GuidanceResponse.reason [0..*]: CodeableReference Why guidance is needed
• GuidanceResponse.note [0..*]: Annotation Additional notes about the response
• GuidanceResponse.evaluationMessage [0..1]: Reference(OperationOutcome) Messages resulting from the evaluation of the artifact or artifacts
• GuidanceResponse.outputParameters [0..1]: Reference(Parameters) The output parameters of the evaluation, if any
• GuidanceResponse.result [0..*]: [Reference(Appointment](/Reference(Appointment), AppointmentResponse, CarePlan, Claim, CommunicationRequest, Contract, CoverageEligibilityRequest, DeviceRequest, EnrollmentRequest, MedicationRequest, NutritionOrder, RequestOrchestration, ServiceRequest, Task, VisionPrescription)) Proposed actions, if any
• GuidanceResponse.dataRequirement [0..*]: DataRequirement Additional required data

Mappings

• GuidanceResponse Mappings — 18 mapping entries

Resource Packs

list-GuidanceResponse-packs.xml

<?xml version="1.0" encoding="UTF-8"?>

<List xmlns="http://hl7.org/fhir">
  <id value="GuidanceResponse-packs"/>
  <status value="current"/>
  <mode value="working"/>
</List>

Search Parameters

• identifier — token — The identifier of the guidance response — GuidanceResponse.identifier
• patient — reference — The identity of a patient to search for guidance response results — GuidanceResponse.subject.where(resolve() is Patient)
• request — token — The identifier of the request associated with the response — GuidanceResponse.requestIdentifier
• subject — reference — The subject that the guidance response is about — GuidanceResponse.subject
• status — token — The status of the guidance response — GuidanceResponse.status

Full Search Parameters

Examples

• additional-data-example — guidanceresponse-additional-data-example — Example of guidanceresponse requesting additional data
• example — guidanceresponse-example — Example of guidanceresponse
• guidanceresponse-example — guidanceresponse-example
• guidanceresponse-examples-header — guidanceresponse-examples-header

Full Examples

Mapping Exceptions

guidanceresponse-event-mapping-exceptions.xml

Divergent Elements

• Event.status → GuidanceResponse.status
  • shortUnmatched | reason=Guidance response statuses are specific to the response to the request for guidance from a service. | pattern=preparation | in-progress | not-done | suspended | aborted | completed | entered-in-error | unknown | resource=success | data-requested | data-required | in-progress | failure | entered-in-error
  • definitionUnmatched | reason=Guidance response statuses are specific to the response to the request for guidance from a service. | pattern=The current state of the guidance response. | resource=The status of the response. If the evaluation is completed successfully, the status will indicate success. However, in order to complete the evaluation, the engine may require more information. In this case, the status will be data-required, and the response will contain a description of the additional required information. If the evaluation completed successfully, but the engine determines that a potentially more accurate response could be provided if more data was available, the status will be data-requested, and the response will contain a description of the additional requested information.
  • commentsUnmatched | reason=Guidance response statuses are specific to the response to the request for guidance from a service. | pattern=A nominal state-transition diagram can be found in the (Event pattern documentation

Unknown does not represent "other" - one of the defined statuses must apply. Unknown is used when the authoring system is not sure what the current status is. | resource=This element is labeled as a modifier because the status contains codes that mark the resource as not currently valid.

• Event.subject → GuidanceResponse.subject
• Event.occurrence[x] → GuidanceResponse.occurrenceDateTime
  • missingTypes | reason=Guidance response is returned at a specific point in time | pattern=Period, Timing
  • shortUnmatched | reason=More specific text | pattern=When guidance response occurred/is occurring | resource=When the guidance response was processed
  • definitionUnmatched | reason=More specific text | pattern=The date, period or timing when the guidance response did occur or is occurring. | resource=Indicates when the guidance response was processed.
  • commentsUnmatched | reason=Unnecessary because the type is specific | pattern=This indicates when the activity actually occurred or is occurring, not when it was asked/requested/ordered to occur. For the latter, look at the occurence element of the Request this {{event}} is "basedOn". The status code allows differentiation of whether the timing reflects a historic event or an ongoing event. Ongoing events should not include an upper bound in the Period or Timing.bounds. .
• Event.performer.actor → GuidanceResponse.performer
  • missingTypes | reason=Unknown | pattern=Reference(Practitioner, PractitionerRole, Organization, CareTeam, Patient, RelatedPerson)
  • summary | reason=Not part of summary | pattern=true
  • shortUnmatched | reason=Specific text | pattern=Who performed guidance response | resource=Device returning the guidance
  • definitionUnmatched | reason=Specific text | pattern=Indicates who or what performed the guidance response. | resource=Provides a reference to the device that performed the guidance.
• Event.reason → GuidanceResponse.reason
  • shortUnmatched | reason=More specific text | pattern=Why was guidance response performed? | resource=Why guidance is needed
  • definitionUnmatched | reason=More specific text | pattern=Describes why the guidance response occurred in coded or textual form or Indicates another resource whose existence justifies this guidance response. | resource=Describes the reason for the guidance response in coded or textual form, or Indicates the reason the request was initiated. This is typically provided as a parameter to the evaluation and echoed by the service, although for some use cases, such as subscription- or event-based scenarios, it may provide an indication of the cause for the response.
  • commentsUnmatched | reason=Unknown | pattern=Textual reasons can be captured using reasonCode.text. | resource=Although this reference can be used to point to any resource, it is typically expected to refer to subject-specific data appropriate to the subject of the guidance. For example, patient-based decision support would be expected to reference patient-level data. In addition, implementations should provide as much detail as possible by using the http://hl7.org/fhir/StructureDefinition/targetElement and http://hl7.org/fhir/StructureDefinition/targetPath extensions to indicate the specific elements relevant to providing the reason for the guidance.
• Event.note → GuidanceResponse.note
  • shortUnmatched | reason=More specific text | pattern=Comments made about the event | resource=Additional notes about the response
  • definitionUnmatched | reason=More specific text | pattern=Comments made about the guidance response by the performer, subject or other participants. | resource=Provides a mechanism to communicate additional information about the response.

Unmapped Elements

• Event.partOf — GuidanceResponses are individual
• Event.reported — Reported is not different than occurrence
• Event.relevantHistory — GuidanceResponses are typically logged and not changed
• Event.code — Mapping resulted in ordering changes
• Event.statusReason — Not required
• Event.performer.function — Not required, performer is always a device
• Event.category — Not required
• Event.recorded — Recorded is not different than occurrence
• Event.product — Too specific for guidance response
• Event.performer — This is mapped, just isn't a backbone in this resource
• Event.basedOn — Guidance response is not basedOn other request resources
• Event.researchStudy — Too specific for guidance response

guidanceresponse-fivews-mapping-exceptions.xml

Unmapped Elements

• FiveWs.what — Mapping causes element order warnings
• FiveWs.recorded — Not different than when
• FiveWs.author — Not used
• FiveWs.cause — Not used
• FiveWs.version — Not used
• FiveWs.witness — Not used
• FiveWs.class — Not used
• FiveWs.where — Not used
• FiveWs.init — Not used
• FiveWs.source — Not used
• FiveWs.who — Not used
• FiveWs.grade — Not used
• FiveWs.planned — Not used