> ![](media/image1.png){width="1.0673611111111112in"
> height="1.0416666666666667in"}
>
> ![](media/image2.png){width="2.6215277777777777in"
> height="1.5680555555555555in"}

![](media/image3.wmf)

**Table of Contents**

[Introduction 1](#introduction)

[Overview of caAdapter 1](#overview-of-caadapter)

[caAdapter 1.2 Tested Platforms 1](#caadapter-1.2-tested-platforms)

[caAdapter Software Requirements 2](#caadapter-software-requirements)

[Required Software---Not Included in caAdapter
2](#required-softwarenot-included-in-caadapter)

[Required Software for Source Distribution---Not Included in caAdapter
3](#required-software-for-source-distributionnot-included-in-caadapter)

[Upgrading to caAdapter 1.2 from Previous HL7 SDK Versions\*
4](#upgrading-to-caadapter-1.2-from-previous-hl7-sdk-versions)

[Downloading caAdapter 4](#__RefHeading___Toc125935283)

[Installing caAdapter 5](#installing-caadapter)

[Installing the Source and Binary Distributions
5](#installing-the-source-and-binary-distributions)

[Installing the Windows Distribution
5](#installing-the-windows-distribution)

[Updating the Installation 6](#updating-the-installation)

[Obtaining HMD Files 6](#obtaining-hmd-files)

[Reviewing Appropriate Licenses 6](#reviewing-appropriate-licenses)

[JavaSIG License 6](#javasig-license)

[Common Terminology Services (CTS) License
6](#common-terminology-services-cts-license)

[Verifying Installation 7](#verifying-installation)

[Verifying Binary Installation 7](#verifying-binary-installation)

[Verifying Source Installation 7](#verifying-source-installation)

[Verifying Windows Installation 7](#verifying-windows-installation)

[Contacting Technical Support 8](#contacting-technical-support)

[NCICB Application Support 8](#ncicb-application-support)

####  {#section .unnumbered}

## Introduction 

This installation guide outlines the supported configurations and
technical installation instructions for caAdapter 1.2. Directions for
validating the caAdapter installation are also included.

+-------------+--------------------------------------------------------+
| #####       | The caAdapter consists of a technical architecture and |
|  Overview o | a tool                                                 |
| f caAdapter | (<http://trials.                                       |
|             | nci.nih.gov/projects/infrastructureProject/caadapter>) |
|             | to support data sharing via the HL7 version 3 (v3)     |
|             | messaging standard at National Cancer Institute Center |
|             | for Bioinformatics (NCICB)                             |
|             | (                                                      |
|             | [http://ncicb.nci.nih.gov](http://ncicb.nci.nih.gov/)) |
|             | or any cancer center as part of the cancer Biomedical  |
|             | Informatics Grid (caBIG)                               |
|             | (                                                      |
|             | [http://caBIG.nci.nih.gov](http://cabig.nci.nih.gov/)) |
|             | solution.                                              |
|             |                                                        |
|             | The caAdapter facilitates HL7 v3 message building,     |
|             | parsing and validation. It offers an open source       |
|             | platform for enabling healthcare applications to build |
|             | and parse HL7 v3 messages based on specific message    |
|             | definitions. The caAdapter provides the capability to  |
|             | perform vocabulary validation and integrates with      |
|             | NCICB cancer Common Ontologic Representation           |
|             | Environment (caCORE) components                        |
|             | (<http://ncicb.nci.nih.gov/NCICB/infrastructure>).     |
|             | This supports NCICB's mission of developing a          |
|             | translational research infrastructure and building a   |
|             | clinical research network by providing a common        |
|             | platform for sharing data.                             |
|             |                                                        |
|             | > The caAdapter Mapping Tool provides users a          |
|             | > graphical user interface (GUI) and a runtime engine  |
|             | > to map and convert clinical data in various incoming |
|             | > formats to an equivalent target HL7 v3 XML. For more |
|             | > information about the caAdapter, see the *caAdapter  |
|             | > 1.2 User\'s Guide*.                                  |
+-------------+--------------------------------------------------------+

## caAdapter 1.2 Tested Platforms

Table 1 contains the system platforms and their requirements that
caAdapter 1.2 has been tested on at NCICB.

+----------------+-------------------------+--------------------------+
|                | NCICB Windows Server    | NCICB Linux App Server   |
+================+=========================+==========================+
| Model          | DELL Optiplex GX270     | HP Proliant ML 330       |
+----------------+-------------------------+--------------------------+
| CPU            | 1 x Intel® Pentium™     | 1 x Intel® Xeon™         |
|                |                         | Processor 2.80 GHz       |
|                | 2.8 GHz                 |                          |
+----------------+-------------------------+--------------------------+
| Memory         | 1.3 GB                  | 4 GB                     |
+----------------+-------------------------+--------------------------+
| Local Disk     | System = 40 GB          | System = 2 x 36 GB       |
|                |                         | (RAID 1)                 |
|                |                         |                          |
|                |                         | Data = 2 x 146 (RAID 1)  |
+----------------+-------------------------+--------------------------+
| Network        | 100mb / full duplex     | 100mb / full duplex      |
+----------------+-------------------------+--------------------------+
| OS             | Windows 2000            | Red Hat Linux ES 3       |
|                | Professional            |                          |
+----------------+-------------------------+--------------------------+
| Resolution     | 1280 x 1024             | 1600x1200                |
|                |                         |                          |
| (Recommended)  | 1024 x 768              | 1400x1050                |
|                |                         |                          |
|                |                         | 1280x960                 |
|                |                         |                          |
|                |                         | 1280x864                 |
+----------------+-------------------------+--------------------------+
| Resolution     | 800 x 600               | 800 x 600                |
|                |                         |                          |
| (NOT           | 640 x 480               | 640 x 480                |
| Recommended)   |                         |                          |
+----------------+-------------------------+--------------------------+

Table 1 caAdapter Tested Platforms

## caAdapter Software Requirements

+-------------+--------------------------------------------------------+
| ##### R     | > You must download and install Java that is not       |
| equired Sof | > included with caAdapter. Table 2 contains detailed   |
| tware---Not | > information on the software and URL hyperlinks (for  |
|  Included i | > download). The version is in accordance with the     |
| n caAdapter | > NCICB technology stack.                              |
+-------------+--------------------------------------------------------+

+----------------+---------+----------------------------+--------------+
| Software Name  | Version | Description/URL            | Example      |
|                |         |                            | Directory    |
+================+=========+============================+==============+
| Java 2         | 1       | The J2SE Software          | If your root |
| Platform       | .5.0_04 | Develop­ment Kit (SDK)      | directory in |
| Enterprise     |         | supports creat­ing J2SE     | Windows is   |
| Edition (J2EE) |         | applications               | C:\\, then   |
| or Standard    |         |                            | install to   |
| Edition (J2SE) |         | <                          | the          |
|                |         | http://java.sun.com/j2se/> | C:\          |
|                |         |                            | \jdk1.5.0_04 |
|                |         |                            | Java home    |
|                |         |                            | directory    |
+----------------+---------+----------------------------+--------------+

Table 2 Required software for all caAdapter distributions

Verify the JAVA_HOME environment variable is set and add it to your
PATH. Perform the following steps to do this in Windows:

+--------+-------------------------------------------------------------+
| Step   | Action                                                      |
+========+=============================================================+
| 1      | Right click **My Computer \> Properties** and select the    |
|        | **Advanced** tab.                                           |
+--------+-------------------------------------------------------------+
| 2      | Click the **Environment Variables** button.                 |
+--------+-------------------------------------------------------------+
| 3      | **JAVA_HOME** must each be listed in the **User variables** |
|        | or **System variables** dialog box. To add either, click    |
|        | the **New** button below one of the panels.                 |
+--------+-------------------------------------------------------------+
| 4      | In the **New User Variable** dialog box, add the            |
|        | **Variable** and **Variable Value** for your home           |
|        | directory.                                                  |
|        |                                                             |
|        | Examples:                                                   |
|        |                                                             |
|        | **Variable** = ***JAVA_HOME***; **Variable Value** =        |
|        | ***C:\\jdk1.5.0_04***                                       |
+--------+-------------------------------------------------------------+
| 5      | Find the **PATH** environment variable, double click it or  |
|        | click the **Edit** button and add ***%JAVA_HOME%\\bin*** to |
|        | the end of its value. Click all **OK** buttons to confirm   |
|        | the changes.                                                |
+--------+-------------------------------------------------------------+
| 6      | To verify that the **PATH** statement listed in the         |
|        | **Environment Variables** dia­log box includes               |
|        | **JAVA_HOME**, open a command window (**Start \> Command    |
|        | Prompt**). Type ***path*** at the prompt and hit **enter**  |
|        | to display your path. For example, ***C:\\jdk1.5.0_04***    |
|        | should be at the end of your path. If you were successful,  |
|        | you can run java anywhere in your system.                   |
+--------+-------------------------------------------------------------+

+-------------+--------------------------------------------------------+
| ##### Req   | > If you are installing source code, you must download |
| uired Softw | > and install Ant that is not included with caAdapter. |
| are for Sou | > Table 3 contains detailed information on the         |
| rce Distrib | > software and URL hyperlinks (for download). The      |
| ution---Not | > version is in accordance with the NCICB technology   |
|  Included i | > stack.                                               |
| n caAdapter |                                                        |
+-------------+--------------------------------------------------------+

+----------------+---------+----------------------------+--------------+
| Software Name  | Version | Description/URL            | Example      |
|                |         |                            | Directory    |
+================+=========+============================+==============+
| Ant            | 1.6.2   | Apache Ant is a Java-based | If your root |
|                |         | build tool                 | directory in |
|                |         |                            | Windows is   |
|                |         | <http://ant.apache.org/>   | C:\\, then   |
|                |         |                            | install to   |
|                |         |                            | C:\\apac     |
|                |         |                            | he-ant-1.6.2 |
|                |         |                            | Ant home     |
|                |         |                            | directory    |
+----------------+---------+----------------------------+--------------+

Table 3 Required software for caAdapter source distribution

Verify the ANT_HOME environment variable is set and add it to your PATH.
Perform the following steps to do this in Windows:

+--------+-------------------------------------------------------------+
| Step   | Action                                                      |
+========+=============================================================+
| 1      | Right click **My Computer \> Properties** and select the    |
|        | **Advanced** tab.                                           |
+--------+-------------------------------------------------------------+
| 2      | Click the **Environment Variables** button.                 |
+--------+-------------------------------------------------------------+
| 3      | **ANT_HOME** must each be listed in the **User variables**  |
|        | or **System variables** dialog box. To add either, click    |
|        | the **New** button below one of the panels.                 |
+--------+-------------------------------------------------------------+
| 4      | In the **New User Variable** dialog box, add the            |
|        | **Variable** and **Variable Value** for your home           |
|        | directories.                                                |
|        |                                                             |
|        | Examples:                                                   |
|        |                                                             |
|        | **Variable = *ANT_HOME*; Variable Value =                   |
|        | *C:\\apache-ant-1.6.2***                                    |
+--------+-------------------------------------------------------------+
| 5      | Find the **PATH** environment variable, double click it or  |
|        | click the **Edit** button and add ***%ANT_HOME%\\bin*** to  |
|        | the end of its value. Click all **OK** buttons to confirm   |
|        | the changes.                                                |
+--------+-------------------------------------------------------------+
| 6      | To verify that the **PATH** statement listed in the         |
|        | **Environment Variables** dia­log box includes **ANT_HOME**, |
|        | open a command window (**Start \> Command Prompt**). Type   |
|        | ***path*** at the prompt and hit **enter** to display your  |
|        | path. For example, ***C:\\apache-ant-1.6.2\\bin*** should   |
|        | be at the end of your path. If you were successful, you can |
|        | run ant anywhere in your system.                            |
+--------+-------------------------------------------------------------+

## Upgrading to caAdapter 1.2 from Previous HL7 SDK Versions\*

+------------+---------------------------------------------------------+
| ![](media/ | \*All users of previous HL7 SDK versions are encouraged |
| image4.wmf | to upgrade to the caAdapter 1.2. This release fixes     |
| ){width="0 | some important bugs and includes the caAdapter Mapping  |
| .594444444 | Tool graphical user interface (GUI).                    |
| 4444444in" |                                                         |
| height="0  | -   It is recommended to uninstall any previous         |
| .59375in"} |     versions of HL7 SDK before following the procedures |
|            |     to install caAdapter 1.2.                           |
| HL7 SDK    |                                                         |
| Users      |                                                         |
| Upgrading  |                                                         |
| to         |                                                         |
| caAdapter  |                                                         |
| 1.2        |                                                         |
+------------+---------------------------------------------------------+

## Downloading caAdapter

> Complete the following steps to download caAdapter:

+--------+-------------------------------------------------------------+
| Step   | Action                                                      |
+========+=============================================================+
| e.     | Go to the NCICB download web site                           |
|        | <http://ncicb.nci.nih.gov/download/index.jsp>.              |
| 1      |                                                             |
+--------+-------------------------------------------------------------+
| f.     | Provide your email, name, and institution. Click **Enter    |
|        | the Download Center**.                                      |
| 2      |                                                             |
+--------+-------------------------------------------------------------+
| g.     | Select **caAdapter** and agree to the caAdapter software    |
|        | licenses by selecting **Checking this box indicates that    |
| 3      | you agree to the above terms**.                             |
+--------+-------------------------------------------------------------+
| h.     | Select the appropriate distribution as listed below and     |
|        | save it to a temporary directory on your computer (for      |
| 4      | example, C:\\temp in Windows). Each type of distribution    |
|        | has files with (w) or without (wo) Hierarchical Message     |
|        | Definition (HMD) files.                                     |
|        |                                                             |
|        | +---------------+---------------------------------------+   |
|        | | NOTE:         | You MUST be a member of HL7 to choose |   |
|        | |               | the files with HMDs. See Obtaining    |   |
|        | | ![](medi      | HMD Files on page                     |   |
|        | | a/image5.wmf) | [6](#obtaining-hmd-files) for more    |   |
|        | |               | information.                          |   |
|        | +---------------+---------------------------------------+   |
|        |                                                             |
|        | -   **Binary Distribution**:  The caAdapter binary          |
|        |     distribution file contains the binary code for          |
|        |     caAdapter and HL7 JavaSIG software, Javadocs for        |
|        |     caAdapter and HL7 JavaSIG code, Release Notes, HL7      |
|        |     message schemas, example messages, and licenses.        |
|        |                                                             |
|        |   -------------------------- ------------------------------ |
|        |   Binary Zip File Name       Description                    |
|        |                                                             |
|        |   caadapterv1.2_bin_w.zip    Binary file with HL7 HMD files |
|        |                                                             |
|        |   caadapterv1.2_bin_wo.zip   Binary file without HL7 HMD    |
|        |                              files                          |
|        |   -------------------------- ------------------------------ |
|        |                                                             |
|        | -   **Source Distribution:  The caAdapter source            |
|        |     distribution file contains the source java code for     |
|        |     caAdapter and HL7 JavaSIG software, Javadocs for        |
|        |     caAdapter and HL7 JavaSIG code, Release Notes,          |
|        |     readme.txt, HL7 message schemas, example messages, and  |
|        |     licenses.**                                             |
|        |                                                             |
|        |   -------------------------- ------------------------------ |
|        |   Source Zip File Name       Description                    |
|        |                                                             |
|        |   caadapterv1.2_src_w.zip    Source file with HL7 HMD files |
|        |                                                             |
|        |   caadapterv1.2_src_wo.zip   Source file without HL7 HMD    |
|        |                              files                          |
|        |   -------------------------- ------------------------------ |
|        |                                                             |
|        | **Windows Distribution**:  The caAdapter windows            |
|        | distribution file contains binary code for caAdapter and    |
|        | HL7 JavaSIG software, Javadocs for caAdapter and HL7        |
|        | JavaSIG code, Release Notes, readme.txt, HL7 message        |
|        | schemas, example messages, and licenses.                    |
|        |                                                             |
|        |   ------------------------- ------------------------------  |
|        |   Binary Zip File Name      Description                     |
|        |                                                             |
|        |   caadapterv1.2_w.msi       Windows file with HL7 HMD       |
|        |                             files                           |
|        |                                                             |
|        |   caadapterv1.2_wo.msi      Windows file without HL7 HMD    |
|        |                             files                           |
|        |   ------------------------- ------------------------------  |
+--------+-------------------------------------------------------------+

## Installing caAdapter

> Complete the appropriate steps for your distribution to install
> caAdapter.

+-------------+--------------------------------------------------------+
| ##### Ins   | > Extract the contents of the caAdapter source or      |
| talling the | > binary distribution zip file to your root directory. |
|  Source and | > For example, if your root direc­tory in Windows is    |
|  Binary Dis | > C:\\, then your caAdapter home directory becomes     |
| tributions  | > C:\\caadapter. (**Note**: The caadapter directory is |
|             | > created for you.) Table 4 contains the directory     |
|             | > structure after installation.                        |
+-------------+--------------------------------------------------------+

+-------------+--------------------------------------------------------+
| ##### In    | > Double-click on the .msi file and follow the         |
| stalling th | > instructions provided to complete installation.      |
| e Windows D | > Table 4 contains the directory structure after       |
| istribution | > installation.                                        |
+-------------+--------------------------------------------------------+

  -----------------------------------------------------------------------
  Directory                Contents
  ------------------------ ----------------------------------------------
  build                    Binaries (.class files) (only for source
                           distribution and is created at runtime)

  etc                      Important supplementary files

  hmd                      HL7 HMD files (you must manually create if
                           your distribution did not include HMDs)

  images                   Images used by the GUI

  lib                      Java libraries and dependencies

  license                  License and legal information

  schema                   HL7 v3 Schema files

  src                      Source code (.java files) (only for source
                           distribution)

  workingspace             Default directory where you can save project
                           files. It contains log files and HL7 v3 XML
                           instances. It also contains an examples
                           directory with sample data.
  -----------------------------------------------------------------------

Table 4 Directory Structure of caAdapter

## Updating the Installation

+-------------+--------------------------------------------------------+
| ###         | > If your distribution did not include HMD files, then |
| ## Obtainin | > you must update your home directory to include the   |
| g HMD Files | > \\hmd directory, (for example:                       |
|             | > C:\\caadapter\\hmd)and download the HMD files.       |
|             | >                                                      |
|             | > HMD files (in XML format, ending in .hmd) are needed |
|             | > to run the parser and builder. You can download the  |
|             | > HMD files from                                       |
|             | > [**h                                                 |
|             | ttp://www.hl7.org/Special/committees/java/index.cfm**] |
|             | (http://www.hl7.org/Special/committees/java/index.cfm) |
|             | > . You MUST be a member of HL7 to access and download |
|             | > these files. Login using your HL7 username and       |
|             | > password (<http://www.hl7.org/>). Then select the    |
|             | > **Technical Committees** link from the community     |
|             | > section of the main HL7 page. Follow the **Special   |
|             | > Interest Groups** link to the Java SIG page. A link  |
|             | > to download the HMD files is available under **Work  |
|             | > Products** on this page.                             |
+-------------+--------------------------------------------------------+

## Reviewing Appropriate Licenses

+-------------+--------------------------------------------------------+
| ##### Java  | > The JavaSIG is an HL7 Special Interest Group whose   |
| SIG License | > goal is to define an Application Programming         |
|             | > Interface (API) for HL7 v3 artifacts. They have      |
|             | > developed an open source software package which      |
|             | > contains an XML parser and builder as well as RIM    |
|             | > and datatype objects. See the                        |
|             | >                                                      |
|             | > JavaSIG website                                      |
|             | > (<                                                   |
|             | http://www.hl7.org/Special/committees/java/index.cfm>) |
|             | > for more details.                                    |
+-------------+--------------------------------------------------------+

+-------------+--------------------------------------------------------+
| ###         | > CTS is an API specification that is intended to      |
| ## Common T | > describe the basic functionality that is needed by   |
| erminology  | > HL7 v3 software implementations to query and access  |
| Services (C | > terminological content. The caAdapter contains java  |
| TS) License | > interfaces that are based on this specification and  |
|             | > an implementation                                    |
|             | >                                                      |
|             | > based on this specification that accesses the        |
|             | > NCICB\'s                                             |
|             | >                                                      |
|             | > Enterprise Vocabulary Services (EVS). See the        |
|             | >                                                      |
|             | > CTS website                                          |
|             | > (<http://informatics.mayo.edu/index.php?page=11>)    |
|             | > for more details.                                    |
+-------------+--------------------------------------------------------+

## 

## Verifying Installation

> Perform the appropriate processes for your distribution to ensure the
> installation was successful.

##### Verifying Binary Installation

> Perform the following steps to launch the caAdapter Mapping Tool GUI:

+--------+-------------------------------------------------------------+
| Step   | Action                                                      |
+--------+-------------------------------------------------------------+
| i.     | In a **Command Prompt** window, enter ***cd                 |
|        | {home_directory}*** to go to your home directory (for       |
| 1      | example, in Windows C:\\caadapter).                         |
+--------+-------------------------------------------------------------+
| j.     | Enter ***java -jar caadapter_ui.jar***                      |
|        |                                                             |
| 2      |                                                             |
+--------+-------------------------------------------------------------+
| k.     | The caAdapter Mapping Tool GUI displays.                    |
|        |                                                             |
| 3      |                                                             |
+--------+-------------------------------------------------------------+

##### Verifying Source Installation

> Perform the following steps to launch the caAdapter Mapping Tool GUI:

+--------+-------------------------------------------------------------+
| Step   | Action                                                      |
+--------+-------------------------------------------------------------+
| l.     | In a **Command Prompt** window, enter ***cd                 |
|        | {home_directory}*** to go to your home directory (for       |
| 1      | example, in Windows C:\\caadapter).                         |
+--------+-------------------------------------------------------------+
| m.     | Enter ***ant compile***                                     |
|        |                                                             |
| 2      |                                                             |
+--------+-------------------------------------------------------------+
| n.     | Enter ***ant launchui***                                    |
|        |                                                             |
| 3      |                                                             |
+--------+-------------------------------------------------------------+
| o.     | The caAdapter Mapping Tool GUI displays.                    |
|        |                                                             |
| 4      |                                                             |
+--------+-------------------------------------------------------------+

##### Verifying Windows Installation

> Perform the following steps to launch the caAdapter Mapping Tool GUI:

+--------+-------------------------------------------------------------+
| Step   | Action                                                      |
+--------+-------------------------------------------------------------+
| p.     | Navigate to the **caAdapter** shortcut from the **Start**   |
|        | menu and click **caAdapter**.                               |
| 1      |                                                             |
+--------+-------------------------------------------------------------+
| q.     | The caAdapter Mapping Tool GUI displays.                    |
|        |                                                             |
| 2      |                                                             |
+--------+-------------------------------------------------------------+

> **Congratulations!** If you can view the caAdapter Mapping Tool GUI,
> your installation was successful. See the *caAdapter 1.2 User\'s
> Guide* for detailed information on using caAdapter.

## Contacting Technical Support

+-----------+----------------------------------------------------------+
| #####     | <http://ncicbsupport.nci.nih.gov/sw/>                    |
|  NCICB Ap |                                                          |
| plication | Telephone: 301-451-4384                                  |
|  Support  |                                                          |
|           | Toll free: 888-478-4423                                  |
+-----------+----------------------------------------------------------+