Evaluate ServiceDefinition Interaction
This is a FHIR operation performed by the Encounter Management System (EMS). It is an evaluate operation performed against the Service Definition resource to request clinical decision support guidance from a selected Clinical Decision Support System (CDSS).
Trigger for Evaluate ServiceDefinition Interaction
The ServiceDefinition.trigger element is of datatype TriggerDefinition and this structure defines when a knowledge artifact, in this case a ServiceDefinition, is expected to be evaluated.
Within the CDS implementation, the Data Event trigger type has been chosen. This means that the EMS’s evaluation of a ServiceDefinition will be triggered in response to a data-related activity within an implementation, for example by an addition or an update of a record such as a QuestionnaireResponse resource.
The triggering data of the event is described in the trigger.eventData element of the ServiceDefinition and this is populated by the CDSS.
Note: It is the responsibility of the CDSS to ensure the triggering requirements have been met for this journey based on the assertions passed by the EMS.
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. |
MUST |
POST ServiceDefinition
The ServiceDefinition.$evaluate operation is performed by an HTTP POST command as shown:
Parameters
The ServiceDefinition.$evaluate operation has a number of parameters and the EMS will select appropriate IN parameters to include in the operation.
The CDSS will return a GuidanceResponse resource as the OUT parameter of the operation.
IN Parameters
| Name | Cardinality | Type | FHIR Documentation | CDS Implementation Guidance |
|---|---|---|---|---|
requestId |
0..1 |
id | An optional client-provided identifier to track the request. | This MUST be populated. Each invocation of the $evaluate method MUST use a unique requestId The requestId MUST be locally unique |
evaluateAtDateTime |
0..1 |
dateTime | An optional date and time specifying that the evaluation should be performed as though it was the given date and time. The most direct implication of this is that references to "Now" within the evaluation logic of the module should result in this value. In addition, wherever possible, the data accessed by the module should appear as though it was accessed at this time. The evaluateAtDateTime value may be any time in the past or future, enabling both retrospective and prospective scenarios. If no value is provided, the date and time of the request is assumed. | This SHOULD NOT be populated. |
inputParameters |
0..1 |
Parameters | The input parameters for a request, if any. These parameters are defined by the module that is the target of the evaluation, and typically supply patient-independent information to the module. | These will be determined by the EMS and CDSS specific to each implementation. |
inputData |
0..* |
Any | The input data for the request. These data are defined by the data requirements of the module and typically provide patient-dependent information. | The inputData element MUST be populated with FHIR resources detailing the current state of the triage journey as follows:
|
patient |
0..1 |
Reference (Patient) |
The patient in context, if any. | This MUST be populated with a reference to a Patient resource. |
encounter |
0..1 |
Reference (Encounter) |
The encounter in context, if any. | This MUST be populated by the EMS with the logical Id of the Encounter. |
initiatingOrganization |
0..1 |
Reference (Organization) |
The organisation initiating the request. | This SHOULD be populated by the EMS using the logical Id for the UEC service provider. Note that this is the same as the receivingOrganization. If this is an online (patient facing) system, then this MUST NOT be populated. |
initiatingPerson |
0..1 |
Reference (Patient | Practitioner | RelatedPerson) |
The person initiating the request. | This MUST be populated by the EMS. The initiatingPerson is the user of the EMS. This will typically be a Patient or RelatedPerson if the EMS is being used by a member of the public (e.g. a patient-facing public internet system) or a Practitioner where initiatingOrganisation is populated. Note that this is the same as the receivingPerson. |
userType |
0..1 |
CodeableConcept | The type of user initiating the request, e.g. patient, healthcare provider, or specific type of healthcare provider (physician, nurse, etc.). | The userType parameter of note MUST be provided by the EMS. If the userType is patient, then the CDSS SHOULD use first person pronouns. |
userLanguage |
0..1 |
CodeableConcept | Preferred language of the person using the system. | This SHOULD be provided by the EMS, based on the user requirements. |
userTaskContext |
0..1 |
CodeableConcept | The task the system user is performing, e.g. laboratory results review, medication list review, etc. This information can be used to tailor decision support outputs, such as recommended information resources. | This SHOULD be provided by the EMS, as it may be used to tailor decision support outputs. |
receivingOrganization |
0..1 |
Reference (Organization) |
The organization that will receive the response. | This SHOULD be populated with the organisation identifier for the UEC service provider. If this is an online (patient facing) system, then this MUST NOT be populated. Note that this is the same as the initiatingOrganisation. |
receivingPerson |
0..1 |
Reference (Patient | Practitioner | RelatedPerson) |
The person in the receiving organization who will receive the response. | This MUST be populated by the EMS, based on the user. In the case of an online (patient-facing) system, this may be Patient or RelatedPerson. Note that this is the same as the initiatingPerson. |
recipientType |
0..1 |
CodeableConcept | The type of individual that will consume the response content. This may be different from the requesting user type (e.g. if a clinician is getting disease management guidance for provision to a patient). E.g. patient, healthcare provider or specific type of healthcare provider (physician, nurse, etc.). | This will be the patient (or a related person, if telephoning on behalf of the patient). |
recipientLanguage |
0..1 |
CodeableConcept | Preferred language of the person that will consume the content. | This SHOULD be populated by the EMS where known for the recipient and will be populated with the same value as contained in the userLanguage parameter. |
setting |
0..1 |
CodeableConcept | The current setting of the request (inpatient, outpatient, etc). | This MUST be provided by the EMS to give context for decision support. |
settingContext |
0..1 |
CodeableConcept | Additional detail about the setting of the request, if any. | This MUST NOT be populated. |
OUT Parameters
| Name | Cardinality | Type | Documentation |
|---|---|---|---|
return |
1..1 |
GuidanceResponse | The result of the request as a GuidanceResponse resource. Note: as this the only out parameter, it is a resource, and it has the name 'return', the result of this operation is returned directly as a resource. |
ServiceDefinition $evaluate parameters of note
Parameters passed in the ServiceDefinition.$evaluate operation of particular significance to implementers are noted below:
encounter element
This element carries reference to the encounter currently in context for the triage. It is the responsibility of the EMS to identify the correct encounter in each $evaluate interaction with the CDSS to reduce the risk of inappropriate triage.
inputData element
This element carries the triage journey data for the decision. The EMS will populate this element with all assertions collected in a particular triage journey and any other assertions considered to be of relevance.
The CDSS is obliged to consider anything carried in the ServiceDefinition.dataRequirement element, but can ignore resources posted in inputData which are not in the dataRequirement element.
In particular, where there are ‘branching’ or bundled ServiceDefinitions within a single journey, the last ServiceDefinition will have all assertions passed in inputData from prior ServiceDefinitions.
This may or may not affect the population of the result element in GuidanceResponse created by the CDSS.
patient element
It should be noted that within a number of triage scenarios it may not be possible to accurately establish the identity of a patient. In some cases it may be possible to establish their identity, but only at a later stage in their triage.
Some scenarios where this might apply:
- when dealing with an unconscious patient
- when a patient does not wish to disclose their identity
- during an online journey for a system does not establish identity/ only establishes identity later in the journey
In these types of scenario the EMS MUST still populate the Patient resource (.subject). The Patient resource will be populated as appropriate for the EMS. This may be generating a temporary patient identifier, suitably identified, with appropriate information for an unidentified patient.
The manner in which an EMS uses anonymous and interim identifiers is outside the scope of this Implementation Guide.
userType element
The userType element carries the type of user initiating the request to the CDSS. It MUST be populated by the EMS and can have the values Patient, RelatedPerson, or Practitioner.
Response from CDSS
Success
- MUST return a
200OK HTTP status code on successful execution of the operation. - MUST return a
GuidanceResponseresource.
View further information about the result of the triage journey.
Time out
It is recommended that the EMS sets a time out limit on the response back from the CDSS, appropriate to an interactive process (e.g. around 1000 milliseconds).
If the CDSS does not respond within the time out period, then it is recommended that the EMS retry the $evaluate operation. This is to allow for intermittent network errors.
After a limited number of retries (e.g. 3-5) the EMS may assume that the CDSS is unavailable and should respond appropriately to the user.
