[Deprecated] Patient Manager - Installation & Configuration

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

The PatientManager project was firstly named PAMSimulator since it was only dedicated to the testing of the actors defined in the Patient Administration Management (PAM) integration profile. Later we need to implement the PIX and PDQ actors and decided to have all the tools concerning the management of patient demographics, identifiers and encounters in a same place and the PAMSimulator became the PatientManager. However, the maven project has not been renamed and is still named PAMSimulator.

Sources & binaries

To get the name of the latest release, visit the PAM project in JIRA and consult the "Change log" section.

If you intent to you the CAS service provided by Gazelle at https://gazelle.ihe.net or if you choose to not use the CAS, you can download the last release of the tool, available in our Nexus repository.

Note that

if you use the CAS service provided by Gazelle, you will have access to the administration tasks only if you have the admin priviledges in Gazelle
if you do not use a CAS service, users will not be able to authenticate theirselves and any user can access the administration tasks (see the Configuration section for an overview of those tasks)

If you have your own CAS service, you need to package your own version of the tool. Proceed according the following steps:

Checkout the last tagged version available in Gazelle sources repository ($versionName will depend of the release you want to checkout)
```
svn co https://scm.gforge.inria.fr/svn/gazelle/Maven/simulators/PAMSimulator/tags/PAMSimulator-$versionName
```
Edit PAMSimulator/pom.xml file and in the public profile section, update the cas.url properties to match your CAS service URL
Package the project
```
mvn -P public clean package
```
The binary will be available in PAMSimulator/PAMSimulator-ear/target folder

Database configuration

The PDQ part of the simulator uses fuzzystrmatch extension of postgreSQL. Follow the instructions below to enable this module in your database:

Install the contrib module of postgreSQL

 sudo apt-get install postgresql-contrib

Restart postgreSQL (if an application is using it, first close it)
```
 sudo /etc/init.d/postgresql restart 
```
Login as postgres user
```
 sudo su postgres 
```
Enable the fuzzystrmatch module

# for psql 9.1 and above
psql
postgres# CREATE EXTENSION fuzzystrmatch;
# for psql 8.4
psql -U postgres -d pam-simulator -f fuzzystrmatch.sql

Installation

Check the General considerations page, it will inform you about the prerequisites for installing Gazelle tools.
Create a new database named pam-simulator, using encoding UTF-8 and owned by gazelle
```
createdb -U gazelle -E UTF8 pam-simulator
```
Copy the EAR in your JBoss server and start it.
Connect to the database and execute the initialization script. If you have checkout a copy of a tagged version, this file is available at PAMSimulator/PAMSimulator-ear/src/main/sql/import.sql

If you do not intent to use any CAS service, execute the following SQL command

update app_configuration set value = 'true' where variable = 'application_works_without_cas';

Finally, open your favorite browser (please avoid usage of IE), and go to http://yourJbossInstance/PatientManager

Configuration

Application preferences

User the Administration menu, you will find a sub-menu entitied "Configure application preferences". The following preferneces must be updated according to the configuration of your system. The table below summarizes the variables used by the PatientManager tool.

Variable	Description	Default value
application_url	The URL used by any user to access the tool. The application needs it to build permanent links inside the tool	http://publicUrlOfJboss/PatientManager
application_namespace_id	Defines the namespaceID of the issuer of the identifiers generated by the tool	IHEPAM
application_universal_id	Defines the universal ID of the issuer of the identifiers generated by the tool. It's formatted as an OID and shall be unique across all instances of PatientManager tool	a uniquely defined OID
application_universal_id_type	Defines the type of universal id	ISO
cas_url	URL of the SSO service	https://gazelle.ihe.net/cas
create_worklist_url	The URL of the OrderManager instance you may use to create DICOM worklists	OrderManager on Gazelle
default_pdq_domain	For PDQv3, defines if we use SeHE or ITI rules	ITI
hl7v3_organization_oid	OID of the organization issuing/receiving HL7v3 messages	a uniquely defined OID
hl7v3_pdq_pdc_device_id	Identifies the PDQv3/PDC actor of the tool	a uniquely defined OID
hl7v3_pdq_pds_device_id	Identifies the PDQv3/PDS actor of the tool	a uniquely defined OID
hl7v3_validation_xsl_location	Stylesheet for displaying HL7v3 validation service reports	http://gazelle.ihe.net/xsl/hl7v3validatorDetailedResult.xsl
hl7v3_validator_url	URL of the web service exposed by Gazelle HL7 Validator for validating HL7v3 messages	http://sake.irisa.fr:8080/GazelleHL7v2Validator-GazelleHL7v2Validator-ejb/GazelleHL7v3ValidationWS?wsdl
pdqv3_pds_url	Endpoint of the PDQv3/PDS embedded in the tool (for display to the user)	http://ovh1.ihe-europe.net:8180/PAMSimulator-ejb/PDQSupplier_Service/PDQSupplier_Port_Soap12?wsdl
sending_application sending_facility	Used to populate MSH-3 and MSH-4 fields of the HL7 messages produced by the tool	PAMSimulator IHE
time_zone	Defines which time zone to use to display dates and timestamps	Europe/Paris
application_works_without_cas	Tells the application how users are authenticated	True: all users are granted as admin False: uses a CAS service to authenticate users
ip_login	whether to enable or not the authentication by IP address	false
ip_login_admin	if ip_login = true, a regex to grant users with admin role according to their IP addresses	.*
dds_ws_endpoint	Location of the Demographic Data server WSDL	DDS WS on Gazelle
gazelle_hl7v2_validator_url	URL of the Gazelle HL7 Validator tool	http://gazelle.ihe.net/GazelleHL7Validator
svs_repository_url	URL of the Sharing Value Set Repository actor of the SVSSimulator	http://gazelle.ihe.net
timeout_for_receiving_messages	How long must the HL7 initiator wait for a response (in ms)	10000
url_EVSC_ws	URL of the Gazelle HL7 Validator wsdl (the one for HL7v2.x validation)	GazelleHL7Validator WS on Gazelle
use_ids_from_dds	DDS generates patient identifiers, the PatientManager can use them or generate its own using the application_namespace_id and application_universal_id. This value is used as the default choice on patient generation panel	true
xsl_location	URL to access the XML stylesheet used to display HL7v2.x validation results	XSL location

HL7v2.x responders

From the Administration/HL7 Responders configuration page, you will be able to configure each actor of the tool playing the role of a responder in a HL7-based transaction. A configure consists in the receiving application and facility and the port on which it listens to incoming messages. The IP address is not used by the server but must be set properly so that the users can configure their systems under test to communicate with the tool. DO NOT update the other parameters, it would prevent the tool from working correctly.

Note: When you update a configuration, do not forget to restart it.

Home page

The first time you access the application, you may notice that the home page of the tool is not configured. To set a title and a welcome message, log into the application with admin rights (every user can update this if you are not using CAS).

Note that you will have to set up this page for all the languages supported by the application.