<DEPRECATED>

Introduction

EVS allows to manipulate vault contents using specific actors and specific patients, manually or based on previously exported vault contents.

After initial installation, some examples are available to get familiar with the functionalities of EVS, without the need for further configuration.

This manual describes EVS v1.2.2.

Functionality

General

EVS allows a certain actor to perform, for a certain patient, a number of actions.

These actions are triggered by dropping input files in (subfolders of) the input-folder:

EVS watches these folder(s), executes the action(s) and generates output in the processed-folder:

EVS can be launched via the "vault-uploader.cmd" batch file:

The behaviour of 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 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". EVS will, depending on the action folder, parse the files and extract the Kmehrmessage(s).

What is a Kmehrmessage?

A Kmehrmessage is that part of the file that starts with <kmehrmessage ...> and ends with </kmehrmessage>. One file can contain 0 or more Kmehrmessages. 

EVS will only work with Kmehrmessages of Kmehr-standard 20120401. In this standard, 1 medicationschemeelement transaction and 0 or more treatmentsuspension transactions were considered as the business data of 1 "data entry".

All other data (among which the metadata) will be generated by the EVS and/or the Vitalink platform. As input the business data as depicted in blue here below will be used:

How is a Kmehrmessage identified?

For some actions, typically removing and updating data entries, the input Kmehrmessage needs to have an identification.

There are 2 ways to identify Kmehrmessages:

• by Vitalink ID,
• by EVS reference.

Identification by Vitalink ID

The Kmehrmessage should be preceeded by a Vitalink URI.

The Vitalink ID can not be chosen by the sender when adding new data entries, but are dynamically generated by the Vitalink platform. By consequence, they are not deterministic and are hard to use when defining scenarios.

In the next example, this URI is /subject/83051839468/medication-scheme/32055/1. EVS detects the reserved format  "/subject/###########/medication-scheme/32055" and finally uses "32055" as unique ID.

Identification by EVS reference

An EVS reference is put in 1 (and only 1) free text field in the concerned Kmehrmessage.

The EVS reference can be freely chosen, and facilitates the definition and execution of scenarios.

In the next example, this REF is "===EVSREF:901===". EVS detects the reserved format  "===EVSREF:<any text>===" and finally uses "<any text>" as unique REF.

As from release 1.1.0 the REF must contain a minimum of 3 characters and can contain up to 20 characters, so both ===EVSREF:123=== and ===EVSREF:A123456789B123456789=== are considered valid REFs.

Which actions?

Depending on the folder where the inout-file is dropped, EVS will execute an action.

Action "add"

This action will add a data entry to the vault for each Kmehrmessage found in all dropped files.

In the example below, 3 Kmehrmessages are dropped to be added to the vault:

Action "empty"

This action will remove all data entries from the vault. EVS will do this action once for each dropped file, without any parsing. 

In the example below, a newly created file will trigger emptying of the vault by removing all existing data entries:

Action "export"

This action will export the contents of the vault, without any change to the vault itself. 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 "removeID"

This action will remove the data entries identified by the Vitalink ID in the input file from the vault.

Action "removeREF"

This action will remove the data entries identified by the EVS REF in the input file from the vault.

Action "replace"

This action will replace the contents of the vault by all the Kmehrmessages 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 Kmehrmessages of the last input file!

In the next example, after processing the next 3 input files, the vault contains 2 data entries. 

Action "updateID"

This action will update the data entries identified by the Vitalink ID in the input file.

Action "updateREF"

This action will update the data entries identified by the EVS REF in the input file.

Action "generateREF"

This action will generate an EVS REF for each Kmehrmessage in the input file, and will then replace the contents of the vault by all the Kmehrmessages found in the input file.

A Vitalink ID must be present for each Kmehrmessage in the input file as the EVS REF is derived from the Vitalink ID.

If an EVS REF exists already in the Kmehrmessage, the existing EVS REF is removed and the new EVS REF is put at the same location.

