FHIR Implementation Guide CiO version 2.0.0-beta.2
|
|
This FHIR IG is currently under development and can not be considered stable and ready for use. For questions and change requests regarding this IG, please create a ticket in BITS. |
1 Introduction
This is the implementation guide (IG) for the information standard CiO (Dutch: Contra-indicaties en overgevoeligheden, English: Contraindications and hypersensitivities), version 2.0.0-beta.2. The functional specification can be found here and is implemented using HL7 FHIR R4. This implementation guide assumes that the reader is familiar with both the functional specification and this version of FHIR.
Apart from this document, the guidelines as specified in the general FHIR Implementation Guide apply. In particular, the reader should take note of the Overarching principles and the use of FHIR packages. Where the general IG uses the term ‘use case’, this IG uses the term ‘transaction’ for the various processes that are described.
This IG first describes the boundaries and relationships in place, after which the implementation is described per transaction.
2 Boundaries and relationships
2.1 Boundaries
Note that this version of the CiO information standard is only focused on medication contraindications and hypersensitivities due to medication (see section 1.1 of the functional specification). Technically this scope is reflected in for instance the terminology used within the FHIR profiles or the naming of the cio-MedicationContraIndication profile. In this IG however, we will not further elaborate on this narrower scope and instead describe the technical implementation of this standard as general as possible, in order to make it easier to incorporate a broadening of the scope in subsequent versions of this IG.
2.2 Building blocks and profiles
The exchange of data within the CiO standard version 2.0.0-beta.2 is partly based on the 2020 publication of the Dutch Health and Care Information Models (Dutch: ‘zorginformatiebouwstenen’ or ‘zibs’), and subsequent changes made that will be present in the 2024 prepublication. In particular, the prepublication of 2021 saw the introduction of the Hypersensitivity and Reaction zibs which are based on and still have quite some overlap with the zib AllergyIntolerance that already existed. In the prepublication of 2024 the zibs Hypersensitivity and Reaction have been overhauled in such a way that they only contain 'diagnostic' elements. The concepts within these zibs that were related to surveillance with respect to substances have been removed, resulting in a new zib SurveillanceDecision. Moreover, the zib Alert has changed in this prepublication such that the zib MedicationContraIndication has become superfluous, by adding a new AlertType reserved for medication contraindications. The functional data set of CiO has further built upon these four zibs, and the resulting objects (which are actually exchanged) are referred to as ‘building blocks’ in the data set, and can thus be seen as ‘extended zibs’ suitable for implementation.
Due to new insights, the building blocks Hypersensitivity and Reaction in the functional data set have deviated quite a lot from the zib AllergyIntolerance present in the 2020 publication, making them incompatible in varying degrees from a technical point of view. Therefore it was not possible to implement the FHIR profiles for these building blocks by building on and extending the nl-core profiles based on zib publication 2020. Hence the profiles for these building blocks have been created ‘independently’ from the nl-core profiles, meaning that they are not derived from nl-core-AllergyIntolerance. Similarly, for the building block MedicationContraIndication it was not possible to derive its profile from the nl-core-Alert profile corresponding to zib publication 2020, due to incompatible changes introduced in the zib Alert in the prepublication of 2024. Lastly, the zib SurveillanceDecision is newly introduced, so obviously no derivation from nl-core profiles is possible.
In a subsequent version of the information standard, it is the intention to base the profiles for all building blocks on their respective nl-core profiles based on zib publication 2024. There are however some considerations to be taken into account, since it is only possible to use these nl-core profiles provided:
- the underlying zibs are still part of the 2024 publication;
- no incompatible changes will be added on the relevant zibs between the prepublication and publication of 2024;
- they are defined in FHIR R4 (otherwise the cio profiles would also need to be converted to another FHIR version).
It is important to note that there is still extensive discussion about the exact scope and content of the CiO building blocks, meaning that the current profiles definitely cannot be considered to be stable and ready for use.
|
|
Nictiz uses the FHIR Packaging mechanism. This conveniently bundles all profiles, terminology, example material and other conformance resources you need into a single archive, which can be downloaded or installed using the appropriate FHIR tooling. This version of the information standard uses the following packages:
Note: packages use Semantic Versioning. Other versions can be used at will as long as they have the same major.minor number or a minor number higher than the stated version. |
Note that the package versioning does not follow the versioning of the information standard, as CiO version 2.0.0 was the first release of the CiO information standard based on FHIR R4. This means that CiO version 2.0.0-beta.x makes use of version 1.0.0-beta.x of the nictiz.fhir.nl.r4.cio FHIR package.
2.2.1 Main building blocks
As described above, the main building blocks have no dependency on any zib counterparts of the 2020 publication, resulting in so-called ‘cio’ profiles.
| Building block (EN) | Building block (NL) | FHIR resource | FHIR profile |
|---|---|---|---|
| MedicationContraIndication | MedicatieContraIndicatie | Flag | http://nictiz.nl/fhir/StructureDefinition/cio-MedicationContraIndication |
| SurveillanceDecision | BewakingBesluit | Flag | http://nictiz.nl/fhir/StructureDefinition/cio-SurveillanceDecision |
| Hypersensitivity | Overgevoeligheid | AllergyIntolerance | http://nictiz.nl/fhir/StructureDefinition/cio-HypersensitivityDisposition |
| Reaction | Reactie | AllergyIntolerance | http://nictiz.nl/fhir/StructureDefinition/cio-Reaction |
| Condition | Aandoening | Condition | http://nictiz.nl/fhir/StructureDefinition/cio-Condition |
| RegistrationData | RegistratieGegevens | Provenance | http://nictiz.nl/fhir/StructureDefinition/cio-RegistrationData |
The last two building blocks in the above table have a special status:
- Condition is not a separate building block within the CiO data set, and the cio-Condition profile actually contains mappings to concepts within the Hypersensitivity and Reaction building blocks that relate to the underlying condition and diagnosis. Thus, in order to convey the complete Hypersensitivity or Reaction building block, it is necessary to use an instance conforming to the cio-Hypersensitivity or cio-Reaction profile, together with an instance conforming to the cio-Condition profile.
- The RegistrationData building block is part of every other main building block in the data set, containing data that relates to the registering process instead of the medical concept itself. Such data is often not (completely) mappable within the profiles corresponding to the medical concept. Hence, whenever another main building block is exchanged, it is represented by its own profile in conjunction with an instance of the cio-RegistrationData profile. In the future, if more information standards will make use of the Provenance resource to represent the administrative concepts present in RegistrationData, it is intended to create an nl-core-RegistrationData profile that replaces the cio-RegistrationData profile.
2.2.2 Secondary building blocks
Additionally, the standard uses several secondary building blocks referenced from the main building blocks. All secondary building blocks are part of the ‘nl-core’ package.
| Building block (EN) | Building block (NL) | FHIR resource | FHIR profile |
|---|---|---|---|
| Patient | Patient | Patient | http://nictiz.nl/fhir/StructureDefinition/nl-core-Patient |
| HealthProfessional | Zorgverlener | PractitionerRole | http://nictiz.nl/fhir/StructureDefinition/nl-core-HealthProfessional-PractitionerRole |
| Practitioner | http://nictiz.nl/fhir/StructureDefinition/nl-core-HealthProfessional-Practitioner | ||
| HealthcareProvider | Zorgaanbieder | Location | http://nictiz.nl/fhir/StructureDefinition/nl-core-HealthcareProvider |
| Organization | http://nictiz.nl/fhir/StructureDefinition/nl-core-HealthcareProvider-Organization | ||
| ContactPerson | Contactpersoon | RelatedPerson | http://nictiz.nl/fhir/StructureDefinition/nl-core-ContactPerson |
Note the following:
- Each occurrence of the zib HealthProfessional is normally represented by two FHIR resources: an instance of nl-core-HealthProfessional-PractitionerRole and an instance of nl-core-HealthProfessional-Practitioner. Sending systems should only fill the reference to the PractitionerRole instance where relevant. Receiving systems can resolve the reference to the Practitioner resource from that PractitionerRole instance.
- The zib HealthcareProvider is mapped to both a Location and Organization profile. In general the Location profile acts as the focal resource, because most references to this zib are concerned about the recording of the physical location where the care to patient takes place rather than the organizational information. However, within the CiO information standard, the HealthcareProvider is only referenced indirectly via the PractitionerRole resource, hence a reference to the Organization profile is sufficient in those cases. The Location profile is mentioned in the table above for completeness purposes.
2.2.3 Relations between building blocks
.drawio.png)
2.3 Mappings between profiles and data set
Each transaction starts with links to the functional definition in an ART-DECOR publication and references one or several FHIR profiles. The FHIR profiles contain mappings to all data elements that are present in the functional data set (prefixed with ‘cio-dataelement-20-’).
Each transaction contains a Patient building block with cardinality 1..1 M. This patient is the subject of all other building blocks in the transaction, although no explicit relation exists in the data set. Therefore, a reference to a Patient resource conforming to the nl-core-Patient profile is expected in .subject (or .patient in the case of the AllergyIntolerance resource) of each FHIR instance of each main building block.
Relations between different building blocks exist in transactions by means of concepts with a name starting with ‘Relation…’ (Dutch: ‘Relatie…’) and an underlying concept 'Identification' of data type Identification, for example RelationHypersensitivityDisposition (cio-dataelement-20-734) in building block HypersensitivityDisposition. These relations are mapped to the FHIR data type ‘Reference’. Implementers SHOULD use literal references (using .reference) instead of logical references (using .identifier) where possible, see the general FHIR IG on the Reference data type.
2.4 Patient identification
This implementation guide assumes that the client system is able to make a connection to the right server that contains the patient's information. It does not provide information on finding the right server nor does it provide information about security. Moreover, each transaction is performed in the context of a specific patient, whose context might have been established using the authentication mechanisms described in external specifications such as the MedMij ‘Afsprakenstelsel’ or through the usage of search parameters for patient identification.
Each server is required to perform filtering based on the patient associated with the context for the request or based on the patient identification search parameters, which is a chained search parameter for all resource types except Patient, so only the records associated with the authenticated patient are returned.
When patient identification requires the use of search parameters, the following search parameters SHALL be supported:
- Patient:
identifier - AllergyIntolerance:
patient.identifier - Condition:
patient.identifierandsubject:Patient.identifier - Observation:
patient.identifierandsubject:Patient.identifier - Flag:
patient.identifierandsubject:Patient.identifier
An example of a request that retrieves all AllergyIntolerance resources of a patient with a fake BSN of 111222333:
GET [base]/AllergyIntolerance?patient.identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333
Most request examples in this IG do not include patient identification mechanisms. Requesters are assumed to include these if necessary.
3 Transactions
This section describes the FHIR implementation of all transactions listed in section 2 of the functional specification. Transactions are paired per transaction group. Each subsection below hyperlinks the names of the transaction groups and transactions to the functional definition in an ART-DECOR publication. The ART-DECOR publication details which data elements are expected to be supported (cardinality and conformance) for each transaction. Where the functional specification uses the terms ‘Query’ and ‘Making available’, this IG uses the terms ‘Retrieving’ and ‘Serving’.
3.1 Medication Contraindication (Retrieve/Serve)
The retrieve medication contraindications transaction is used by the client to retrieve medication contraindications from a server.
| Transaction group | Transaction | Actor | System role | FHIR CapabilityStatement |
|---|---|---|---|---|
| MedicationContraIndication (PULL) | Retrieving medication contraindications | Client | CIO-CIR | CapabilityStatement Retrieve/serve medication contraindications |
| Serving medication contraindications | Server | CIO-CIB |
3.1.1 Retrieve (request message)
When a health professional or healthcare provider wants to obtain all medication contraindications or specific ones matching various parameters, they issue a retrieve medication contraindications request message. This message uses the HTTP GET method parameterized query against the server's FHIR Flag endpoint.
The search interaction is performed by an HTTP GET conform the FHIR search specification, as shown below. This URL is configurable by the client by configuring the search query.
GET [base]/Flag?category=http://snomed.info/sct|350241000146102&_revinclude=Provenance:target{&[additional parameter(s)]}
3.1.1.1 Search parameters
All search parameters listed in the table below SHALL be supported for processing by servers and MAY be supported by clients, with the exception of the category parameter, as well as the _revinclude=Provenance:target and _include=Flag:detail search result parameters, which SHALL be supported by clients as well (as these are always part of the search query in this transaction).
| CiO search parameter | Description | FHIR search parameter | FHIR resource | Example |
|---|---|---|---|---|
| - | Search on MedicationContraIndication building blocks (not taking into account the RegistrationData building block). | category [1]
|
Flag | Retrieves all Flag resources representing a MedicationContraIndication.
GET [base]/Flag?category=http://snomed.info/sct|350241000146102 |
| - | Include the RegistrationData building block referenced from the MedicationContraIndication. | _revinclude=Provenance:target
|
Flag | Retrieves all Flag and corresponding Provenance resources representing a MedicationContraIndication.
GET [base]/Flag?category=http://snomed.info/sct|350241000146102&_revinclude=Provenance:target |
| PatientIdentificationNumber | Search on patient. | patient.identifier [2]
|
Flag | Retrieves all MedicationContraIndication building blocks of a patient with a fake BSN of 111222333.
GET [base]/Flag?category=http://snomed.info/sct|350241000146102&patient.identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333&_revinclude=Provenance:target&_include=Flag:detail |
| ReferenceDate | Search on the MedicationContraIndication building blocks that were active on or after a certain date. | date
|
Flag | Retrieves all MedicationContraIndication building blocks that were active from 01-05-2023.
GET [base]/Flag?category=http://snomed.info/sct|350241000146102&date=ge2023-05-01&_revinclude=Provenance:target&_include=Flag:detail |
| - | The client may request that the server returns resources related to the search results, in order to reduce the overall network delay of repeated retrievals of related resources.
Supporting the include of the Patient resource referenced by building blocks is required. Others (PractitionerRole, Practitioner) are optional. However: all resources referenced per literal reference SHALL be resolvable per the Nictiz IG. |
_include=Flag:patient
|
Flag | Retrieves all MedicationContraIndication building blocks of a patient with a fake BSN of 111222333 and includes the Patient resource in the search results.
GET [base]/Flag?category=http://snomed.info/sct|350241000146102&patient.identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333&_revinclude=Provenance:target&_include=Flag:detail&_include=Flag:patient |
The following custom search parameter is defined for this transaction:
3.1.2 Serve (response message)
The server returns an HTTP Status code appropriate to the processing outcome and returns a Bundle, with Bundle.type = searchset, including the resources matching the search query. The resources included in the Bundle SHALL conform to the profiles listed in the 'List of profiles' below.
3.1.3 List of profiles
The table below includes all profiles that are explicitly mentioned in the data set of this transaction, and thus need to be supported.
| Building block (EN) | Building block (NL) | FHIR resource | FHIR profile |
|---|---|---|---|
| MedicationContraIndication | MedicatieContraIndicatie | Flag | http://nictiz.nl/fhir/StructureDefinition/cio-MedicationContraIndication |
| RegistrationData | RegistratieGegevens | Provenance | http://nictiz.nl/fhir/StructureDefinition/cio-RegistrationData |
| Patient | Patient | Patient | http://nictiz.nl/fhir/StructureDefinition/nl-core-Patient |
| HealthProfessional | Zorgverlener | PractitionerRole | http://nictiz.nl/fhir/StructureDefinition/nl-core-HealthProfessional-PractitionerRole |
| Practitioner | http://nictiz.nl/fhir/StructureDefinition/nl-core-HealthProfessional-Practitioner | ||
| HealthcareProvider | Zorgaanbieder | Organization | http://nictiz.nl/fhir/StructureDefinition/nl-core-HealthcareProvider-Organization |
3.2 Medication Contraindication (Send/Receive)
The send medication contraindications transaction is used by the client to send medication contraindications to a server.
| Transaction group | Transaction | Actor | System role | FHIR CapabilityStatement |
|---|---|---|---|---|
| MedicationContraIndication (PUSH) | Sending medication contraindications | Client | CIO-CIS | CapabilityStatement Send/receive medication contraindications |
| Receiving medication contraindications | Server | CIO-CIO |
3.2.1 Send (request message)
Because the data sent in this transaction potentially consists of several building blocks along with secondary resources, a transaction interaction is used. This allows for sending a Bundle with a set of resources in a single interaction and makes it possible to include referenced secondary resources if needed. The interaction is performed by an HTTP POST command as shown:
POST [base]
The body of the POST submission is a Bundle with Bundle.type = transaction. Each entry SHALL carry request details (Bundle.entry.request) that provide the HTTP method of the action to be executed. Usually, this will be POST, even for informative secondary resources.
The resources included in the Bundle SHALL conform to the profiles listed in the 'List of profiles' below.
3.2.2 Receive (response message)
The server returns an HTTP Status code appropriate to the processing outcome. If the transaction is successful, the server returns a Bundle with Bundle.type = transaction-response, that contains one entry for each entry in the request, in the same order, with the outcome of processing the entry. Included secondary resources are handled following the Nictiz IG.
If the transaction fails, the server returns an OperationOutcome with one or multiple .issue elements filled with information, as detailed as possible, that describes why the transaction failed and which resource and/or request caused this.
3.2.3 List of profiles
The table below includes all profiles that are explicitly mentioned in the data set of this transaction, and thus need to be supported.
| Building block (EN) | Building block (NL) | FHIR resource | FHIR profile |
|---|---|---|---|
| MedicationContraIndication | MedicatieContraIndicatie | Flag | http://nictiz.nl/fhir/StructureDefinition/cio-MedicationContraIndication |
| RegistrationData | RegistratieGegevens | Provenance | http://nictiz.nl/fhir/StructureDefinition/cio-RegistrationData |
| Patient | Patient | Patient | http://nictiz.nl/fhir/StructureDefinition/nl-core-Patient |
| HealthProfessional | Zorgverlener | PractitionerRole | http://nictiz.nl/fhir/StructureDefinition/nl-core-HealthProfessional-PractitionerRole |
| Practitioner | http://nictiz.nl/fhir/StructureDefinition/nl-core-HealthProfessional-Practitioner | ||
| HealthcareProvider | Zorgaanbieder | Organization | http://nictiz.nl/fhir/StructureDefinition/nl-core-HealthcareProvider-Organization |
3.3 Medication Hypersensitivity (Retrieve/Serve)
The retrieve medication hypersensitivities transaction is used by the client to retrieve medication hypersensitivities from a server.
| Transaction group | Transaction | Actor | System role | FHIR CapabilityStatement |
|---|---|---|---|---|
| MedicationHypersensitivity (PULL) | Retrieving medication hypersensitivities | Client | CIO-BBR | CapabilityStatement Retrieve/serve medication hypersensitivities |
| Serving medication hypersensitivities | Server | CIO-BBB |
3.3.1 Retrieve (request message)
When a health professional or healthcare provider wants to obtain all medication hypersensitivities or specific ones matching various parameters, they issue a retrieve medication hypersensitivities request message. This message uses the HTTP GET method parameterized query against the server's FHIR Flag endpoint.
The search interaction is performed by an HTTP GET conform the FHIR search specification, as shown below. This URL is configurable by the client by configuring the search query.
GET [base]/Flag?category=http://snomed.info/sct|225419007&_revinclude=Provenance:target&_include=Flag:detail{&[additional parameter(s)]}
3.3.1.1 Search parameters
All search parameters listed in the table below SHALL be supported for processing by servers and MAY be supported by clients, with the exception of the category parameter, as well as the _revinclude=Provenance:target and _include=Flag:detail search result parameters, which SHALL be supported by clients as well (as these are always part of the search query in this transaction).
| CiO search parameter | Description | FHIR search parameter | FHIR resource | Example |
|---|---|---|---|---|
| - | Search on SurveillanceDecision building blocks (not taking into account the RegistrationData building block). | category [1]
|
Flag | Retrieves all Flag resources representing a SurveillanceDecision.
GET [base]/Flag?category=http://snomed.info/sct|225419007 |
| - | Include the RegistrationData building block referenced from the SurveillanceDecision. | _revinclude=Provenance:target
|
Flag | Retrieves all Flag and corresponding Provenance resources representing a SurveillanceDecision.
GET [base]/Flag?category=http://snomed.info/sct|225419007&_revinclude=Provenance:target |
| - | Include the Hypersensitivity or Reaction building block referenced from the SurveillanceDecision. | _include=Flag:detail [1]
|
Flag | Retrieves all Flag and corresponding Provenance resources representing a MedicationContraIndication, and includes the Hypersensitivity and Reaction building blocks referenced in the Flags.
GET [base]/Flag?category=http://snomed.info/sct|350241000146102&_revinclude=Provenance:target&_include=Flag:detail |
| PatientIdentificationNumber | Search on patient. | patient.identifier [2]
|
Flag | Retrieves all SurveillanceDecision building blocks of a patient with a fake BSN of 111222333.
GET [base]/Flag?category=http://snomed.info/sct|225419007&patient.identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333&_revinclude=Provenance:target&_include=Flag:detail |
| ReferenceDate | Search on the SurveillanceDecision building blocks that were active on or after a certain date. | date
|
Flag | Retrieves all SurveillanceDecision building blocks that were active from 01-05-2023.
GET [base]/Flag?category=http://snomed.info/sct|225419007&date=ge2023-05-01&_revinclude=Provenance:target&_include=Flag:detail |
| - | The client may request that the server returns resources related to the search results, in order to reduce the overall network delay of repeated retrievals of related resources.
Supporting the include of the Patient resource referenced by building blocks is required. Others (PractitionerRole, Practitioner, AllergyIntolerance, Condition) are optional. However: all resources referenced per literal reference SHALL be resolvable per the Nictiz IG. |
_include=Flag:patient
|
Flag | Retrieves all SurveillanceDecision building blocks of a patient with a fake BSN of 111222333 and includes the Patient resource in the search results.
GET [base]/Flag?category=http://snomed.info/sct|225419007&patient.identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333&_revinclude=Provenance:target&_include=Flag:detail&_include=Flag:patient |
The following custom search parameters are defined for this transaction:
- http://nictiz.nl/fhir/SearchParameter/Flag-category
- http://nictiz.nl/fhir/SearchParameter/Flag-detail
3.3.2 Serve (response message)
The server returns an HTTP Status code appropriate to the processing outcome and returns a Bundle, with Bundle.type = searchset, including the resources matching the search query. The resources included in the Bundle SHALL conform to the profiles listed in the 'List of profiles' below.
3.3.3 List of profiles
The table below includes all profiles that are explicitly mentioned in the data set of this transaction, and thus need to be supported.
3.4 Medication Hypersensitivity (Send/Receive)
The send medication hypersensitivities transaction is used by the client to send medication hypersensitivities to a server.
| Transaction group | Transaction | Actor | System role | FHIR CapabilityStatement |
|---|---|---|---|---|
| MedicationHypersensitivity (PUSH) | Sending medication hypersensitivities | Client | CIO-BBS | CapabilityStatement Send/receive medication hypersensitivities |
| Receiving medication hypersensitivities | Server | CIO-BBO |
3.4.1 Send (request message)
Because the data sent in this transaction potentially consists of several building blocks along with secondary resources, a transaction interaction is used. This allows for sending a Bundle with a set of resources in a single interaction and makes it possible to include referenced secondary resources if needed. The interaction is performed by an HTTP POST command as shown:
POST [base]
The body of the POST submission is a Bundle with Bundle.type = transaction. Each entry SHALL carry request details (Bundle.entry.request) that provide the HTTP method of the action to be executed. Usually, this will be POST, even for informative secondary resources.
The resources included in the Bundle SHALL conform to the profiles listed in the 'List of profiles' below.
3.4.2 Receive (response message)
The server returns an HTTP Status code appropriate to the processing outcome. If the transaction is successful, the server returns a Bundle with Bundle.type = transaction-response, that contains one entry for each entry in the request, in the same order, with the outcome of processing the entry. Included secondary resources are handled following the Nictiz IG.
If the transaction fails, the server returns an OperationOutcome with one or multiple .issue elements filled with information, as detailed as possible, that describes why the transaction failed and which resource and/or request caused this.
3.4.3 List of profiles
The table below includes all profiles that are explicitly mentioned in the data set of this transaction, and thus need to be supported.
4 Release notes
Release notes can be found on the functional design page.
