Bill Majurski edited this page Jun 21, 2018 · 5 revisions

Installing Toolkit


The downloads are found at Grab the most recent.

System set up

Java version 8 and Tomcat version 7 or later. We run on Tomcat 8.

Version 4: As of Version 4 our development environment is Oracle Java 8 and Tomcat 7.

Version 4: If you are testing SAML then Java 8 is required. See [[Issue with Java 7 and Toolkit 4]] for details.

Java 9 is not yet supported. We have tested with it and Toolkit will not run correctly.

Install the WAR

The above download is for the WAR file for toolkit. This should be installed in Tomcat by copying it to the webapps directory. Tomcat should open it immediately. If not then restart Tomcat.

Multiple versions of toolkit can be run at the same time from the same instance of Tomcat. If you name the downloaded WAR file xdstools2.war then it will run from that name (http://host:port/xdstools2). Change the filename (before you move it to Tomcat’s webapps directory) and the URL will follow. Technically this name is the App Context.

If you run multiple copies they must each have their own private external cache.

Version 4: As of Version 4 the download will be named xdstools4.X.Y.war and should be renamed to xdstools4.war before installing it in Tomcat. Actually this is only our convention. It can be installed under any name you like. See [[Renaming Toolkit]] for details.

Create the External Cache

The External Cache is an area on local disk that Toolkit uses for saving generated data. This is a directory on the same machine as Toolkit. The path to this directory should not contain any spaces or special characters. Create this directory now. You will configure toolkit to use it in a later step.

Optional: Add Files for Testing Imaging Functions

If you are testing XDS-I.b or XCA-I.b, there is additional configuration required. You can find those instructions here: [[Configuring Toolkit for Imaging Tests]]. If you are only concerned with the traditional XDS.b, XCA, …​ tests, you can ignore this.

Launch Toolkit

If you just installed Tomcat for the first time and are running it on your desktop then the URL will be


assuming the WAR file for toolkit was xdstools2.war when you moved it to Tomcat’s webapps directory.

Version 4 note: Version 4 is delivered as xdstools4.war so the URL will be


When toolkit is opened it will complain about not finding the External Cache. That gets configured next.


When Toolkit starts for the first time it is likely that the configured External Cache location will not exist on your machine. The exact error message will vary since it is coming from your system. Either way the error will be displayed in a dialog box. Hit Ok to get rid of the error and continue below.

At the top of the window is a link labeled Toolkit Configuration. Open it. It will challenge you for a password. It is easy.

If the Toolkit Properties are not displayed and you get another error dialog box instead then there is a problem you need to report. See [[Reporting Toolkit Installation Problems]].

At a minimum you need to enter your local value for the path to the External Cache. If you type it wrong the Save button will verify so you will get feedback.

Note to Windows users - the path to your External Cache is probably something like c:\Toolkit. Here are variants that we have seen work on Window systems:


If the External Cache directory is empty at this point, toolkit will initialize it.

Other things you may want to configure…​

If you are going to use simulators then you will need to enter a real hostname and port number where toolkit is running. These get configured into the endpoints for simulators.

If you are going to use a Registry simulator then you will need to allocate a few ports for Patient Identity Feed listener to use. These are listed as Listener Port Range. Each Registry simulator allocates a port so make sure to supply enough.

TLS configuration will be discussed separately. It is a little more involved.

Auto-install of codes.xml and certificates

As of Version 4 Toolkit is distributed with the most recent version of codes.xml and its certificate for Pre-Connectathon and Connectathon testing. These are kept in an environment named default. This environment will be automatically installed by Toolkit the first time it boots. It will not over-write an existing environment named default. If you already have an environment named default delete or rename it and restart Tomcat. The new default environment will be installed.

Note: the auto install of the certificate will only affect Toolkit as client. When using simualtors (Toolkit as server) it is also necessary to configure Tomcat.

Configuring Tomcat

If you are not using TLS then Tomcat requires no configuration. Just update with the non-TLS port from Tomcat.

Configuring for TLS

Toolkit acts as a client, initiating connectations, and as a server, accepting connections. Client and server must be individually configured for TLS.

Client TLS configuration

Assuming you are using the default Environment, the Java Keystore is stored at


with the keystore password saved in


When Toolkit automatically builds the default External Cache, the keystore for IHE Connectathon testing is installed. These certs are issued by the IHE Gazelle CA. If you need to install a different cert then do that in a different Environment.

Server TLS configuration

See here for instructions.

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.