Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
The downloads are found at https://github.com/usnistgov/iheos-toolkit2/releases. 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.
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.
If you are not using TLS then Tomcat requires no configuration. Just update toolkit.properties 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.