Skip to main content

Using the IHE Test Utility

The IHE test utility is a tool that assists in configuring and testing IHE scenarios. The IHE test utility is available from the Other Management menu in a registry production, or from the production menu in a foundation production. It can generate and send test data for PIX, PDQ, and XDS.b transactions, taking the place of an external testing utility like SoapUI.

Configuring your Productions to Use the Test Utility

In order to use the test utility, your Foundation production must have the HS.Test.ServiceOpens in a new tab enabled. This is the business service to which the utility will send SOAP messages. It includes a series of settings that point to the relevant business actors that perform the IHE transactions.

If you have installed one or more FHIR IHE profiles, your list of additional settings will include the relevant FHIR IHE business hosts.

To test XDS.b, your Foundation production must also have HS.IHE.XDSb.DocumentSource.OperationsOpens in a new tab enabled.

To test metadata update, your Foundation production must also have HS.IHE.XDSb.Administrator.OperationsOpens in a new tab enabled.

To enhance your ability to track down any testing issues, you may wish to enable TraceOperations in your PIX, PDQ, and XDS.b business operations. Just remember to turn off trace operations before going into a production environment.

IHE Test Utility Main Menu

The IHE test utility uses a tabbed menu with the following sections:

  • Main

  • PIX and PDQ

  • XDSB

  • DSUB

  • XCPD

  • Any FHIR IHE profiles that you installed

Within each tab are menu items that bring up a particular page, for example the Configuration page.

Configuring the IHE Test Utility

For a single user on an instance, no configuration is required other than enabling the HS.Test.ServiceOpens in a new tab business service in your Foundation production. Your production must be running. If either of these conditions is not met, the utility issues a warning when you open it.

The utility uses three unique values during its testing: Trace configuration name, Trace configuration port, and SAML username. The utility automatically assigns default values for these fields; you do not need to change these default values unless multiple users are accessing the test utility. In this case, each user must enter unique values and click Save before using the utility. If multiple users are using the test utility, keep the following in mind when choosing unique values:

  • Trace configuration name is any unique string. Default is IHE.Testusername.

  • Trace configuration port is a numeric value that does not conflict with other ports in use. The utility does not check whether the port number is already being used. Default is 54321.

  • In many cases, SAML username can be any unique string. However, if the utility is sending messages to parts of HealthShare that validate the username against a registry, you must specify a valid SAML username. For example, if HealthShare is using the username for Consent processing, it must be valid.

Enabling Logging in the Test Utility

Optionally, you can select Enable logging to turn on logging by default for your transactions. You can also enable or disable logging for transactions on an individual basis. When logging is enabled, a log button appears after you run the transaction. It is labelled with an incrementing log number. The log shows the SOAP message sent to the test service, and the response received. You can also view the full set of logs across all of your transactions from the Trace option on the Main menu tab.

Viewing Endpoints in the IHE Test Utility

Click EndPoints on the Main menu tab to bring up a view into the Service Registry. Here you can view and edit the endpoints that the IHE test utility will work with.

Using the History Page in the IHE Test Utility

Click History on the Main menu tab to bring up a history of the transactions that you have previously performed in the test utility. This is useful in several cases:

  • when you need to provide an identifier, as you can copy it from a search response in order to paste it into a new transaction.

  • when you need to rerun a transaction, for example after tweaking your production settings after an unsuccessful test.

  • when you need to view the logging or session information from a previous transaction.

Submitting a SOAP Request with the Test Utility

To submit a SOAP request outside the scope of the provided transactions, or to submit a request to a different location, the test utility provides a generic Web Service Submit page. To submit a SOAP request:

  1. Select WS Submit from the Main menu tab.

  2. Optionally select an EndPoint to populate the Host, Port, and URL fields. The endpoint list is populated from the Service Registry.

  3. Alternatively, populate the Host, Port, and URL fields manually.

  4. Enter an SSL Configuration if appropriate.

  5. Select an Action from the dropdown. The dropdown is populated with the IHE transactions that InterSystems supports. This populates the second Action field with the IHE urn for the transaction.

  6. Type or paste the SOAP request in the Request field.

  7. Click Send.

  8. To see the response, click on the Response tab.

  9. To view the request or response as an XML tree, click Show XML.

Testing a PIX Add Transaction

To test adding a patient to your system via the PIX add transaction:

  1. Click the PIX and PDQ menu tab.

  2. Click Patient Add.

  3. Optionally Enable logging.

  4. Select whether you wish to use PIX v2 or PIX v3. This preselects the EndPoint as PIXv2.Manager or PIXv3.Manager.

  5. Enter a set of demographics for the patient. A minimum set of demographics should include:

    • First Name

    • Last Name

    • Gender

    • Date of Birth

    • Assigning Authority — select an assigning authority from the dropdown which is populated by assigning authority registry entries that have an OID associated with them.

    • AssigningAuthority OID — this is populated automatically when you select an assigning authority.

    • Facility — select a facility from the dropdown which is populated by the facility registry. When you enter an assigning authority, if there is a facility with the same code, the utility selects this facility by default.

    • MRN — the test utility automatically suggests an incremented MRN when you select an assigning authority. Either accept the suggested MRN or enter your own.

  6. Optionally change the EndPoint for the transaction. The EndPoint dropdown is populated from the Service Registry. The EndPoint field is preselected by the v2 and v3 buttons at the top of the page.

  7. Click Submit Request.

