Select ServiceDefinition Interaction
This action is performed by the Encounter Management System (EMS) in order to get a ServiceDefinition from a Clinical Decision Support System (CDSS).
When the CDSS publishes a ServiceDefinition, the ServiceDefinition will have elements which describe how the ServiceDefinition can be used, for example the ServiceDefinition.useContext element could carry patient gender, age group.
The description of where in the clinical process a ServiceDefinition sits is described in the ServiceDefinition.trigger. This element will hold all the data conditions which need to be satisfied for the ServiceDefinition to be chosen.
The ServiceDefinition.trigger will typically be defined through Observation resources which MUST be true in order for the ServiceDefinition to be suitable for evaluation. For a given CDSS, these will typically be aligned to the ServiceDefinition.dataRequirements of a prior ServiceDefinition.
Each CDSS SHOULD provide a ServiceDefinition where the trigger is NULL (e.g. no information is required).
During a given patient journey, there may be points where there is more than one ServiceDefinition available. Any one CDSS should avoid this situation, but if a provider has more than one CDSS available, there may be situations where more than one CDSS can provide an appropriate ServiceDefinition. In this case, it will be up to local providers on how to choose between the available ServiceDefinitions.
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 |
Get ServiceDefinition
The EMS will select a preferred ServiceDefinition using chosen parameter(s).
The interaction is performed by the FHIR RESTful search interaction as shown:
Search Parameters and Responses
Detailed guidance relating to searching for FHIR resources can be viewed.
Guidance on search parameters for a ServiceDefinition is available.
Two scenarios which may be used to search for a ServiceDefinition in the CDS context are outlined below:
Searching for a ServiceDefinition by _id
The search parameter _id refers to the logical id of the ServiceDefinition resource and would be used when the EMS already knows the _id of the required ServiceDefinition.
When the _id search parameter is used by the EMS it SHALL only be used as a single search parameter and SHALL not be used in conjunction with any other search parameter to form part of a combination search query with the exception of the _format parameter.
The _id parameter can be used as follows:
This search finds the ServiceDefinition resource with the given id (there can only be one resource for a given id).
Further details relating to the _id search parameter are available.
Search Response
Success
- MUST return a
200OK HTTP status code on successful execution of the interaction. - MUST return a
Bundleof type searchset, containing either:- One
ServiceDefinitionresource or - A ‘0’ (zero) total value indicating no record was matched e.g. an empty
Bundle.
- One
Failure
The following errors can be triggered when performing this operation:
- Invalid parameter (if using the ‘_format’ parameter without a mime type recognised by a CDSS or EMS server).
- Resource not found
Searching for a ServiceDefinition using defined search parameters
A second scenario would occur when an EMS searches for a ServiceDefinition using a combination of the search parameters listed below.
The parameters can be used independently or in combination to help refine the search results returned.
This section outlines the search parameter syntax used, with some examples provided.
| Name | Type | Description | Conformance | Path |
|---|---|---|---|---|
status |
token |
The status of this service definition | SHOULD | ServiceDefinition.status |
experimental |
token |
For testing purposes, not real usage | SHOULD | ServiceDefinition.experimental |
effective |
date |
When the service definition is expected to be used | SHOULD | ServiceDefinition.effectivePeriod |
jurisdiction |
token |
Intended jurisdiction for service definition (if applicable) | SHOULD | ServiceDefinition.jurisdiction |
| The following search parameters have been defined using the SearchParameter resource. More details can be found here. | ||||
useContext-code |
token |
Type of context being specified | SHOULD | ServiceDefinition.useContext.code |
useContext-valueconcept |
token |
Value that defines the context | SHOULD | ServiceDefinition.useContext.valueCodeableConcept |
useContext-valuequantityrange |
quantity |
Value that defines the context | SHOULD | ServiceDefinition.useContext.valueQuantityServiceDefinition.useContext.valueRange
|
trigger-type |
token |
The type of triggering event | MUST | ServiceDefinition.trigger.type |
trigger-eventdata-type |
token |
The type of the required data | MUST | ServiceDefinition.trigger.eventData.type |
trigger-eventdata-profile |
uri |
The profile of the required data | MUST | ServiceDefinition.trigger.eventData.profile |
trigger-eventdata-valuecoding |
code |
The code of the required data | MUST | ServiceDefinition.trigger.eventData.valueCoding.code |
status
To search for ServiceDefinition(s) with a status of ‘active’, the following search would be executed:
See token for details relating to the type of this parameter.
experimental
To search for ServiceDefinition(s) which has not been developed for testing purposes, the following search would be executed:
See token for details relating to the type of this parameter.
effective
To search for ServiceDefinition(s) whose content was effective at the time of the search.
If the date when the search was executed was 31-03-2019, the following search would be executed:
See date for details relating to the type of this parameter.
useContext-code
To search for a ServiceDefinition by its context type as specified in the ServiceDefinition.useContext.code element, for example a context of ‘gender’, the following search could be executed:
You can also search using more than one context code. For example to search using the context code of ‘gender’ and ‘workflow’ then the following search would be executed:
See token for details relating to the type of this parameter.
useContext-valueconcept
To search for ServiceDefinition(s) by the value that defines its context specified in the ServiceDefinition.useContext.value[x] element, for example a value of ‘female’ within a context type of ‘gender’, the following search could be executed:
In the above scenario, the ServiceDefinition.useContext.value[x] element would have a datatype of CodeableConcept.
See token for details relating to the type of this parameter.
useContext-valuequantityrange
To search for ServiceDefinition(s) by the quantity or range that defines its context specified in the ServiceDefinition.useContext.value[x] element, for example a value of ‘<50’ within a context type of ‘age’, the following search could be executed:
In the above scenario, the ServiceDefinition.useContext.value[x] element would have a datatype of Quantity or Range.
See quantity for details relating to the type of this parameter.
jurisdiction
To search for ServiceDefinition(s) by its jurisdiction e.g. the legal or geographic region in which it is intended to be used, for example for a ServiceDefinition intended for use in Great Britain, the following search could be executed:
See token for details relating to the type of this parameter.
trigger-type
To search for ServiceDefinition(s) by its trigger type e.g. the type of event which will determine when the module will be invoked, the following search could be executed:
See token for details relating to the type of this parameter.
trigger-eventdata-type
To search for ServiceDefinition(s) by the type of required data for the triggering event (where the trigger is a data trigger), the following search could be executed:
See token for details relating to the type of this parameter.
trigger-eventdata-profile
To search for ServiceDefinition(s) using the profile uri for the profile of the required data (where the trigger is a data trigger), the following search could be executed:
See uri for details relating to the type of this parameter.
trigger-eventdata-valuecoding
To search for ServiceDefinition(s) using the value code of the required data (where the trigger is a data trigger), the following search could be executed:
GET [baseUrl]/ServiceDefinition?trigger-eventdata-valuecoding=125602001
Search for a ServiceDefinition which is triggered where the event data code is 125602001.See Coding for details relating to the type of this parameter.
Combination of search parameters
If required, a search could be executed to return ServiceDefinition(s) using a combination of the above search parameters. An example request is shown below:
Search Response
Success
- MUST return a
200OK HTTP status code on successful execution of the interaction. - MUST return a
Bundleof type searchset, containing either:- One or more
ServiceDefinitionresources - A ‘0’ (zero) total value indicating no record was matched e.g. an empty
Bundle.
- One or more
Failure
The following errors can be triggered when performing this operation: