Configuring Toolkit

Toolkit configuration guide

Table of Contents

• Properties
  • External Cache
  • Toolkit Host
  • Toolkit Port
  • Tomcat TLS Port
  • Use Actors File=false
  • Default Environment
  • Admin Password=easy
  • Client_Cipher_Suites
  • Enable all ciphers=false
  • Listener Port Range
  • Gazelle Config URL
  • Gazelle_Assertions_for_Connectathon_URL
  • Enable_SAML=true
  • Auto_init_conformance_tool=true
  • MSH
  • Archive_Logs=false
  • Proxy_Port=7297
  • Multiuser_mode=false
  • Cas_mode=false
  • Nonce_size=6
  • Gazelle_testing_session=40
  • Using_SSL=false
  • SSL_Port=9443
  • Default_Test_Session
  • Default_Test_Session_is_Protected=false
  • Bypass_SecurityHeaderMuOnIncomingResponse=true
  • Sts_ActorName=GazelleSts
  • Sts_TpName=GazelleSts
  • Sts_RemoveWhitespace=true
  • Wiki_Base_URL

These parameters are kept in the file toolkit.properties which in the downloadable WAR file is located at

WEB-INF/classes/toolkit.properties

It should never be necessary to edit this file directly. If you do then you must restart Tomcat for the changes to take effect.

Normally you should the built-in editor which is found in the Tool Tray (left side). The configuration editor tool is named Toolkit Configuration. You must be signed in to open this tool.

Sometimes you will see the property names with spaces between the words and sometimes with _ between the words. The file format uses _ but the on-screen display is spaces.

When a default value exists it is shown in the title.

Properties

External Cache

Location of the toolkit external cache. The external cache is where toolkit keeps your local data. It is maintained separate from the toolkit WAR so that if you update the toolkit your data can remain.

Rules for creating the external cache:

• A directory writable by the user account that runs tomcat. This could be the account tomcat or your personal account depending on your installation.

• The directory path must contain no white space (blank characters for instance) As an example of what will not work, /home/bill/temp dir/ec. This will not work because of the temp dir directory name with the embeded space character.

• This directory should start empty. Toolkit will initialize it.

For more detail on the External Cache see here and this.

Toolkit Host

This is the hostname of the machine running Toolkit. This must be configured so that endpoints can be created for simulators. If you use the value localhost then the simulator endpoints will only be usable by software running on this machine.

Toolkit Port

This is the port number for Tomcat. This gets configured into simulator endpoints.

Tomcat TLS Port

This is the TLS port number for Tomcat. This gets configured into simulator endpoints. For TLS to work with simulators you must install the appropriate certificates in Tomcat.

Use Actors File=false

This should always be set to false.

Default Environment

This is initialized to default. The default environment is automatically installed in the external cache when toolkit is first launched.

Admin Password=easy

The password needed to configure toolkit. Toolkit is delivered with the password easy.

Client_Cipher_Suites

comma separated list of cipher suites that toolkit will use when initiating a TLS connection. If nothing is specified in this property, toolkit software defaults to whatever the Java Runtime Environment uses when it creates a socket connection. An example is: TLS_RSA_WITH_AES_128_CBC_SHA, SSL_RSA_WITH_3DES_EDE_CBC_SHA

Enable all ciphers=false

This must always be false

Listener Port Range

The range of port numbers that can be managed by toolkit for accepting Patient Identity Feed messages. One port is allocated to each Document Registry simulator. If you run out of ports then attempts to create new Document Registry simulators will fail.

The format is low_port, high_port.

Gazelle Config URL

This is the URL to contact Gazelle to download system configurations. It is only used at the North American and European Connectathons. An example is

https://gazelle.ihe.net/EU-CAT/systemConfigurations.seam

Gazelle_Assertions_for_Connectathon_URL

Documentation maintained by the Gazelle team regarding the XUA assertions that the Assertion Manager provides to toolkit. For now the value is

Gazelle_Assertions_for_Connectathon_URL=https://docs.google.com/spreadsheets/d/18dG9yKJizxOBQl8JKiTr2_OPHGhgRd-4Ue0NBNHWC60/edit#gid=0

Enable_SAML=true

Enable/dispable SAML operations. This should be disabled if the the link to Gazelle Assertion manager is not available.

Auto_init_conformance_tool=true

Automatically run the orchestration provided for each actor type in the Conformance tool.

MSH

These properties control the respective fields in the V2 Patient Identity Feed

MSH_3=XDSTOOLS
MSH_4=TK
MSH_5=UNKNOWN
MSH_6=UNKNOWN

Archive_Logs=false

Archive every transaction issued by the Test Client or received by a simulator in the directory EXTERNAL_CACHE/archive. This is used at Connectathon to build a record of the event for later analysis of the tooling and by CAS for certification documtation.

Proxy_Port=7297

Toolkit includes a recording proxy that performs translation. This is used by the MHD simulators.

Multiuser_mode=false

Enables multi-user mode.

Cas_mode=false

Enable CAS mode. If set to true then Multiuser_mode must also be set to true. CAS Mode is an extension of multi-user mode.

Nonce_size=6

In multi-user mode, Test Sessions are private to the creator and carry a hexadecimal name/id. This controls the size of that id.

Gazelle_testing_session=40

When Toolkit is linked to Gazelle for Connectathon or CAS environments, this is the Gazelle Test session number/name that holds the system configurations to be used.

Using_SSL=false

Used only for the HTTPS GUI.

SSL_Port=9443

Used only for the HTTPS GUI link generation.

Default_Test_Session

By default when using Multi-user mode, a user launches Toolkit and must enter a Test Session before opening any tool. If this is set then this Test Session will be automatically entered upon launch. The Test Session must be configured before this is engaged. For Connectathon the value is cat.

Default_Test_Session_is_Protected=false

Normally set to true for Multi-user mode. When true no tools may be opened in default Test Session and entering default Test Session required admin privileges.

Wiki_Base_URL=https://github.com/usnistgov/iheos-toolkit2/wiki

Pointer to the project wiki. Wiki references in code use this base address.

Bypass_SecurityHeaderMuOnIncomingResponse=true

Bypasses the must understand directive on an incoming response SOAP security header.

Sts_ActorName=GazelleSts

The Actor site name which contains the endpoints.

Sts_TpName=GazelleSts

The Test Plan name that executes a Gazelle SAML request.

Sts_RemoveWhitespace=true

If false, white space is not removed from the SAML assertion.

Wiki_Base_URL

Location of wiki holding toolkit documentation. If wiki is moved all links from within toolkit can be updated by changing this setting. See Documentation references from toolkit.