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 latest release of ICE - either the binary (zipfile) distribution or the docker image from Docker Hub.
The Implementation Guide for Integrating with ICE. (A "track changes" version of this same guide - highlighting what has changed since the last version of the guide - is also available.)

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.

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
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

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.
Download the WSDL files.
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.
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.

Browser not supported