Managing system configurations

There are two approaches to managing system configurations: Private and Connecatathon.

Managing system configurations for private testing

Here Private testing means that Gazelle is not being used to manage system configurations. Pre-Connectathon testing falls into this category.

In this environment the Systems Configuration tool is used to enter and maintain your configurations. From this tool you can create, edit and delete a system configuration.

Managing system configurations at Connectathon

Here is where things get a little more complicated.

All system configurations are entered into Gazelle before the event. If there are errors in these configurations they are fixed in Gazelle. Toolkit gets these configurations by loading them from Gazelle. We do not edit system configurations in toolkit at Connectathon.

If you have to update your system configuration after the start of Connectathon...

1. Edit the configuration in Gazelle
2. Make sure the item is labeled approved. Only approved items are loaded into toolkit.
3. In toolkit open the System Configuration tool.
4. Select your system.
5. Click the Reload from Gazelle button.
6. Review the log output generated. If there are errors the fix your configuration in Gazelle and reload again.
7. If your test partner does not see your updated configuration in his view of toolkit, have him use the Reload systems from server button.
8. Never press the red button.

Note that both Gazelle and toolkit have their own definition of what goes into a system definition. Read the next section to see how your Gazelle system configuration will be translated into toolkit.

What goes into a System Configuration in toolkit

A Gazelle system definition and a toolkit system definition are different. A Gazelle system definition at times will generate up to 6 toolkit system definitions.

IHE profiles reuse Transaction definitions. For example both a Document Repository and a Document Recipient can accept the Provide and Register transaction. The system manager in toolkit only manages transactions. So if your system (Gazelle) contains both a Document Recipient and a Document Repository then they must be split up into two system definitions for toolkit because the Technical Framework does not require they use the same endpoint.

Gazelle defines the system name for use at Connectathon. When toolkit must split a Gazelle system into multiple toolkit systems it adds a suffix to the name. Here are the suffixes used:

- REC - Document Recipient

- ROD - Registry that accepts Register ON Demand transaction

- IDS - Imaging Document Source

- EMBED - Embedded Repository

- ODDS - On Demand Document Source

The name assigned to your system in Gazelle will be used as a toolkit system name to hold all other configurations.

When configurations are reloaded from Gazelle, choose any of the toolkit configurations that match your Gazelle system name. The suffix will be ignored. The primary toolkit system (no suffix) and all it friends (with suffix) will be updated at the same time.

##Configuring for use with Gazelle

To connect toolkit to Gazelle, go to the Toolkit configuration page and edit the Gazelle URL parameter as

 https://gazelle.ihe.net/EU-CAT/systemConfigurations.seam?testingSessionId=35

Where 35 is the event ID assigned by Gazelle.

Gazelle configurations in toolkit

System configurations are stored in the External Cache in the actors directory. Before loading up Gazelle configurations it would be good to know what local configurations exist so can avoid deleting them later when the Gazelle configurations are no longer needed. Where as Gazelle manages system configurations for each test session, toolkit does not. There is one set of system configurations.

File names used

Several special files are generated (actually downloaded from Gazelle):

AllOids.csv - list of all OIDS defined for this test session
V2Resp.csv - HL7 V2 configurations (contains info about XDS Patient Identity Feed)
Configs.csv - all system configurations. This is only used to get the list of all known systems. The actual source of system configurations is the individual system files discussed below.

These files are downloaded once and can only be updated by deleting the local file.

Next are the per-system files, labeled SYSTEMNAME.csv where SYSTEMNAME is the system name assigned by Gazelle.

Initializing

On the Toolkit configuration tool, below the properties editor, is a button to download all configurations. When this finishes, a status page will be displayed. It has very little content. While this download will grab everything it is mostly useful as a way to initialize toolkit from Gazelle. All finer operations are done on the System configuration tool.

System configuration tool

Here is listed all known system for this test session. The Update from Gazelle button is the more useful. Given a selected system, pressing it will update the configuration from Gazelle and display, in a separate tab, the detailed analysis of the conversion of Gazelle systems to toolkit systems. As discussed above this is not one-to-one. Note that with one Gazelle system translating to multiple toolkit systems, selecting any related system and requesting update will all the related toolkit systems from the appropriate Gazelle system.

When things go wrong

The files described below are all in the actors directory within the External Cache.

If the pull from Gazelle stops working consider the following:

1. Is the Gazelle Config URL in toolkit properties (Toolkit configuration tool) correct?
2. There are three system wide CSV files that are downloaded first. If one of these is damaged then everything stops working. These are AllOids.csv, Config.csv, and V2Resp.csv. If one of these is damaged then you need to restart the process (see below).
3. You will see a lot ot CSV and log.txt files. There will be a CSV file for every system defined in Gazelle. There will be a log.txt file for every CSV file that contains configurations that Toolkit can use.
4. The log page that toolkit displays when the download is run shows the contents of one or more of the log.txt files.
5. Toolkit generates the file GazelleSts.xml on startup if it does not already exist.

To restart the process

1. Assuming you have no local configurations (no system configurations generated locally) then delete the contents of the actors directory and restart the download with the Load all Gazelle configs button.
2. If you do have locally defined systems, do not delete them (unless you want to).
3. If you delete GazelleSts.xml then restart toolkit from the Tomcat console or restart Tomcat. On startup its absence will be noticed and the file recreated with the default settings.
4. If you change a configuration in Gazelle you can reload just that system by going to the System Configurations tool, selecting that system, and pressing the Reload from Gazelle button found in that tool.