| Table of Contents |
|---|
Introduction
EVS is an evolution of EVSc, using gateway-integration instead of Vitalink connector-integration. It allows the manipulation of vault contents using specific actors and specific patients, manually or based on previously exported vault contents.
...
This manual describes EVS v2.1.0.
Functionality
General
EVS allows a certain actor to perform, for a certain patient, a number of actions.
...
EVS can be launched via the "vault-uploader.cmd" batch file:
The behaviour of EVSg must EVS must be determined by passing some mandatory parameters. Instead of using the "vault-uploader.cmd" batch file, it is easier to use the example batch file "start EVS.cmd":
...
This batch file contains parameter values for a standard behaviour. How the parameters change the behaviour can be found in the paragraph EVS_2.1.X_manual.Parameterisation.
Input-folder
Which patient?
The patient is determined by the folder under "..\exe\interaction\input".
After initial installation, 1 patient named "katrien" is available:
Which actor?
The actor is determined by the folder under "..\exe\interaction\input\<patient folder>".
After initial installation, 1 actor named "gp_van_gucht" is available:
Which files?
Any type of files, with any extension, can be dropped. They are considered as "input-files". EVSg willEVS will, depending on the action folder, parse the files and extract the MSE and TS transactions.
| Note |
|---|
All MS transactions are ignored as input. |
What is a Kmehrmessage?
A Kmehrmessage is a part of the file that starts with <kmehrmessage ...> and ends with </kmehrmessage>. One file can contain 0 or more Kmehrmessages. One Kmehrmessage can contain 0 or more MSE and TS transactions.
EVSg EVS will work with Kmehrmessages of Kmehr-standard 20120401 and Kmehr-standard 20161201 as input.
All extra data needed for the communication with the gateway will be generated by the EVSgEVS. As input the data as depicted in the image below will be used:
How is a "medication" identified?
For some actions, typically removing and updating "medications", the medication that should be changed needs to have an identification. Those medications are expressed as MSE transactions. These MSE transactions are identified by using an EVS reference.
| Note |
|---|
TS transactions can not be updated and should not contain EVS references! They can only be added or removed. |
Identification by EVS reference
An EVS reference is put in 1 (and only 1) free text field in the concerned MSE transaction.
...
In the next example, this REF is "===EVSREF:901===". EVSg EVS detects the reserved format "===EVSREF:<any text>===" and finally uses "<any text>" as unique REF.
...
If multiple EVS REFs have been given for 1 MSE transaction, EVSg EVS will not execute the action and will raise an error.
Which actions?
Depending on the folder where the input-file is dropped, EVSg EVS will execute an action.
Action "add"
This action will add a transaction to the vault for all transactions found in each Kmehrmessage found in all dropped files. If one of the MSE transactions within a kmehrmessage does not have an EVS REF yet, an EVS REF will be generated.
In the example below, 3 transactions are dropped to be added to the vault:
Action "export"
This action will export the contents of the vault, without any change to the vault itself. EVSg EVS will do this action once for each dropped file, without parsing this file.
In the example below, a newly created file will trigger an export of the contents of the vault:
Action "generateREF"
This action will generate an EVS REF for each MSE transaction currently in the vault.
...
If no EVS REF exists, the new EVS REF is put in the instructionforpatient field.
Action "replace"
This action will replace the contents of the vault by all the transactions found in the input file. Be aware of the fact that dropping multiple files in the replace-folder will result in a vault with as contents the transactions of the last input file! If one of the MSE transactions within a file does not have an EVS REF yet, this will be generated.
In the next example, after processing the next 3 input files, the vault contains 2 transactions.
Action "updateschemeREF"
This action will update the complete contents of the vault, based on the input file compared with the current contents of the vault.
...
| Tip | ||
|---|---|---|
| ||
The 'old' EVS, with Vitalink connector-integration, offered an action 'empty'. EVSg EVS doesn't offer this action anymore. Now, emptying the vault can be done by dropping an empty file for the actions "updateschemeREF" or "replace". |
Processed-folder
After execution of an action a variable number of output files are generated in the processed folder.
...
| Name | Output suffix | Extension | Description | Remarks |
|---|---|---|---|---|
Validation file | VALIDATION-OK VALIDATION-<###>-FAILED | .val | The report of the validation. | The filename contains the number of warnings and errors when the validation fails.
|
Global scheme PDF | globalscheme | A visualisation of the global scheme in PDF format. | - | |
Daily scheme PDF | dailyscheme-<date> | A visualisation of the daily scheme in PDF format. | This is the scheme of the medication that should be taken today. | |
Export file | - | .exp | An export of the contents of the vault. | - |
Input file | - | .inp | The original input file. | The filename does not include the number of data entries in the vault. |
...
| Name | Output suffix | Extension | Description | Remarks |
|---|---|---|---|---|
Error file | - | .err | The report containing the error. | The content of the error file will identify the problem. |
Logs-folder
Root
This folder contains:
- the eHealth technical connector logs for EVSgEVS: ehealth_uploader*.log
- the eHealth technical connector logs for EVSgEVS-exporter: ehealth_exporter*.log
- the proprietary EVSg EVS log for EVSgEVS: evs_uploader.log
- the proprietary EVSg EVS log for EVSgEVS-exporter: evs_exporter.log
- a folder 'communication'
Communicaton-folder
This folder contains all the requests and responses done by EVSg EVS when communicating with the gateway.
Configuration
This paragraph explains how to configure EVSgEVS.
How to add a patient?
Extra patients can be added by creating files in the next folder:
...
Since EVS follows all the rules for eHealth and Vitalink, it is up to the user to make sure the proper eHealth dependencies (informed consent, therapeutic relation, ...) are set in function of the wanted behaviour.
| Note | ||
|---|---|---|
| ||
EVSg EVS (and EVS-exporter) should be restarted when newly added patients will be used. |
How to add an actor?
Extra actors can be added by creating files in the next folder:
...
| Note |
|---|
The 'old' EVS, with Vitalink connector-integration, used another syntax in this files. EVSg EVS is not compatible with this old format! |
...
Since EVS follows all the rules for eHealth and Vitalink, it is up to the user to make sure the proper eHealth dependencies (therapeutic relation, ...) are set in function of the wanted behaviour.
| Note | ||
|---|---|---|
| ||
EVSg EVS (and EVSgEVS-exporter) should be restarted when newly added actors will be used. |
Parameterisation
The next parameters can be passed when launching EVSgEVS:
| Name | Values | Meaning |
|---|---|---|
| rootdir | "..\exe\interaction" | Relative or absolute path to the folder that needs to be watched by EVSgEVS. This folder should contain the requested actions. |
| writeAsIs | true|false | false: All patient data from the source Kmehrmessage will be replaced by the correspondign data of the used input patient. Since the Kmehr data model is used for this transformation, it is possible that other Kmehr structure elements are slightly changed too. true: The Kmehrmessage will be sent to the vault untouched. Use this when really no manipulation on the source Kmehrmessage is desired. |
| exportAfterUpload | true|false | true: Each action, excepted "export" itself, should be followed by an export. false: No export is needed after execution of the triggered action. |
| validateExportAfterUpload | true|false | true: Each action should be followed by validation of the vault content. false: No validation is needed. |
| generateGlobalMedicationScheme | true|false | true: Each action should be followed by the generation of a global scheme visualisation PDF. false: No global scheme visualisation is needed. |
| generateDailyMedicationScheme | true|false | true: Each action should be followed by the generation of a daily scheme visualisation PDF. false: No daily scheme visualisation is needed.
|
| dailyMedicationSchemeDate | date("yyyy-MM-dd") | If no date has been given, it will generate a daily medication scheme of the current date. If a date has been given, it will generate a daily medication scheme of the given date. |
| startTransactionId | number | This number will be the number for the first transaction within the kmehrmessage of a putTransactionSetRequest in the context of a medicationscheme. |
Example of a parameterisation:
Appendix A: Folder structure
...
EVS 2.x.y
This paragraph gives a brief overview of the folder structure after initial installation. It can be used as reference while using and configuring EVSgEVS.
| Path | Reserved path | Reserved name | Explanation | ||||||
|---|---|---|---|---|---|---|---|---|---|
| EVSgEVS |  | | The root folder. The name and location can be freely chosen. Keep in mind that paths used in scenarios, patient and actor files are possibly impacted by changes to this! | ||||||
| \config |  | | Everything that defines the behaviour of EVSgEVS, configured as needed by the user. | |||||
| \actors | | | All the actors that can be used by EVSgEVS. | ||||||
| \log4j | | | Settings of the log4j library. Please refer to https://logging.apache.org/log4j/2.x/manual/configuration.html for more explanation. | ||||||
| \patients | | | All the patients that can be used by EVSgEVS. | ||||||
| \exe | | | |||||||
| \certificates | | | The certificates used in the actor configuration files. | ||||||
| \exports | |
| The folder were the EVS-exporter will put exported vault contents, see EVS_2.1.X_manual AppendixB:EVSexporter | ||||||
| \interaction | | | |||||||
| \input | | | |||||||
| \katrien | | | |||||||
| \gp_van_gucht | | | |||||||
| \add | | | |||||||
| \export | | | |||||||
\generateREF | | | |||||||
| \replace | | | |||||||
| \updateschemeREF | | | |||||||
| \patient_template | | | |||||||
| \processed | | | |||||||
| \logs | | | Can be configured through the log4j settings. | ||||||
| \communication | | | |||||||
\scenarios | | | |||||||
| \basic_example | | | |||||||
| \system | | | |||||||
| \dependency-jars | | | |||||||
Appendix B:
...
EVS-exporter
Besides the interaction provided by dropping files in the input folder, EVSg EVS offers as extended functionality the continuous monitoring of the vault contents. This functionality is provided by EVSgEVS-exporter.
Launching
EVSgEVS-exporter can be launched via the "vault-exporter.cmd" batch file:
The behaviour of EVSgEVS-exporter must be determined by passing some mandatory parameters. Instead of using the "vault-exporter.cmd" batch file, it is easier to use the example batch file "start EVS.cmd":
...
After initial installation, launching the EVSgEVS-exporter means that the vault contents of the patient "katrien" will be monitored.
Output
When EVSgEVS-exporter detects for the given patients a change in the vault contents, an export is executed. The export is also executed after initial launch.
...
The files contain the same as the files generated by EVSg EVS in the processed-folder, but the filenames differ.
For EVSgEVS-exporter, each filename exists out of:
MS_<version>_<patient>_<date>_<time>-<author>_size-<nr of MSE transactions>_<unique code>_<output suffix>.<output extension>
| Name | Source |
|---|---|
Version | "Version" from the MS transaction. In case of an empty medicationscheme, the "version" is derived from the getLatestUpdate method. |
Patient | Name of the patient as defined in the EVSg EVS configuration. |
Date | Date of the latest update derived from the MS transaction. |
Time | Time of the latest update derived from the MS transaction. |
| Author | "Author" of the latest update, derived from the MS transaction->UpdatedBy as returned by the gateway. |
| Nr of MSE transactions | The amount of MSE transactions in the vault. |
| Unique code | Code making the filename unique in case an export exists already. |
| Output suffix | Hard coded, depending on file type. For the validation file, the number of warnings and errors and possible failure are shown. |
| Output extension | Hard coded, depending on file type. |
When the export fails, an error file will be generated, which is the same behaviour as for the folder-triggered export action of EVSgEVS.
Parameterisation
The next parameters can be passed when launching EVSgEVS-exporter:
| Name | Values | Meaning |
|---|---|---|
| transactionType | "medicationscheme" | This parameter is for future use. For the moment only 1 transaction type is supported. |
| patients | name(s) as defined in EVSg EVS configuration, comma separated | This(these) is(are) the patient(s) that will be monitored and whose vault content(s) will be exported. |
| actor | name as defined in EVSg EVS configuration | This is the actor that will be used for exporting. |
| exportDir | default "..\exe\exports" | This is the path where the output files will be generated. This location can be freely chosen. |
| validate | true|false | true: Each export should be followed by validation of the vault content. false: No validation is needed. |
| generateGlobalMedicationScheme | true|false | true: Each action should be followed by the generation of a global scheme visualisation PDF. false: No global scheme visualisation is needed. |
| generateDailyMedicationScheme | true|false | true: Each action should be followed by the generation of a daily scheme visualisation PDF. false: No daily scheme visualisation is needed.
|
| dailyMedicationSchemeDate | date("yyyy-MM-dd") | If no date has been given, it will generate a daily medication scheme of the current date. If a date has been given, it will generate a daily medication scheme of the given date. |
...