User Manual

Contents

• Work with Source Code
•    Source Code Overview
•    Build from Source Code
• Work with Binary Code
•    Prerequisite
•    Installation
•    Set Up OpenEMPI
•    Deployment
•    Configure OpenPIXPDQ
•    Start/Stop PIX and PDQ servers
• OpenPIXPDQ Configuration
•    Understand Configuration Files
• OpenPIXPDQ UI

Work with Source Code

Source Code Overview

The source code of OpenPIXPDQ library is divided into three modules

1. OpenPIXPDQ
2. OpenEmpiAdapter
3. OpenWeb

OpenPIXPDQ library implements IHE Patient Identifier Cross-Reference (PIX) profile, and Patient Demographic Query (PDQ) profile.

IHE PIX and PDQ profiles specify both client and server side PIX/PDQ implementation. However, OpenPIXPDQ implements only the server side actors such as PIX Manager and PDQ supplier. PIX Manager and PDQ Supplier together can also be called PIX/PDQ server.

OpenPIXPDQ supports 4 server side transactions: 3 transactions for PIX Manager, namely PIX Feed, PIX Query and PIX Update Notification, and one transaction, PDQ Query, for PDQ Supplier.

EMPI lies underneath PIX Manager and PDQ Supplier, that provides a patient matching algorithm and patient data manipulation API such as create, update and merge patients. (OpenPIXPDQ uses open source OpenEMPI as an eMPI. OpenEMPI is available for download from Open Health Tools site: https://openhie.projects.openhealthtools.org/svn/openhie)

OpenEmpiAdapter is an adapter meant to fill the gap between eMPI and OpenPIXPDQ. This Adapter converts all data supplied by OpenPIXPDQ to the eMPI understandable format, so that the PIX Manager and PDQ Supplier would not rely on a particular eMPI system.

OpenWeb is the UI for OpenPIXPDQ. This contains pages like Registration, PIX Query, Patient Demographic Query, Configuration and Message Log. We can configure all actors of PIX/PDQ server using Configuration page, and Message Log page is used to render raw messages from database.

Build from Source Code

To build your own OpenPIXPDQ, you need the projects OpenPIXPDQ, OpenEmpiAdapter and OpenWeb, as well as OpenEMPI from the openhie project on the OHT site .

OpenPIXPDQ URL: https://openpixpdq.svn.sourceforge.net/svnroot/openpixpdq

OpenEMPI URL: https://openhie.projects.openhealthtools.org/svn/openhie

Each of the three OpenPIXPDQ modules can be run in either IDE or by ant build script. We use Eclipse v3.3 IDE. The required project classpath and setting files are checked into the SVN. To make it work, you may need just minimal setting changes such as JDK location and JBoss (or Tomcat) server configuration.

The following files can be built by ant build files:

openempi-adapter.jar: Run ant build file (build.xml) under OpenEMPIAdapter. Make sure that all paths in build.properties are configured properly.

openpixpdq.jar: Run ant build file (build.xml) under OpenPIXPDQ. Make sure that all paths in build.properties are configured properly. This jar contains core functionality of PIX/PDQ server, and can be run outside web container in a stand alone mode.

openpixpdq.war: Run ant build file (build.xml) under OpenWeb. Make sure that all paths in build.properties are configured properly. This will create openpixpdq.jar, openempi-adapter.jar copies under OpenWeb library, and create openpixpdq.war and deploy the war file under \server\default\deploy.

openempi.ear: This file is the work from the openhie project on OHT. However, we provide a ready to deploy copy of openempi.ear in Resources\OpenEMPI folder on our SVN repository, where you can also find relevant configuration files.

Work with Binary Code

Before install OpenPIXPDQ, you can either download a distributable file, or build your own from the source code as mentioned above.

Prerequisite

Make sure you have installed the following software and java environment before setting up OpenPIXPDQ and OpenEMPI,

• Database – Postgresql or My SQL (Our tested DB version is Postgresql 8.3)
• Application Server - JBoss Server (Our tested version is JBoss 4.0.5GA)
• Java – Jdk 1.6

Installation

• Just unzip the distributable file to a machine where you would like to install the PIX/PDQ server

Setup OpenEMPI

• ? Create a database instance, for example openempi. You may want to create a database user for it.
• Create tables - run ICS_schema_creat-postgres.sql or ICS_schema_creat-mysql.sql script located under openempi\conf
• Copy ICS.properties, IcsSql.xml (from openempi/conf ) to a configuration directory on the server where jboss is hosted, and add -Dics.properties.file property to JBoss JVM. For example, in Windows, add this JAVA_OPTS in the run.bat file: JAVA_OPTS=%JAVA_OPTS% -Dics.properties.file= \ICS.properties
• Edit ICS.properties, set the property ICS_SQL_FILE = your configuration directory \IcsSql.xml
• Configure a data source in Jboss server, If your data source name is OpenempiDS, then edit ICS.properties, and set the property JNDI_DATASOURCE = java:/OpenempiDS
• Make sure you have a jdbc driver for the database of your choice under jboss server\default\lib. For Postgres, we use postgresql-8.3-603.jdbc4.jar

Deployment

The out-of-the-box distributable file (openpixpdq-1.0.zip) contains both openpixpdq.war and openempi.ear. To deploy, just drop the both files to the \server\default\deploy directory. That’s all you need to do.

Configure OpenPIXPDQ

To configure PIX Manager and PD Supplier actors, follow the section below: OpenPIXPDQ Configuration

Start/Stop PIX and PDQ servers

There are two ways to start/stop PIX and PDQ servers

1. For web based OpenPIXPDQ running in JBoss Server

• Follow the above deployment section to deploy openempi.ear and openpixpdq.war.
• Start JBoss server.
• Go to http://localhost:8080/openpixpdq, where 8080 is the default JBoss server port iunless you have changed it.
• Load all actors by browsing IheActors.xml on the Configuration UI
• Select the check box of particular actor or all actors
• Click on save button to start selected actors
• To stop press Stop all button.

2. For stand alone OpenPIXPDQ running with command line

• Unfortunately, you still need to deploy and run openempi.ear in JBoss server.
• But instead of using openpixpdq.war, you just run the main method in PixPdqServer to start or stop PIX/PDQ server. The required libs are enclosed in the distributable.

Note: We have not created Windows and Unix command scripts to start up and shut down the PIX/PDQ server. We leave them as your home work assignment. You are welcome to contribute them to us if you have worked on them.

OpenPIXPDQ Configuration

OpenPIXPDQ requires specific information about the PIX/PDQ server itself as well as the information about the peers in order to properly format the data to accept an incoming request and send a response. This information is configured in XML actor files, and loaded by the configuration loader before the PIX/PDQ server starts.

OpenPIXPDQ have sample configuration files located at conf/mesatests/actors folder, which is located in the root folder of OpenPIXPDQ. These files were successfully used for mesa tests and Connectathon tests. You are free to copy the whole actors folder and create your own configuration files. The actors folder has a bunch of xml configuration files. The starting xml file is IheActors.xml; all the other xml files can be linked from the IheActors.xml. This file contains connections, actors, or files that describe actors or connections. The certs folder under actors contains private key and public certificate used by secure transactions.

Understand Configuration Files

Tags:

Note: The xml syntax including tags, attributes and elements is all case-insensitive. But we will try to be consistent across all the configuration files.

Configuration Tag:

Configuration

Each XML configuration file has a root Configuration tag.

ConnectionFile Tag:

ConnectionFile	Specifies a file that defines standard connection and/or secure connection configuration.
Attributes
File	Required	The file name of this ConnectionFile.

Example: <connectionfile file="AuditRepositoryConnections.xml" />

Actor Tag:

Actor	Defines an actor such as PIX Manager, PD Supplier or Secure Node
Attributes
Name	Required	The name of this actor. Any name can be given, but be sure to avoid duplication.
Type	Required	Use PixManager for a PIX Manager actor, and PdSupplier for a PD Supplier actor
Elements
Description	Optional	The detailed description of this actor
Connection	Required	Describes the connection source for this actor.
-source	Required	The connection name of this Connection, which has to be defined in one of the Connections.xml files
PixConsumer	Optional	Describes a PIX Consumer that subscribes to PIX Update Notification messages. It is applicable to a PixManager actor.
-connection	Required for PixConsumer	The connection name of this PIX Consumer, which has to be defined in PixConsumerConnections.xml
XdsRegistry	Optional	Describes a XdsRegistry that accepts PIX Feeds from this PIX Manager. It is applicable to a PixManager actor.
- connection	Required for XdsRegistry	The connection name of this XDS Registry.

 

Ex:  <Actor name="pixman" type="PixManager">

      <Description>Misys PIX Manager</Description>

      <Connection source="misys-pix-manager" />

    </Actor>

Example for IheActors.xml:

StandardConnection Tag:

StandardConnection	Defines a non-TLS connection.
Attributes
Name	Required	The name of this connection, which must be referenced by the Actors defined in IheActor.xml.
Elements
HostName	Optional for server; required for Client.	The host name or ip address that this connection connects to. Use localhost if this connection is for a server socket.
Port	Required	The port of this connection
Identifier -NamespaceId -UniversalId -UniversalIdType	Required	The identifier tag specifies an assigning authority, or an identity such as ReceivingApplication and ReceivingFacility. It can include 3 elements: NamespaceId, UniversalId and UniversalIdType. There are two ways to specify an Identity: one way is to use NamespceId; the other is to use the combination of UniversalId and UniversalIdType. If both NamespaceId and the combination of UniversalId and UniversalIdType are used, they must be consistent and refer to the same entity.
Property	Required and Optional	The Property tag defines a property for this connection. There are multiple properties defined for each actor connection. Some are required; some others optional. For a PixManager connection, pixManagerAdapter is required, and storeLogger is optional. For a PdSupplier connection, pdSupplierAdapter is required, and storeLogger is optional.
PropertySet	Optional	Defines a group of related properties. For example, QueryProperties in a PdSupplier connection.
-Entry	Optional	Each entry defines a specific property for this PropertySet.
IncludeFile	Optional	This is an inline element. It can be used to place a trunk of properties in a separate xml file. The main purpose of the Include File is to reuse some common configuration

 

 

The following example defines Misys ReceivingApplication

<Identifier name="ReceivingApplication">            <NamespaceId>PAT_IDENTITY_X_REF_MGR_MISYS</NamespaceId>

</Identifier>

The following example defines a specific domain (the global domain) configuration

<Identifier type="domain" name="GLOBAL">

         <NamespaceId>IHENA</NamespaceId>

         <UniversalId>1.3.6.1.4.1.21367.2009.1.2.300</UniversalId>

         <UniversalIdType>ISO</UniversalIdType>

</Identifier>

The following example defines an IncludeFile.

Ex: <includefile name="PixPdqClientDomains.xml" />

The above example means that the Content of PixPdqClientDomains.xml can be used to replace this tag.

Example for PixManagerConnections.xml

Example for PixPdqClientDomains.xml

SecureConnection Tag:

SecureConnection	Defines a TLS connection.
It has the same attributes and elements as the corresponding StandardConnection. In addition, a SecureConnection must include the following additional Elements:
KeyStore	Required	The file containing the Key Store for this connection. By default, it is in the certs folder.
KeyPass	Required	The password for the Key Store.
TrustStore	Required	The file containing the Trust Store for this connection. By default, it is in the certs folder.
TrustPass	Required	The password for the Trust Store.

 

Example for Trust and KeyStore in SecureConnection tag.

OpenPIXPDQ UI

OpenPIXPDQ UI has five pages of different purpose.

Registration: Registration page is used to register a patient.

Demographic Query: used to query patients using demographics. As a result this page displays all matched patients with the given demographics.

Pix Query: Used to query a patient with Patient ID and Assigning Authority.

Configuration: Used to load actors and start/stop the servers.

Message Log: Used to search for the all audit information.