The test utility returns a string which includes the patient’s name and the home community OID.

Click the Session button to view a visual trace of the test utility session. Click Next Session to see the details of the actual PIX Add. Click Next Session three more times to view additional processing that occurs on a PIX Add. You may wish to enable TraceOperations in HS.IHE.PIXv3.Source.OperationsOpens in a new tab, HS.IHE.PIX.Manager.ProcessOpens in a new tab, and HS.Hub.MPI.Manager in order enhance your ability to track down any issues that arise during testing.

Testing a PIX Merge Transaction

In a PIX merge, you provide demographics, an assigning authority and facility, a surviving MRN, and a prior MRN. The system should merge the prior MRN into the surviving MRN and return a success or failure message in response.

To test PIX merge:

  1. Click the PIX and PDQ menu tab.

  2. Click Patient Merge.

  3. Optionally Enable logging.

  4. Select whether you wish to use PDQ v2 or PDQ v3. This preselects the EndPoint as PIXv2.Manager or PIXv3.Manager.

  5. Enter the patient name.

  6. Select an AssigningAuthority from the dropdown which is populated by assigning authority registry entries that have an OID associated with them. The AssigningAuthority OID is populated automatically when you select an assigning authority.

  7. Select a Facility from the dropdown which is populated by the facility registry. When you enter an assigning authority, if there is a facility with the same code, the utility selects this facility by default.

  8. Enter the surviving MRN.

  9. Enter the Prior MRN.

  10. Optionally change the EndPoint for the transaction. The EndPoint dropdown is populated from the Service Registry. The EndPoint field is preselected by the v2 and v3 buttons at the top of the page. The typical choice is PIXv2.Manager or PIXv3.Manager.

  11. Click Submit PIX Merge Request.

The test utility returns a success or failure message.

Click the Session button to view a visual trace of the test utility session. Click Next Session to see the details of the actual PIX Merge. You may wish to enable TraceOperations in HS.IHE.PIXv3.Source.OperationsOpens in a new tab, HS.IHE.PIX.Manager.ProcessOpens in a new tab and HS.Hub.MPI.Manager in order enhance your ability to track down any issues that arise during testing.

Testing an XDS.b Provide and Register Transaction

An XDS.b provide and register (PnR) involves submitting:

  • a document to a repository

  • the document metadata to a registry

In the test utility, this is a two-part transaction: first identify the document, then submit it.

Note:

In addition to the HS.Test.ServiceOpens in a new tab, your Foundation production must have the HS.IHE.XDSb.DocumentSource.OperationsOpens in a new tab enabled in order to test XDS.b provide and register. This component builds the ProvideAndRegister transaction by extracting the relevant data from a CDA stream. It is only used in a testing context.

To test an XDS.b provide and register:

  1. First perform a PIX or PDQ search for the patient as described in the previous sections. This will save you a lot of time and effort since the test utility remembers the results and offers to fill in certain fields for you.

  2. Click the XDSb menu tab.

  3. Click Provide & Register. This takes you to the document source page:

  4. Choose a data source. The options are:

    • Upload Local CDA file — Select Choose File. Click the Browse button and select a C-CDA file on your local disk.

    • Use sample xdata block CDA — Select Use sample xdata block CDA to generate a CDA document from an xdata block. A sample is provided.

      You can create an alternate CDA document in your own class if you like. Use the following specification to enter the location of your xdata block in the Use sample xdata block CDA field: xdata://classname:xdatablockname.

    • Use sample HL7 — Select Use sample HL7 to generate HL7 from an xdata block. A sample is provided, or you can create your own.

      You can create an alternate HL7 document in your own class if like. Use the following specification to enter the location of your xdata block in the Use sample xdata block HL7 field: xdata://classname:xdataBlockName.

    • Upload Local (non) CDA file — Select Choose File. Click the Browse button and select a file not of CDA format on your local disk.

  5. Click Upload/generate document. This takes you to the document submit page:

  6. Optionally Enable logging.

  7. If you have previously performed a PIX or PDQ search, you can select a patient from the Select Patient dropdown. This will also populate the Full Patient ID field with the MPIID of the form MPIID^^^&homeCommuniyOID&ISO.

  8. If you did not select a patient, enter the MPIID in the Full Patient ID field of the form MRN^^^&AssigningAuthority&ISO. If this an HL7 transaction from an xdata block, this field should already be populated.

  9. If you did not specify a Source Patient ID on the previous page, enter it here of the form MPIID^^^&homeCommuniyOID&ISO.

  10. Optionally select non-default values for the following types of XDS.b metadata:

    • Format Code

    • Confidentiality Code

    • HealthcareFacilityType Code

    • Practice Setting Code

    • Type Code

    • Class Code

    The values in the dropdowns come from the Coded Entry Registry, which is found under the IHE Configuration menu in the Registry namespace.

  11. Select the endpoint for the generated provide and register transaction, typically your XDS.b repository.

  12. Click Generate XDSb PnR Request.

