ihe pre-connectathon pix and pdq test tool tutorial and guide (2011 cycle) robert snelick national...

IHE Pre-Connectathon PIX and PDQ Test Tool Tutorial and Guide (2011 Cycle)Robert Snelick

National Institute of Standards and Technology

Version 1.4 November 3rd 2010

Contact: [email protected]

2

Table of Contents

• Overview

• Test Case Walkthrough

• Registration and Login

• Tool Demonstration

• Configuration, Preparing to Run Tests, and Troubleshooting

• Validating the v3 SOAP Message Wrapper

• Validation Overview (HL7 v2)

• Validation Overview (HL7 v3)

• Summary

Overview of the NIST PIX/PDQ Pre-Connectathon Test Tool

4

NIST PIX/PDQ Test Tool: Process Overview• The Test Tool cam be used to fulfill 2011 V2 and V3 PIX/PDQ Pre-Connectathon testing requirements• Supports Pre-Connectathon testing for:

• Covers the PIX/PDQ Integration Profile– Version 7.0 August 10, 2010– http://www.ihe.net/Technical_Framework/index.cfm#IT– V2: ITI-8, ITI-9, ITI-21, ITI-22– V3: ITI-44, ITI-45, ITI-47

• Results are stored in the NIST PIX/PDQ tool• The IHE project manager will review the results

Profile/HL7 Version Actors

IHE PIX HL7 v2 Source, Manager, Consumer

IHE PDQ HL7 v2 Supplier, Consumer

IHE PIX HL7 v3 Source, Manager, Consumer

IHE PDQ HL7 v3 Supplier, Consumer

5

NIST PIX/PDQ Test Tool: Access

• Web-based application (no downloads or installations needed)– Site: http://pixpdqtests.nist.gov:8080/

• Tool may be used in Anonymous Mode or Registered Mode– Anonymous Mode (“Guest” Users)

• Does not require user registration and may be used to conduct ad-hoc system testing

– Registered Mode• Required for completing the Pre-Connectathon and participating in the

Connectathon• Required to save pre-connectathon test results• Test reports are made available to the IHE project manager

• User’s Guide is available on the site under “Documentation”

6

NIST PIX/PDQ Test Tool: Support

• IHE PIX/PDQ Google Group– http://groups.google.com/group/ihe_pix_pdq_testing– Preferred method of communication for discussing common issues– Go to the site and request membership– Administrative (only) issues can be sent directly to [email protected]

• Issues Tracker– http://code.google.com/p/pixpdqtool/issues/list– Google utility to report issues, bugs, and enhancement suggestions

7

Testing Environments

• Instance Testing– Conformance (e.g., against HL7 2.x or CDA)

• Test object conforms to specification on which it is based• IHE Model: ~Virtual and Pre-Connectathon • NIST IHE PCD v2 Message Validation Test Tool

• Isolated System Testing– Includes Instance Testing Activities– Protocol Conformance – Functional Behavior Conformance

• Features and operational behavior correspond to specifications• IHE Model: ~Virtual and Pre-Connectathon• NIST IHE PIX/PDQ v2/v3 Test Tool

• Peer-to-Peer System Testing– Includes Isolated System Testing Activities– Interoperability Testing

• Testing complete application environment • May include interacting with Database, using Network Communications, or interacting with

other hardware, applications, or systems if appropriate• IHE Model: ~Connectathon

8

NIST PIX/PDQ Test Tool: Operational Process

END-USER(VENDOR)

SYSTEM UNDER TEST (SUT)

NIST PIX/PDQ HL7 v2/v3 TEST TOOL

SPECIFICATIONS(test material that defines test assertions)

INTERACTION/REPORTS

MESSAGES (TEST OBJECTS)

STIMULUS OR RESPONSE (MESSAGES)

MANUAL OR AUTOMATED SUT

Web Application Interface

(via the communication protocol)

9

NIST PIX/PDQ Test Tool: PIX Test Coverage

Actor Test Cases

Source ITI-8-Source-A01ITI-8-Source-A04ITI-8-Source-A05ITI-8-Source-A08ITI-8-Source-A40

Consumer ITI-9-Consumer

Manager ITI-8-Feed-Check-PID-3.4-A01

ITI-8-Feed-Check-PID-3.4-A04

ITI-8-Feed-Check-PID-3.4-A05

ITI-8-Feed-Unknown-Domain-A01



ITI-8-Feed-Valid-Domain-A01



ITI-8-Merge-Patient

ITI-8-Update-Check-PID-3.4

ITI-8-Update-Unknown-Domain

ITI-8-Update-Valid-Domain-Patient-Exist

ITI-8-Update-and-Link

ITI-9-Query-Case1-Data-Found

ITI-9-Query-Case2-Data-Not-Found

ITI-9-Query-Case3

ITI-9-Query-Case4

ITI-9-Query-Case5 ITI-9-Query-Case6

Actor Test Cases

Source ITI-44-Source-FeedITI-44-Source-UpdateITI-44-Source-Merge

Consumer ITI-45-Consumer

Manager ITI-44-Feed-Unknown-DomainITI-44-Feed-Valid-DomainITI-44-Merge-PatientITI-44-Update-Unknown-DomainITI-44-Update-Valid-Domain-Patient-ExistITI-44-Update-and-LinkITI-45-Query-Case1-Data-FoundITI-45-Query-Case2-Data-Not-FoundITI-45-Query-Case3ITI-45-Query-Case4ITI-45-Query-Case5ITI-45-Query-Case6

PIX HL7 v2 PIX HL7 v3

10

NIST PIX/PDQ Test Tool: PDQ Test Coverage

Actor Test Cases

Consumer ITI-21-Consumer-Query-Continuation-Protocol ITI-21-Consumer-Query-Patient-Address ITI-21-Consumer-Query-Patient-Name-Administrative-Sex ITI-21-Consumer-Query-Patient-Name-DOB ITI-21-Consumer-Query-Patient-PatientId

