General
This paragraph explains the general principles concerning the storage and consultation of a medication scheme.
When reading or updating the medication scheme, all this information should be displayed, validated and checked by the user in its entirety.
A medication scheme consists of
- 1 transaction MS (medicationscheme),
- 0 or more transactions MSE (medicationschemeelement) and
- 0 or more transactions TS (treatmentsuspension)
These transactions are named "a transaction set". This is reflected in the presence of the eHealth Interhub Webservices getTransactionSet and putTransactionSet.
Medication scheme
Read a medication scheme
The web service getTransactionList needs to be called in order to retrieve the id for the transaction MS.
A succesfull getTransactionListResponse will contain an <id S="LOCAL" SL="vitalinkuri"> whose value is needed as input for the next step in the reading of the medication scheme:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
<soap:Body>
<ns3:GetTransactionListResponse xmlns="http://www.ehealth.fgov.be/hubservices/core/v3" xmlns:ns10="urn:be:fgov:ehealth:metahub:protocol:v2" xmlns:ns2="http://www.ehealth.fgov.be/standards/kmehr/schema/v1" xmlns:ns3="http://www.ehealth.fgov.be/hubservices/protocol/v3" xmlns:ns4="urn:be:fgov:ehealth:metahub:core:v2" xmlns:ns5="http://www.w3.org/2001/04/xmlenc#" xmlns:ns6="http://www.w3.org/2000/09/xmldsig#" xmlns:ns7="urn:be:fgov:ehealth:safe:internal:v3" xmlns:ns8="urn:be:fgov:ehealth:safe:common:decryptor:v3" xmlns:ns9="urn:be:fgov:ehealth:safe:common:v3">
<response>
...
</response>
<acknowledge>
...
</acknowledge>
<kmehrheader>
<folder>
<patient>
...
</patient>
<transaction>
<id S="ID-KMEHR" SV="1.0">1</id>
<id S="LOCAL" SL="vitalinkuri" SV="1.0">/subject/72071135503/medication-scheme</id>
<cd S="CD-TRANSACTION" SV="1.6">medicationscheme</cd>
<cd S="CD-HUBSERVICE" SV="1.0">GetTransactionSet</cd>
...
</transaction>
</folder>
</kmehrheader>
</ns3:GetTransactionListResponse>
</soap:Body>
</soap:Envelope>
Reading the medication scheme is parsing the getTransactionSetResponse for a specific patient and with the id of the needed transaction MS.
Some Kmehr elements of the response have a meaning in the context of future manipulation of the medication scheme:
| Transaction | Element | Meaning | Store for later use? | Extra information |
|---|---|---|---|---|
| MS | id | S="ID-KMEHR" This is a unique Kmehr-identifier for the transaction within the transactionset. | NO | |
S="LOCAL" SL="vitalinkuri" This is the unique Vitalink-identifier for the MS transaction. | YES | This is the same value as the Vitalink-identier retrieved with getTransactionList. | ||
| MSE/TS | id | S="ID-KMEHR" This is a unique Kmehr-identifier for the transaction within the transactionset. | NO | Although storage is not needed for the web service manipulation flow, it is off course needed to know the link between TS transactions and the MSE transactions they poin to. |
S="LOCAL" SL="vitalinkuri" This is the unique Vitalink-identifier for the MSE/TS transaction. | YES |
Update a medication scheme
Updating a medication scheme means doing putTransactionSetRequest for a specific patient and with the id of the needed transaction MS.
The number of MSE transactions in the kmehrmessage of a PutTransactionSetRequest should not exceed 100. The TS transactions are not taken into account for this maximum.
In this set of transactions, MSE/TS transactions can be manipulated as follows:
Manipulation of MS/TSE transaction | Description |
|---|---|
| create | A new MS/TSE transaction is added to the set. Please refer to the paragraph below how created MS/TSE transactions are structured. |
| delete | The MS/TSE transaction that needs to be deleted is not present anymore in the <kmehrmessage> of the putTransactionSetRequest. |
| update | The MS/TSE transaction that needs to be updated is present in the <kmehrmessage> of the putTransactionSetRequest. Please refer to the paragraph below how updated MS/TSE transactions are structured. |
| preserve | The MS/TSE transaction that needs to be preserved is present in the <kmehrmessage> of the putTransactionSetRequest, and is an exact copy of the earlier read transaction. |
The MS transaction itself must also be passed as input for the putTransactionSetRequest.
| Element | Meaning | Extra information |
|---|---|---|
| author | The author of the manipulation of the transaction set. | It is good practice to provide the author information of the user of the application. However, the Vitalink gateway will generate this information based on the used session certificates. |
iscomplete | This is not used in the Vitalink business flow. | It is good practice to hard code this to "true". |
isvalidated | This is not used in the Vitalink business flow. | It is good practice to hard code this to "true". |
| version | The version of the medication scheme on which this manipulation is based. | An application must pass here the value that was earlier read in the reading sequence. The are several ways to retrieve the correct input value:
|
Here an example of an updated MS transaction:
<transaction> <id S="ID-KMEHR" SV="1.0">1</id> <cd S="CD-TRANSACTION" SV="1.4">medicationscheme</cd> <date>2018-02-09</date> <time>10:21:13.603+01:00</time> <author> <hcparty> <id S="ID-HCPARTY" SV="1.0">18334780</id> <id S="INSS" SV="1.0">82051234978</id> <cd S="CD-HCPARTY" SV="1.1">persphysician</cd> <firstname>Hannes</firstname> <familyname>De Clercq</familyname> </hcparty> </author> <iscomplete>true</iscomplete> <isvalidated>true</isvalidated> <version>41</version> </transaction>
A list of URI’s will be returned with the response message. In this list you’ll find all the transaction in the set defining the complete medication scheme. So this list contains the unchanged, added and modified MSE/TS transactions, and not the deleted MSE/TS transactions.
Here an example of a putTransactionSetResponse indicating succesful writing:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
<soap:Body>
<ns3:PutTransactionSetResponse xmlns="http://www.ehealth.fgov.be/hubservices/core/v3" xmlns:ns10="urn:be:fgov:ehealth:metahub:protocol:v2" xmlns:ns2="http://www.ehealth.fgov.be/standards/kmehr/schema/v1" xmlns:ns3="http://www.ehealth.fgov.be/hubservices/protocol/v3" xmlns:ns4="urn:be:fgov:ehealth:metahub:core:v2" xmlns:ns5="http://www.w3.org/2001/04/xmlenc#" xmlns:ns6="http://www.w3.org/2000/09/xmldsig#" xmlns:ns7="urn:be:fgov:ehealth:safe:internal:v3" xmlns:ns8="urn:be:fgov:ehealth:safe:common:decryptor:v3" xmlns:ns9="urn:be:fgov:ehealth:safe:common:v3">
<response>
...
</response>
<acknowledge>
<iscomplete>true</iscomplete>
<error>
<ns2:cd S="LOCAL" SL="vitalinkstatuscode" SV="1.0">200</ns2:cd>
<ns2:description L="en">The request was successfully completed.</ns2:description>
</error>
</acknowledge>
<transaction>
<id S="ID-KMEHR" SV="1.0">1</id>
<id S="LOCAL" SL="vitalinkuri" SV="1.0">/subject/72071135503/medication-scheme</id>
</transaction>
<transaction>
<id S="ID-KMEHR" SV="1.0">2</id>
<id S="LOCAL" SL="vitalinkuri" SV="1.0">/subject/72071135503/medication-scheme/07223/3</id>
</transaction>
<transaction>
<id S="ID-KMEHR" SV="1.0">3</id>
<id S="LOCAL" SL="vitalinkuri" SV="1.0">/subject/72071135503/medication-scheme/07223/3</id>
</transaction>
<transaction>
<id S="ID-KMEHR" SV="1.0">4</id>
<id S="LOCAL" SL="vitalinkuri" SV="1.0">/subject/72071135503/medication-scheme/07223/3</id>
</transaction>
<transaction>
<id S="ID-KMEHR" SV="1.0">5</id>
<id S="LOCAL" SL="vitalinkuri" SV="1.0">/subject/72071135503/medication-scheme/70696/1</id>
</transaction>
<transaction>
<id S="ID-KMEHR" SV="1.0">6</id>
<id S="LOCAL" SL="vitalinkuri" SV="1.0">/subject/72071135503/medication-scheme/18134/1</id>
</transaction>
<transaction>
<id S="ID-KMEHR" SV="1.0">7</id>
<id S="LOCAL" SL="vitalinkuri" SV="1.0">/subject/72071135503/medication-scheme/14199/1</id>
</transaction>
</ns3:PutTransactionSetResponse>
</soap:Body>
</soap:Envelope>
RSW/RSB annotation
In the RSW and RSB implementations, only the ID of the medication scheme as a whole will be returned.
Delete a medication scheme
There is no explicit function to delete a medication scheme. A medication scheme is however implictly deleted by deleting all its MS/TSE transactions.
Create a medication scheme
There is no explicit function to create a medication scheme. A medication scheme is however implictly created by creating 1 or more MS/TSE transaction(s).
MSE/TS transaction
Read a MSE/TS transaction
Reading the MSE/TS transactions means parsing the correspondent transaction elements in the getTransactionSetResponse.
Create a MSE/TS transaction
An MSE/TS transaction needs to be composed, compliant to the structure described in M. Kmehrmessage Structure, where the following elements have a specific meaning:
| Element | Meaning | Extra information |
|---|---|---|
| id S="ID-KMEHR" | A unique Kmehr-identifier that distinguishes this transaction from all others. | This does not need to be the same value from the orginally read one. However make sure the relations between TS and MSE transactions are not broken. |
| id S="LOCAL" SL="vitalinkuri" | This should not be present! | Absence of this id means for Vitalink that this is a newly created transaction. RSW/RSB annotation In the RSW, this local_id is named “RSWID” and in RSB “RSBID”. |
| date | Date of creation | Typically, the creating application should choose "today". |
| time | Time of creation | Typically, the creating application should choose "now". |
| author | The author of the manipulation of the transaction set. | It is good practice to provide the author information of the user of the application. However, the Vitalink gateway will generate this information based on the used session certificates. |
iscomplete | This is not used in the Vitalink business flow. | It is good practice to hard code this to "true". |
isvalidated | This is not used in the Vitalink business flow. | It is good practice to hard code this to "true". |
Here an example of a created MS transaction:
<transaction> <id S="ID-KMEHR" SV="1.0">6</id> <cd S="CD-TRANSACTION" SV="1.11">medicationschemeelement</cd> <date>2018-02-09</date> <time>10:21:13</time> <author> ... </author> <iscomplete>true</iscomplete> <isvalidated>true</isvalidated> ... </transaction>
Update a MSE/TS transaction
An earlier MSE/TS transaction needs to be adapted, compliant to the structure described in M. Kmehrmessage Structure, where the following elements have a specific meaning:
| Element | Meaning | Extra information |
|---|---|---|
| id S="ID-KMEHR" | A unique Kmehr-identifier that distinguishes this transaction from all others. | This does not need to be the same value from the orginally read one. However make sure the relations between TS and MSE transactions are not broken. |
| id S="LOCAL" SL="vitalinkuri" | The unique identifier provided by Vitalink that distinguishes the MSE transaction from all other MSE transactions and the TS . | This need to be the same value from the orginally read one, in other words Vitalink needs to know which transaction needs to be updated. RSW/RSB annotation In the RSW, this local_id is named “RSWID” and in RSB “RSBID”. |
| date | Date of creation | Typically, the creating application should choose "today". |
| time | Time of creation | Typically, the creating application should choose "now". The fact that the date and time are more recent than the original ones means for Vitalink that this is an updated transaction. |
| author | The author of the manipulation of the transaction set. | It is good practice to provide the author information of the user of the application. However, the Vitalink gateway will generate this information based on the used session certificates. |
iscomplete | This is not used in the Vitalink business flow. | It is good practice to hard code this to "true". |
isvalidated | This is not used in the Vitalink business flow. | It is good practice to hard code this to "true". |
Here an example of an updated MS transaction:
<transaction> <id S="ID-KMEHR" SV="1.0">6</id> <id S="LOCAL" SL="vitalinkuri" SV="1.0">/subject/72071135503/medication-scheme/70277/2</id> <cd S="CD-TRANSACTION" SV="1.11">medicationschemeelement</cd> <date>2018-02-12</date> <time>14:57:45</time> <author> ... </author> <iscomplete>true</iscomplete> <isvalidated>true</isvalidated> ... </transaction>
Delete a MSE/TS transaction
This can be achieved by not adding the transaction (that needs to be deleted)in the <kmehrmessage> of the putTransactionSetRequest.
Preserve a MSE/TS transaction
This is almost exactly the same as for updating a MSE/TS transaction. The only difference is however that the date and time of the transaction that needs to be preserved, is not set to "today" and "now", but is the same as the value originally read.