FHIR Implementation Guide CiO version 2.0.0-beta.3
|
|
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. |
Inhoud
- 1 Introduction
- 2 Boundaries and relationships
- 3 Transactions
- 4 Release notes
- 5 Footnotes
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.3. 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.3 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. The 2021 prepublication introduced the Hypersensitivity and Reaction zibs, which had significant overlap with the pre-existing zib AllergyIntolerance. In the 2024 prepublication, the zib HypersensitivityIntolerance replaced the 2021 Hypersensitivity zib and along with the zib Reaction, now only contains '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. Additionally, the zibs Condition and Symptom were introduced in the zib 2024 prepublication. Condition represents the pathological state of the patient underlying a HypersensitivityIntolerance, while Symptom describes the phenomena through which a condition manifests in the patient. Furthermore, 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 six 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 HypersensitivityIntolerance 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 zibs SurveillanceDecision, Condition and Symptom are newly introduced, so obviously no derivation from nl-core profiles are 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. A list of discussion topics with regards to the technical implementation can be found in section 2.5.
|
|
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 |
| HypersensitivityIntolerance | OvergevoeligheidIntolerantie | AllergyIntolerance | http://nictiz.nl/fhir/StructureDefinition/cio-HypersensitivityIntolerance |
| Reaction | Reactie | AllergyIntolerance | http://nictiz.nl/fhir/StructureDefinition/cio-Reaction |
| Condition | AandoeningOfGesteldheid | Condition | http://nictiz.nl/fhir/StructureDefinition/cio-Condition |
| Symptom | Symptoom | Observation | http://nictiz.nl/fhir/StructureDefinition/cio-Symptom |
| RegistrationInformation | RegistratieInformatie | Provenance | http://nictiz.nl/fhir/StructureDefinition/cio-RegistrationInformation |
The last building block in the above table has a special status:
- The RegistrationInformation 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-RegistrationInformation profile. In the future, if more information standards will make use of the Provenance resource to represent the administrative concepts present in RegistrationInformation, it is intended to create an nl-core-RegistrationInformation profile that replaces the cio-RegistrationInformation profile.
2.2.2 Secondary building blocks
Additionally, the standard uses several secondary building blocks referenced from the main building blocks. Most of these secondary building blocks are part of the ‘nl-core’ package, with the exception of the ProposalContraIndication, ReplyProposalContraIndication and MedicationAgreement building blocks. The MedicationAgreement building block is part of the Medication Process 9 information standard.
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
_version1.drawio.png)
_version2.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-’).
From version 2.0.0 of the CiO standard onwards, changes in the functional definition have lead to mappings being deprecated. The following situations can be identified:
- If an element in the functional definition was modified in a non-compatible way (for example, a concept has been removed from or added to the value set on that element, the data type of the element has changed, or the cardinality of the element (in all relevant transactions) has changed)
- and the element had a zib mapping applied, the zib mapping gets a suffix [DEPRECATED], and a mapping to the latest version of MP9 is added following the rules stated before.
- and the element had a mapping applied to the previous version of CiO, that mapping gets a suffix [DEPRECATED], and a mapping to the latest version of CiO is added following the rules stated before.
- If an element in the functional definition is removed
- and the element had a zib mapping applied (not on an extension), the zib mapping gets a suffix [DEPRECATED], and all other profiling characteristics are removed.
- and the element had a mapping applied to the previous version of CiO (not on an extension), that mapping gets a suffix [DEPRECATED], and all other profiling characteristics are removed.
- If an element in the functional definition is removed and the element had a mapping applied on an extension, that extension is removed entirely. In particular no [DEPRECATED] mapping will be visible in the FHIR profile. This is done to ensure no redundant extensions remain in the FHIR profiles.
Moreover, all mappings to earlier versions of CiO (i.e. versions before the previous version) are entirely removed.
Following the procedure outlined above thus results in the following:
- All relevant zib mappings stay visible, and moreover all elements in the corresponding ART-DECOR data set that aren't compatible anymore with their zib counterparts are marked.
- All incompatible changes made in the latest version with respect to the previous version are marked.
- Exceptions are extensions that would otherwise only contain deprecated mappings; these are removed fully.
Because of open world modelling, the cardinality of elements in the FHIR profiles can be less strict than the cardinalities in the ART-DECOR transactions. However, the latter cardinality is leading when it comes to exchanging building blocks in the context of a specific transaction.
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 of each FHIR instance of each main building block (with the exception of RegistrationInformation).
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 Identifier, for example RelationHypersensitivityIntolerance (cio-dataelement-20-823) in building block Reaction. 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 Medication Hypersensitivity Identification
The building blocks HypersensitivityIntolerance, Condition, Reaction, SurveillanceDecision, and Symptom are collectively referred to as 'MedicationHypersensitivity' (Dutch: 'GeneesmiddelOvergevoeligheid'). In FHIR, the MedicationHypersensitivity does not have an explicit resource representation. Instead, each building block contains the MedicationHypersensitivityIdentifier extension which contains the ‘Medication Hypersensitivity Identifier’. This identifier shall be the same across the related building blocks that relate to making decisions about medication contraindications. This concept is of type 'Identifier' (cio-dataelement-20-888) and is mapped to FHIR as an extension with the data type 'Identifier'. The custom search parameter medication-hypersensitivity-identifier, see ‘Search parameters’, is used within the ‘Medication Hypersensitivity’ transaction to query a server for all building blocks within MedicationHypersensitivity.
2.5 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 - Flag:
patient.identifierandsubject:Patient.identifier
An example of a request that retrieves all Flag resources of a patient with a fake BSN of 111222333:
GET [base]/Flag?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.
2.6 Differentiating between transactions
All transactions described in this IG use the same medication building blocks in different combinations and settings, making it necessary to differentiate between them. Several mechanisms are used to achieve this. Aside from PUSH/PULL, the type of medication building blocks, supporting resources like Communication for specific transactions and fixing the value of specific FHIR elements in applicable profiles, the actionable tag is used. The latter is described more in depth in the following section.
Note that Resource.meta.profile, although present in each building block (see the general FHIR IG on ‘Profile use and declaration’), SHOULD not be used for identification of the building block type and therefore for differentiating between transactions.
2.6.1 Actionable tag
To differentiate between sending or serving building blocks that are either of informative nature or of actionable nature, the actionable tag is used. Tags are Coding elements present in Resource.meta.tag used for workflow management.
If applicable, the profiles used by a transaction require the use of .meta.tag with .system = http://terminology.hl7.org/CodeSystem/common-tags and .code = actionable to indicate that the resource is part of a request intended to be acted upon. The absence of this tag indicates that the resource is merely of informative nature.
It is up to systems to determine how and when the transactions using the actionable tag are handled from a functional perspective. Systems may store the resource including the actionable tag or remove it either upon storing or when the request is acted upon. However, systems SHALL make sure the tag is removed when serving or sending the resource as part of an informative transaction.
This tag is used for the ‘Send Proposal ContraIndication’ transaction.
2.7 Discussion
As stated before, the current profiles cannot be considered to be stable and ready for use. This is partly due to the ongoing discussion about the exact scope and content of the functional building blocks in CiO. However, there are also some topics regarding the technical implementation that need to be addressed before considering the resulting FHIR profiles to be ready for use:
- The functional data set defines several relations between different building blocks (concepts with a name starting with ‘Relation…’), which have been implemented in FHIR as custom extensions of data type ‘Reference’. Some of these refer to instances of the same building block and are meant to track updates done between different instances of the same building block. In that sense the approach of the Medication Process information standard is followed here, where such relations are used for building blocks that are changed or stopped. In FHIR however it is possible to just update existing resources resulting in a new version of the same instance, and therefore it is up for debate whether this approach is deemed necessary and desirable for the CiO use cases. In particular one might wonder whether this approach is justified for Flag resources, since this resource has a different nature than for instance medication-related resources. The conclusion on this topic also depends on the way object identification and mutations will be handled on a functional level within the CiO information standard. This has not been fully thought out yet and will be taken into consideration for the 2.0.0-beta.3 release.
- For this release, the information standard uses the Provenance resource but does not represent the concepts within the zib RegistrationData. As this resource does not currently align with the information standard, we have developed a derived building block called 'RegistrationInformation' from the zib. This derived building block addresses our needs for concepts such as RegistrationDateTime (referred to as 'CreationDateTime' in this release) and InformationSource, avoiding the necessity of defining additional extensions. Further discussion is necessary to finalize these concepts.
- The HypersensitivityIntolerance and Reaction building blocks are modeled by different AllergyIntolerance profiles, as they are both representing diagnostic insight of a health professional regarding (the predisposition to develop) a reaction, while in core FHIR the relation between a hypersensitivity intolerance and reactions due to that hypersensitivity intolerance are modeled within one AllergyIntolerance. This discrepancy might result in difficulties when exchanging information on hypersensitivities and reactions on a broader/international scale. Both modeling approaches mentioned here need to be taken into account while deciding on the definitive modeling of the aforementioned building blocks.
- The exact requirements regarding the search parameters used within CiO aren't fully fledged yet, especially the
_revincludedefined onProvenance.target, and the possible requirement of an_includeon the contents of theflag-detailextension (the latter being out of scope for this release). Note that in general, references are required to be either resolvable or readily available in the search request results; since the reference between the Provenance resource and other resources is reversed with respect to the focal resource of the search requests, supporting the_revincludeonProvenance.targetis required. Further discussion with software suppliers is necessary to finalize these requirements.
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-MCIR | CapabilityStatement Retrieve/serve medication contraindications |
| Serving medication contraindications | Server | CIO-MCIB |
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 search result parameter, 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 RegistrationInformation building block). | category [1]
|
Flag | Retrieves all Flag resources representing a MedicationContraIndication.
GET [base]/Flag?category=http://snomed.info/sct|350241000146102 |
| - | Include the RegistrationInformation 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 |
| 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 |
| - | 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, RelatedPerson, Organization) 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: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 |
| RegistrationInformation | RegistratieInformatie | Provenance | http://nictiz.nl/fhir/StructureDefinition/cio-RegistrationInformation |
| 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 |
| ContactPerson | Contactpersoon | RelatedPerson | http://nictiz.nl/fhir/StructureDefinition/nl-core-ContactPerson |
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-MCIS | CapabilityStatement Send/receive medication contraindications |
| Receiving medication contraindications | Server | CIO-MCIO |
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 |
| RegistrationInformation | RegistratieInformatie | Provenance | http://nictiz.nl/fhir/StructureDefinition/cio-RegistrationInformation |
| 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 |
| ContactPerson | Contactpersoon | RelatedPerson | http://nictiz.nl/fhir/StructureDefinition/nl-core-ContactPerson |
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-GOR | CapabilityStatement Retrieve/serve medication hypersensitivities |
| Serving medication hypersensitivities | Server | CIO-GOB |
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{&[additional parameter(s)]}
References within the flag-detail extension (in the Flag resources present in the search result) to instances conforming to the cio-HypersensitivityIntolerance or cio-Reaction profiles can be resolved afterwards by individual read operations. The same holds true for instances conforming to the cio-Condition profile referenced from Provenance.target.
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 search result parameter, 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 RegistrationInformation building block). | category [1]
|
Flag | Retrieves all Flag resources representing a SurveillanceDecision.
GET [base]/Flag?category=http://snomed.info/sct|225419007 |
| - | Include the RegistrationInformation 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 |
| 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 |
| 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 |
| - | 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.
References to AllergyIntolerance and Condition resources are resolved by individual read operations, as mentioned above. Supporting the include of the Patient resource referenced by building blocks is required. Others (PractitionerRole, Practitioner, RelatedPerson, Organization) 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:patient |
| IdentificationGMO | Search on the medication hypersensitivity identifier
Note: retrieval of all medication resources belonging to one medication hypersensitivity requires to search on all medication resource types. |
medication-hypersensitivity-identifier[1]
|
Flag, AllergyIntolerance, Condition, Observation | Retrieves all Flag resources that are part of a medication hypersensitivity with a specific identifier.
GET [base]/Flag?medication-hypersensitivity-identifier=http://example.nl/fhir/NamingSystem/medicationhypersensitivity|1234567 |
The following custom search parameters are defined for this transaction:
- http://nictiz.nl/fhir/SearchParameter/Flag-category
- http://nictiz.nl/fhir/SearchParameter/medication-hypersensitivity-identifier
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-GOS | CapabilityStatement Send/receive medication hypersensitivities |
| Receiving medication hypersensitivities | Server | CIO-GOO |
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.
3.5 Proposal Contraindication (Send/Receive)
The send proposal contraindications transaction is used by the client to send proposal contraindications to a server.
| Transaction group | Transaction | Actor | System role | FHIR CapabilityStatement |
|---|---|---|---|---|
| ProposalContraIndication (PUSH) | Sending proposal contraindications | Client | CIO-PCIS | CapabilityStatement Send/receive proposal contraindications |
| Receiving proposal contraindications | Server | CIO-PCIO |
3.5.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 Bundle SHALL conform to the cio-ProposalContraIndication-Bundle profile, which contains at least a ProposalContraIndication building block. Additionally, one instance of nl-core-Patient, and one instance of cio-RegistrationInformation must be included. All resources included in the Bundle SHALL conform to their respective profiles listed in the 'List of profiles' below.
The cio-ProposalContraIndication-Bundle profile prescribes the use of actionable tags to indicate that the resources sent are part of a proposal and of actionable nature.
3.5.2 Receive (response message)
The client checks the ProposalContraIndication building block present within the Bundle it receives for the presence of actionable tags to determine the transaction type.
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.
Aside from the technical processing outcome described above, after functional processing an invocation of the ‘Send reply proposal contraindication’ transaction is expected.
3.5.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.6 Reply Proposal Contraindication (Send/Receive)
The send reply proposal contraindications transaction is used by the client to send reply proposal contraindications to a server.
| Transaction group | Transaction | Actor | System role | FHIR CapabilityStatement |
|---|---|---|---|---|
| ReplyProposalContraIndication (PUSH) | Sending reply proposal contraindications | Client | CIO-RPCIS | CapabilityStatement Send/receive reply proposal contraindications |
| Receiving reply proposal contraindications | Server | CIO-RPCIO |
3.6.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 Bundle SHALL conform to the cio-ReplyProposalContraindication-Bundle profile, which contains at least one Communication resource that conforms to the cio-ReplyProposalContraindication profile. Additionally, one instance of nl-core-Patient and other supporting resources might be included. The resources included in the Bundle SHALL conform to the profiles listed in the ‘List of profiles’ below.
3.6.2 Receive (response message)
The client checks the Communication resource present within the Bundle it receives for the presence of actionable tags and the type of building block referenced to determine the transaction type.
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.6.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 |
|---|---|---|---|
| ReplyProposalContraIndication | AntwoordVoorstelContraIndicatie | Bundle | http://nictiz.nl/fhir/StructureDefinition/cio-ReplyProposalContraIndication-Bundle |
| Communication | http://nictiz.nl/fhir/StructureDefinition/cio-ReplyProposalContraIndication | ||
| RegistrationInformation | RegistratieInformatie | Provenance | http://nictiz.nl/fhir/StructureDefinition/cio-RegistrationInformation |
| 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 |
4 Release notes
Release notes can be found on the release notes page.
