Skip to content

Configuration

Jump to bottom
Sunil Bhaskarla edited this page Oct 27, 2022 · 13 revisions

There are two configuration files that can be adjusted. If everything is running on localhost and only referenced from the same machine then the delivered configuration will work.

Configuration Files

File

Location

Description

application.yaml

<installation-directory>/tomcat/HapiFhir/base/webapps/ROOT/WEB-INF/classes/application.yaml

HAPI FHIR 5.4.0 configuration properties

service.properties

<installation-directory>/tomcat/Toolkits/FhirToolkit/conf/service.properties

FHIR Toolkit service properties. Contains all of the FHIR Toolkit backend process

serviceProperties.json

<installation-directory>/tomcat/Toolkits/FhirToolkit/webapps/ROOT/serviceProperties.json

Mainly used by the FHIR Toolkit Web Interface to communicate with the FHIR Toolkit backend API API related URLs (XDS Toolkit, HAPI FHIR)

toolkit.properties

<installation-directory>/tomcat/Toolkits/XdsToolkit/conf/toolkit.properties

XDS Toolkit properties

Service Properties file

This file is located at tomcat/Toolkits/FhirToolkit/conf/service.properties. This file may need to be edited to reflect your local installation. It governs the configuration of the main Asbestos (test engine, proxy) servlet.

# TLS XdsToolkit base path should not end with a slash
tlsXdsToolkitBase=https://localhost:9773/xdstools
# Base path should not end with a slash
xdsToolkitBase=http://localhost:9770/xdstools
# Base path should not end with a slash
fhirToolkitBase=http://localhost:9760/asbestos
# Base path should not end with a slash
httpsFhirToolkitBase=https://fhirtoolkit.test:9743/asbestos
# UI can be HTTP or HTTPS. If HTTPS, a self-signed certificate must be trusted or a real certificate must be used. Home page path should not end with a slash
fhirToolkitUIHomePage=http://localhost:9760
# Fhir Toolkit Version
fhirToolkitVersion=4.1.2
# Base path should not end with a slash
hapiFhirBase=http://localhost:7080/fhir
# Base path should not end with a slash
fhirValidationServer=http://localhost:7080/fhir
# Test Patient server base. This value should be updated when running at Connectathon.
# Test Patient used by conformance tests need to exist on the patient server base,
# The channel that uses this patient server base needs its cache needs to built by
# running specific tests from the Test_Patients test collection
# patientServerBase=http://tools.iheusa.org/FHIR_RW/fhir
# MHD channel capability statement file
mhdChannelCapabilityStatementFile=capabilitystatement/mhdCapabilityStatement.xml
# startup sessionId
startUpSession=default

The following properties may be adjusted for your installation:

  • xdsToolkitBase and tlsXdsToolkitBase

  • fhirToolkitBase

  • hapiFhirBase

If you use a non-standard installation it is likely that all of these will need adjustment. The Tomcat running asbestos (proxy, test engine) must be restarted for changes to take effect.

UI Properties file

This file is located at tomcat/Toolkits/FhirToolkit/webapps/ROOT/serviceProperties.json. This is loaded by the UI code and tells it how to find the server.

{
    // localhost may be changed to the real host name of the FHIR Toolkit server
  "fhirToolkitBase": "http://localhost:9760/asbestos",
  // not currently in use
"httpsFhirToolkitUIBase": "https://fhirtoolkit.test:9743/asbestos",
    // controls the version display on the UI
  "projectVersion": "1.2.0-SNAPSHOT"
}

The Tomcat running asbestos (proxy, test engine) must be restarted for changes to take effect. The UI will need to be reloaded. You may need to clear your browser Cached Content.

External Cache

XDS Toolkit and FHIR Toolkit may share a common External Cache. If the External Cache is not shared then some consistency is required between the two Caches. Details are provided below. Most areas of the External Cache are initialized from the WAR file at system startup.

environment - used by XDS Toolkit, the file

environment/default/codes.xml

is used by FHIR Toolkit for MHD to XDS translation of codes. If two External Caches are used this file must be identical in the two Caches. The external cache used by FhirToolkit must have this file if the XDSonFHIR option is to be tested. Also, the self tests listed on the Setup page of the UI require this file.

FhirChannels - channel configurations (config.json) and logs (fhir directory). The configurations get initialized at start-up if they do not exist. When it is initialized, values get taken from the Service Properties file. The logs get collected as the tool runs. Every event through the proxy gets logged.

FhirTestAssertions - holds documentation for various test assertions.

FhirTestCollections - current Test Definitions. These are TestScript resources.

FhirTestLogs - log files generated by running the Test Definitions. These are TestReport resources.

Not running XDS Toolkit

If you are not running XDS Toolkit then the environemnt directory of the External Cache will not be initialized and message validation in FHIR Toolkit will fail. The minimum content of this directory for FHIR Toolkit to operate is:

environment/
   default/
       codes.xml

HOW-TO

Change the ExternalCache directory

The External Cache directory comes from the -DEXTERNAL_CACHE Java System Property in the

<installation-directory>/tomcat/Toolkits/FhirToolkit/bin/setenv.sh
(or `setenv.bat`).

Change FHIR Toolkit host name

The default host name used by the FhirToolkit is "localhost". This value gets reflected in the FhirToolkit Capability Statement and used in making backend API calls. To change the host name:

  • Update the relevant part of the fhirToolkitBase property in <installation-directory>/tomcat/Toolkits/FhirToolkit/webapps/ROOT/serviceProperties.json

  • Update the relevant part of the fhirToolkitBase property in <installation-directory>/tomcat/Toolkits/FhirToolkit/conf/service.properties

Change FHIR Toolkit port

The default port for the FhirToolkit web application is 9760. This value gets included in the FhirToolkit Capability Statement and used by backend API calls. To change the port, stop the Tomcat instance and:

  • Update the relevant part of the fhirToolkitBase property in <installation-directory>/tomcat/Toolkits/FhirToolkit/webapps/ROOT/serviceProperties.json

  • Update the relevant part of the fhirToolkitBase property in <installation-directory>/tomcat/Toolkits/FhirToolkit/conf/service.properties

  • Update the relevant part of the <installation-directory>/tomcat/Toolkits/FhirToolkit/conf/server.xml (Other Tomcat related ports such as 9705, 9709, 9743 are also configured in the same server.xml file.)

  • Restart Tomcat.

Setup HTTPS and TLS

Additional setup is required to make Asbestos Release run in HTTPS and TLS. What this means is only the web user interface and the Asbestos TestEngine backend servlets will be configured to use a TLS web server certificate. Asbestos Channels and Asbestos Tests still use regular HTTP (non-TLS) ports for conformance and interoperability testing purposes.

Create a Java Keystore with the web server certifcate.

If PEM files need to be converted into a Java Keystore,

Concatenate the files in this order as shown:

cat ServerCertificate.crt Intermediate.crt Root.crt private.key > fullchain.pem

Create an intermediate PKC12 to import into a new Java Keystore

openssl pkcs12 -export -in fullchain.pem -out fullchain.p12 -name example.com
keytool -importkeystore -srckeystore fullchain.p12 -srcstoretype pkcs12 -srcalias example.com -destkeystore identity.jks -deststoretype jks -deststorepass password -destalias domain.com

Confirm keystore entry

keytool -list -storepass password  -keystore  identity.jks
Keystore type: jks
Keystore provider: SUN
Your keystore contains 1 entry
domain.com, Date, PrivateKeyEntry,
Certificate fingerprint (SHA1): ...

Update FhirToolkit Tomcat server.xml

    <Connector port="9743"
        protocol="org.apache.coyote.http11.Http11NioProtocol"
        SSLProtocol="TLSv1.2"
        SSLVerifyClient="false"
        keystorePass="password"
        keystoreFile="fhirtoolkitui-certificate/identity.jks"
        sslProtocol="TLS"
        clientAuth="false"
        SSLEnabled="true"
        maxThreads="150"/>

