ServiceDefinition: Implementation Guidance
Usage
The ServiceDefinition resource is published by the CDSS, describing what decisions the CDSS is able to provide support for. The resource describes in what circumstances the CDSS is valid, and what information is needed to render a decision.
A CDSS can publish one or many ServiceDefinition
resources. The resources SHOULD form a logically complete set. All CDSS MUST publish at least one ServiceDefinition
.
A ServiceDefinition
can encapsulate any amount of information – some CDSS may find it simpler to have a single ServiceDefinition
, and routing of patients through the CDSS is managed entirely within that single ServiceDefinition
. Other CDSS may publish a different ServiceDefinition
for different areas – for example, a ServiceDefinition
for each presenting complaint. It is also possible to be even more granular, with a CDSS having a different ServiceDefinition
for different complaints, and also for different types of user (e.g. headache for adult females, and a separate ServiceDefinition
for headache for male children).
In general, more granular ServiceDefinitions
will make change management simpler, as these can be updated without changing other ServiceDefinitions
. Conversely, fewer ServiceDefinitions
can make the triage journey simpler to control.
CDSS Suppliers MUST ensure that all ServiceDefinitions
end in the provision of CareAdvice
, a ReferralRequest
or redirection to another ServiceDefinition
to reduce the risk of triage failing to complete. ServiceDefinitions
that end with a redirection to another ServiceDefinition
MUST NOT redirect to the initiating ServiceDefinition
either directly or indirectly.
Details of how a ServiceDefinition
SHOULD be implemented within in the scope of this implementation guide is outlined in the table below:
Name | Cardinality | Type | FHIR Documentation | CDS Implementation Guidance |
---|---|---|---|---|
id |
0..1 |
id | Logical id of this artifact | Note that this will always be populated except when the resource is being created (initial creation call) |
meta |
0..1 |
Meta | Metadata about the resource | |
implicitRules |
0..1 |
uri | A set of rules under which this content was created | |
language |
0..1 |
code | Language of the resource content. Common Languages (Extensible but limited to All Languages) |
|
text |
0..1 |
Narrative | Text summary of the resource, for human interpretation | |
contained |
0..* |
Resource | Contained, inline Resources | This SHOULD NOT be populated. |
extension |
0..* |
Extension | Additional Content defined by implementations | |
modifierExtension |
0..* |
Extension | Extensions that cannot be ignored | |
url |
0..1 |
uri | Logical URI to reference this service definition (globally unique) | |
identifier |
0..* |
Identifier | Additional identifier for the service definition | |
version |
0..1 |
string | Business version of the service definition | This SHOULD be populated. |
name |
0..1 |
string | Name for this service definition (computer friendly) | The name used is not expected to be globally unique. The name SHOULD be a simple alpha-numeric type name. |
title |
0..1 |
string | Name for this service definition (human friendly) | This MUST be populated. |
status |
1..1 |
code | draft | active | retired | unknown PublicationStatus (Required). | This MUST be populated with the value 'active' in live service |
experimental |
0..1 |
boolean | For testing purposes, not real usage | This SHOULD be populated. Where populated this MUST be true for draft or experimental ServiceDefinitions which are not to be used in LIVE operation. This MUST be FALSE if the ServiceDefinition is for use in LIVE operation. Where not populated, this means the ServiceDefinition is appropriate for both experimental and live operation. |
date |
0..1 |
dateTime | Date this was last changed | |
publisher |
0..1 |
string | Name of the publisher (organization or individual) | |
description |
0..1 |
markdown | Natural language description of the service definition | This MUST be populated. |
purpose |
0..1 |
markdown | Why this service definition is defined | This MUST be populated. |
usage |
0..1 |
string | Describes the clinical usage of the module | This MUST be populated. |
approvalDate |
0..1 |
date | When the service definition was approved by publisher | |
lastReviewDate |
0..1 |
date | When the service definition was last reviewed | |
effectivePeriod |
0..1 |
Period | When the service definition is expected to be used | A null value means the ServiceDefinition is appropriate for any period. |
useContext |
0..* |
UsageContext | Context the content is intended to support | This element SHOULD be populated with the appropriate expected usage of the ServiceDefinition . This will be determined by the EMS and CDSS specific to each implementation.If no useContext is specified, this means the ServiceDefinition is appropriate for any useContext.
|
jurisdiction |
0..* |
CodeableConcept | Intended jurisdiction for service definition (if applicable) |
A null value means the ServiceDefinition is appropriate for any/all jurisdictions.
Click here for more information. Extended valueset includes England, Scotland, Wales, Northern Ireland and Ireland. |
topic |
0..* |
CodeableConcept | E.g. Education, Treatment, Assessment, etc DefinitionTopic valueset (Example) | |
contributor |
0..* |
Contributor | A content contributor | The information in this element MAY be used to assist consumers in quickly determining who contributed to the content of the knowledge module. |
contact |
0..* |
ContactDetail | Contact details for the publisher | |
copyright |
0..1 |
markdown | Use and/or publishing restrictions | Consumers MUST be able to determine any legal restrictions on the use of the ServiceDefinition and/or its content. |
relatedArtifact |
0..* |
RelatedArtifact | Additional documentation, citations, etc | |
trigger |
0..* |
TriggerDefinition | "when" the module should be invoked | See below for more information. |
dataRequirement |
0..* |
DataRequirement | What data is used by the module | This element MUST be populated with the set of machine-processable assertions (see GuidanceResponse.
outputParameters ) which the CDSS requires in order to render the response fully.The custom value set for dataRequirement.codeFilter.valueCodeableConcept is UEC-ObservationCode-1 |
operationDefinition |
0..1 |
Reference | (OperationDefinition) |
Operation to invoke | A reference to the operation that is used to invoke this service. |
ServiceDefinition: Element Guidance
useContext
The useContext element is used to describe the expected usage of the ServiceDefinition. This SHOULD be populated where available to reduce the risk of using a ServiceDefinition that is inappropriate for the context, for example the service type, patient type or user role (which may lead to inappropriate triage).
The EMS will typically use the ServiceDefinition.useContext to filter available ServiceDefinitions in the Select ServiceDefinition interaction.
The following json code block shows how to define the useContext in a ServiceDefinition. Note that useContext can only use key value pairs.
"useContext": [
{
"code": {
"system": "http://hl7.org/fhir/usage-context-type",
"code": "age",
"display": "Age Range"
},
"valueCodeableConcept": {
"coding": [
{
"system": "http://snomed.info/sct",
"code": "133936004",
"display": "Adult (person)"
}
]
}
},
{
"code": {
"system": "http://hl7.org/fhir/usage-context-type",
"code": "user",
"display": "User Type"
},
"valueCodeableConcept": {
"coding": [
{
"system": "http://hl7.org/fhir/valueset-provider-taxonomy.html",
"code": "103GC0700X",
"display": "Clinical"
}
]
}
}
],
jurisdiction
The jurisdiction element is used to describe the intended usage jurisdiction of the ServiceDefinition. If no jurisdiction is defined as part of the ServiceDefinition then it is deemed to be appropriate for any/all jurisdictions.
The EMS will typically use the ServiceDefinition.jurisdiction to filter available ServiceDefinitions in the Select ServiceDefinition interaction.
The following json code block shows how to define the jurisdiction in a ServiceDefinition.
"jurisdiction": [
{
"coding": [
{
"system": "urn:iso:std:iso:3166",
"code": "GB",
"display": "United Kingdom of Great Britain and Northern Ireland (the)"
}
]
}
]
version
If a CDS decides not to populate the version element, then there is deemed to be only a single version in existence.
In practice this SHOULD be populated where available although not mandatory.
Where a set of ServiceDefinitions provide a set of unified content, they must share a common version.
publisher
Population of the publisher element is optional.
The EMS will always know (and be able to log) exactly which ServiceDefinition was ‘called’ for any patient journey - at a minimum, through the url which was invoked during evaluation.
title, description, usage
The human readable title, description and usage elements MUST be populated by the CDSS to help mitigate the risks of selecting an inappropriate ServiceDefinition.
It is the decision of the EMS how and when, if ever to display this information.
trigger
If populated, this MUST be populated with DataRequirements for the clinical assertions required for this ServiceDefinition to be valid.
It is valid for this not to be populated - a NULL trigger means that the ServiceDefinition does not require any preconditions to be valid.
The custom ValueSet for trigger.eventData.value
is UEC-ObservationCode-1.