This process kicks off the following steps:

  1. The test utility sends a SOAP message containing the document and metadata to HS.Test.ServiceOpens in a new tab at the Foundation production.

  2. HS.Test.ServiceOpens in a new tab forwards the document and metadata to HS.IHE.XDSb.DocumentSource.OperationsOpens in a new tab.

  3. HS.IHE.XDSb.DocumentSource.OperationsOpens in a new tab generates a provide and register request and forwards it to the repository as a SOAP message.

  4. The repository stores the document and sends an XDS.b register request to the registry.

  5. HS.Test.ServiceOpens in a new tab returns a success or failure message.

Click the Session button to view a visual trace of the test utility session. Click Next Session to see the details of the Register request returned from the repository. You may wish to enable TraceOperations in HS.IHE.XDSb.DocumentSource.OperationsOpens in a new tab and HS.HC.IHE.XDSb.Registry.OperationsOpens in a new tab to enhance your ability to track down any issues that arise during testing. You can view the message trace of the repository side of the provide and register by opening the Interoperability message viewer on your repository production.

Testing an XDS.b Query

An XDS.b query transaction allows you to search the registry for documents that are related to specific patient. You can filter an XDS.b query by document type and document status. The query returns a list of document unique IDs and the name of the repository where they are stored.

Note:

In order to test an XDS.b query, your Foundation production must contain the HS.IHE.XDSb.Consumer.Operations or HS..HC.IHE.XDSb.Consumer.OperationsOpens in a new tab business host as well as the HS.Test.ServiceOpens in a new tab.

To test XDS.b query:

  1. First perform a PIX or PDQ search for the patient as described in the previous sections. This will save you a lot of time and effort since the test utility remembers the results and offers to fill in certain fields for you.

  2. Click the XDSb menu tab.

  3. Click Query.

  4. Optionally Enable logging.

  5. If you already did a search for the patient, select the patient from the Select Patient dropdown. This will fill in the Full Patient ID.

  6. If you did not conduct a search for the patient, enter the Full Patient ID (MPIID) of the form MRN^^^&AssigningAuthority&ISO.

  7. If you are looking for a specific document, enter the Document Unique ID.

  8. In the Document Status field, select whether you want only Approved documents, only Deprecated documents or both.

  9. Optionally select Search for Stable documents or Search for OnDemand documents. The default is to check for both types if no checkbox is selected.

  10. Select the EndPoint for your query, typically your document registry, XDSb.Registry.

  11. Click Submit Request.

The query returns a list of document unique IDs and the name of the repository where they are stored.

Click the Session button to view a visual trace of the test utility session. Click Next Session to see the details of the XDS.b query. You may wish to enable TraceOperations in HS.IHE.XDSb.Consumer.Operations (or HS.HC.IHE.XDSb.Consumer.OperationsOpens in a new tab) and HS.HC.IHE.XDSb.Registry.OperationsOpens in a new tab to enhance your ability to track down any issues that arise during testing.

Testing an XDS.b Retrieve

You can retrieve a document that you queried for using the IHE test utility. While the IHE XDS.b Retrieve Document Set transaction allows you to retrieve multiple documents in a single transaction, the test utility supports the retrieval of only a single document for testing purposes.

Note:

In order to test an XDS.b retrieve, your Foundation production must contain the HS.IHE.XDSb.Consumer.Operations or HS.HC.IHE.XDSb.Consumer.OperationsOpens in a new tab business host as well as the HS.Test.ServiceOpens in a new tab.

To retrieve an XDS.b document:

  1. Query for a patient’s documents as described above.

  2. Click the XDSb menu tab.

  3. Click Retrieve.

  4. Optionally Enable Logging.

  5. In the Select Document for Retrieval field, select a patient and document unique ID from the list returned by your previous query. This fills in the Repository Unique Id and Document Unique Id fields and selects the EndPoint associated with the Repository Unique Id OID.

  6. Enter the Home Community ID (optional if it is the same community).

  7. Click Submit Retrieve Request.

  8. To view the document, click the View Document button that appears after the transaction succeeds.

Click the Session button to view a visual trace of the document retrieve session. You may wish to enable TraceOperations in HS.IHE.XDSb.Consumer.Operations or HS.HC.IHE.XDSb.Consumer.OperationsOpens in a new tab to enhance your ability to track down any issues that arise during testing. You can view the message trace of the repository side of the retrieve transaction by opening the message viewer on your repository production.

AuditingNext section
Previous sectionRegistry Settings for IHE Communication
FeedbackOpens in a new tab