If Apache Proxy is being used as a frontend web server proxy, some ports should be excluded due to request/response messaging problems:

    # HAPI FHIR
     ProxyPass        /asbts-fhir ajp://127.0.0.1:7709/asbts-fhir
     ProxyPassReverse /asbts-fhir ajp://127.0.0.1:7709/asbts-fhir

    # NON-TLS Asbestos proxy
    # ProxyPass        /asbestos http://127.0.0.1:9760/asbestos
    # ProxyPassReverse /asbestos http://127.0.0.1:9760/asbestos

    # NON-TLS simulators
     ProxyPass        /xdstools ajp://127.0.0.1:9779/xdstools
     ProxyPassReverse /xdstools ajp://127.0.0.1:9779/xdstools

Apache ssl.conf

    #   Point SSLCertificateFile at a PEM encoded certificate.
    SSLCertificateFile /opt/NA-2021/Asbestos/certs/ServerCertificate.crt

    #   Server Private Key:
    SSLCertificateKeyFile /opt/NA-2021/Asbestos/certs/priv.key

Service Properties file

    # TLS XdsToolkit base path should not end with a slash
    tlsXdsToolkitBase=http://localhost:9443/xdstools

    # Base path should not end with a slash
    xdsToolkitBase=http://localhost:8980/xdstools

    # Base path should not end with a slash
    fhirToolkitBase=http://real-domain.example.com:9760/asbestos

    # Only for the HTTPS UI. Base path should not end with a slash
    httpsFhirToolkitBase=https://real-domain.example.com:9743/asbestos

    # UI can be HTTP or HTTPS. If HTTPS, a self-signed certificate must be trusted or a real certificate must be used. Home page path should not end with a slash
    fhirToolkitUIHomePage=https://real-domain.example.com:9743

    # Fhir Toolkit Version
    fhirToolkitVersion=2.1.1

    # Base path should not end with a slash
    hapiFhirBase=http://localhost:7080/asbts-fhir/fhir

    # Base path should not end with a slash
    fhirValidationServer=http://localhost:7080/asbts-fhir/fhir

    # Patient server base. This value should be updated when running the Connectathon.
    # patientServerBase=http://localhost:8080/fhir/fhir
    patientServerBase=https://gazelle.ihe.net/PatientManager/fhir

    # FUTURE USE -- Empty capability statement from the HL7 FHIR site
    emptyCapabilityStatementFile=capabilitystatement/empty-capabilitystatement-base2.xml

    # MHD capability statement file
    mhdCapabilityStatementFile=capabilitystatement/capabilitystatement-fhirToolkitDocRecipientDocResponder.xml

    # MHD limited channel capability statement file
    limitedChannelCapabilityStatementFile=capabilitystatement/limitedChannelCapabilityStatement.xml

    # MHD comprehensive channel capability statement file
    xdsChannelCapabilityStatementFile=capabilitystatement/xdsChannelCapabilityStatement.xml

    # startup sessionId
    startUpSession=default

serviceProperties.json

Update httpsFhirToolkitBase to the same value in service.properties

    "httpsFhirToolkitBase": "${httpsFhirToolkitBase}",
    "fhirToolkitBase": "${fhirToolkitBase}",

Admin SignIn features requires an update to Tomcat conf\tomcat-users.xml file:

    <!-- begin FhirToolkit Channel Configuration editor authorization -->


    <role rolename="editRole"/>

    <user roles="editRole" password="easy" username="admin"/>

    <!-- end FhirToolkit -->

When Vue links do not work as expected, check this Tomcat rewrite.config file

    RewriteRule ^/about(.*)$    /index.html [L]
    RewriteRule ^/setup(.*)$    /index.html [L]
    RewriteRule ^/mhdtesting(.*)$ /index.html [L]
    RewriteRule ^/home(.*)$    /index.html [L]
    RewriteRule ^/configurations(.*)$    /index.html [L]
    RewriteRule ^/session(.*)$    /index.html [L]
    RewriteRule ^/script(.*)$     /index.html [L]
Clone this wiki locally