Supplier ITI-21-Query-Case1-Data-Found-Exact-Match-Single-Domain ITI-21-Query-Case1-Data-Found-Single-Domain ITI-21-Query-Case2-Data-Found-Exact-Match-Single-Domain ITI-21-Query-Case2-Data-Found-Single-Domain ITI-21-Query-Case3 ITI-21-Query-Continuation-Protocol

PDQ HL7 v2 PDQ HL7 v3

Actor Test Cases

Consumer ITI-47-Consumer-Query-Continuation-ProtocolITI-47-Consumer-Query-Patient-AddressITI-47-Consumer-Query-Patient-Name-Administrative-SexITI-47-Consumer-Query-Patient-Name-DOBITI-47-Consumer-Query-Patient-PatientId

Supplier ITI-47-Query-Case1-Data-Found-Exact-Match-Single-DomainITI-47-Query-Case1-Data-Found-Single-DomainITI-47-Query-Case2-Data-Found-Exact-Match-Single-DomainITI-47-Query-Case2-Data-Found-Single-DomainITI-47-Query-Case3ITI-47-Query-Continuation-Protocol

Test Case Walkthrough

PIX Manager Test Case: ITI-9-Query-Case1-Data-Found

12

Test Case ITI-9-Query-Case1-Data-Found – HL7 Version 2

IHE ITI Technical FrameworkVolume 2a (ITI TF-2a) 3.9 PIX Query

Case 1: The Patient Identifier Cross-reference Manager Actor recognizes the specified Patient Identification Domain and Patient ID sent by the Patient Identifier Cross-reference Consumer in QPD-3, and corresponding identifiers exist for the specified patient in at least one of the domains requested in QPD-4 (one identifier per domain). (See Case 6 below for the required behavior if there are multiple identifiers recognized within a given Identifier Domain by the Patient Identifier Cross-reference Manager Actor.)

AA (application accept) is returned in MSA-1.

OK (data found, no errors) is returned in QAK-2.

A single PID segment is returned in which one repetition of PID-3 Patient Identifier List is populated for each of the domains, if any, that the Patient Identifier Cross-reference Manager Actor did recognize in which a single identifier exists for the requested patient, not including the queried-for patient identifier that is returned in QPD-3.

13

Test Case ITI-9-Query-Case1-Data-Found: Description

Description Test case ITI-9-Query-Case1-Data-Found covers the PIX Query Case One patient (ALPHA) is registered in three different domains. Three registration

messages are sent to a Cross Reference Manager. A PIX Query is sent to resolve a reference to ALPHA in a specific domain (NIST2010-

2). Patient ALPHA should be found. Another PIX Query is sent to resolve a reference to ALPHA in two different domains

(NIST2010-2 and NIST2010-3). Patient ALPHA should be found in those two domains. Another PIX Query is sent to resolve a reference to ALPHA in all domains. Patient

ALPHA should be found in two domains (NIST2010-2 and NIST2010-3).

References IHE ITI TF-2a: Transactions Part A (Revision 6.0, August 10, 2009) 3.9.4.2.2.6 Patient Identifier Cross-reference Manager Actor Query Response Behavior

Actors Patient Identity Source (Test Agent) Patient Identity Consumer (Test Agent) Patient Identity Cross-Reference Manager (Vendor System Under Test)

14

Test Case ITI-9-Query-Case1-Data-Found: Test Steps

1 The NIST PIX Source sends a registration message (ADTÂ04) to register patient ALAN ALPHA in domain NIST2010&2.16.840.1.113883.3.72.5.9.1&ISO. Patient ID is PIX10501. The PIX Manager shall register the patient and send a correct ACK message back.

• PIX Source• Reference Message

• PIX Manager• Reference Example • Message

2 The NIST PIX Source sends a registration message (ADTÂ04) to register patient ALAN ALPHA in domain NIST2010-2&2.16.840.1.113883.3.72.5.9.2&ISO. Patient ID is XYZ10501. The PIX Manager shall register the patient and send a correct ACK message back.



3 The NIST PIX Source sends a registration message (ADTÂ04) to register patient ALAN ALPHA in domain NIST2010-3&2.16.840.1.113883.3.72.5.9.3&ISO. Patient ID is ABC10501. The PIX Manager shall register the patient and send a correct ACK message back.



4 The NIST PIX Consumer sends a query message (QBP^Q23) to ask for ALAN ALPHA''s ID in domain NIST2010-2&2.16.840.1.113883.3.72.5.9.1&ISO using his id PIX10501 in domain NIST2010&2.16.840.1.113883.3.72.5.9.1&ISO. The PIX Manager shall answer correctly to the query with ALAN ALPHA''s ID XYZ10501 in domain NIST2010-2&2.16.840.1.113883.3.72.5.9.1&ISO.

• PIX Consumer• Reference Message


5 The NIST PIX Consumer sends a query message (QBP^Q23) to ask for ALAN ALPHA''s ID in domain NIST2010-2&2.16.840.1.113883.3.72.5.9.1&ISO and NIST2010-3&2.16.840.1.113883.3.72.5.9.1&ISO using his id PIX10501 in domain NIST2010&2.16.840.1.113883.3.72.5.9.1&ISO. The PIX Manager shall answer correctly to the query with ALAN ALPHA''s ID XYZ10501 and ABC10501 in domain NIST2010-2&2.16.840.1.113883.3.72.5.9.1&ISO and NIST2010-3&2.16.840.1.113883.3.72.5.9.1&ISO.



6 The NIST PIX Consumer sends a query message (QBP^Q23) to ask for ALAN ALPHA''s ID in all domains using his id PIX10501 in domain NIST2010&2.16.840.1.113883.3.72.5.9.1&ISO. Your PIX Manager shall answer correctly to the query with ALAN ALPHA''s ID XYZ10501 and ABC10501 in domain NIST2010-2&2.16.840.1.113883.3.72.5.9.1&ISO and NIST2010-3&2.16.840.1.113883.3.72.5.9.1&ISO.



STEPS DESCRIPTION SOURCE DESTINATION

15

Test Case ITI-9-Query-Case1-Data-Found

NISTPIX

SourceTest Agent

NISTPIX

SourceTest Agent

ADTA04 – Register patient“ALAN ALPHA” (ID = PIX10501) in domain “NIST2010”

ACKA04 – Send acknowledgement

1

1a

PIX/PDQ Test Tool

End User(Vendor)

ADTA04 – Register patient “ALAN ALPHA” (ID = ABC10501) in domain “NIST2010-3”


2

2a

ADTA04 – Register patient“ALAN ALPHA” (ID = XYZ10501) in domain “NIST2010-2”


3

3a

VendorPIX

ManagerApplication

VendorPIX

ManagerApplication

System Under Test

NISTPIX

ConsumerTest Agent

NISTPIX

ConsumerTest Agent

QBPQ23 – Send query message for patient “ALAN ALPHA” in domain “NIST2010-2” using the patient ID in domain “NIST2010”

4

4aRSPK23– Send response that the identifier “XYZ10501” for patient “ALPHA” was found in domain “NIST2010-2”

QBPQ23 – Send query message for patient “ALAN ALPHA” in domain “NIST2010-2” and “NIST2010-3” using the patient ID in domain “NIST2010”

5

RSPK23 – Send response that the identifiers “XYZ10501” and “ABC10501” for patient “ALPHA” were found in domains “NIST2010-2” and “NIST2010-3”

5a

We

b A

pp

lic

ati

on

In

terf

ac

e

6QBPQ23 – Send query message for patient “ALAN ALPHA” in all domains using the patient ID in domain “NIST2010”


6a

Registration and Login

17

Steps for Completing Test Cases

1. Register/log-in

2. Select HL7 Version (v2 or v3) and Actor

3. Select Test Case• Client Type (PIX Source and PIX Consumer, PDQ Consumer)

• Server Type (PIX Manager, PDQ Supplier)

4. Set Configuration Information

5. Run Test

6. View/Save/Submit Reports

18

Registration/Log-in

• To register, click-on Register in the upper-right corner of the tool’s home page– Name– Organization Name– Email Address– Login Information– Application Name (MSH 3.1)– Facility Name (MSH 4.1)– IP Address(es) and Port Number(s)

• NIST Administrator will confirm log-in credentials• Log-in is required to save test results, submit results to

the IHE project manager, and gain credit for test completion NIST

PIX/PDQTest Tool

IHE Gazelle*Push/Pull to Gazelle

IHE Project Manager can view

database of results * not yet implemented

19

Registration/Log-in

Fill out the User Information section completely. Users unable to be verified by the NIST administrators will have accounts deleted.

Document v2 and/or v3 actor information as appropriate for your case studies.

Fields exist for multiple IP Addresses and Port Numbers if needed, based on your system configuration.

20

Viewing Account InformationTo view information about the currently logged in user, go to the User Account page.

The Actor Information section will display the server configuration fields documented during registration.

The Responder Information section will display as a reference the unique client configuration information, which the test tool dynamically generates.

Tool Demonstration

PIX Manager Test Case: ITI-9-Query-Case1-Data-Found

22

Overview and Home Page

Go to the PIX/PDQ Test Tool User Guide for step-by-step instructions

After registration, users can log-in using the ‘Log-in’ tab to submit test results to the IHE Project Manager

Click to register

Discuss PIX/PDQ Profile and Tests on the Google Discussion Group

Click to run test cases

23

Select Test Case – Client (PIX Consumer, PIX Source, PDQ Consumer)

Select an ‘HL7 Version’ and ‘Actor’ to view a list of available test cases

Select a test case by selecting the corresponding radio button

Select the ‘Display Configuration Information’ button to view the test configuration details. The ‘Start Test’ button will become enabled once the configuration information dialog has been closed

24

Configure – v2 User Client (for Registered Users)

View the ‘Application Name’, ‘Facility Name’, ‘IP Address’, ‘Port Number(s)’ needed to configure your client application to send messages. Please note that each NIST PIX Manager instance is unique for each user.

The name of the NIST PIX server for a registered user is created based on your user account (login) name. The NIST server name (receiving application name ) is “NIST_PIX_PDQ_Manager_” + “Login Name”. Therefore, if your login name is Vendor then you send messages to NIST_PIX_PDQ_Manager_VENDOR. If your system is not configured accordingly you will receive an acknowledge error message over the network and nothing will appear in the console.

Important!

25

Configure – v2 User Client (for Guest Users)

View the ‘Application Name’, ‘Facility Name’, ‘IP Address’, ‘Port Number(s)’ needed to configure your client application to send messages. Please note that each NIST PIX Manager instance is unique for that run, if not logged in as a registered user.

The name of the NIST PIX server is temporary and will changed for every test that is run. You must review the configuration information each time and change the receiving application name accordingly. Using an old name will result in failure; you will receive an acknowledge error message over the network and nothing will appear in the console.

Important!

26

Configure – v3 User Client

Registered User Guest User

As with v2 client configuration, the application name will be the same for all tests performed when logged in as this user. Guest users, however, will receive a new application name each time a test is run.

Unlike v2, which generates an application name based on the registered user’s login, v3 client configuration will generate an application name with a unique ID appended to the end (in this example, 56).

27

Select Test Case – Server (PIX Manager, PDQ Supplier)

Select an ‘HL7 Version’ and ‘Actor’ to view a list of available test cases

Select a test case by selecting the corresponding radio button to view a description, references, and list of transactions

Select the ‘Configure’ button to enter the test configuration details – the ‘Start Test’ button will become enabled once the configuration information has been entered

28

Configure – v2 Test Cases - User Server (Single IP/Port)

Single IP/PortEnter the ‘Application Name’ and ‘Facility Name’ for the System Under Test – these fields are associated with MSH.3.1 and MSH.4.1 in the HL7 v2 message and match exactly.

Select ‘Single IP/Port’ or ‘Multi IP/Port’ and enter the information accordingly – ‘Multi IP/Port’ may be used to handle ADT and PDQ messages separately.

Example PIX Manager

V2 Application Name: PAT_IDENTITY_X_REF_MGR_MISYSV2 Facility Name: MISYSIP Address: 198.160.211.53Port: 3600 (PDQ Port: 3601)

Use this PIX Manager from Open Health Tools (OHT) to try the tool if you don’t have an application to test

Select the “With user interaction” execution type to stop the test after each transaction and manually tell the tool to begin the next step. Choosing “Without user interaction” will run all of the transactions within the test case without pausing.

29

Configure – v2 Test Cases - User Server (Multi IP/Port)

Multi IP/Port

Select ‘Multi IP/Port’ and enter the information accordingly

30

Configure – v3 Test Cases - User Server

Multi IP/PortSingle IP/Port

Note: the configuration information in this example is fictitious.

31

Run TestTest cases are executed one transaction at a time and real-time results can be tracked in the ‘Console Log’

Individual validation reports can be viewed by selecting the ‘Magnifying Glass’ icon at the end of each transaction

Select ‘Next Step’ at the conclusion of each transaction to initiate the next one

Results, Messages Sent/Received, and Detailed Results (XML/HTML) can be viewed in between each transaction

32

View/Save/Submit Report

Select the ‘Submit Results and Finish’ button to submit test results to the IHE Project Manager for review

A summary-level report will also be available – reports may be printed or saved to the user’s local file system

33

Validation and Summary Reports

Individual validation reports are available at the end of each transaction and again at the conclusion of a test case

A summary-level report that compiles individual validations reports will also be available – reports may be printed or saved to the user’s local file system

It is always a good idea to download your results to your local system for backup!

34

View Past Results

Registered users can view their test history on the ‘Reports’ tab – this tab provides access to saved transaction and summary-level reports

Users can download and save the ‘Result Summary’ in both HTML and PDF formats

Users may select the ‘Actor Tested’ and ‘HL7 Version’ to view their list of previously run test cases. Users may then select the corresponding radio button to view the results for a particular test case

Configuration, Preparing to Run Tests, and Troubleshooting

36

Configuration Information

• v2 Applications sending ER7– IP Address: 129.6.24.143

– Port Number: 9080

• v2 Applications sending XML– IP Address: 129.6.24.143


• v3 Applications– IP Address: 129.6.24.143


• v3 SOAP end point– http:// 129.6.24.143:9090

37

Example v2 PIX Source Vendor Configuration Information• Configuration Information for sending v2 messages

For Registered User:

Application Name: NIST_PIX_PDQ_Manager_BobVendor*

For Guest User:

Application Name: NIST_PIX_PDQ_Manager_78 (varies each time)

Same for Registered and Guest User:

Facility Name: NIST

IP Address: 129.6.24.143

Port Number: 9080 (ER7 Messages)

Port Number: 9070 (XML Messages)

* The application name is derived from the log-in name. Registered users can view this under the “User Account” tab. It will remain the same for every client test.

38

Example v3 PIX Source Vendor Configuration Information• Configuration Information for sending v3 messages

For Registered User:

Application Name: 2.16.840.1.113883.3.72.6.5_13*

For Guest User:

Application Name: 2.16.840.1.113883.3.72.6.5.92 (varies for each test case run)

Same for Registered and Guest User:

Facility Name: 2.16.840.1.113883.3.72.6.1 (Optional)

IP Address: 129.6.24.143

Port Number: 9090 (v3 Messages)

* The application name is derived from the log-in name. Registered users are assigned a number and this can be viewed this under the “User Account” tab. It will remain the same for every client test.

39

PIX/PDQ Server Application Name Allocation (for Registered Users)• For each user the name of the PIX Manager or PDQ Supplier

is uniquely assigned– Is based on the user login name– This ensures that each vendor test is isolated

• In order to interact with the NIST PIX Manager or the NIST PDQ Supplier Test Agent you will need to use the information provided in “Configuration Information” dialog– For example (V2):

• Application Name: NIST_PIX_PDQ_Manager_BobVendor• Facility Name: NIST

– For example (V3): • Application Name: 2.16.840.1.113883.3.72.6.5.17• Facility Name: 2.16.840.1.113883.3.72.6.1 (Optional)

• If you send to an application name that doesn’t exists you will get the following response from our system:– Nothing from the user console (it’s still listening for messages)– An acknowledge message with error is sent back to you over the network

40

Dynamic PIX/PDQ Server Application Name Allocation (for Guest Users)• For each test case instance the name of the PIX Manager or

PDQ Supplier is created dynamically– The life of this test agent exists only for the duration of the test– This ensures that each vendor test is isolated

• In order to interact with the NIST PIX Manager or the NIST PDQ Supplier Test Agent you will need to use the information provided in “Configuration Information” dialog– For example (V2):

• Application Name: NIST_PIX_PDQ_Manager_150• Facility Name: NIST

– For example (V3): • Application Name: 2.16.840.1.113883.3.72.6.5.98• Facility Name: 2.16.840.1.113883.3.72.6.1 (Optional)

• If you send to an application name that no longer exists you will get the following response from our system:– Nothing from the user console (it’s still listening for messages)– An acknowledge message with error is sent back to you over the network

41

Test Case Preparation

• Before testing a PIX/PDQ server, users need to:

1. Clean your database of patients used in the test cases to avoid mixing tests with residual data. This is particularly important for test cases such as Merge since the merge patient will already exist if the test had been run previously.

2. Configure the PIX/PDQ Server to handle the following patient identifier assigning authority domains:

NIST2010&2.16.840.1.113883.3.72.5.9.1&ISO

NIST2010-2&2.16.840.1.113883.3.72.5.9.2&ISO

NIST2010-3&2.16.840.1.113883.3.72.5.9.3&ISO

IHE2010&1.3.6.1.4.1.21367.2010.1.1&ISO

42

Troubleshooting

• Site is unavailable– Typically means we are redeploying the application to make updates and

the tool – We will announce redeployments– The downtime will be in the neighborhood of 10-15 minutes– Please refresh the browser following the redeployment– Server is controlled by central computing facility and may be unavailable

• Site appears to be down– Restart in a new browser window

• Site has timed out– This will happen if the tool is open in an inactive browser window– To correct, refresh the browser

43

Troubleshooting (continued)

• No response from console log– You may have sent to a destination that we could not process (i.e., an

incorrect receiving name)– We will send back an acknowledge/error over the network– On the console log nothing will happen– You need to check the destination on your end– If you determined that this was the problem you can resend a properly

addressed message; we’ll still be listening up to the session timeout• Completed report is missing

– When we discover an error in the test case (i.e., the test case is wrong) we fix it

– Tests that passed using an incorrect test are no longer valid– This should not occur often

Validating the v3 SOAP Message Wrapper

Prior to using the PIX/PDQ Tool

45

Introduction

• The NIST PIX/PDQ test tool is primarily concerned with the PIX/PDQ payload.

• However, since the tool is interactive, messages are exchanged using transport layer protocols - namely SOAP for HL7 V3.

• Testing this layer is not in the scope NIST PIX/PDQ test tool, but a malformed message will prevent delivery to the tool.

• Therefore, users need to ensure that messages are well-formed and adhere to transport layer requirements

• Users need to test V3 messages at this layer before beginning testing with the interactive PIX/PDQ test tool or if you don’t get a response from the PIX/PDQ test system

• The following slides provide some helpful hints and a link to additional tooling for debugging your V3 SOAP messages

• Please note that these tools are not part of the PIX/PDQ tool, and the PIX/PDQ team does not support the tools

46

Debugging PIX/PDQ v3 Messages

• Malformed SOAP envelopes may cause the PIX/PDQ tool to not respond

• This is due mostly to malformed XML

• Use the NIST XDS Toolkit to validate SOAP messages– http://ihexds.nist.gov/xdstools2/

– The tool provides testing for the various layers of the v3 message• HTTP Header

• SOAP Wrapper

– The tool does not provide validation of the SOAP body (or payload).• In this case the PIX/PDQ payload

• The PIX/PDQ tool validates the payload in the context of the test case

47

Using the XDS Toolkit

• The toolkit requires sending the entire HTTP message in plain text format

• If this is not easily obtained from your server, consider using TCPMon to act as a proxy: – https://tcpmon.dev.java.net/

48

XDS Tool Kit

Click here to reach the Message Validator

http://ihexds.nist.gov/xdstools2/

49

XDS Tool Kit

Step 1: Leave this option as “Guess based on content”

Step 2: Use this button to locate the text file on your local system which contains the server’s HTTP SOAP message.

3) Once the file has been selected click here to have the tool validate the SOAP message.

50

XDS Validation Results

This section reports on the correctness of the HTTP header.

This section reports XML violations

51

XDS Validation Results (continued)

This section will report SOAP violations

Note: As the XDS Toolkit was not built to validate the PIX/PDQ message payload this error message is expected.

If this is the only error you get, then you are ready to move onto the PIX/PDQ tool!

52

Example Malformed Messages

• The following example messages will not be processable by the PIX/PDQ tool

• The XDS Tool Kit can be used to help debug implementation challenges

53

Example v3 Message with Malformed HTTP Header

POST / HTTP/1.1

Host:

Content-Length: 3556

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">

<env:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">

<wsa:To>http://www.fakelistener.com/myapp</wsa:To>

<wsa:From>http://pixpdq2010tests.nist.gov:8080/</wsa:From>

<wsa:ReplyTo>

<wsa:Address>http://pixpdq2010tests.nist.gov:8080/</wsa:Address>

</wsa:ReplyTo>

</env:Header>

<env:Body>

<PRPA_IN201301UV02 xmlns="urn:hl7-org:v3" ITSVersion="XML_1.0">

<id root="0cc360d6-445e-11dc-a6be-3603d6866807"/>

<creationTime value="20070803130712"/>

<interactionId extension="PRPA_IN201301UV02" root="2.16.840.1.113883.1.6"/>

<processingCode code="P"/>

.

.

.

</PRPA_IN201301UV02>

</env:Body>

</env:Envelope>

Missing Content-Type header

54

Example Message Validation Results

Malformed HTTP Headers cause the tool to be unable to determine content type and thus messages cannot be parsed

55

Example V3 Message with Malformed XML Content

POST / HTTP/1.1

Content-Type: application/soap+xml

Host:






<wsa:ReplyTo>


</wsa:ReplyTo>

<env:Body>






.

.


</env:Body>

</env:Envelope>

Missing closing wsa:Header tag

56


Malformed XML causes the parser to halt

57

Example v3 Message with Malformed SOAP StructurePOST / HTTP/1.1

Content-Type: application/soap+xml

Host:






<wsa:ReplyTo>


</wsa:ReplyTo>

</env:Header>

<env:body>






.

.


</env:body>

</env:Envelope>

Misspelled env:Body element

58


59

Misspelled env:Body element makes it impossible to extract message payloads

Example Message Validation Results (continued)

60

Example Message with Malformed SOAP Header• The following shows an example of attempting to validate

a message with a malformed SOAP Header.• Messages like this category will be accepted by our the

PIX/PDQ tool, but errors reported by the XDS Toolkit should be fixed to bring implementations in line with the specification.

61

Example v3 Message with Malformed SOAP Header

POST / HTTP/1.1Content-Type: application/soap+xmlHost:Content-Length: 3556

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"><env:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">

<wsa:To>http://www.fakelistener.com/myapp</wsa:To><wsa:From>http://pixpdq2010tests.nist.gov:8080/</wsa:From><wsa:ReplyTo>


</wsa:ReplyTo></env:Header><env:Body>

<PRPA_IN201301UV02 xmlns="urn:hl7-org:v3" ITSVersion="XML_1.0"> <id root="0cc360d6-445e-11dc-a6be-3603d6866807"/> <creationTime value="20070803130712"/> <interactionId extension="PRPA_IN201301UV02" root="2.16.840.1.113883.1.6"/> <processingCode code="P"/>

.

.

.</PRPA_IN201301UV02>

</env:Body></env:Envelope>

wsa:From elements are optional but must have a nested wsa:Address element that contains the sender uri

wsa:Action is absent

At least one element must contain the attribute env:mustUnderstand=“1”

62


63

Example Message Validation Results (continued)

Caused by missing wsa:Action element

Caused by missing env:mustUnderstand attribute

Caused by missing wsa:Address element

64

Examining Your Validation Results

• (1) Errors reported in the sections “HTTP Parser,” and “Validate Simple SOAP” must be fixed before using the PIX/PDQ tool– If not, the PIX/PDQ tool will not respond

• (2) Errors in the “SOAP Wrapper”– (a) Errors pertaining to the Envelope and Body of the message

must be fixed before using the PIX/PDQ tool (PIX/PDQ won’t respond)

– (b) Errors pertaining to Header, WS-Addressing and WS-Action should not affect processing of the message by the PIX/PDQ tool but they should be fixed

– (c) All well-formed messages will show the following error: “Cannot validate SOAP Body - WS-Addressing Action header **** is not understood.” This error is to be expected; the XDS Tool Kit is not designed to evaluate the PIX/PDQ payload

65

Summary

• Before using the PIX/PDQ make sure you have valid SOAP messages

• Use the XDS Tool Kit to find out

• Examine your test report, if you get errors:

• 1 or 2a You need to fix

• 2b You should fix

• 2c You are OK, proceed to the PIX/PDQ Tool

See previous slide for explanation of 1, 2a, 2b, 2c

Validation

HL7 v2 Messages and IHE Actor Functional Behavior

67

HL7 v2 Transaction Validation Process• HL7 v2 Syntax Validation

– Ensure the message structure is valid with respect to the HL7 v2 message definition and the HL7 v2 conformance profile

– Ensure that the conformance requirements such as usage, cardinality, data type usage, etc. are valid with respect to the standard and the HL7 v2 conformance profile that constrains the message, in accordance with the IHE technical framework for a given transaction

• Value Set Semantic Validation– Ensure that elements that refer to a table are valid with respect to the value set it

references. The value set is given by the HL7 v2 standard or as constrained by the IHE technical framework. An example includes confirming that the administrative sex element (PID.8) of the PID segment contains a value that is given in the HL7 v2 Administrative Sex table (HL70001).

– Identify conformance violations of constraints implied by the IHE Integration Profile. These constraints are captured in a validation context file. An example of such a test includes an element that is fixed in the IHE integration profile (e.g., RCP.1 = I).

• HL7 v2 MLLP Validation– Ensure the message is valid with respect to the HL7 v2 MLLP specification for

wrapping and unwrapping HL7 v2 messages. This is an implied test.• Test Case Specific Validation

– Verify element content against a validation context file that captures test values as defined in the Pre-Connectathon test cases.

68

Test Case Specific Validation Checks

ValidationCriteria

1 • Assert an “AA” acknowledge message for registration of patient “ALPHA” in domain “NIST2010”; Patient ID is “PIX10501”

2 • Assert an “AA” acknowledgement message for registration of patient “ALPHA” in domain “NIST2010-2”; Patient ID is “XYZ10501”

3 • Assert an “AA” acknowledgement message for the registration of patient “SIMPSON” in domain “NIST2010-3”; Patient ID is “ABC10501”

4 • PIX Query Case 1: Assert response message with MSA.1 = “AA”• PIX Query Case 1: Assert response message with PID.3.1 = “XYZ10501”• PIX Query Case 1: Assert response message with QAK.2 = “OK”• more…

5 • PIX Query Case 1: Assert response message with MSA.1 = "AA“• PIX Query Case 1: Assert response message with PID.3[1].1 = "XYZ10501" and PID.3[2].2 = "ABC10501“• PIX Query Case 1: Assert response message with QAK.2 = "OK“• more...

6 •PIX Query Case 1: Assert response message with MSA.1 = "AA“• PIX Query Case 1: Assert response message with PID.3[1].1 = "XYZ10501" and PID.3[2].2 = "ABC10501“• PIX Query Case 1: Assert response message with QAK.2 = "OK“• more...

STEPS ASSERTIONS

69

Validation Operational Process: Origin of Test Assertions

HL7 v2StandardMessageDefinition

IHE TFMessage

TransactionConstraints

HL7 v2Standard

Value Sets

IHE TFMessage

TransactionValue Set

Constraints

Test CaseSpecific

TestAssertions**

IHE TFMessage

TransactionTest

Assertions

Assertions

ValidationContext

File(XML)

TableLibrary(XML)

ConformanceProfile(XML)

ValidationEngine

** Dynamic Data (Future Work)

70

HL7 V2 Conformance Profile Example (ADT A04 Message)

- <HL7v2xStaticDef MsgType="ADT" EventType="A04" MsgStructID="ADT_A01" EventDesc="ADT/ACK - Register a patient" Role="Sender"> <MetaData Name="Patient Identity Feed" OrgName="IHE" Version="2.3" Status="DRAFT" Topics="confsig-IHE-2.3.1-static-ADT-A04-null-ADT_A01-2.3-DRAFT-Sender" /> - <Segment Name="MSH" LongName="message header segment" Usage="R" Min="1" Max="1">- <Field Name="Field Separator" Usage="R" Min="1" Max="1" Datatype="ST" Length="1" ItemNo="00001">

