Installation Guide v4.3.0

Table of Contents

• Release Distribution Contents
• Overview
  • asbestos.zip
  • docker.zip
• System Requirements
  • NIST FHIR Toolkit Ports
  • XDS Toolkit Ports
  • HAPI FHIR JPA Server
• Terms
• Installation
• Configuration
• Starting FHIR Toolkit
  • Starting FHIR Toolkit the easy way
  • On Windows 10
  • Launching FHIR Toolkit UI
• Advanced installation options
• HL7 HAPI FHIR
• The version of the HAPI FHIR that was used to test FHIR Toolkit can be found here
• The Default External Cache Location

Release Distribution Contents

The asbestos.zip file contains a Tomcat Application Server bundled with the following Java Web Applications:

• FHIR Toolkit (based on HL7 FHIR v4 Resources, Asbestos proxy channels, Asbestos FHIR TestEngine, and Web UI)

• XDS Toolkit v7.12.0 (needed for testing MHD XDSonFHIR option)

• HAPI FHIR JPA Server v5.4.0

Of these elements, XDS Toolkit is optional. It is only required if the IHE MHD (XDSonFHIR) options are used for testing. In the future its installation will be optional.

The docker.zip file is a supplement to the release distribution, it contains a Dockerfile and specialized configuration parameters. At the moment only system administrators are expected use the docker.zip file. Basic installation of Asbestos does not require setting up of docker.zip.

Overview

asbestos.zip

The asbestos.zip file contains a full installation of Tomcat pre-loaded with the toolkit components.

While there is one Tomcat Home there are several Tomcat Bases (independent runtime configuration of Tomcat instances). The overall contents look like:

asbestos/
   tomcat/
      bin/
          start.sh            Starts entire tool
          start.bat
          stop.sh             Shuts down entire tool
          stop.bat
      HapiFhir/
               base           The HAPI FHIR JPA Starter Web Application base
      Toolkits/
          ExternalCache/      External Cache shared between XDS Toolkit and FHIR Toolkit
                              All internal tools auto-configure to use it
          FhirToolkit/
              conf/
                  service.properties   Controlling properties file for server
              webapps/
                  asbestos    FHIR Toolkit WAR
                  ROOT/
                      serviceProperties.json   Secondary properties file for UI
          XdsToolkit/
              webapps/
                   xdstools/  XDS Toolkit

docker.zip

docker/                    This directory contains service properties to be used by system administrators only
       Dockerfile
       service.properties
       serviceProperties.json
       start.sh

System Requirements

At least Java 16 should be installed and accessible through your system shell environment or command prompt. The system should also meet requirements to run Apache Tomcat Server Version 9.0.26. At least one of these environment variables is needed to run this program: JAVA_HOME or JRE_HOME. The following system ports should be available and free to use:

NIST FHIR Toolkit Ports

Port	Used by
9705	Tomcat Shutdown port
9709	AJP
9743	TLS* **
9760	HTTP

XDS Toolkit Ports

Port	Used by
5000-5035	PIF Listener port range
8297	Proxy Port
9770	HTTP
9773	TLS *
9775	Tomcat Shutdown port
9779	AJP

HAPI FHIR JPA Server

Port	Used by
7705	Tomcat Shutdown port
7080	HTTP
7081	TLS *

* TLS requires additional setup, please see https://github.com/usnistgov/asbestos/wiki/Configuration.

** Asbestos TestScript Debugger feature requires TLS configuration.

Terms

Term	Description
CATALINA_HOME	The Tomcat installation directory.
CATALINA_BASE	The CATALINA_BASE environment variable specifies location of the root directory of the "active configuration" of Tomcat. See tomcat/RUNNING.txt for more details on CATALINA_BASE. Each type of Toolkit (FHIR, XDS) makes use of a dedicated CATALINA_BASE.
FHIR Toolkit	NIST FHIR Toolkit is used for the IHE MHD profiles and FHIR testing.
XDS Toolkit	NIST XDS Toolkit is used for the IHE XDS profiles.

Installation

Unzip the asbestos.zip contents to a directory of your choice. The full path of the directory to which the ZIP file was extracted will be referred to as <installation-directory>. In the references below, you will have to replace <installation-directory> with the directory location of the folder where the ZIP file was extracted.

Configuration

See https://github.com/usnistgov/asbestos/wiki/Configuration.

Starting FHIR Toolkit

Starting FHIR Toolkit the easy way

We have installed two custom scripts in tomcat/bin. The scripts will start HAPI FHIR, XDS Toolkit, and FHIR Toolkit (in that order).

On *nix

Script	Java Runtime	Description
start.sh	Java 16 or above	To start the HapiFhir, XDSToolkit base, and the FhirToolkit base (in that order).
stop.sh		to stop all components

On Windows 10

Batch file	Java Runtime	Description
start.bat	Java 16 or above	To start the HapiFhir, XDSToolkit base, and the FhirToolkit base (in that order). Note: start.bat must be typed along with the .bat file extension.
stop.bat		To stop all components

Launching FHIR Toolkit UI

To launch the UI for FHIR Toolkit, open a Web browser to http://localhost:9760/

Setup

Once FHIR Toolkit is open, navigate to the Setup page and run the necessary tests according to the instructions on the Setup page. NOTE: It is necessary to run Test Patients against the default Test Session’s default channel prior to running any of the MHD tests.

IMPORTANT:

When configuring a FHIR Toolkit channel for a SUT, please select the IHE MHD version. There are three choices available: MHDv3.x, MHDv4, MHDv410, MHDv420. The default is MHDv3.x. The FHIR Toolkit release number 4.3.0 is independent of the IHE MHD profile version and has no relation to profile version.

Advanced installation options

In the above default configuration, FHIR Toolkit, HAPI, XDS Toolkit and the user’s browser are all running on one machine and all references between system components are through localhost. FHIR Toolkit can be installed and configured with all the Tomcat services in different instances of Tomcat on different machines and the UI running through a real hostname.

There are currently two sources for configuration information: the HOW-TO section below and https://github.com/usnistgov/asbestos/wiki/Configuration. These will be combined in the future.

HL7 HAPI FHIR

HAPI FHIR is used for encoding and decoding FHIR v4 Resources. Test patients are stored on the JPA server.

https://hapifhir.io/

The version of the HAPI FHIR that was used to test FHIR Toolkit can be found here

• https://github.com/hapifhir/hapi-fhir-jpaserver-starter/releases

• You may need to update the FHIR Toolkit service.properties file to reflect the FHIR Base URL that is in use.

The Default External Cache Location

The default ExternalCache location for all Toolkits is <installation-directory>/tomcat/Toolkits/ExternalCache

HL7®, HEALTH LEVEL SEVEN®, FHIR® and the FHIR Logo ® are trademarks owned by Health Level Seven International, registered with the United States Patent and Trademark Office.

Sun, the Sun logo, Sun Microsystems, Solaris, HotJava, and Java are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and certain other countries.