**caTISSUE Clinical Annotation Engine**

Release Notes

Software iteration 5: CAE 1.0 Final

University of Pittsburgh Cancer Institute

SOW caBIG-TBPT-40-04-02

April 5, 2006

TABLE OF CONTENTS

[1. Introduction 3](#introduction)

[1.1 Content of the release 3](#content-of-the-release)

[1.2 Related Documents 3](#related-documents)

[2. System Scope 4](#system-scope)

[2.1 Functionality 4](#functionality)

[2.2 Common Data Elements 4](#common-data-elements)

[3. Requirements Non-Compliance 6](#requirements-non-compliance)

[4. Issues corrected In CAE 1.0 Final Release
7](#issues-corrected-in-cae-1.0-final-release)

[5. Known Bugs in CAE 1.0 Final Release
7](#known-bugs-in-cae-1.0-final-release)

[6. System Limitations 9](#system-limitations)

[7. LOG FILE MAINTENANCE 10](#log-file-maintenance)

[APPENDIX A. ACRONYMS and abbreviations
11](#appendix-a.-acronyms-and-abbreviations)

[APPENDIX B. CAE 1.0 beta-2 Audit Functionality summary
12](#appendix-b.-cae-1.0-beta-2-audit-functionality-summary)

# Introduction

This document provides information about the functionality and
limitations of the caTISSUE Clinical Annotation Engine 1.0 software
release delivered April 6, 2006. CAE provides standards-based
annotations and tools for integrating data from existing clinical and
research systems. The Clinical Annotation Engine (CAE) is a web-based
application built using Java and a number of NCI-developed applications.

Incorporated in this release is support for annotations relating to
three disease types: Prostate, Breast and Melanoma cases. Supported
annotations sets were derived from the College of American Pathologists
(CAP) checklists.
(http://www.cap.org/apps/docs/cancer_protocols/protocols_index.html)

This version includes all the required functionality defined in the
Software Requirements Specification for the project and incorporates the
bug fixes identified by adopters during their testing as well as some
enhancements they recommended.

## Content of the release

The release of caTISSUE CAE is checked into the NCICB's CVS repository
as a .zip file. The contents of that file are as follows:

-   Software source code for the following

    -   caTISSUE CAE

    -   caCORE, as modified for CAE

    -   CSM, as modified for CAE

-   XML schemas that specify the format for import of data into CAE

-   Sample XML files of test data, demonstrating instantiation of the
    schemas for import

-   Scripts for creating the Oracle database tables

-   Ant script for building the system from source files

-   Instructions for creating CAE users by using the Common Security
    Module's User Provisioning Tool

-   caTISSUE CAE System Administrator's Guide

-   README.txt describing the content of the file

The System Administrator's Guide is available in the caCAE/install
subdirectory of this release.

## Related Documents

> All documentation for the caTISSUE CAE project is available at
>
> [http://cabigcvs.nci.nih.gov/viewcvs/viewcvs.cgi/catissue_annotation/](http://cabigcvs.nci.nih.gov/viewcvs/viewcvs.cgi/catissue_annotation/caTISSUE_CAE_Risk_Matrix_1.3_15nov2005.doc).

# System Scope

## Functionality

caTISSUE CAE 1.0 provides the following major areas of functionality:

-   Import of the data that is represented in the project's object
    model, in XML format conforming to the schemas provided with the
    system. The schemas validate that any data values provided conform
    to the data type and enumerated value restrictions specified in the
    caDSR.

-   Query by one or more of most of the data elements that are
    represented in the project's object model. Query results are
    presented in a single, default view, and the user may click on any
    case to see all of the associated data values.

-   Entry of data values for most of the data elements that are
    represented in the project's object model, with system
    validation-checking of the values against the data types and
    enumerated values specified in caDSR.[^1]

-   Ability for a user to maintain his or her own case list (that is, to
    add retrieved cases to that list and delete cases from it).

## Common Data Elements

CAE 1.0 uses Common Data elements from three caBIG classifications in
caDSR, as follows:

-   The CDEs for ParticipantIdentifiers.gender,
    ParticipantIdentifiers.ethnicity, and ParticipantIdentifiers.race
    are from the Data Standards classification.

-   The following CDEs are from the caTISSUE Core classification on the
    caDSR staging server:

    -   ParticipantIdentifiers.firstName

    -   ParticipantIdentifiers.lastName

    -   ParticipantIdentifiers.middleName

    -   ParticipantIdentifiers.birthDate

    -   ParticipantIdentifier.medicalRecordNumber

    -   AccessionIdentifiers.surgicalPathologyNumber

    -   EventParameters.id

    -   EventParameters.timeStamp

-   The remaining CDEs are from the CAP Cancer Checklists
    classification. CAE uses all of the CDEs from that classification
    except for Synoptic Surgical Report Comment Text (Public ID 2431525)
    and Synoptic Surgical Report Version Date (Public ID 2431526). Those
    data elements are not required in the CAE application.

After the initial CAE model was loaded to the caDSR stage server, that
server was intermittently unavailable due to testing of caCORE 3.1 and
related tools. As a step in the final installation of those tools, the
caDSR content on the stage server was replaced with that from the
Production server. As a result, at the time of this delivery the final
CAE model is not loaded. As a result, CAE continues to use the CDEs from
other applications as described above. While the CAE model was still
available on stage, we validated and added two CAE-specific CDEs:

-   ParticipantIdentifiers.uniquePatientIdentifier (CDE 2444107)

-   Accession.accessionDate (CDE 2444109)

There is still no CDE available for the object attribute
SpecimenIdentifier.surgicalLabel. As a result, the text displayed for
that attribute on the user interface is in camel case, indicating that
the application is not reading the appropriate text from the
\<DocumentText\> element of a CDE. We expect that the CAE model will be
reloaded to stage by COB 4/7/06, and the next release of the software
will incorporate all of the CDEs that are created by that load.

# Requirements Non-Compliance

This section lists the documented software requirements that caTISSUE
CAE 1.0 beta does not yet satisfy, along with a comment for each
explaining that status.

+------------------------------------+---------------------------------+
| > **Requirement**                  | **Comment**                     |
+------------------------------------+---------------------------------+
| > CAE COMPAT-1 For all data entry  | Current procedures dictate that |
| > fields caTISSUE Clinical         | this review occur as part of    |
| > Annotation Engine shall use:     | the interoperability review     |
| > CDEs that have been reviewed and | scheduled by the VCDE workspace |
| > validated by the caBIG V/CDE     | near the end of a project. That |
| > Workspace, terminologies that    | review has yet to be scheduled. |
| > have been reviewed and validated | As noted above, we expect the   |
| > by the caBIG V/CDE Workspace.    | model will be loaded by         |
| > Terminology that is in the NCI   | 4/7/2006.                       |
| > Metathesaurus shall be assumed   |                                 |
| > to have been so validated.       |                                 |
+------------------------------------+---------------------------------+
| > CAE-QUERY-1 REQ: A user shall be | The Adopters decided that       |
| > able to submit a query that      | implementing this requirement   |
| > consists of one or more case     | was not a high priority for     |
| > numbers. The mechanism for       | this version. It will be added  |
| > entering multiple case numbers   | to a future version if Adopter  |
| > (e.g. multiple text fields, or a | priorities indicate it should   |
| > predetermined separator between  | be.                             |
| > case numbers) will be specified  |                                 |
| > in the System Administration and |                                 |
| > User Guides, and will be         |                                 |
| > communicated to the initial      |                                 |
| > users at the Adopter sites via   |                                 |
| > informal training.               |                                 |
+------------------------------------+---------------------------------+
| > CAE-QUERY-5 REQ: When the user   | Depends on CAE-QUERY-1          |
| > submits a query that consists of |                                 |
| > one or more case numbers, the    |                                 |
| > system shall identify each case  |                                 |
| > in the local database that       |                                 |
| > matches one of those case        |                                 |
| > numbers                          |                                 |
+------------------------------------+---------------------------------+
| > CAE-ADMIN-10 REQ: When the       | The User Provisioning Tool does |
| > system finds that the email      | not currently check for         |
| > address or full name of the user | duplicates. Per Ian Fore of the |
| > in a request for a new user      | NCICB, we are not adding        |
| > account is the same as an        | functionality to the UPT in     |
| > existing email address, the      | advance of the next CSM         |
| > system shall display a request   | release. If this functionality  |
| > for the System Administrator to  | is not in the next CSM release, |
| > confirm the account request.     | we will consider adding it to   |
|                                    | the UPT.                        |
+------------------------------------+---------------------------------+

# Issues corrected In CAE 1.0 Final Release

The beta3 version had a bug related to the rebuildindex.bat routine. The
command would not run successfully due to session structure changes made
in beta3.

All earlier versions included a bug in the handling of CDEs that
associated more than one Valid Value with a given Value Meaning. This
affected the CDEs for Nottingham Grade total score and for Tumor
Infiltrating Lymphocytes in CutaneousMelanoma. In both cases the CDEs
were modified to give each Valid Value a distinct Value Meaning.

Both of these issues are fixed in version 1.0.

# Known Bugs in CAE 1.0 Final Release 

The known bugs for CAE 1.0 are as follows:

**Bug# Description**

612 For each data element on which a user may query, the system shall
allow the user to view the definition for the element.

**Status**- The only remaining issue with this bug is that the CDE for
SpecimenIdentifiers.surgicalLabel is not available in the caDSR. It will
be loaded to caDSR with the rest of our model very shortly. This causes
the label in the system to appear as camel case. No other functionality
is affected.

720 Specimen Overview of caselist screen: column title \"Name\" is
confusing.

**Status**- The "Invasive Prostate Carcinoma Neoplasm Histologic Type"
object has an attribute called "name". This is the source of the label.
No other functionality is affected. For future releases we will add some
ability to combine the object and attribute name into a more descriptive
label as required.

919 The value could be saved incorrectly after manual annotation if a
value meaning of an element corresponds to multiple values.

**Status**- This issue has been traced to CDE's that have identical
Value Meanings for distinct Valid Values (e.g. for total Nottingham
Score, both the value 6 and the value 7 were associated with the Value
Meaning 'Grade II'. ) As noted in the previous section, the Value
Meanings were changed to distinguish them from each other. We list the
bug here because the underlying issue was not addressed; rather, the
CDEs were changed to make the issue moot in this version.

908 API: Able to read Identified data with user login having rights to
see only DeIdentified data.

**Status**- Addressing this requires modifying the APIs generated by
caCORE. Future versions of CAE will develop a secure service-level API.

913 API: Search Participant having search criteria of
ParticipantIdentifiers attributes - Exception:
java.lang.StackOverflowError

**Status**- Addressing this requires modifying the APIs generated by
caCORE. Future versions of CAE will develop a secure service-level API.

920 Reset for Collection on manual annotation does not work

**Status**- The Reset option on Manual annotation screens does not reset
additional options added using the green plus sign. The workaround is to
use the red plus sign to remove those entries manually.

910 Multiple MRN not handled

**Status**- Entry of duplicate MRNs gets collapsed to a single element
when a user chooses submit (that is, only one instance of the MRN is
displayed). The functional impact of this should be negligible.

803 The Specimen editor does not save big integers (9 or more digits)
correctly.

**Status**- We do not anticipate users needing any values of nine digits
so the functional impact of this should be low.

807 The time of accession date may be lost after user edits an
accession.

**Status**- The import format allows a time to be specified along with
the date; however, the manual annotation interface does not accept time
as part of an accession date. As the exact time of an accessions is not
generally included in reports, the functional impact of this should be
low.

973 NullPointerException adding a new case on a user without the
csmSDKdefault group

**Status**- This is a known issue with the CAE 1.0 release. The
workaround is to always assign the csmSDKdefault group to a new user.
This step is described in the System Administration Guide. Future
versions of CAE are expected to address this problem.

For the current status of all bugs and their priority please refer to
CAE gforge site:

<http://gforge.nci.nih.gov/tracker/index.php?group_id=20>

# System Limitations

Additional features have been requested by Adopters or suggested by
Developers for future versions, and are listed with these on the
project's GForge site:
http://gforge.nci.nih.gov/tracker/?atid=236&group_id=20&func=browse.

One current limitation of the user interface merits discussion because
it may lead to some confusion on the part of end users. CAE 1.0 does not
recognize dependencies among values specified between and within
annotation sets, and it does not validate values within a set for
logical consistency. The caDSR currently provides no way to specify such
dependencies or validation rules in the metadata. This creates several
issues; for example:

-   In cases of prostate cancer and melanoma, users should be able to
    specify the surgical procedure used to obtain an Accession or
    Specimen, and that value should constrain the availability of other
    annotation sets. For example, if the user specified that
    SurgicalPathologySpecimen.surgicalProcedure for an Accession was
    'Radical Prostatectomy', then the user would be able to specify
    values for attributes in the annotation sets
    RadicalProstatectomyInvasiveProstateCarcinoma and
    RadicalProstatectomyGleasonHistopathologicGrade, but not for
    attributes in TransurethralResectionInvasiveProstateCarcinoma or
    NeedleBiopsyProstateSurgicalPathologySpecimen. CAE does not
    currently represent these dependencies; rather, all the procedure
    types are displayed to the user. We intend to develop a mechanism
    for defining these dependencies and other types of business rules
    for CAE 2.0. (See also Feature Request 133.)

-   When the user specifies the components of a Gleason Grade or
    Nottingham Grade score, ideally the application would calculate the
    total score. In CAE 1.0 the calculation is not performed and the
    total score is not validated against the components to ensure that
    it is logically consistent.

-   In Breast Cancer TNM Findings values, CAE 1.0 does not verify that
    the value specified for "number of lymph nodes involved" is less
    than or equal to the value of "number of lymph nodes examined".

Another notable limitation of CAE 1.0 is the fact that only one
attribute -- Participant's age at accession \-- can be searched for a
range of values rather than for a specific value. Requirements for
range-based searching of other attribute values will be collected for
version 2.0.

# LOG FILE MAINTENANCE

CAE has implemented the JAVA log4j feature in our code. It currently
logs a lot of debug and informational records. You may configure the log
to roll over whenever you would prefer. Be aware that these files can
become fairly large and you should monitor the accumulation of these
files. Left unmonitored, they could fill up your disk partition.

To configure the amount of logging and the rate at which new files are
generated, go to the JBOSS\\server\\default\\conf directory. Edit the
file log4j.xml. The first section that defines the class
"org.jboss.logging.appender.DailyRollingFileAppender" defines the
rollover type. The default is to rollover at midnight. The following
table can be used to find other alternative rollover times. You may also
visit:
[[http://logging.apache.org/log4j/docs/api/index.html]{.underline}](http://logging.apache.org/log4j/docs/api/index.html)
to get a detailed explanation and more options.

  ----------------------- ------------------ --------------------------------------------
  \'yyyy-MM               Rollover at the    At midnight of May 31st, 2002 /foo/bar.log
                          beginning of each  will be copied to /foo/bar.log.2002-05.
                          month              Logging for the month of June will be output
                                             to /foo/bar.log until it is also rolled over
                                             the next month.

  \'.\'yyyy-ww            Rollover at the    Assuming the first day of the week is
                          first day of each  Sunday, on Saturday midnight, June 9th 2002,
                          week. The first    the file */foo/bar.log* will be copied to
                          day of the week    */foo/bar.log.2002-23*. Logging for the 24th
                          depends on the     week of 2002 will be output to /foo/bar.log
                          locale.            until it is rolled over the next week.

  \'.\'yyyy-MM-dd         Rollover at        At midnight, on March 8th, 2002,
                          midnight each day. /foo/bar.log will be copied to
                                             /foo/bar.log.2002-03-08. Logging for the 9th
                                             day of March will be output to /foo/bar.log
                                             until it is rolled over the next day.

  \'.\'yyyy-MM-dd-a       Rollover at        At noon, on March 9th, 2002, /foo/bar.log
                          midnight and       will be copied to
                          midday of each     /foo/bar.log.2002-03-09-AM. Logging for the
                          day.               afternoon of the 9th will be output to
                                             /foo/bar.log until it is rolled over at
                                             midnight.

  \'.\'yyyy-MM-dd-HH      Rollover at the    At approximately 11:00.000 o\'clock on March
                          top of every hour. 9th, 2002, /foo/bar.log will be copied to
                                             /foo/bar.log.2002-03-09-10. Logging for the
                                             11th hour of the 9th of March will be output
                                             to /foo/bar.log until it is rolled over at
                                             the beginning of the next hour.

  \'.\'yyyy-MM-dd-HH-mm   Rollover at the    At approximately 11:23,000, on March 9th,
                          beginning of every 2001, /foo/bar.log will be copied to
                          minute.            /foo/bar.log.2001-03-09-10-22. Logging for
                                             the minute of 11:23 (9th of March) will be
                                             output to /foo/bar.log until it is rolled
                                             over the next minute.
  ----------------------- ------------------ --------------------------------------------

# APPENDIX A. ACRONYMS and abbreviations {#appendix-a.-acronyms-and-abbreviations .unnumbered}

  --------------- -------------------------------------------------------
  **Acronym**     **Stands for**

  AACI            American Association of Cancer Institutes

  API             Application Programming Interface

  AP LIS          Anatomic Pathology Laboratory Information System

  caBIG           Cancer Biomedical Informatics Grid

  caDSR           Cancer Data Standards Repository

  CAE             Clinical Annotation Engine

  CAP             College of American Pathologists

  CDE             Common Data Element

  EVS             Enterprise Vocabulary System

  HIPAA           Health Insurance Portability and Accountability Act

  NCI             National Cancer Institute

  PCABC           Pennsylvania Cancer Alliance Bioinformatics Consortium

  PHI             Protected Health Information

  RDBMS           Relational Database Management System

  SOW             Statement of Work

  SQL             Structured Query Language

  TBPT            Tissue Banks and Pathology Tools (Workspace)

  UML             Unified Modeling Language

  UPCI            University of Pittsburgh Cancer Institute

  V/CDE           Vocabulary and Common Data Elements (Workspace)
  --------------- -------------------------------------------------------

# APPENDIX B. CAE 1.0 beta-2 Audit Functionality summary {#appendix-b.-cae-1.0-beta-2-audit-functionality-summary .unnumbered}

Auditing in CAE 1.0 captures information relating to the following
events:

-   User Login

-   User Logout

-   User Timeout

-   Import Initiation

-   Import Accepted

-   Import Aborted

-   Import Committed

-   Disease Type Selection / Privilege Level

-   Read of Case PHI Data

-   Edit / Create PHI Data

User timeout is calculated by recording all page accesses per user and
take the last one to be the end of session marker in the event there is
no explicit user logout.

All Import events capture details on username, filename, organ type,
time success / failure.

Privilege auditing is captured at the role name level

CAE version 1.0 auditing takes advantage of the CIAF common logging
module routines.

**UPT 3.0.1 Audit Limitations**

CAE 1.0 uses UPT (3.0.1) which does not maintain an audit log of user
privilege changes or account creations. This functionality is expected
in the next release of UPT. Future phases for CAE development will take
advantage of UPT 4.0's auditing features.

**Description of the AUDIT_LOG Table**

The AUDIT_LOG table records user activities by audit event. Audit events
include URL REQUEST(monitor all the user activities), LOGIN, LOGOUT,
TIMEOUT, DISEASE SELECTIONTION, IMPORT INITIATION, IMPORT ACCEPTED,
IMPORT ABORTED, IMPORT COMMITED, ADD ENTITY, EDIT ENTITY, READ CASE.

  ---------------------------------------------------------------------------------
  **Column Name**            **Data Type**    **Description**
  -------------------------- ---------------- -------------------------------------
  AUDIT_LOG_ID               NUMBER(20)       Internal system id

  USER_ID                    NUMBER(20)       Internal system user id from table
                                              CSM.CSM_USER

  USER_NAME                  VARCHAR2(64)     User login name

  USER_CURRENT_PRIVILEGE     VARCHAR2(512)    Privileges the user currently has

  USER_CHANGE_TO_PRIVILEGE   VARCHAR2(512)    Privileges the user is changing to if
                                              the audit event is PRIVILEGE CHANGE.

  AUDIT_EVENT                VARCHAR2(32)     Event of audit. The values are as
                                              mentioned above.

  ENTITY_ID                  NUMBER(20)       Internal system ID from table
                                              ANNOTATABLE_ENTITY. The column will
                                              have value only if the audit events
                                              are ADD ENTITY, EDIT ENTITY and READ
                                              CASE.

  ENTITY_TYPE                VARCHAR2(64)     Type of entity. Values are
                                              Participant, Accession, Specimen,
                                              Sub-Specimen. The column will have
                                              value only if the audit events are
                                              ADD ENTITY, EDIT ENTITY and READ
                                              CASE.

  DISEASE_TYPE               VARCHAR2(64)     Type of disease the user selected.
                                              The column will have value only after
                                              the user select a disease.

  IMPORT_FILE_NAME           VARCHAR2(128)    The import file name. The column will
                                              have value only if the audit events
                                              are IMPORT INITIATION, IMPORT
                                              ACCEPTED, IMPORT ABORTED and IMPORT
                                              COMMITED.

  SOURCE                     VARCHAR2(64)     The source of import file. The column
                                              will have value only if the audit
                                              events are IMPORT INITIATION, IMPORT
                                              ACCEPTED, IMPORT ABORTED and IMPORT
                                              COMMITED.

  HTTPSESSION_ID             VARCHAR2(64)     The HTTPSession Id.

  LOG_TIME                   VARCHAR2(28)     Date and time of the log.

  LOGGER                     VARCHAR2(256)    The java class of logger. Currently
                                              only the
                                              edu.pitt.cabig.cae.audit.AuditDBLog
                                              is used for audit log.

  MESSAGE                    VARCHAR2(2000)   Message for the log record. If the
                                              event is URL REQUEST, the message
                                              will be the URL the user requested.

  APP_NAME                   VARCHAR2(32)     Application name. Currently only
                                              CACae.
  ---------------------------------------------------------------------------------

**Sample Audit Table Queries**

This sample shows details of login date and time and account privileges
for the user "super" during the month of January 2006

select USER_NAME,

AUDIT_EVENT,

LOG_TIME,

USER_CURRENT_PRIVILEGE

from audit_log

where USER_NAME=\'super\'

and AUDIT_EVENT=\'LOGIN\'

and to_date(subStr(LOG_TIME,1,10),\'YYYY-MM-DD\') between

to_date(\'2006-01-01\',\'YYYY-MM-DD\') and
to_date(\'2006-01-31\',\'YYYY-MM-DD\')

order by LOG_TIME ;

This sample shows details of the "super" account's viewing of PHI
identifier data during the month of January 2006

select USER_NAME,

AUDIT_EVENT,

LOG_TIME,

ENTITY_TYPE,

USER_CURRENT_PRIVILEGE

from audit_log

where USER_NAME=\'super\'

and AUDIT_EVENT=\'READ CASE\'

and to_date(subStr(LOG_TIME,1,10),\'YYYY-MM-DD\') between

to_date(\'2006-01-01\',\'YYYY-MM-DD\') and
to_date(\'2006-01-31\',\'YYYY-MM-DD\')

order by LOG_TIME ;

[^1]: We say "most" of the data elements, because some of the classes in
    the model are abstract only and do not have attributes that are
    meaningful to users for query and annotation. In particular, the
    classes EventParameters, AnnotationEventParameters, and
    AnnotatableEntity are abstract classes in the CAE model. The id
    attribute of each of those classes is for system use only and will
    never be displayed to the user or entered by the user.
    AnnotationEventParameters.source is displayed to the user as the
    source of an annotation, and can be entered only by users who are
    authorized to import data.