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.
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
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.
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,
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
To configure PIX Manager and PD Supplier actors, follow the section below: OpenPIXPDQ Configuration
There are two ways to start/stop PIX and PDQ servers
1. For web based OpenPIXPDQ running in JBoss Server
2. For stand alone OpenPIXPDQ running with command line
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 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.
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||Each XML configuration file has a root Configuration 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||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:
|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
Example for PixPdqClientDomains.xml
|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 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.