Join GitHub today
Introduction to XDS Toolkit
XDS Toolkit is an open source tool collection supporting IHE Document Sharing profiles. It is packaged as a WAR file suitable for running on Tomcat.
Many of the IHE actors that Toolkit tests are implemented as servers - they start operation by receiving a message. As a result most users download Toolkit and run it on their own system. We do maintain a copy of Toolkit as a service on the Internet for developers of client-style IHE actors like Document Source. We recently transitioned off of the old Public Registry server for this purpose. As a result many of the client tests, for actors like Document Source, have not yet been implemented on Toolkit.
The tools packaged in Toolkit are of several types: utilities, simulators, and the Conformance tool. In this discussion we refer to tools as being of client or server style. This is not an IHE designation but a general description. Clients start their work by initiating a connection and servers start by accepting a connection.
These are client-style tools used to informally interrogate server-style actors. An example is the FindDocuments tool which can send a FindDocuments Stored Query to a Document Registry, Initiating Gateway, or Responding Gateway. Each utility is focused on a single function like FindDocuments Stored Query. If that query can be issued from multiple IHE actors and/or issued to multiple IHE actors then that is seletable in the tool. So there is no XDS FindDocuments tools separate from an XCA FindDocuments tool. There is one FindDocuments tool that servers both via selections on the user interface.
When these tools receive metadata back in the response it is validated against the appropriate Schema and configured coding conventions.
A special tool called the Inspector can be launched from most utilities to inspect the details of the response message.
Simulators are implementations of server-style IHE actors included in Toolkit. Examples are Document Registry and Document Repository. Simulators are very light weight in that they can be created and destroyed quickly as needed. Each simulator has a configuration tool to control its operation. Simulators are tied to a logging service so the request and response messages can be viewed in mass in a time-sequenced listing or in detail in the Inspector.
This tool is special and must be addressed separately. The Conformance tool is a centralized user interface for all conformance testing. Here we describe several aspects of its operation.
This is a general feature of Toolkit that is used in the Conformance tool. Toolkit can have multiple Environments loaded at once and selectable on the user interface. The Environment selection governs:
Document Sharing relies on a community agreement on the coding schemes to be used in document exchange. This agreement is called the Affinity Domain design. The selection of an Environment selects a coding set to be used in two ways. First, message received by the tool are validated against this coding set. Second, test messages sent can be aligned with this coding set. See Extended Test Kits below for details.
Choice of certificate used in TLS handshake
The Environment contains a certificate used in TLS handshakes when Toolkit is the client in the exchange (initiates the connection). Since Toolkit runs in a Servlet environment (on top of Tomcat typically) it is the configuration of Connectors in Tomcat that associate certificates with ports. So, certificate issues must be handled both in Toolkit Environment configuration and Tomcat configuration.
Extended Test Kits
The purpose of the Extended Test Kits is to allow users or regional projects to author local or private testa and install them in Toolkit.
A test kit is a collection of named tests that can be run by the Conformance tool. There can be multiple test kits loaded into Toolkit at one time and there is a specific order to how they are searched.
First there is an internal Test Kit that is delivered with Toolkit. For most users the discussion ends here.
Next there is a scheme involving the chosen Environment and Test Session that controls the order that the remaining Test Kits are searched.
Each Environment can contain multiple Test Kits, one for each Test Session defined in the system. To know which Test Kits will be searched for a test you must know the current Environment and Test Session. The order of search is:
If the current Environment has a Test Kit named for the current Test Session then look there first.
If the current Environment has a Test Kit named for the default Test Session look there.
If the default Environment (always exists) has a Test kit named default look there.
Look in the internal Test Kit shipped with Toolkit.
Test Sessions server two purposes aligned with maintaining Conformance test logs and results. First when testing multiple actors and/or multiple systems each actor/system should be in its own Test Session. This isolates the results.
Second when using Toolkit in multi-user mode, Test Sessions are used like user accounts to keep users results separated and private. In multi-user mode Test Session names are system generated and secret. This provides the isolation.
This opening display within the Conformance tool allows the selection of focus of the testing.
These are high level selections made before running the tool. Examples are the enabling of TLS and SAML in the overall testing exchange.
Given the profile/actor/option and configuration selections, this part of the tool builds the testing environment. Here environment is used in the generic sense, not connected to the selected Environment. This can involve building and configuring simulators, registering Patients by their IDs, and submitting supporting data to simulators or systems under test. When Orchestration is complete a summary of its operation is displayed.
Below the Orchestration section is the display of tests appropriate for the selected profile/actor/option and configuration. These tests are found by searching the available Test Kits.
Tests can be run individually or in a batch mode. Results come back to the display.
Test Results display
Each test is represented on the display along with its status. It can be opened to investigate details of its operation.
The Inspector tool can be launched from any test result to look at details.