<Reference>11.6.1</Reference> </Field>- <Field Name="Encoding Characters" Usage="R" Min="1" Max="1" Datatype="ST" Length="4" ItemNo="00002"> <Reference>11.2.2</Reference> </Field>- <Field Name="Sending Application" Usage="R" Min="1" Max="1" Datatype="HD" Length="180" Table="0361" ItemNo="00003"> <Reference>11.2.3</Reference> <Component Table="0300" Name="namespace ID" Usage="O" Datatype="IS" Length="3" /> <Component Name="universal ID" Usage="O" Datatype="ST" Length="3" /> <Component Name="universal ID type" Usage="O" Datatype="ID" Length="3" Table="0301" /> </Field>- <Field Name="Sending Facility" Usage="R" Min="1" Max="1" Datatype="HD" Length="180" Table="0362" ItemNo="00004"> <Reference>11.2.4</Reference> <Component Table="0300" Name="namespace ID" Usage="O" Datatype="IS" Length="3" /> <Component Name="universal ID" Usage="O" Datatype="ST" Length="3" /> <Component Name="universal ID type" Usage="O" Datatype="ID" Length="3" Table="0301" /> </Field>- <Field Name="Receiving Application" Usage="R" Min="1" Max="1" Datatype="HD" Length="180" Table="0361" ItemNo="00005"> <Reference>11.6.6</Reference> <Component Table="0300" Name="namespace ID" Usage="O" Datatype="IS" Length="3" /> <Component Name="universal ID" Usage="O" Datatype="ST" Length="3" /> <Component Name="universal ID type" Usage="O" Datatype="ID" Length="3" Table="0301" /> </Field>

71

HL7 V2 Table Library Example<TableDefinition Id="0001" Name="Sex" Codesys="HL7" Type="User">

<TableElement Code="F" DisplayName="Female" Source="HL7"/>

<TableElement Code="M" DisplayName="Male" Source="HL7"/>

<TableElement Code="O" DisplayName="Other" Source="HL7"/>

<TableElement Code="U" DisplayName="Unknown" Source="HL7"/>

</TableDefinition>

<TableDefinition Id="0002" Name="Marital status" Codesys="HL7" Type="User">

<TableElement Code="A" DisplayName="Separated" Source="HL7"/>

<TableElement Code="D" DisplayName="Divorced" Source="HL7"/>

<TableElement Code="M" DisplayName="Married" Source="HL7"/>

<TableElement Code="S" DisplayName="Single" Source="HL7"/>

<TableElement Code="W" DisplayName="Widowed" Source="HL7"/>

</TableDefinition>

72

HL7 v2 Validation Context Example

 - <DataValueLocationItem>- <Location>- <Segment Name="PID" InstanceNumber="1">- <Field Position="3" InstanceNumber="1"> <Component Position="1" /> </Field> </Segment> </Location>- <Value> <PlainText>XYZ10501</PlainText> </Value> </DataValueLocationItem>  - <DataValueLocationItem>- <Location>- <Segment Name="PID" InstanceNumber="1">- <Field Position="3" InstanceNumber="1">- <Component Position="4"> <SubComponent Position="1" /> </Component> </Field> </Segment> </Location>- <Value> <PlainText>XREF2005</PlainText> </Value> </DataValueLocationItem>

73

HL7 v2 Message Validation Report

74

Testing Validation Types

• Validation against ‘failure types’: – VERSION*: The version in the message and in the profile should match. – MESSAGE_STRUCTURE_ID*: The message type (MSH.9 element) in the profile and in the

message should match. – MESSAGE_STRUCTURE: The message should have a valid message structure (correct usage,

correct cardinality, and correct element name). – USAGE: R elements should be present; X elements should not be present in the message. – CARDINALITY: Elements should be present at least the minimum times and at most the maximum

times specified in the profile. It should also take into account the usage of the element (X element with a minimum of 4 should not be present in the message).

– LENGTH: The value of the element should have a length equal or less than the value specified in the profile.

– DATATYPE: For the datatype NM, DT, DTM, SI and TM, the value of the element should match the regular expression defined in the standard.

– DATA: The value of the element should match a constant specified in the profile, a value set specified in a table, a value or a regular expression specified in the message validation context.

– MESSAGE_VALIDATION_CONTEXT*: This is a user input error when the location specified in the message validation context can't be found in the message.

– TABLE_NOT_FOUND*: This is a user input when a table can't be found in the table files (TableProfileDocument).

– AMBIGUOUS_PROFILE*: The profile should not be ambiguous.

75

Conceptual View of HL7 v2 PIX Manager Test

End-User(Vendor)

VendorPIX

ManagerApplication

VendorPIX

ManagerApplication

NISTPIX

SourceTest Agent

NISTPIX

SourceTest Agent

PIX/PDQ Test Tool

NISTPIX

ConsumerTest Agent

NISTPIX

ConsumerTest Agent

We

b A

pp

lic

ati

on

Real-TimeLog

Screen

TestCases

Reports

NIST Server

Co

mm

un

ica

tio

n

HL7v2

HL7v3

Te

st

Ex

ec

uto

r

Va

lid

ati

on

MLLP (v2)

OtherNIST

Test Agents

OtherNIST

Test Agents

TestFlow

Engine

76

Step 1 and 1a

Validation Criteria

Check against ADTA04 Profile Check against Value Set Check against TC10501-1 Validation Context

Assert an “AA” acknowledge message for registration of patient “ALPHA” in domain “NIST2010”; Patient ID is “PIX10501”

NISTPIX SourceTest Agent


VendorPIX

ManagerApplication

VendorPIX

ManagerApplication

TC10501-1Generation

Context (XML)

ADTA04Profile (XML)

Value Set (XML)

- Profiles- Test Scenarios- Test Cases- Value Sets- Generation and Validation Context Files

TestRepository

Patient ID Last Name First Name

PIX10501 ALPHA ALAN

XYZ10501 ALPHA ALAN

ABC10501 ALPHA ALAN

TC10501-1ValidationContext

(XML)

ACKProfile (XML)

ADTA04 – Register patient“ALAN ALPHA” (ID = PIX10501) in domain “NIST2010”


1

1a

77

Step 2 and 2a

Validation Criteria


Assert an “AA” acknowledgement message for the registration of patient “ALPHA” in domain “NIST2010-2”; Patient ID is “XYZ10501”



