Evaluate Response

Important: This site is under active development by NHS Digital and is intended to provide all the technical resources you need to successfully develop applications using the FHIR® CDS API.

Evaluate Response

The GuidanceResponse is the synchronous response generated by the Clinical Decision Support System (CDSS). It is returned by the CDSS in response to the EMS’s ServiceDefinition.$evaluate operation. It carries the status of the response, any warnings or messages returned by the service, as well as the output data of the module and the result in the form of any suggested actions to be performed.

View the CDS implementation guidance for a GuidanceResponse.

Result interaction

Any triage interaction undertaken by a user needs to end by providing an appropriate recommendation as to what action to perform next. To facilitate the above user outcomes each ServiceDefinition should in turn end in either:

Care advice,
A referral to a service, or
Redirection to a more appropriate ServiceDefinition based on the responses entered by the user

For example, a user might initially answer questions related to a ServiceDefinition for a rash. If their responses suggested potential meningitis, the system should have the ability to switch to a ServiceDefinition relating to meningitis so that an appropriate triage can be completed.

A ServiceDefinition may need to be capable of redirecting to multiple other ServiceDefinitions. For example, dependent on what answers are provided a ServiceDefinition relating to headache might need to redirect to ServiceDefinitions such as migraine, head injury or stroke.

Given that a ServiceDefinition may redirect to other appropriate ServiceDefinitions there is potential for:

A circular user journey, i.e. the user being asked questions that have already been answered earlier in the journey
An unintended loop within the system, where ServiceDefinitions directly or indirectly redirect to each other

The possibility of this occurring will be based on the CDSS triage logic. Deploying organisations should configure their solution to prevent being directed back to a previous ServiceDefinition unintentionally.

It is recommended that testing is undertaken to ensure a given solution can prevent unintentional looping.

Request Headers

The following HTTP request headers are supported for this interaction:

Header	Value	Conformance
`Accept`	The `Accept` header indicates the format of the response the client is able to understand, this will be one of the following `application/fhir+json` or `application/fhir+xml`. See the RESTful API Content types section.	MAY
`Authorization`	The `Authorization` header MUST carry a base64url encoded JSON web token. See the RESTful API Security section.	MAY

Key Aspects of the Return GuidanceResponse Interaction

Key aspects of this interaction which are of particular significance to implementers are noted below:

Outcome of the Triage Journey

This is carried in the result element of the GuidanceResponse. The outcome of the triage journey is displayed to the user by the EMS.

There are three main outcomes for a triage journey and these are outlined below:-

1. Triage referral

A recommendation as to where the patient should go next; the result element in GuidanceResponse MUST be populated with a RequestGroup resource which will reference a ReferralRequest.

The details of the referral carried in the ReferralRequest may be displayed to the user by the EMS. This referral may be also used to drive a directory search within the EMS to locate a specific provider, location or service for a patient.

View CDS implementation guidance for a ReferralRequest

2. Care Advice

Care advice for the patient (or third party) on actions that can be performed now to either assist the patient, or to assist the triage process.

More than one piece of care advice may be appropriate for a given triage, for example in a scenario where a patient has multiple injuries requiring care
The result element in GuidanceResponse MUST be populated with a RequestGroup resource which will reference at least one CarePlan, and may optionally reference a ReferralRequest
Any care advice carried in the one or more CarePlan resources MUST be displayed to the user by the EMS.

View CDS implementation guidance for a CarePlan

3. Redirection of the Service Definition

A recommendation to redirect to a different ServiceDefinition; the result element in GuidanceResponse SHOULD NOT be populated. Additionally, the GuidanceResponse.dataRequirement element will be used to carry a description of the data required by the EMS to enable it to select the new ServiceDefinition as directed by the CDSS.

View CDS implementation guidance for a GuidanceResponse

The final result or outcome of a triage journey will be available only when the GuidanceResponse.status is set to ‘success’.

Status of the returned GuidanceResponse

The status of the GuidanceResponse is a trigger for the Encounter Management System (EMS). It MUST contain one of the following values:

Code	Display	Definition
`success`	Success	The request was processed successfully
`data-requested`	Data Requested	The request was processed successfully, but more data may result in a more complete evaluation
`data-required`	Data Required	The request was processed, but more data is required to complete the evaluation

Status of success

This means that the result is ready and no further Questionnaires are posted in the GuidanceResponse.
The CDSS has all information possible for the ServiceDefinition to which the GuidanceResponse is responding and has provided a result.
If the CDSS is recommending a referral to another service, the GuidanceResponse.result element will reference a RequestGroup which will in turn reference a ReferralRequest with a status of active. This referral may be accompanied by care advice (not self-care) and/or information about a procedure which the recommended service is expected to provide.
If the CDSS is recommending care advice for a patient, the result element will reference a RequestGroup which will reference a CarePlan with a status of active.
Alternatively, the result element will be null and the GuidanceResponse.dataRequirement element will be used to carry a description of the data required by the EMS to enable it to select the new ServiceDefinition as directed by the CDSS.

The table below gives additional information relating to outcome scenarios when the status element of the GuidanceResponse is set to ‘success’:

