Revision as of 14:43, 27 June 2007

Patient Demographics Consumer

Architecture & API Documentation

Version 0.2.0 �

API Documentation

The Patient Demographics Consumer client supports three formats for input. The client will accept:

• a raw HL7 message (String)
• an HL7v2 message object (org.eclipse.ohf.ihe.hl7v2.core Message)
• an ITI-21 Patient Demographics Query message supporting the construction of event:

QBP^Q22 Patient Demographics Query 

Examples for the three types of inputs are found in the org.eclipse.ohf.ihe.pdq.consumer plugin.

org.eclipse.ohf.ihe.pdq.consumer > src_tests > org.eclipse.ohf.ihe.pdq.consumer.tests > HL7PdqQuery.java org.eclipse.ohf.ihe.pdq.consumer > src_tests > org.eclipse.ohf.ihe.pdq.consumer.tests > MSGPdqQuery.java org.eclipse.ohf.ihe.pdq.consumer > src_tests > org.eclipse.ohf.ihe.pdq.consumer.tests > ClientPdqQuery.java

The files in src_tests use a TestConfiguration.java file for extracting the various file locations and MLLP connection parameters. Update this file with your settings before running the sample code.

A raw HL7 message string should be used as input when the originating application is fully capable of sending and receiving HL7 messages. In this case, the Patient Demographics Consumer client is simply providing auditing, communication with the PIX server, and optional message verification. Server responses are returned to the caller as raw HL7v2 message strings. (HL7PdqQuery)

A message object should be used as input when the originating application is directly using the OHF HL7v2 component which the Patient Demographics Consumer client sits on top of. In this case, the application has taken full responsibility for message creation and reading the response. The Patient Demographics Consumer client is simply providing conversion to raw HL7, auditing, communication with the PIX server, and optional message verification. Server responses are returned to the caller as HL7v2 message objects. (MSGPdqQuery)

A ITI-21 Patient Demographics Query message should be used as input when the originating application has neither support for raw HL7 nor message objects. The Patient Demographics Consumer client provides a friendly interface to set and read message fields as well as auditing, communication with the PIX server, and optional message verification. Server messages are returned to the caller as PdqConsumerResponse objects. (ClientPdqQuery)

• ITI-21 Patient Demographics Query Message Class

PdqConsumerQuery 

• ITI-21 Patient Demographics Query Server Response Class

PdqConsumerResponse 

Use Case -ITI-21 Patient Demographics Query

The Patient Demographics Consumer has one transaction. This use case demonstrates in step-by-step and with sample code the creation and use of the Patient Demographics Consumer client, including the three input options. It includes example client construction of the event specific message object as input but not the creation of raw HL7 or an HL7v2 Message object.

Flow of Execution

[[Image�:Flow of Execution.jpg]] Create a Patient Demographics Consumer object:

1. Construct ITI-21 Patient Demographics Query
2. Construct and associate MLLP (Minimum Lower Level Protocol) Destination
3. Disable auditing if desired.
4. Override the maximum level of validation error allowed before message submission is halted. The levels of error are constants in the OHF HL7v2 CPValidator.java file. The default is to allow up to the warning level.

Create a tailored HL7v2 message object:

1. Create Patient Demographics Consumer Message. Message field defaults are obtained first from the

associated Conformance Profile. Required fields not found there default to settings for the IBM Dallas Server.

1. Change default settings.
2. Add optional query values.
3. As not all fields have a corresponding method, use the generic method to set these additional values. Use method .addOptionalDemographicSearch(alias, data).
4. Add optional domain restrictions.
5. Add optional number of patients to return restriction.

The Patient Demographics Consumer supports querying data from PID and PD1 segments. Information about the fields, components, and sub-components available in these segments is available in the HL7 Version 2.5 Standard document in Chapter 3 Section 3.4 Message Segments.

Send the message:

1. Send message

Read the response message:

1. Read response message fields.

Sample Code

Create a Patient Demographics Consumer Query:

1. Construct ITI-21 Patient Demographics Query

