User Manual


Work with Source Code

Source Code Overview

The source code of OpenPIXPDQ library is divided into three modules

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:

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 .



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 are configured properly.

openpixpdq.jar: Run ant build file (build.xml) under OpenPIXPDQ. Make sure that all paths in 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 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.


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


  • 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, IcsSql.xml (from openempi/conf ) to a configuration directory on the server where jboss is hosted, and add property to JBoss JVM. For example, in Windows, add this JAVA_OPTS in the run.bat file: JAVA_OPTS=%JAVA_OPTS% \
  • Edit, 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, 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


The out-of-the-box distributable file ( 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


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.
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
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
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" />


Example for IheActors.xml:

 <!--Defines the configuration of Audit Repository Server for Audit Client-->
  <connectionfile file="AuditRepositoryConnections.xml" />
 <!--Defines the configuration of local system as PD Supplier-->
  <connectionfile file="PdSupplierConnections.xml" />
 <!--Defines the configuration of local system as PIX Manager-->
    <connectionfile file="PixManagerConnections.xml" />
 <!--Defines the configuration of PIX Consumers-->
    <connectionfile file="PixConsumerConnections.xml" />

    <!--The PIX Manager actor configuration-->
    <actor name="pixman" type="PixManager">
      <description>Misys PIX Manager</description>
      <connection source="misys-pix-manager" />
      <!--Define 0 or more PIX Consumers that subscribe to PIX Update Notification -->
      <!-- PixConsumer connection="swpartners" /-->
      <!-- PixConsumer connection="tiani-spirit" /-->

    <!--The PD Supplier actor configuration-->
    <actor name="pdsup" type="PdSupplier">
      <description>Misys PD Supplier</description>
      <connection source="misys-pd-supplier" />

StandardConnection Tag:

StandardConnection Defines a non-TLS connection.
Name Required The name of this connection, which must be referenced by the Actors defined in IheActor.xml.
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





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>


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

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





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

    <standardconnection name="misys-pix-manager">
        <!--The host name of the PIX Manager Server-->
        <!--The port for PIX Query transaction-->
        <Identifier name="ReceivingApplication">
            <!-- NamespaceId>MESA_XREF</NamespaceId-->
        <Identifier name="ReceivingFacility">
            <!-- NamespaceId>XYZ_HOSPITAL</NamespaceId-->
        <!-- If test is true, it will by pass some receiving application
             and receiving facility validation -->
        <Property name="test" value="true"/>

        <!-- pixManagerAdapter - required :
            The java adapter class that provides the patient data source for this Pix Manager (required).
            This class must implement org.openhealthexchange.openpixpdq.ihe.IPixManagerAdapter -->
         <Property name="pixManagerAdapter" value="org.openhealthexchange.pixpdqadapter.openempi.PixManagerAdapter" /> 

        <!-- storeLogger - optional :
            The java adapter class that persists messages of this Pix Manager (optional).
            This class must implement org.openhealthexchange.openpixpdq.ihe.log.IMessageStoreLogger -->
         <Property name="storeLogger" value="org.openhealthexchange.messagestore.service.MessageStoreService" /> 

        <!-- Configuration file for each client domains -->
          <includefile name="PixPdqClientDomains.xml" />

Example for PixPdqClientDomains.xml

     <!--To configure each PIX/PDQ client, always use type="domain" -->
     <Identifier type="domain" name="HIMSS2005">
     <Identifier type="domain" name="XREF2005">
     <Identifier type="domain" name="NIST">
     <Identifier type="domain" name="Master">
     <Identifier type="domain" name="IHE Local">

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.

 <!-- Trust and Keystore -->

 <!-- Used by Connectathon 2009 -->






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.

Demographic Query

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

Pix Query

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


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

Message Log