[Deprecated] EVSClient - Installation & Configuration

Warning: This documentation is out-dated, newest version of the documentation is available at https://gazelle.ihe.net/gazelle-documentation 

External Validation Service Front-end is a maven project which calls several the web services exposed by the Gazelle tools to validate messages and documents. It may also be plugged to other validation services. 

Sources

Sources of this project are available on the INRIA Forge; sources are managed using SVN. An anonymous access is available if you only want to checkout the sources (read-only access). If you intent to build the tool and to install it on your own server, we recommand to use a tagged version; not the trunk which is the development branch.

svn co https://scm.gforge.inria.fr/svn/gazelle/Maven/EVSClient/tags/EVSClient-version

To retrieve the current version of the tool, consult the release notes of the project in Jira.

Before compiling the application for the first time, you might want have to update the pom.xml file of the parent project (EVSClient) in order to configure the database connection. 

Maven artifact

Each version of the tool is published in our Nexus repository, download the latest release from here. Be carreful, this released artifact is configured to connect to a database named evs-client-prod and owned by user gazelle.

Installation

Read general considerations section of the installation guides to learn about JBoss application server and postgreSQL database.

Once you have retrieved the archive, copy it to your JBoss server in the deploy directory. Be carreful, the file copied in this folder shall be exactly named EVSClient.ear.

cp EVSClient-ear-3.1.0.ear /usr/local/jboss/server/${YOUR_SERVER}/deploy/EVSClient.ear

Users of the EVSClient tool will upload files to be validated on the server, those files are stored in the file system in specific directories. Only the root of the main directory and be configured in the database. Under debian-like systems, we usually store those files at /opt/EVSClient_prod. A ZIP file is available on the Forge that you can unzip in order to easily create all the required directories, starting at /opt.

wget -nv -O /tmp/EVSClient-dist.zip "http://gazelle.ihe.net/jenkins/job/EVSClient-RELEASE/ws/EVSClient-ear/target/EVSClient-dist.zip"
unzip /tmp/EVSClient-dist.zip -d /

To finalize the installation, you must run the script which initialize the application preferences. A SQL script is available here, edit it and check its content before running it.

In order to take into account the new preferences, the application SHALL be restarted:

touch /usr/local/jboss/server/${YOUR_SERVER}/deploy/EVSClient.ear

Configuration

The application databse is : evs-client-prod.

The application uses its database to store:

  • The application preferences
  • The references to the standard/integration profiles that the user will be able to validate against
  • The validation services which are available in the tool
  • The topbar menu
  • The link to the tools which forwards messages/documents to the EVSClient for validation and might query the EVSClient for the result

The following sections explain how to configure the tool.

Application preferences

Users with admin_role role can access the application preference section through the menu Administration --> Manage application preferences.

The table below summarizes the preferences which are used by the tool along with their description and default value.

Variable Default value Description
application_database_initialization_flag database_successfully_initialized Indicates that the DB has been initialized
application_url http://localhost:8080/EVSClient URL to reach the tool
cas_enabled false Indicates authentication mechanism to use
ip_login true Indicates authentication mechanism to use
ip_login_admin .* Pattern to grant users as admin based on their IP address
cas_url Not defined URL of the CAS service
time_zone Europe/Paris Time zone to display time to users
atna_repository /opt/EVSClient_prod/validatedObjects/ATNA Where to store ATNA messages
cda_repository /opt/EVSClient_prod/validatedObjects/CDA Where to store CDA documents
dicom_repository /opt/EVSClient_prod/validatedObjects/DICOM Where to store DICOM files
dicom_scp_screener_xsl dicom/TestDicomResults.xsl XSL used to display Dicom SCP Screener results
display_SCHEMATRON_menu false Indicates if we need a link to the list of schematrons for download
dsub_repository /opt/EVSClient_prod/validatedObjects/DSUB Where to store DSUB files
epsos_repository_codes /opt/EVSClient_prod/bin/EpsosRepository path to epsos codes for epsos-cda-display-tool
gazelle_hl7v2_validator_url http://gazelle.ihe.net/GazelleHL7Validator Path to Gazelle HL7 Validator
hl7v3_repository /opt/EVSClient_prod/validatedObjects/HL7v3 Where to store HL7v3 messages
hpd_repository /opt/EVSClient_prod/validatedObjects/HPD Where to store HPD messages
include_country_statistics true Authorize or not the application to query geoip to retrieve the countries the users are from
monitor_email test@test.com Contact of the person who monitors the application
number_of_segments_to_display 40 Number of segment to display when displaying HL7v2 messages
object_for_validator_detector_repository /opt/EVSClient_prod/validatedObjects/validatorDetector path to the repository where object for validator_detector are stored
pdf_repository /opt/EVSClient_prod/validatedObjects/PDF Where to store PDF files
root_oid 1.2.3 Root of the OID used to uniquely identify validation requests
saml_repository /opt/EVSClient_prod/validatedObjects/SAML Where to store SAML assertions
svs_repository /opt/EVSClient_prod/validatedObjects/SVS Where to store SVS messages
tls_repository /opt/EVSClient_prod/validatedObjects/TLS Where to store certificates
xds_repository /opt/EVSClient_prod/validatedObjects/XDS Where to store XDS messages
xdw_repository /opt/EVSClient_prod/validatedObjects/XDW Where to store XDW messages
application_admin_email contact@evsclient.net Contact of the person responsible for the application
application_admin_name contact Person responsible for the application
application_issue_tracker_url http://gazelle.ihe.net/browse/EVSCLT URL of the project in the issue tracking system

 References to standards

 What we call a referenced standard in the EVS Client tool is an entry which indicates the underlying standard or integration profile implemented by the system which produces the documents and/or messages that the tool is able to validate. We use this concept to structure both the Java code and the graphical user interface.