Result	Status of the GuidanceResponse	Resource(s) referenced from GuidanceResponse	Additional information
The CDSS has completed successfully with a recommendation of what service the patient should use next.	success	`GuidanceResponse` references `RequestGroup` which in turn references `ReferralRequest` to carry the information pertinent to the recommended referral.	The `ReferralRequest` will have a `status` of 'active'.
The CDSS has completed successfully with a recommendation of what service the patient should use next and there is a known procedure which the referring service is intended to perform.	success	`GuidanceResponse` references `RequestGroup` which references `ReferralRequest` which in turn references `ProcedureRequest`.	The `ReferralRequest` and the `ProcedureRequest` will have a `status` of 'active'.
The CDSS has completed successfully with a recommendation regarding what service the patient should use next and also some care advice (not self-care) for the patient.	success	`GuidanceResponse` references `RequestGroup` which references `ReferralRequest` which in turn references one or more `CarePlans`.	The `ReferralRequest` and the `CarePlan` will have a `status` of 'active'.
The CDSS has completed successfully with some recommended care advice (self-care) for the patient.	success	`GuidanceResponse` references `RequestGroup` which references a `CarePlan`.	The `CarePlan` will have a `status` of 'active'.
The CDSS has completed successfully and has re-directed the user to a new `ServiceDefinition`.	success	`GuidanceResponse.result` is null and the `GuidanceResponse.dataRequirement` element will be used to carry a description of the data required by the EMS to enable it to select the new `ServiceDefinition`.

Status of data-requested

This means that the CDSS has sufficient information to render a result, but additional information will provide a better result. There are additional Questionnaire resources in the GuidanceResponse which SHOULD be answered.
The result element in GuidanceResponse MUST be populated with a RequestGroup resource.
If the CDSS is recommending an interim or initial recommendation relating to a referral to another service, the RequestGroup will reference a ReferralRequest in draft status.
Care advice may additionally be given alongside this interim referral recommendation. If the CDSS is additionally recommending care advice (not self-care), the ReferralRequest will also reference a CarePlan in draft status.
If the CDSS is recommending an interim or initial recommendation relating to care advice for the patient (self-care), the RequestGroup will reference a CarePlan in draft status.
The dataRequirement element in GuidanceResponse MUST be populated with at least one Questionnaire.

The table below gives additional information relating to outcome scenarios when the status element of the GuidanceResponse is set to ‘data-requested’:

Result	Status of the GuidanceResponse	Resource(s) referenced from GuidanceResponse	Additional information
The CDSS has sufficient information to recommend a referral, but additional information will provide a better result.	data-requested	`GuidanceResponse` references `RequestGroup` which in turn references `ReferralRequest` to carry the information pertinent to the recommended referral.	The `ReferralRequest` will have a `status` of 'draft' updating to 'active' when the finalised score is available. When the result is final, the `GuidanceResponse.status` SHOULD be 'success' as above.
The CDSS has sufficient information to make a recommendation regarding what service the patient should use next and there is also a recommendation relating to a care plan (not self-care).	data-requested	`GuidanceResponse` references `RequestGroup` which references `ReferralRequest` which in turn references `CarePlan`.	The `ReferralRequest` and the `CarePlan` will have a `status` of 'draft' updating to 'active' when the finalised score is available. When the result is final, the `GuidanceResponse.status` SHOULD be 'success' as above.

Status of data-required

This means that the CDSS has insufficient information to render an outcome. There are additional Questionnaire(s) in the GuidanceResponse which MUST be answered.
The result element in GuidanceResponse MAY be populated with a RequestGroup, for example referencing one or more CarePlans or one ReferralRequest.
The CDSS can make a referral during the triage journey, and also wish to continue the triage process. This is referred to as an inline referral, and is commonly done for Ambulance Despatch.
This can be represented by setting GuidanceResponse.status to ‘data-required’, but populating the result element with a ReferralRequest resource with a status of ‘active’. Care advice can be given with this inline referral (not self-care). The CDSS can also recommend inline care advice (self care). The dataRequirement element in GuidanceResponse MUST be populated with at least one Questionnaire.

The table below gives additional information relating to outcome scenarios when the status element of the GuidanceResponse is set to ‘data-required’:

Result	Status of the GuidanceResponse	Resource(s) referenced from GuidanceResponse	Additional information
The CDSS is requesting additional information from the EMS using a `Questionnaire` resource.	data-required	A `GuidanceResponse` is returned which references one or more `Questionnaires`.
The CDSS is making an inline referral.	data-required	`GuidanceResponse` references `RequestGroup` which references `ReferralRequest`.	The `ReferralRequest` will have a `status` of 'active'.
The CDSS is making an inline referral with care advice (not self-care).	data-required	`GuidanceResponse` references `RequestGroup` which references `ReferralRequest` which in turn references `CarePlan`.	The `ReferralRequest` and the `CarePlan` will have a `status` of 'active'.
The CDSS is giving inline care advice (self-care).	data-required	`GuidanceResponse` references `RequestGroup` which references a `CarePlan`.	The `CarePlan` will have a `status` of 'active'.

OutputParameters of the returned GuidanceResponse

As users input answers to triage questions, the EMS will relay them to the CDSS within the QuestionnaireResponse element.

In response the CDSS will generate assertions, which will be captured in the GuidanceResponse.outputParameters element. Within this element, the CDSS MUST also return the QuestionnaireResponse resources originally populated by the EMS. Not all QuestionnaireResponses will generate assertions, but any QuestionnaireResponse which can generate an assertion MUST generate an assertion.

Tags:

API Hub

Explore and Make use of Nationally Defined Messaging APIs

Evaluate Response