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.

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 .

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,

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

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.

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.

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:

<Configuration>

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

</actor>

<!--The PD Supplier actor
configuration-->

<actor name="pdsup"
type="PdSupplier">

<description>Misys PD
Supplier</description>

<connection
source="misys-pd-supplier" />

</actor>

</Configuration>

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