NLP cTAKES Project
Space shortcuts
Space Tools

Informatics for Integrating Biology and the Bedside






i2b2 Installation Guide

c linical T ext A nalysis and K nowledge E xtraction S ystem





Document Version:


I2b2 Software Release:




Table of Contents

Document Management

About this Guide

1. Prerequisites

1.1 Required Software

1.1.1 First Required Software

1.1.2 Second Required Software

2. Install

2.1 Installing the cTAKES GUI

2.1.1 Download and Extract Package

2.1.2 Verify app is running

2.1.3 Running a test experiment

2.1.4 Configuring custom Input and Output Data Sources

2.2 Loading the ontology



Document Management


Revision Number



Description of change



Pei J. Chen

Initial Draft







About this Guide

This guide is intended to walk you through the installation of the cTAKES GUI and populating an additional ontology for querying NLP concepts via the web client.

This installation guide assumes you are familiar with Java and Tomcat Servlet Containers.  [There will be a self-executable bundled with Jetty in the very near future.]

It has been tested on Java6, Tomcat 5.5/7.0 and i2b2 1.6 with MSSQL.  It should work on others platforms, but we have not tested and verified yet.

Note: The cTAKES GUI was designed to output the data in the i2b2 format.  However, it can also be run as a stand-alone UI where the data could be outputted to other RDMS or its embedded DB where it could be queried via standard SQL.



  1.   P rerequisites
    1.          Required Software

Java 1.6 or above

Apache Tomcat 5.5 or above

1.1.1         First Required Software

If you do not already have the Java Runtime Environment, you can download it at: (Currently tested with JRE SE 6)

  1. Follow the installation instructions for installing JRE:
    1.      Second Required Software

If you do not already have an instance of Tomcat, you can download and install it at:
(Currently tested with Tomcat 7.0)

  1. Follow the installation instructions for  installing Tomcat:
  2. Be sure to modify the environment variables in setclasspath.bat or .sh:

set "JRE_HOME=%ProgramFiles%\Java\jre6"

set "JAVA_OPTS=%JAVA_OPTS% -Xms500M -Xmx1024M"

set "CLASSPATH=%CLASSPATH%;%CATALINA_HOME%\resources\cTAKES\dictionary lookup\lib\hsqldb_1_8_0_10.jar" (Note: This is only needed for older versions of tomcat such as 5.5.  Later version such as 7.0 will pick this up from the webapp/WEB-INF/lib automatically.)

  1.   Install
    1.          Installing the cTAKES GUI
      1.      Download and Extract Package

Unpack the zip file from [Add link to download directory here].

Within the package, there should be a war file (ctakes-gui-{version}.war), and a resources folder.

Steps :

  1. Copy the resources folder into your TOMCAT_HOME/bin/resources directory (Or local to wherever Tomcat is being started from).  Be sure to grant write access to the resources (and /db) directory to public or the user running tomcat.
  2. Deploy the ctakes-gui-{version}.war to the webapps directory as ctakesgui.war
  3. Startup Tomcat by executing TOMCAT_HOME/bin/startup.bat or
    1.      Verify app is running

Once the web application has been successfully deployed, you should be able to launch a new browser and point it to the http://{hostname}:{port}/ctakesgui .
If you do not get the login screen, it is most likely that the webapp was not deployed properly.  Check the TOMCAT_HOME/logs/catalina log files for any errors (ensure that all the jars/libs have been included in the classpath).

For example:


2.1.3         Running a test experiment

  • Click on ‘Login with admin’
  • Create New Experiment…
  • Enter in a Name and Description
  • Click Save and Run

There already is a test dummy note bundled in the Sample i2b2 input database.  To verify that the pipeline has successfully been executed.  Click on the results link, and you should see the full extracted results in a generic name-value pair format.

Note: The app was designed to be executed asyncrously.  Feel free to check the servlet container logs for current status of processing.

2.1.4         Configuring custom Input and Output Data Sources

  • Click on Data Sources from the left navigation menu
  • Create New or Modify the existing sample Data Source

  • Fill in the required information
  • After you have saved you custom data sources, you could create a new experiment and run using them now:

  • The output should be redirected to the new destination.
  • Verify the contents of the destination table via your SQL client of choice such as MS SQL Server Management Studio or Oracle client.

Note: MSSQL 2005 drivers and hsqldb drivers have been prebundled.  If you require other JDBC drivers, be sure to include them in the WEB-INF/lib or tomcat’s classpath.

2.2              Loading the ontology

To mimic the supported ontology, perform and DB import to the ontology table from the ctakes-nlp-ontology.csv file [Add Link to file here].

If you require building a custom ontology, feel free to use the i2b2 related project:

Which we used to subset SNOMED CT, RxNorm to build the Ontology used for the NLP tools.

After the ontology has been loaded and configured: Your web client should look like the following:




* Copyright: (c) 2012  Children's Hospital Boston


* Except as contained in the copyright notice above, or as used to identify

* MFMER as the author of this software, the trade names, trademarks, service

* marks, or product names of the copyright holder shall not be used in

* advertising, promotion or otherwise in connection with this software without

* prior written authorization of the copyright holder.


* Licensed under the Apache License, Version 2.0 (the "License");

* you may not use this file except in compliance with the License.

* You may obtain a copy of the License at




* Unless required by applicable law or agreed to in writing, software

* distributed under the License is distributed on an "AS IS" BASIS,


* See the License for the specific language governing permissions and

* limitations under the License.