If multiple EVS REFs exist in the Kmehrmessage, all EVS REFs are removed and the new EVS REF is put in the instructionforpatient field.

Likewise, if no EVS REF exists, the new EVS REF is also put in the instructionforpatient field.

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.

The next actions will take place:

• an input-Kmehrmessage with EVS REF not yet existing in the vault will be added to the vault
• an input-Kmehrmessage with EVS REF already existing in the vault will cause an update but only if the input-Kmehrmessage differs from the vault-Kmehrmessage 
• all vault-Kmehrmessages without corresponding EVS REF in the input file will be removed from the vault

If the input-file contains Kmehrmessages without EVS REF or if the EVS REFs used are not unique, the action will not be executed and an error will be thrown.

Processed-folder

After execution of an action a variable number of output files are generated in the processed folder.

The next screenshot shows the output of a successful add-action. Each output file will be explained below:

Each filename exists out of:

<date>-<time>_<patient>_<actor>_<action>_<input filename>_size-<nr of data entries>_<output suffix>.<output extension>

If for some reason the action fails, an error output file is generated:

Configuration

This paragraph explains how to configure EVS.

How to add a patient?

Extra patients can be added by creating files in the next folder:

After initial installation, 2 patient config files are already present. Both can be used as example (copy-paste) to add extra patients. The name of the file, without the extension, needs to be used to identify for which patient the action needs to performed.

After copy paste of the example files, insert the correct info for the new patient:

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.

How to add an actor?

Extra actors can be added by creating files in the next folder:

After initial installation, some actor config files are already present. All can be used as example (copy-paste) to add extra actors. The name of the file, without the extension, needs to be used to identify by which actor the action needs to be performed.

The template examples are given for 3 different types of actors: doctor, nurse and pharmacy.

After copy paste of the appropriate example file, insert the correct info for the new actor:

The needed info in the above example is the SSIN, the location of the certificate and the password of the certificate. The location of the certificate can be freely chosen, but it is good practice to put it in the same folder as the example by installation:

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.

Parameterisation

The next parameters can be passed when launching EVS:

Example of a parameterisation:

Appendix A: Folder structure EVS 1.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 the EVS.

Path							Reserved path	Reserved name	Explanation
EVS									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 EVS, configured as needed by the user.
		\actors							All the actors that can be used by EVS.
		\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 EVS.
	\exe
		\certificates							The certificates used in the actor configuration files.
		\exports							The folder were the EVS-exporter will put exported vault contents, see AppendixB:EVSexporter
		\interaction
			\input
				\katrien
					\gp_van_gucht
						\add
						\empty
						\export
						\removeID
						\removeREF
						\replace
						\updateID
						\updateREF
						\generateREF
						\updateschemeREF
				\patient_template
			\processed
	\scenarios
		\basic_example
	\system
		\dependency-jars

Appendix B: EVS-exporter

Besides the interaction provided by dropping files in the input folder, EVS offers as extended functionality the continuous monitoring of the vault contents. This functionality is provided by EVS-exporter.

Launching

EVS-exporter can be launched via the "vault-uploader.cmd" batch file:

The behaviour of EVS-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 EVS-exporter means that the vault contents of the patient "katrien" will be monitored.

Output

When EVS-exporter detects for the given patients a change in the vault contents, and export is executed. The export is also executed after intial launch.

The exported files are put in the next folder, with for each monitored patient a subfolder. The subfolder is automatically created when the monitoring for this patient is initially started.

The files contain the same as the files generated by EVS in the processed-folder, but the filenames differ.

For EVS-exporter, each filename exists out of:
sv-<subject version>_nv-<node version>_<date>-<time>_<patient>_size-<nr of data entries>_<unique code>_updatedby_<actor>_<output suffix>.<output extension>

When the export fails, an error file will be generated, which is the same behaviour as for the folder-triggered export action of EVS.

Parameterisation

The next parameters can be passed when launching EVS-exporter:

Example of a parameterisation: