Patient Manager
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 privileges 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)
git clone https://gitlab.inria.fr/gazelle/public/simulation/patient-manager.git cd PAMSimulator git checkout tags/PAMSimulator-$versionName -
Package the Patient Manager project. Go to the PAMSimulator folder then apply the following command line
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
4.1. for psql 9.1 and above
psqlpostgres\# CREATE EXTENSION fuzzystrmatch;4.2. 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.
WARNING : From version 9.11.0, datasources have been extracted from the ear. The template file can be found in /src/main/application/datasource in the source or in the file PAMSimulator-X.X.X-datasource.zip from the nexus. For more informations about how to manage that externalization, please refer to general considerations for JBoss7.
-
Create a new database named pam-simulator, using encoding UTF-8 and owned by gazelle
createdb -U gazelle -E UTF8 pam-simulator -
WARNING : From version 9.11.0, datasources need to be extracted from the ear folder (found in /src/main/application/META-INF). For more informations about how to manage that externalization, please refer to general considerations for JBoss7.
Datasource name : PAMSimulatorDS
Database name : pam-simulator
-
Copy the PAMSimulator.ear file 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 = 'cas\_enabled'; -
Finally, open your favorite browser (please avoid usage of IE), and go to
http://yourJbossInstance/PatientManager
Interaction with other applications
This section describes with which other tools Patient Manager needs to interact to offer a complete experience to the user.
Integration diagram
Tools
| Application name | Recommended version | Usage |
|---|---|---|
| Demographic Data Server | latest | Used to generate patients (Required when PAM, ADT features are used, optional otherwise) |
| Gazelle HL7 Validator | latest | Used to validate HL7v2/HL7v3 messages (Not used by PDQm/PIXm features) |
| Gazelle FHIR Validator | latest | Used to validate FHIR messages (Used only by PDQm/PIXm features) |
| SVS Simulator | latest | Used by the PAM/ADT actors to build the messages and display options to the user |
| Gazelle STS | latest | Used by the XUA feature to request / validate SAML assertions |
| Order Manager | latest | Create a worklist for a given patient or encounter |
Requirements
The table below gathers which tools are required based on the activated features.
Legend:
- R: required, feature will not work correctly without it
- O: optional, not needed to use the feature but might help
- N: Not used by the feature at all
| Application Name | PAM | ADT | PDQ | PDQv3 | PDQm | PIX | PIXv3 | PIXm | XCPD | SEQUOIA | ITI-FR | CONNECTATHON | EPD | XUA | AUTOMATON | WORKLIST |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Demographic Data Server | R | R | O | O | O | O | O | O | O | R | O | R | N | R | N | |
| Gazelle HL7 Validator | R | R | R | R | N | R | R | N | R | R | R | R | R | N | R | N |
| Gazelle FHIR Validator | N | N | N | N | R | N | N | R | N | N | N | N | N | N | N | N |
| SVS Simulator | R | R | O | O | O | O | O | O | O | R | R | R | N | R | N | |
| Gazelle STS | N | N | N | N | N | N | N | N | N | N | N | N | N | R | N | N |
| Order Manager | N | N | N | N | N | N | N | N | N | N | N | N | N | N | N | R |
Configuration
Menu configuration
The menu bar of the application is configurable. That means that you can hide the profiles that you are not going to test.
To choose the features to be enabled in your instance of the tool, access Administration > Enable/Disable features. For each entry, check (enable) or uncheck (disable) the checkbox in the last column. Changes are saved automatically. To reload the menu bar with its new content, simply refresh the page or access the home page.
The table below gathers the available features
| Feature | Description | EPD | BP6 | IHE | CA | Sequoia |
|---|---|---|---|---|---|---|
| CONNECTATHON - Connectathon demographics sharing | Use this feature to enable the Sharing of specific demographics among test session participants | enabled | disabled | enabled | enabled | disabled |
| EPD - Electronische Patient Dossier (eHealthSuisse) | Use this feature if the simulator is used in the context of the eHealthSuisse EPD project. Shall be used with application preference default_pdq_domain = EPD | enabled | disabled | disabled | disabled | disabled |
| IHE - Default version of the profiles | Use this feature if the simulator is only used for IHE default version of the profile. Shall be used with application preference default_pdq_domain = IHE | disabled | enabled | enabled | enabled | enabled |
| ITI-FR - French version of the ITI profiles | Use this feature to causes the simulator to offer the user to send PAM messages compliant with the French extension of the PAM profile | disabled | enabled | disabled | disabled | disabled |
| Modality Worklist - Users can share patients with Order Manager | Enable this feature will add a button in the list of patient to allow the user to share this patient with Order Manager and thus create a worklist or any other kind of orders for this patient | disabled | disabled | enabled | disabled | disabled |
| PAM Automaton | Gives access to the automaton for the PAM profile (based on GraphWalker), you do not use this feature if you do not test the PAM profile | disabled | enabled | enabled | disabled | disabled |
| PAM - Patient Administration Management | Displays the PAM menu and gives access to the simulated actors for this profile | disabled | enabled | enabled | enabled | disabled |
| PDQm - Patient Demographic Query for Mobile | Displays the PDQ* menu and gives access to the simulated actors for this profile | disabled | disabled | enabled | disabled | disabled |
| PDQ - Patient Demographic Query | Displays the PDQ* menu and gives access to the simulated actors for this profile | disabled | disabled | enabled | enabled | disabled |
| PDQV3 - Patient Demographic Query HL7V3 | Displays the PDQ* menu and gives access to the simulated actors for this profile | enabled | disabled | enabled | enabled | enabled |
| PIXm - Patient Identifier Cross-referencing for Mobile | Displays the PIX* menu and gives access to the simulated actors for this profile | disabled | disabled | enabled | disabled | disabled |
| PIX - Patient Identifier Cross-referencing for MPI | Displays the PIX* menu and gives access to the simulated actors for this profile | disabled | disabled | enabled | enabled | disabled |
| PIXV3 - Patient Identifier Cross-referencing HL7V3 | Displays the PIX* menu and gives access to the simulated actors for this profile | enabled | disabled | enabled | enabled | enabled |
| Radiology ADT | Displays the ADT menu to send RAD-1 and RAD-12 messages to your MPI | disabled | disabled | enabled | disabled | disabled |
| Sequoia - Extensions for The Sequoia project | Use this feature if the simulator is used in the context of the Sequoia project, it will causes HL7v3 initiators to append the SOAP security header as defined by Sequoia project specifications | disabled | disabled | disabled | disabled | enabled |
| XCPD - Cross-Community Patient Discovery | Displays the XCPD menu and gives access to the simulated actors for this profile | enabled | disabled | enabled | enabled | enabled |
| XUA - Cross-Enterprise User Access | Displays the XUA menu and allows the user to ask the XCPD Initiator to include a SAML assertion in the SOAP header | disabled | disabled | enabled | disabled | enabled |
Application preferences
Under the Administration menu, you will find a sub-menu entitled “Configure application preferences”. The following preferences 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 |
| 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_pix_consumer_device_id | Identifies the PIX consumer actor of the tool | a uniquely defined OID |
| hl7v3_pix_mgr_device_id | Identifies the PIX manager of the tool | a uniquely defined OID |
| hl7v3_pix_organization_oid | Identifies the PIX organization of the tool | a uniquely defined OID |
| hl7v3_pix_src_device_id | Identifies the PIX source actor of the tool | a uniquely defined OID |
| hl7v3_pixv_src_device_id | Identifies the PIXv3 source actor of the tool | a uniquely defined OID |
| hl7v3_validation_xsl_location | Stylesheet for displaying HL7v3 validation service reports | https://gazelle.ihe.net/xsl/hl7v3validatorDetailedResult.xsl |
| hl7v3_validator_url | URL of the web service exposed by Gazelle HL7 Validator for validating HL7v3 messages | https://gazelle.ihe.net/GazelleHL7v2Validator-ejb/ModelBasedValidationWSService/ModelBasedValidationWS?wsdl |
| hl7_version | HL7v2.X version used | 2.5 |
| pdqv3_pds_url | Endpoint of the PDQv3/PDS embedded in the tool (for display to the user) | https://gazelle.ihe.net/PAMSimulator-ejb/PDQSupplier_Service/PDQSupplier_PortType?wsdl |
| pixv3_cons_url | Endpoint of the PIXv3 consumer embedded in the tool (for display to the user) | https://gazelle.ihe.net/PAMSimulator-ejb/PIXConsumer_Service/PIXConsumer_PortType?wsdl |
| pixv3_mgr_url | Endpoint of the PIXv3 manager embedded in the tool (for display to the user) | https://gazelle.ihe.net/PAMSimulator-ejb/PIXManager_Service/PIXManager_PortType?wsdl |
| sending_application | Used to populate MSH-3 field of the HL7 messages produced by the tool | PAMSimulator |
| sending_facility | Used to populate MSH-4 field of the HL7 messages produced by the tool | IHE |
| time_zone | Defines which time zone to use to display dates and timestamps | Europe/Paris |
| 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 | https://gazelle.ihe.net/GazelleHL7Validator |
| svs_repository_url | URL of the Sharing Value Set Repository actor of the SVSSimulator | https://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) | https://gazelle.ihe.net/GazelleHL7v2Validator-ejb/gazelleHL7v2ValidationWSService/gazelleHL7v2ValidationWS?wsdl |
| 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 |
| hl7v2_xsl_location | URL to access the XML stylesheet used to display HL7v2.x validation results | https://gazelle.ihe.net/xsl/hl7Validation/resultStylesheet.xsl |
| fhir_validation_url | Fhir validation url | https://gazelle.ihe.net/FhirValidator-ejb/gazelleFhirValidationWSService/gazelleFhirValidationWS?wsdl |
| hl7fhir_json_validation_xsl_location | XSL Stylesheet for JSON Fhir instances | |
| hl7fhir_xml_validation_xsl_location | XSL Stylesheet for JSON XML instances | |
| xcpd_respgw_cron_trigger | Period for the XCPD Responding Gateway to check if deferred responses have to be processed | 1 * * * * ? |
| gazelle_sts_url | URL of gazelle-sts to be contacted for issuing and validating SAML assertions | \(PLATFORM_URL\)/gazelle-sts?wsdl |
| sts_default_password | Default password to provide to Gazelle STS for assertion validation | connectathon |
| sts_default_username | Default username to provide to Gazelle STS for assertion validation | valid |
| sts_default_audience_url | Default audience to provide to Gazelle STS for assertion issue | http://ihe.connectathon.XUA/X-ServiceProvider-IHE-Connectathon |
| account_assigning_authority | ID of the domain to be used to generate account numbers (Configured from Assigning authority page) | |
| movement_assigning_authority | ID of the domain to be used to generate movement identifiers (Configured from Assigning authority page) | |
| visit_assigning_authority | ID of the domain to be used to generate visit numbers (Configured from Assigning authority page) | |
| patient_assigning_authority | ID of the domain to be used to generate default patient identifiers (Configured from Assigning authority page) | |
| keystore_password | Password to access the keystore (used when the SOAP header contains a signature) | |
| private_key_password | Password to access the private key in the keystore (used when the SOAP header contains a signature) | |
| path_to_keystore | Absolute path of the keystore (used when the SOAP header contains a signature) | |
| private_key_alias | Alias of the private key in the keystore (used when the SOAP header contains a signature) |
SSO Configuration
There are additional preferences to configure the SSO authentication.
| Preference name | Description | Example of value |
|---|---|---|
| cas_enabled | Enable or disable the CAS authentication. | true |
| ip_login | Enable authentication by IP address matching ip_login_admin regex. |
false |
| ip_login_admin | Regex to authorize ip authentication if CAS authentication is disabled. | .* |
For more documentation about SSO configurations, follow the link here.
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.