VendorPIX

ManagerApplication

VendorPIX

ManagerApplication



PIX10501 ALPHA ALAN

XYZ10501 ALPHA ALAN

ABC10501 ALPHA ALANTC10501-1Generation

Context (XML)

ADTA04Profile (XML)

Value Set (XML)


(XML)

TestRepository

ACKProfile (XML)


2

2a

ADTA04 – Register patient“ALAN ALPHA” (ID = XYZ10501) in domain “NIST2010-2”

78

Step 3 and 3a

Validation Criteria


Assert an “AA” acknowledgement message for registration of patient “ALPHA” in domain “NIST2010-3”; Patient ID is “ABC10501”



VendorPIX

ManagerApplication

VendorPIX

ManagerApplication



PIX10501 ALPHA ALAN

XYZ10501 ALPHA ALAN

ABC10501 ALPHA ALANTC10501-1Generation

Context (XML)

ADTA04Profile (XML)

Value Set (XML)


(XML)

TestRepository

ACKProfile (XML)

ADTA04 – Register patient “ALAN ALPHA” (ID = ABC10501) in domain “NIST2010-3”


3

3a

79

Step 4 and 4a

Validation Criteria

PIX Query Case 1: Assert response message with MSA.1 = “AA”

PIX Query Case 1: Assert response message with PID.3.1 = “XYZ10501”

PIX Query Case 1: Assert response message with QAK.2 = “OK”

And more…

NISTPIX

ConsumerTest Agent

NISTPIX

ConsumerTest Agent

VendorPIX

ManagerApplication

VendorPIX

ManagerApplication



PIX10501 ALPHA ALAN

XYZ10501 ALPHA ALAN

ABC10501 ALPHA ALANTC10501

GenerationContext

(XML)

QBPQ23Profile (XML)

Value Set (XML)

TC10501ValidationContext

(XML)

TestRepository

RSPK23Profile (XML)

QBPQ23 – Send query message for patient “ALAN ALPHA” in domain “NIST2010-2” using the patient ID in domain “NIST2010”

4

4a RSPK23– Send response indicating that the identifier (“XYZ10501”) for patient “ALPHA” was found in domain “NIST2010-2”

80

Step 5 and 5a

Validation Criteria

PIX Query Case 1: Assert response message with MSA.1 = "AA“

PIX Query Case 1: Assert response message with PID.3[1].1 = "XYZ10501" and PID.3[2].2 = "ABC10501“

PIX Query Case 1: Assert response message with QAK.2 = "OK“

And more...

NISTPIX

ConsumerTest Agent

NISTPIX

ConsumerTest Agent

VendorPIX

ManagerApplication

VendorPIX

ManagerApplication



PIX10501 ALPHA ALAN

XYZ10501 ALPHA ALAN


GenerationContext

(XML)

QBPQ23Profile (XML)

Value Set (XML)


(XML)

TestRepository

RSPK23Profile (XML)

QBPQ23 – Send query message for patient “ALAN ALPHA” in domain “NIST2010-2” and “NIST2010-3” using the patient ID in domain “NIST2010”

5


5a

81

Step 6 and 6a

Validation Criteria

PIX Query Case 1: Assert response message with MSA.1 = "AA“

PIX Query Case 1: Assert response message with PID.3[1].1 = "XYZ10501" and PID.3[2].2 = "ABC10501“

PIX Query Case 1: Assert response message with QAK.2 = "OK“

And more...

NISTPIX

ConsumerTest Agent

NISTPIX

ConsumerTest Agent

VendorPIX

ManagerApplication

VendorPIX

ManagerApplication



PIX10501 ALPHA ALAN

XYZ10501 ALPHA ALAN


GenerationContext

(XML)

QBPQ23Profile (XML)

Value Set (XML)


(XML)

TestRepository

RSPK23Profile (XML)

QBPQ23 – Send query message for patient “ALAN ALPHA” in all domains using the patient ID in domain “NIST2010”

6


6a

Validation

HL7 v3 Messages and IHE Actor Functional Behavior

83

HL7 v3 Validation Overview

• HL7 v3 Syntax Validation– Ensure the message structure is valid with respect to the HL7 V3 conformance

schemas. The schemas used for testing are the IHE schemas and can be downloaded at: ftp://ftp.ihe.net/TF_Implementation_Material/ITI/packages/PIXV3.Support.Materials.v3.zip

ftp://ftp.ihe.net/TF_Implementation_Material/ITI/packages/PDQV3.Support.Materials.v2.zip

– Ensure that the conformance requirements are valid with respect to the standard and the IHE technical framework for a given transaction. These additional requirements are tested using the NIST created schematron rules available at

• Value Set Semantic Validation– Value set semantic testing is also handled with the schemas and schematron

validation described above.

• Test Case Specific Validation– Verify element content against a validation context file that captures test values as

defined in the Pre-Connectathon test cases. – The methodology is the same as v2.

• Transport Layer (SOAP)– Not part of PIX/PDQ Tool; use XDS toolkit to validate this aspect

Summary

85

Support

Report Bugs, Issues, and Suggestions for Improvement to:http://code.google.com/p/pixpdqtool/issues/list

For administrative questions and comments only contact Rob Snelick:[email protected]

IHE PIX/PDQ Google Group (To discuss PIX/PDQ and testing issues):http://groups.google.com/group/ihe_pix_pdq_testing

Before sending questions please read all documentation. Our resources are limited. We will focus on questions related to our testing tool and bugs. We can’t spend time debugging your code.

V3 SOAP Message Validation. This is an external tool and we do not provide support for this tool. The link is provided to help you debug your V3 message wrapper.

ihe pre-connectathon pix and pdq test tool tutorial and guide (2011 cycle) robert snelick national...

Documents

nist pixpdq test tool

nist pixpdq tool

preconnectathon testing

test tool cam

connectathon slide

ihe preconnectathon

test sut nist pixpdq

tool tutorial