Installing ICE

Owned by Michael J. Suralik
Last updated: Aug 20, 2024 by Daryl
Table of Contents

Installing the ICE Web Service


Version 2 was released on August 19th, 2024 and runs Tomcat 10, under the latest version of Java 17. It does not run under earlier versions of Tomcat or Java 21.

Version 1 runs under Tomcat 7 and Tomcat 9, running under the latest version of Java 8.


To install ICE using one of the downloadable distributions, you will need two things:

The installation steps described below apply to the zipfile distribution. Many of the settings are also used by the docker image - see the Docker Hub page for details.

  1. Install the appropriate version of the Apache Tomcat Web Server or identify an existing instance of Tomcat.
    1. Suggested JVM setting for tomcat: -Xms512m -Xmx2560m

  2. Download the binary distribution for the most recent ICE release. (Alternatively, you may build an ICE executable from the source code which has been made available under the GNU LGPL v3 license).
    1. Unzip the zip file into the Tomcat webapp directory.

    2. Edit opencds/opencds-parent/opencds.properties to suit your installation
      1. Set km.threads to specify the number of threads allocated to each knowledgeModule.
        1. Best practice has shown that km.threads should be set between 1 to 2 times the number of CPUs (or CPU cores) available

      2. Set knowledge-repository.path to the location of the ICE knowledge repository as follows: /path/to/opencds-ice-service-data/src/main/resources.

        1. For Windows path locations, specify the drive letter and use forward slashes. (e.g. - C:/path/to/opencds-ice-service-data/src/main/resources)
      3. Set the log4j.logfile property to a location writable by the Tomcat instance

    3. Copy opencds.properties to the appropriate location where it can be found by the Tomcat server, as follows:
      1. For Linux/MacOS: $HOME/.opencds/, where $HOME is the "home" directory of the application server instance.  (NOTE: If installed as a service started at boot, the configuration must live under the $HOME (as defined in /etc/passwd) of the user that starts the container.  E.g., if OpenCDS is running on tomcat as run by the system init scripts, and is run by the tomcat user, the properties must live under the tomcat $HOME as defined in /etc/passwd, which is typically /home/tomcat or something similar.)
      2. For Windows: %HOME%\.opencds\opencds.properties. (NOTE: If OpenCDS is running on tomcat as a service on a Windows system, the configuration will likely have to live at the root (i.e., C:\.opencds\opencds.properties), as there is no default user.)

    4. In the ICE distribution directory, use a text editor to modify the WEB-INF/classes/ice.properties to log to your deployment directory.
      1. Set ice_knowledge_repository_location to the same location as knowledge-repository.path of opencds.properties file.
        1. For Windows path locations, specify the drive letter and use forward slashes. (e.g. - C:/path/to/opencds-ice-service-data/src/main/resources)
      2. Do not edit any of the other properties listed in the file.

    5. In the ICE distribution directory, use a text editor to modify the WEB-INF/classes/log4j.properties to log to your deployment directory.
      1. For Windows path locations, specify the drive letter and use forward slashes. (e.g. - C:/path/to/logfile.log)

    6. Start up Tomcat
      1. The service WSDL will be available from the url: http(s)://hostname:port/opencds-decision-support-service/evaluate?wsdl
      2. The endpoint will be: http(s)://hostname:port/opencds-decision-support-service/evaluate

Integrating with the ICE Web Service

Interface

  1. Implementation Guide for Integrating with ICE - Download this very important document to learn how to integrate a clinical information system with the ICE Web Service.
  2. Download the WSDL files.
  3. All messages to and from the ICE service conform to version 1.0 of the vMR. The vMR 1.0 XML Schema Definition files are required for client application development. In addition, the vMR Domain Analysis Model, Release 1 may be useful in understanding the elements of the vMR and how they are related. These documents and additional supporting documentation are posted on the Downloads page.
  4. See ICE Output Tips and Tricks for other options.

Source Code

Sample ICE client source code is available to make it easier for developers to integrate their clinical information systems with ICE. The source code for those ICE clients are located here:


The ICE server source code is available on GitHub. See Building ICE from Source Code for more information.