1. There are two ways to construct the ITI-21 Patient Demographics Query client. At client creation, HL7 definitions are now automatically loaded for you from the HL7v2 toolkit. You can optionally provide an XML conformance profile for providing message defaults and additional message validation restrictions. The conformance profile can be added at a later time as well.
2. In this sample code, TConfig refers to the TestConfiguration.java file mentioned in the beginning of this section. See this file for example formatting of these constants.

//pdqQuery set-up 
PdqConsumer pdqQuery = new PdqConsumer(); 
//pdqQuery set-up with conformance profile 
InputStream cpStream = new FileInputStream(TConfig.CPROFILE_PATH); 
pdqQuery = new PdqConsumer(cpStream); 
cpStream.close(); 

1. Construct and associate MLLP (Minimum Lower Level Protocol) Destination

Un-Secure Connection:

MLLPDestination mllp = new MLLPDestination(TConfig.MLLP_URI); MLLPDestination.setUseATNA(true); pdqQuery.setMLLPDestination(mllp);

Secure Connection:

MLLPDestination mllps = new MLLPDestination(TConfig.MLLPS_URI); MLLPDestination.setUseATNA(true); pdqQuery.setMLLPDestination(mllps);

Properties props = new Properties(); props.setProperty(SecurityDomain.JAVAX_NET_SSL_KEYSTORE, "/x.jks”); props.setProperty(SecurityDomain.JAVAX_NET_SSL_KEYSTORE_PASSWORD, "pswd"); props.setProperty(SecurityDomain.JAVAX_NET_SSL_TRUSTSTORE, "/y.jks"); props.setProperty(SecurityDomain.JAVAX_NET_SSL_TRUSTSTORE_PASSWORD, "pswd"); SecurityDomain domain = new SecurityDomain("domainXY", props); ConfigurationManager.registerDefaultSecurityDomain(domain);

1. Disable auditing if desired.

//audit ON is the default AtnaAgentFactory.getAtnaAgent().setDoAudit(false); //disable for all actors

1. Override the maximum level of validation error allowed before message submission is halted. The levels

of error are constants in the OHF HL7v2 CPValidator.java file. The default is to allow up to the warning level. ITEM_TYPE_INFORMATION = #ITEM_TYPE_WARNING = #ITEM_TYPE_ERROR = #ITEM_TYPE_FATAL = #

pdqQuery.setMaxVerifyEvent(CPValidator.ITEM_TYPE_INFORMATION);

Page 10 of # � Create a tailored HL7v2 message object:

1. Create Patient Demographics Consumer Message.

PdqConsumerQuery msg = pdqQuery.createQuery(); msg.addQueryPatientNameFamilyName("TRENTON"); msg.addQueryPatientNameGivenName("DOUGLAS");

1. Change default settings.

msg.changeDefaultCharacterSet("UNICODE");

1. Add optional query values.

msg.addOptionalQuerySex("F");

1. As not all fields have a corresponding method, use the generic method to set these additional values.

Use method .addOptionalDemographicSearch(alias, data). msg.addOptionalQuerySex("F"); msg.addOptionalDemographicSearch("PID-8", "F");

For this example, the two statements are identical to show that the methods are equivalent.

1. Add optional domain restrictions.

msg.changeDefaultWhatDomainsReturned("HIMSS2005", "", "");

1. Add optional number of patients to return restriction. By default this value is set to 10 in an attempt to

ensure the audit message does not exceed the maximum size limit. msg.addOptionalQuantityLimit(5);

Send the message:

1. Send message

String response = pdqQuery.sendQuery(msg, isValidateOn, auditUser); Message response = ppdQuery.sendQuery(msg, isValidateOn, auditUser); PdqConsumerResponse response = pdqQuery.sendQuery(msg, isValidateOn, auditUser);

Read the response message:

1. Read response

//HL7v2 message object msg.getElement("MSA-1").getAsTableCode(); //message AckCode msg.getElement("QAK-2").getAsTableDescription(); //message QueryStatus

//PdqConsumerResponse object response.getResponseAckCode(isExpandCodeToString);

Page 11 of # � response.getQueryStatus(isExpandCodeToString);

response.getPatientCount();

for (int i=1; i <= response.getPatientCount(); i++) { String patID[] = response.getPatientIdentifier(i, 0); String patName[] = response.getPatientName(i); logger.debug(" Patient: " + patID[0]

+ "-" + response.getPatientNameFamilyName(i) + ", " + patName[1]); }

Page 12 of # � 4. Security 4.1 Node Authentication Transport Layer Security Protocol (TLS) is supported by creating a secure MLLP connection. Information required to instantiate a secure connection to one of the IBM Dallas Servers is available in the sample code configuration file. For more information and use terms on the IBM Dallas Servers, see

http://ibmod235.dal-ebis.ihost.com:9080/IBMIHII/serverInfoOHF.htm http://lswin10.dfw.ibm.com:9080/IBMIHII/serverInfoIHE_ConnectathonHIMSS2007.htm

4.2 Auditing Auditing to an Audit Record Repository is automatically enabled through the ATNA Agent. The Patient Demographics Consumer automatically generates the following audit messages:

EventID 110100 -Actor Start audit message (EventTypeCode 110120)

EventID 110112 -Query audit message

EventID 110107 -Import audit message

EventID 110100 -Actor Stop audit message (EventTypeCode 11012#Auditing is no longer enabled/disabled with the doAudit boolean variable within the Patient Demographics Consumer client. To disable all auditing, use the ATNA Agent.

AtnaAgentFactory.getAtnaAgent().setDoAudit(false);

Page 13 of # � 5. Configuration There are two types of configuration in this release.

5.1 Conformance Profile Create message default field values, such as message header fields, can now be read from the conformance profile field ConstantValue attribute. This is now supported at all levels: field, component, and subcomponent.

Field example:

<Field Name="MSH-1 Field Separator" Usage="R" Min="1" Max="1" Datatype="ST" Length="1" ItemNo="00001" ConstantValue="|"></Field>

Component example (in this case only the namespaceId is defaulted):

<Field Name="MSH-3 Sending Application" Usage="R" Min="0" Max="1" Datatype="HD" Length="227" Table="0361" ItemNo="00003">

<Component Name="MSH-3-1 sending application: namespace ID" Usage="R" Datatype="IS" ConstantValue="OHFConsumer1"></Component>

<Component Name="MSH-3-2 sending application: universal ID" Usage="O" Datatype="ST"></Component>

<Component Name="MSH-3-3 sending application: universal ID type" Usage="O" Datatype="ID"></Component>

</Field>

Sub-component example (specifies a limit of 5 records):

<Field Name="RCP-2 Quantity Limited Request" Usage="O" Min="0" Max="#Datatype="CQ" Length="10" Table="0126" ItemNo="00031">

<Component Name="RCP-2-1 quantity limited request: quantity" Usage="O" Datatype="NM" ConstantValue="5"></Component>

<Component Name="RCP-2-2 quantity limited request: units" Usage="O" Datatype="CE">

<SubComponent Name="RCP-2-2-1 quantity limited request: units: identifer" Usage="O" Datatype="ST" ConstantValue="RD"></SubComponent>

<SubComponent Name="RCP-2-2-2 quantity limited request: units: text" Usage="O" Datatype="ST"></SubComponent>

<SubComponent Name="RCP-2-2-3 quantity limited request: units: name of coding system" Usage="O" Datatype="ID"></SubComponent>

<SubComponent Name="RCP-2-2-4 quantity limited request: units: alternate identifier" Usage="O" Datatype="ST"></SubComponent>

<SubComponent Name="RCP-2-2-5 quantity limited request: units: alternate text" Usage="O" Datatype="ST"></SubComponent>

</Component>

</Field>

Page 14 of # � 5.2 Test Configuration The files in src_tests now use a TestConfiguration.java file for extracting the various file locations and MLLP connection parameters. Update this file with your settings before running the sample code. Here are the fields that are configured in this file:

//basics public static final String DATA_PATH public static final String LOG4J_PATH

//HL7PixQuery -run from file public static final String HL7FILE_PATH

//Conformance profile for second level HL7 verification and defaults public static final String CPROFILE_PATH

//MLLP Connectivity: //Default IBM Dallas IHII Server -more connection info available at: //http://lswin10.dfw.ibm.com:9080/IBMIHII/serverInfoIHE_ConnectathonHIMSS2 007.htm public static URI MLLP_URI public static URI MLLPS_URI

//TLS: Secure connection parameters public static final String MLLP_KEYSTORE_NAME public static final String MLLP_KEYSTORE_PASSWORD public static final String MLLP_TRUSTSTORE_NAME public static final String MLLP_TRUSTSTORE_PASSWORD

Page 15 of # � 6. Debugging Recommendations Log statements have been entered throughout the Patient Demographics Consumer plugin source code for assistance in monitoring the progress of the running client. To enable logging, there is a Log4j configuration file.

An example log4j configuration file is in the file /resources/conf/pdqconsumer_log4j.xml. The default configuration writes to a log file in the folder /resources/log.

Page 16 of # � 7. IHE Connectathon MESA Tests For current information, please refer to the wiki:

http://wiki.eclipse.org/index.php/IHE_Connectathon_2007#Detailed_MESA_Test_Info

7.1 Plugin Testing The OHF Patient Demographics Consumer plugin completed testing with the following junits and test scripts. org.eclipse.ohf.ihe.pdq.consumer > src_tests > org.eclipse.ohf.ihe.pdq.consumer.test.mesa >

MESA2007Tests.java Test11311 – PDQ Exact Name Search Test11312 – PDQ Name Search no Match Test11315 – PDQ Partial Name Search Test11320 – PDQ Complete ID Search Unspecified Domain Test11325 – PDQ Complete ID Search Single Domain Test11330 – PDQ Complete ID Search Multiple Domains Test11335 – PDQ Partial ID Search Single Domain Test11350 – PDQ Multi-Key Search 1 Test11365 – PDQ Continuation Test 1 MESA2007.txt Sample script for starting the mesa server and running all tests.

7.2 Bridge Testing The OHF Bridge completed testing with the following junits and test scripts. org.eclipse.ohf.bridge.ws > src_tests > org.eclipse.ohf.bridge.ws.tests.mesa >

TestMESA11311.java PDQ Exact Name Search TestMESA11312.java PDQ Name Search no Match TestMESA11315.java PDQ Partial Name Search TestMESA11320.java PDQ Complete ID Search Unspecified Domain TestMESA11325.java PDQ Complete ID Search Single Domain TestMESA11335.java PDQ Partial ID Search Single Domain TestMESA11350.java PDQ Multi-Key Search 1 TestMESA11365.java PDQ Continuation Test 1

org.eclipse.ohf.ihe.pdq.consumer > src_tests > org.eclipse.ohf.ihe.pdq.consumer.test.mesa > MESA2007.txt Sample script for starting the mesa server and running all tests.

Page 17 of # � 8. IHE Connectathon Tests 8.1 Plugin Testing The OHF Patient Demographics Consumer plugin completed testing with the following junits. org.eclipse.ohf.ihe.pdq.consumer > src_tests > org.eclipse.ohf.ihe.pdq.consumer.test.connectathon >

ConnectathonPDQLoadTest.java 2.1 PDQ_Load The initial patient load for PDQ requires use of the Patient Identity Source plugin. This file is a placeholder for the actual junit which is located within the Patient Identity Source connectathon junits org. eclipse.ohf.ihe.pix.source > src_tests > org.eclipse.ohf.ihe.pix.source.test.connectathon ConnectathonPDQTest.java 2.2 PDQ_Exact_Name 2.3 PDQ_Multiple_Query 2.5 PDQ_Continuation_Test

Page 18 of # �