XDSTools Administrators

Overview

You or someone else has installed and configured the xdstools software on a system for your use. You will use the web interface to test one or more actors in one or more domains, but there are some configuration items and directory structures to understand that will make you more efficient.

Toolkit Properties

Basic Access

The toolkit stores a number of properties in a file called toolkit.properties. These properties are available to you through the user interface.

1. Browse to the XDSTools web application. The URL will look something like this: http://hostname.org:port/xdstools4

2. Select the toolkit configuration link (upper left corner) to view the toolkit properties:

3. When prompted for a password, the default password shipped with the xdstools software is "easy" (no quotes). Try that first. If that password works, you are done with this subsection.

4. If the default password does not work

   • Login to the server using ssh and a unix account:ssh xxx@hostname.org
   • Find the tomcat folder that is hosting the toolkit. Maybe just search for xdstools4.war
   • Examine the toolkit properties file: webapps/xdstools4/WEB-INF/classes/toolkit.properties
   • Find the entry for Admin_password. That should be the admin password for the xdstools software.
   • Use that password in the web user interface to open the properties. You should see the password in plain text in the user interface.

Toolkit Properties Review

You will eventually want to understand all of the properties and review all of them. I am going to highlight some of the major values and what you should understand about them.

Property	Comment
External Cache	A folder on the server with data used and produced by toolkit. Separate explanation below. Make sure this folder exists on the server.
Toolkit Host	This hostname is used when the toolkit builds URLs to publish as endpoints for services. It should match the hostname as known by the users of the toolkit. If this is an Internet resource, it needs to be a fully qualified domain name. For internal testing, advanced users may be able to use a simple host name. Make sure the hostnames are consistent.
Toolkit Port	This is the port that Tomcat uses to run the application. Default Tomcat port is 8080, but you can use other values. You just have to match the Tomcat configuration and this value. This is the same port that will be part of the URL for simulator endpoints. That is, users will send SOAP and other HTTP based messages to this port. Make sure the port listed in this field matches the Tomcat port. If you are seeing the xdstools page through an Apache redirect, you have some additional work to do.
Toolkit TLS Port	This is the TLS equivalent of Toolkit Port. Validate this port.
Default Environment	The toolkit supports multiple environments. That means different codes.xml tables and different certificates. This value gives the default value when toolkit is accessed through the web. There is a more complete explanation below. Check that this folder exists in the $EXTERNAL_CACHE/environment.
Listener Port Range	This is a range of TCP ports used for toolkit HL7 receivers. For example, a toolkit XDS Registry simulator includes an HL7 receiver to accept HL7 V2 ADT messages. As simulators are created, they take the next available port from this range. If you intend to have a lot of simulators on the system, you can increase the range. You also need to open firewall rules for these ports.

External Cache Folder Structure

The toolkit uses an external cache (mentioned above). If some of the folders/data do not exist when the toolkit starts, the software will create those. Verify that these exist in the external cache folder:

• ImageCache: Only needed if imaging tests are desired. Can be omitted if just doing standard XDS, XCA...
• TestLogCache: This folder will be used to store test results. Results are accessible through the web interface, but you can extract data from this area for issue tracking, history, ...
• actors: This folder is used to hold configuration information for each system under test. Each system under test will have a file that describes the configuration parameters for that system (endpoints for transactions).
• environment: This contains folders for different environment settings. When toolkit starts, it will create the folder default which is as the name implies. Most users will stick with this option. Other folders can be used to have separate environments. That implies a separate copy of codes.xml and separate certificates.
• simdb: The folder that contains data files for the simulators. Each folder under this heading contains data for a single simulator. Naming convention will be discussed later as part of an exercise.

TestLogCache

The XDSTools user interface allows the user to create a Test Session. Each Test Session that is created corresponds directly to a folder with the same name in the TestLogCache. Test results for a session are collected under that folder in TestLogCache.

Exercise:

• Look in the TestLogCache folder for a list of folders. Compare that list to the names in the Test Session pulldown. These should match.
• Create a new test session in the user interface (alpha).
• Look in the TestLogCache folder and verify that the folder alpha was created successfully.

Simulators

Simulators in the toolkit are typically server applications (think Repository) that respond to requests (SOAP, standard HTTP). In xdstools2, users created simulators manually to test their implementations. In xdstools4, the Conformance Tests software has logic that creates simulators automatically to test specific actors. When you direct the toolkit to test an actor X, the software will create only the simulators that are needed to test that actor, X.

When simulators are created (by hand or automatically), the naming convention is:

$session__$simulator_id

If you used alpha as the name of the Test Session and rep as the Simulator ID, the computed simulator name will be alpha__rep. Note the two underscore characters. When creating simulators by hand, the user enters the value for Simulator ID. These are typically short strings that are easily recognized as identifying an actor (reg == Document Registry). There are recommendations below on Simulator Names.

Support for TLS Testing

Process / Practice Suggestions

Test Session

This assumes that you are managing test sessions and participant testing by hand. There is a mechanism to manage this in coordination with the Gazelle software, but that is not documented here.

Test results are collected in the TestLogCache folder under the folder identified by Test Session.

1. You certainly want to create separate Test Sessions if you are servicing multiple customers in parallel.
2. If you have a customer that wants to test multiple actors (Registry, Repository, Initiating Gateway), you should create separate Test Sessions for each actor. This implies one Test Session for each customer/actor pair. For example: acme-rep.
3. If your installation of toolkit is to be used to service multiple customers in parallel, you will want to define a naming convention for Test Session to make it simple to find the proper test results. The Steve Moore recommendation is to use a 3-4 letter code for the company name (e.g., acme) followed by a dash (-) followed by a short code for the actor (rep, reg, ..); see the section below on Simulator Names.
   • As an example, a Test Session could be acme-rep.
   • This means that simulators created to test acme-rep will be named acme-rep__$simulator_id (acme-rep__reg).

System Configurations

In xdstools2, a system under test was referred to as an actor. The user interface referred to actor configuration. In xdstools4, the link to manage the systems under test is now labelled System Configurations. The underlying concept is the same for both xdstools2 and xdstools4.

The toolkit manages one file for each system under test. The file is a collection of properties. Following is a non-exhaustive list of property types:

• URL: An endpoint for an HTTP (standard HTTP or SOAP) request
• OID: An identifier such as the value for a repositoryUniqueId.
• ADT Feed: Host and port number to accept an HL7 V2 patient identifier feed.

The administrator manages the name of the system and the values for the properties. One system (file) can be used to collect the properties for multiple actors. You do not need to make separate files if a test participant wants a single system to test both a Document Repository and a Document Registry. When naming a new system for testing, we recommend a 3-4 letter acronym for the test participant followed by __sut (for system under test). The example is: acme__sut

When this shows up in other screens, it will be obvious that this is for a system under test and will not be confused with the simulators that are named using the Test Session name.

Simulator Names

Toolkit developers have adopted a convention for the Simulator ID portion of a simulator name. The Simulator ID is a free text string. These are recommended values.

Recommended Value	Actor
rep	Document Repository
reg	Document Registry
rr	Combined Registry/Repository
ig	Initiating Gateway
rg	Responding Gateway
iig	Initiating Imaging Gateway
rig	Responding Imaging Gateway

Acceptance Testing

If someone else has handed you an installed version of the toolkit, there are a set of web-based tests you can run to check the installation and configuration.

That procedure is defined on a separate page: Acceptance Testing