A referenced standard is defined by a name, optionaly a version and an extension. Then each entry in the database is given a unique label and we can also provide a name to be displayed to the user in the drop-down menus and a description explaining what is the standard and what the tool is going to validate.

Note that a pre-defined list of standard names is available and matches the standard for which a validation service client has been implemented within the tool.

Administrators will access the section of the tool which enables the configuration of the standards from Administration --> Manage referenced standards. This page lists the standards already defined within the tool. You can edit them or add new ones.

When you create a new standard, make sure you use a unique label. In addition, check the spelling of the extension, it might be used by the tool to query for the list of available validation methods. Note that you can also provide a link to the image to be used in the drop-down menus. For XML-based documents/messages, you can provide the list of the XML stylesheets to use to nicely display the document/message to the user.

Currently available standards are HL7v2, HL7v3, CDA, TLS (stands for certificates), DSUB (metadata), XDS (metadata), XDW (metadata), HPD (messages), SVS (messages), WADO (requests), DICOM, SAML (assertions), ATNA (Audit messages).

Validation services

 A validation service in the context of the EVSClient tool is either a web service exposed by another tool or a binary executed directly on the server or even a JAR library called by the tool. An entity has been created in the tool to store all the information about those services. It makes easier the management of the services and allows a different configuration depending on the location of the EVSClient tool.

Going to Adminisration --> Manage validation services, the administrator will access the list of all the validation services which are declared and used by the application. Each entry can be edited. You can also create new entries.

When defining a validation service you need to provide:

  • A name and a unique kewyord
  • The validation engine (mainly used for validation of XML-based messages/documents; in that case SHALL be schematron or model-based in order to indicate to the tool which client stub to use)
  • The link to the stylesheet used to display the result (validation service might return results as an XML string)
  • The endpoint to reach the service (may also be a path to a binary on your system)
  • You can also indicate if the validation service is available to the user or not
  • The list of standards to which this validation service applies.

Configuring the top bar menu

A menu bar is made of two kind of entities, the menu groups which are the menu entries displayed in the top bar and the menu entries which are the entries displayed in the drop-down list.  The top bar menu of EVSClient is built using a list of menu groups stored in the database. Administrator users can update this list from the page accessible at Administration --> Menu configuration. On this page are lists all the menu groups defined for this instance of the tool. 

A menu group is defined by:

  • a label and an icon (path to the icon can be relative to the application or can be an external reference)
  • its order on the page
  • the list of referenced standards which will be available from this menu group
  • a boolean which indicates whether or not displaying the menu group

For each standard listed in the menu group, the icon will be the one defined at standard level. For each menu (except for DICOM) the sub menus will be "validate", "validation logs" and "statistics". Links to these sections are automatically built from the standard name and extension.

Calling tools

Some tools of the Gazelle testbed send validation requests to the EVSClient. To do so, we use servlets and then we may want to send back the result to the calling tool. We assume that not only one tool will send such requests, we maintain a list of tools which are likely to redirect the user to the EVS Client. 

This list is accessible under Administration --> Calling tools.

For each tool, we need an OID which uniquely identify the instance of the tool and the URL used to send back results. Currently two categories of tools can use the EVSClient in this way, Gazelle proxy instances and Gazelle Test Management instances; you need to precise it to the tool so that the EVS Client knows how to send back results (if the feature is available in the calling tool).

 

Dicom validator installation

Dicom3Tools

 

We need to install Dicom3Tools :

  •  sudo apt-get install g++
  •  sudo apt-get install xutils-dev

Download the last dicom3tools version (http://www.dclunie.com/dicom3tools/workinprogress/) and untar it.

Go in the untar folder.

  •  ./Configure
  • make World
  • sudo make World install

Now, you need to make symbolic link in /opt/dicom3tools :

  • sudo ln -s /usr/local/bin/dcdump dcdump
  • sudo ln -s /usr/local/bin/dciodvfy dciodvfy
  • cd ..
  • sudo chown -R gazelle:gazelle dicom3tools/

Pixelmed