**Technical Architecture Guide**

**V 1.2**

**CTMS Patient Study Calendar Phase II**

**Robert H. Lurie Comprehensive Cancer Center of Northwestern
University**

Document Change History

  ----------------- ------------ ------------------ ----------------------
  **Version         **Date**     **Contributor**    **Description**
  Number**                                          

  V 1.0             2007-07-1    John Dzak          Added New
                                                    Functionality

  V 1.1             2007-8-16    John Dzak          Updated Diagrams with
                                                    new UML Diagrams

  V 1.1.1           2007-9-13    Sean Whitaker      Minor updates for
                                                    Construction Release 1

  V 1.1.2           2007-10-23   Sean Whitaker      Address BAH feedback

  V 1.1.3           2007-10-29   Sean Whitaker,     Add API stubs and
                                 Saurabh Agrawal    section on Grid
                                                    services

  V 1.1.4           2007-12-11   Sean Whitaker,     Add grid service,
                                 Saurabh Agrawal    address feedback

  V 1.2             2008-2-7     Sean Whitaker      Add RESTful API,
                                                    update diagrams,
                                                    address D&T comments
  ----------------- ------------ ------------------ ----------------------

Audience

This document is designed to meet the needs of software developers who
are interested in learning about or extending PSC. To understand the
information outlined in this document, you should be familiar with basic
concepts of software design and implementation.

Copyright and License

The caBIG software license may be found here:

<https://cabig.nci.nih.gov/working_groups/DSIC_SLWG/FINAL-DSIC-WS-Documents/Model_caBIG_Software_License_Agreement_v1_04.20.06.doc>

+-----------------------+----------------------------------------------+
| **Patient Study       |                                              |
| Calendar Team**       |                                              |
+-----------------------+----------------------------------------------+
| ***Development***     | ***Project Management***                     |
+-----------------------+----------------------------------------------+
| Rhett Sutphin^1^      | Sean Whitaker^1^                             |
| (lead)                |                                              |
+-----------------------+----------------------------------------------+
| Ram Chilukuri^2^      | Warren Kibbe^1^ (Principal Investigator)     |
+-----------------------+----------------------------------------------+
| Andrew Winter^1^      |                                              |
+-----------------------+----------------------------------------------+
| Nataliya Shurupova^1^ |                                              |
+-----------------------+----------------------------------------------+
| Anurag Kondapalli^1^  |                                              |
+-----------------------+----------------------------------------------+
| John Dzak^1^          |                                              |
+-----------------------+----------------------------------------------+
| Saurabh Agrawal^2^    |                                              |
+-----------------------+----------------------------------------------+
| (1) Northwestern      |                                              |
|     University        |                                              |
|     Robert H. Lurie   |                                              |
|     Comprehensive     |                                              |
|     Cancer Center     |                                              |
|                       |                                              |
| (2) SemanticBits      |                                              |
+-----------------------+----------------------------------------------+

Table of Contents

[1. Introduction to the Technical Architecture Guide
1](#introduction-to-the-technical-architecture-guide)

[About Patient Study Calendar 1](#about-patient-study-calendar)

[Overview of the Guide
1](#for-information-about-ccts-architecture-httpgforge.nci.nih.govdocmanview.php36810498ccts_architecture.doc)

[Organization of the Guide 2](#organization-of-the-guide)

[Document Text Conventions 2](#document-text-conventions)

[2. Overview of the Software 1](#overview-of-the-software)

[Software overview 1](#software-overview)

[System requirements 1](#system-requirements)

[Required Software 1](#required-software)

[Database Requirements 1](#database-requirements)

[Design and architecture 2](#design-and-architecture)

[3. Patient Study Calendar Requirements (Use Case View)
3](#patient-study-calendar-requirements-use-case-view)

[Trial Protocols 5](#trial-protocols)

[Tracking Participants 5](#tracking-participants)

[Usability 5](#usability)

[4. Patient Study Calendar Architecture
7](#patient-study-calendar-architecture)

[Overview 7](#overview)

[Architectural Layers (Logical View)
7](#architectural-layers-logical-view)

[Domain 7](#domain)

[Business Logic 9](#business-logic)

[Data access 9](#data-access)

[Presentation 11](#presentation)

[Control 11](#control)

[View 11](#view)

[Dependency injection (Architectural Pattern)
11](#dependency-injection-architectural-pattern)

[Process View 12](#process-view)

[Component View 14](#component-view)

[Deployment View 14](#deployment-view)

[5. Security 17](#security)

[Roles
17](#httpgforge.nci.nih.govpluginsscmcvscvsweb.phpstudycalendarphaseiiconstructioniteration4psc_admin_guide.doccvsrootstudycalendar)

[Authentication 17](#authentication)

[Authorization 17](#authorization)

[6. Patient Study Calendar APIs 19](#patient-study-calendar-apis)

[7. Patient Study Calendar Grid Services
21](#patient-study-calendar-grid-services)

[8. Information Models 27](#information-models)

[9. Customized Tools 29](#customized-tools)

[Bering -- Incremental database development
29](#bering-incremental-database-development)

[Technical Manuals/Articles 31](#technical-manualsarticles)

# Introduction to the Technical Architecture Guide  {#introduction-to-the-technical-architecture-guide .Section-Heading}

## About Patient Study Calendar {#about-patient-study-calendar .unnumbered}

The Patient Study Calendar (PSC) is an open source, standards-compliant,
web-based application that assists with the management of the activities
of subjects on clinical trials. PSC provides the ability to create and
edit a standard template to represent the activities defined by a study
protocol, use this template to generate and view prospective calendars
of subject activities, track the state of activities as a subject
progresses through the study, and manage subject calendars as they
change during a study. PSC also provides interfaces for managing access
to data across a multi-site environment and balancing the workload of
Subject Coordinators.

PSC is being developed to interoperate with other tools within the
Clinical Trials Management System (CTMS) workspace of the caBIG
community. As part of the caBIG Clinical Trials Suite (CCTS), PSC
leverages the caGRID infrastructure to receive study creation and
patient registration information from C3PR, receives and displays on a
subject's schedule Adverse Event notifications from caAERS, and provides
links from a subject's calendar to caAERS and Lab Viewer so that the
coordinator may quickly access additional information about the subject.

## For information about CCTS architecture: [**http://gforge.nci.nih.gov/docman/view.php/368/10498/ccts_architecture.doc**](http://gforge.nci.nih.gov/docman/view.php/368/10498/ccts_architecture.doc) {#for-information-about-ccts-architecture-httpgforge.nci.nih.govdocmanview.php36810498ccts_architecture.doc .unnumbered}

## For information about caGRID: [**https://cabig.nci.nih.gov/workspaces/Architecture/caGrid/**](https://cabig.nci.nih.gov/workspaces/Architecture/caGrid/) {#for-information-about-cagrid-httpscabig.nci.nih.govworkspacesarchitecturecagrid .unnumbered}

##  {#section .unnumbered}

## Overview of the Guide {#overview-of-the-guide .unnumbered}

This document covers the technical and design aspects of the
implementation of the Patient Study Calendar application with an
overview of the requirements for context. Not covered here, but
available in other project documents are:

-   [Detailed
    requirements](http://gforge.nci.nih.gov/plugins/scmcvs/cvsweb.php/studycalendar/PhaseII/Construction/Iteration1/PSC_SRS.doc?cvsroot=studycalendar)

-   [Use
    cases](http://gforge.nci.nih.gov/plugins/scmcvs/cvsweb.php/studycalendar/PhaseII/Construction/Iteration1/PSC_Use_Case.doc?cvsroot=studycalendar)

-   [Domain UML
    model](http://gforge.nci.nih.gov/plugins/scmcvs/cvsweb.php/studycalendar/PhaseII/Construction/Iteration1/PSC_UML.EAP?cvsroot=studycalendar)

-   [Installation](http://gforge.nci.nih.gov/plugins/scmcvs/cvsweb.php/studycalendar/PhaseII/Construction/Iteration1/PSC_Install_Guide.doc?cvsroot=studycalendar)

-   [Administration](http://gforge.nci.nih.gov/plugins/scmcvs/cvsweb.php/studycalendar/PhaseII/Construction/Iteration1/PSC_Admin_Guide.doc?cvsroot=studycalendar)

##  {#section-1 .unnumbered}

##  {#section-2 .unnumbered}

##  {#section-3 .unnumbered}

## Organization of the Guide {#organization-of-the-guide .unnumbered}

  -----------------------------------------------------------------------
  ***Chapter***                 ***Contents***
  ----------------------------- -----------------------------------------

  -----------------------------------------------------------------------

Table 1. 1 Summary of the sections of this guide

## Document Text Conventions {#document-text-conventions .unnumbered}

The following table shows various typefaces to differentiate between
regular text and menu commands, keyboard keys, and text that you type.
This illustrates how conventions are represented in this guide.

+----------------------+------------------------+----------------------+
| ***Convention***     | ***Description***      | ***Example***        |
+======================+========================+======================+
| **Bold & Capitalized | Indicates a Menu       | **Admin \> Refresh** |
| Command**            | command                |                      |
|                      |                        |                      |
| **Capitalized        | Indicates Sequential   |                      |
| command \>           | Menu commands          |                      |
| Capitalized          |                        |                      |
| command**            |                        |                      |
+----------------------+------------------------+----------------------+
| [text in small       | Keyboard key that you  | Press                |
| caps]{.smallcaps}    | press                  | [enter]{.smallcaps}  |
+----------------------+------------------------+----------------------+
| [text in small       | Keyboard keys that you | Press [shift +       |
| caps + text in small | press simultaneously   | ctrl]{.smallcaps}    |
| caps]{.smallcaps}    |                        | and then release     |
|                      |                        | both.                |
+----------------------+------------------------+----------------------+
| Special typestyle    | Used for filenames,    | URL_definition ::=   |
|                      | directory names,       | url_string           |
|                      | commands, file         |                      |
|                      | listings, source code  |                      |
|                      | examples and anything  |                      |
|                      | that would appear in a |                      |
|                      | Java program, such as  |                      |
|                      | methods, variables,    |                      |
|                      | and classes.           |                      |
+----------------------+------------------------+----------------------+
| **Boldface type**    | Options that you       | In the Open dialog   |
|                      | select in dialog boxes | box, select the file |
|                      | or drop-down menus.    | and click the        |
|                      | Buttons or icons that  | **Open** button.     |
|                      | you click.             |                      |
+----------------------+------------------------+----------------------+
| *Italics*            | Used to reference      | *caCORE Software     |
|                      | other documents,       | Development Kit 1.0  |
|                      | sections, figures, and | Programmer's Guide*  |
|                      | tables.                |                      |
+----------------------+------------------------+----------------------+
| ***Italic boldface   | Text that you type     | In the New Subset    |
| type***              |                        | text box, enter      |
|                      |                        | ***Proprietary       |
|                      |                        | Proteins.***         |
+----------------------+------------------------+----------------------+
| Note:                | Highlights a concept   | **Note:** This       |
|                      | of particular interest | concept is used      |
|                      |                        | throughout the       |
|                      |                        | installation manual. |
+----------------------+------------------------+----------------------+
| **Warning!**         | Highlights information | **Warning!**         |
|                      | of which you should be | Deleting an object   |
|                      | particularly aware.    | will permanently     |
|                      |                        | delete it from the   |
|                      |                        | database.            |
+----------------------+------------------------+----------------------+
| {}                   | Curly brackets are     | Replace {root        |
|                      | used for replaceable   | directory} with its  |
|                      | items.                 | proper value such as |
|                      |                        | c:\\cabio            |
+----------------------+------------------------+----------------------+

Table 1. 2 Document Conventions

# 2. Overview of the Software {#overview-of-the-software .unnumbered}

## Software overview {#software-overview .unnumbered}

Patient Study Calendar is a Java web application based on the J2EE
Servlets infrastructure. For details on the implementing libraries, see
Chapter 4.

## System requirements  {#system-requirements .unnumbered}

### Required Software {#required-software .unnumbered}

  -------------------------------------------------------------------------------------------------------
  ***Software      ***Version***   ***Description***   ***URL***
  Name***                                              
  ---------------- --------------- ------------------- --------------------------------------------------
  Java SE          JDK 5.0         The Java SE         <http://java.sun.com/javase/downloads/index.jsp>
  Development Kit                  development kit     
                                   with JRE, compilers 
                                   and debuggers       

  Apache Tomcat    5.5.17 or       Servlet container   <http://tomcat.apache.org/download-55.cgi>
                   higher          for JSP             

  Apache Ant       1.6 or higher   Java-based build    <http://ant.apache.org/bindownload.cgi>
                                   tool                
  -------------------------------------------------------------------------------------------------------

Table 1 Required software and technology

### Database Requirements {#database-requirements .unnumbered}

The Patient Study Calendar requires access to a properly-configured
database. The application is built with database-independence in mind
and has been tested on the following:

  ------------- --------------- ---------------------- --------------------------------------------------------------------------
  ***Database   ***Version***   ***Description***      ***URL***
  Name***                                              

  PostgreSQL    8               PostgreSQL is a        <http://www.postgresql.org/download/>
                                powerful, open source  
                                relational database    
                                system.                

  Oracle        9i              Industry-leading,      <http://www.oracle.com/technology/software/products/oracle9i/index.html>
                                commercial database    
                                product.               
  ------------- --------------- ---------------------- --------------------------------------------------------------------------

For more details, please see the [Installation
Guide](http://gforge.nci.nih.gov/plugins/scmcvs/cvsweb.php/studycalendar/PhaseII/Construction/Iteration1/PSC_Install_Guide.doc?cvsroot=studycalendar).

## Design and architecture {#design-and-architecture .unnumbered}

Patient Study Calendar follows the widely-accepted Model-View-Controller
(MVC) structure for object-oriented software. It is built in layers,
with most communication occurring between adjacent layers only, and
communication consisting of passed domain instances or other model
objects. For more detail, see Chapter 4.

![](media/image2.jpeg){width="6.5in" height="4.875in"}

# 3. Patient Study Calendar Requirements (Use Case View) {#patient-study-calendar-requirements-use-case-view .unnumbered}

This is a brief overview. For more information, please see the Use Case
Document:
<http://gforge.nci.nih.gov/plugins/scmcvs/cvsweb.php/studycalendar/PhaseII/Construction/Iteration4/PSC_Use_Case.doc?cvsroot=studycalendar>

The full Software Requirements and Specifications document can be found
here:

<http://gforge.nci.nih.gov/plugins/scmcvs/cvsweb.php/studycalendar/PhaseII/Construction/Iteration4/PSC_SRS.doc?cvsroot=studycalendar>

The diagram below illustrates the high-level use case model for the
Patient Study Calendar:

![](media/image3.png){width="6.4944444444444445in"
height="8.716666666666667in"}

## Trial Protocols {#trial-protocols .unnumbered}

As modeled in the Patient Study Calendar, a clinical trial protocol is a
*schedule* of procedures, treatments, and examinations (collectively
called *activities*) that a participant is expected to undergo over the
course of the trial. The schedule is broken down into large-scale
segments (*epochs*).

An epoch may have more than one possible course of activities -- these
courses are called *arms* -- of which a participant will usually only
follow one.

Each arm contains one or more *periods*.

A period is a set of consecutive days, beginning at a certain day in the
arm and possibly repeating.

Activities are assigned to days within the period, creating *planned
events*. An activity may be scheduled to happen more than once on a
given day in a period, but there is no requirement to schedule at a
finer time scale than one day.

## Tracking Participants {#tracking-participants .unnumbered}

Once the full protocol is modeled in the application and finalized,
*participants* may be assigned to it. Assigning a participant involves
giving him a start date and selecting which arm he'll be on for the
first epoch. This allows the system to create the first set of
*scheduled events*, which are planned events with a date and participant
attached.

As the participant proceeds through the protocol, a participant
coordinator or research associate will mark the scheduled events he's
completed and/or canceled. At the end of each epoch, the user will be
prompted to select the arm for the participant for the next epoch. At
any time, the user may manually shift the participant to a different
epoch or a different arm within the same epoch.

## Usability {#usability .unnumbered}

The model for a schedule is very complex, with four levels of nested
objects and the possibility of repeats and parallel paths. For this
reason, it is important to display the protocol in a clear,
comprehensible, and familiar manner, and to allow it to be edited simply
and directly.

# 4. Patient Study Calendar Architecture {#patient-study-calendar-architecture .unnumbered}

## Overview {#overview .unnumbered}

Patient Study Calendar is a standard, modern, non-EJB java web
application with a well defined set of public API's. The architecture of
the Patient Study Calendar is described below using the 4 +1 view
paradigm.

## Architectural Layers (Logical View) {#architectural-layers-logical-view .unnumbered}

It has 4 fundamental layers -- domain, data access, business logic, and
presentation -- and several ancillary packages, all glued together using
dependency injection.

## Domain {#domain .unnumbered}

Patient Study Calendar's domain objects are implemented as plain java
beans. They are contained in the
"edu.northwestern.bioinformatics.studycalendar.domain" java package. The
domain model is documented in a UML class diagram, which can be accessed
at:

<http://gforge.nci.nih.gov/plugins/scmcvs/cvsweb.php/studycalendar/PhaseII/Construction/Iteration4/PSC_UML-P2-R3.EAP?cvsroot=studycalendar>

The implementation model is based on a domain analysis model which has
been harmonized with the BRIDG model.

They domain objects in the implementation model are mapped to tables in
the database (commonly referred to as Object Relational Mapping) using
Hibernate Annotations. For more information on Hibernate, please see:
<http://hibernate.org/5.html>

The following graphic enumerates the domain objects of the Patient Study
Calendar:

![](media/image4.png){width="8.924305555555556in"
height="5.917361111111111in"}

## Business Logic {#business-logic .unnumbered}

Business logic based on a single domain object (commonly referred to as
domain logic) and its attributes is implemented within the domain object
itself, following good object-oriented design principles. For example,
an Epoch has no intrinsic length attribute, but it can calculate its own
maximum length by examining its Arms.

Business logic involving multiple domain objects is implemented
externally, generally in the business service tier. For example, adding
a participant to a study involves reads, updates, and inserts spanning
more than 10 different domain objects. It is therefore implemented in a
service class (ParticipantService).

Following graphic enumerates all the classes in the business logic
layer:

![](media/image5.png){width="6.933333333333334in"
height="2.522222222222222in"}

## Data access {#data-access .unnumbered}

The data access layer in the Patient Study Calendar is implemented using
the *Data Access Object (DAO)* J2EE design pattern. The domain objects
are created, updated and queried exclusively via DAOs. A DAO essentially
encapsulates the logic necessary to create, retrieve update, and delete
a domain object from the database. Implementation of DAO pattern
promotes database portability. The DAOs in the Patient Study Calendar
are based on the Spring Framework's Hibernate abstraction layer. Use of
this abstraction layer greatly simplifies the data access by eliminating
the need to write low level and repetitive plumbing code using the API
provided by Hibernate framework.

The DAOs in the Patient Study Calendar are contained in the
"edu.northwestern.bioinformatics.studycalendar.dao" java package. The
graphic below enumerates all the DAO classes in the Patient Study
Calendar.

![](media/image6.png){width="8.938888888888888in"
height="5.179166666666666in"}

## Presentation {#presentation .unnumbered}

The presentation layer can further be sub divided into control and view
layers, which are described below.

## Control {#control .unnumbered}

The control layer is made up of two closely-collaborating types of
classes: *commands* and *controllers*. Commands encapsulate the data and
behavior associated with a user operation, generally including one or
more domain objects. Controllers handle mapping incoming requests onto
command instances and providing the command output back to the view
layer.

Patient Study Calendar uses Spring MVC (which is itself based on
Servlets) to dispatch web requests to the appropriate controllers.

## View {#view .unnumbered}

The view layer uses JSP 2.0 and takes full advantage of tag libraries,
both provided by Spring and custom developed, to reduce boilerplate
code.

Design templating is handled using SiteMesh, which takes the full HTML
pages generated from the JSPs and decorates it with the common site
elements.

## Dependency injection (Architectural Pattern) {#dependency-injection-architectural-pattern .unnumbered}

The objects in different layers are connected or wired together using an
architectural pattern called dependency injection/inversion of control.
This means that, instead of a DAO object acquiring a data source from
JNDI, or a controller finding a DAO using some sort of service locator,
each object declares the objects (commonly referred to as collaborators)
it depends on based on its own requirements. All the collaborators are
instantiated by an external configuration tool; all their dependencies
are satisfied by that tool when they are created.

Inter-layer dependencies are oriented such that higher levels depend on
lower levels, but never vice versa. For instance, a service may depend
on a DAO, but a DAO will never depend on a service.

Patient Study Calendar uses the Spring Framework (version 2.0),
specifically Spring IOC container for dependency injection, with the
dependencies declared in a series of XML files included alongside the
deployed classes. For more information about the Spring Framework,
please see <http://www.springframework.org/documentation>.

The following diagram illustrates the wiring of various objects that
belong to different layers in the Patient Study Calendar:

![](media/image7.jpeg){width="5.429861111111111in"
height="3.6069444444444443in"}

## Process View {#process-view .unnumbered}

The figure below is a generic sequence diagram illustrating the
interaction between the Patient Study Calendar classes and some of the
key classes of the Spring MVC framework during the processing of a user
request for a web page.

All HTTP requests in the Spring MVC go thru the DipatcherServlet, which
serves as a front controller. It uses a HandlerMapping object to figure
out the Controller class that should be used to handle the request. The
mapping between the URL and the controller class is configured in the
spring-servlet.xml file. The DispatcherServlet also retrieves all the
interceptors that are configured for the controller before delegating
the request to the controller class. In the case of the Patient Study
Calendar, two interceptors are used; LoginCheckInterceptor to check if
the user is logged in and has a valid active session and
URLAccessCheckInterceptor to verify if the logged in user is authorized
to access the page that he/she is requesting. If the login check fails,
the user is redirected to the login page and if the user does not have
privileges to access a page then the access denied page is displayed.
The URLAccessCheckInterceptor uses the CSM API for establishing the
access rights of the logged in user.

After the request passes the checks, the DispatcherServlet creates a
command object that encapsulates the HTML form elements and delegates
the processing of the request to a controller object by passing the
command object to it. The controller object uses the command object,
appropriate Patient Study Calendar service and DAO objects to process
the request and returns a ModelAndView object, which contains the model
and the view to be rendered. The Dispatcher uses the model information
to render the view.

## ![](media/image8.pct) {#section-4 .unnumbered}

## Component View {#component-view .unnumbered}

The following UML diagram illustrates the component view of the Patient
Study Calendar system.

![](media/image9.jpeg){width="6.4944444444444445in"
height="5.186111111111111in"}

## Deployment View {#deployment-view .unnumbered}

The following UML diagram illustrates the deployment view for the
Patient Study Calendar system.

![](media/image10.jpeg){width="8.927777777777777in" height="5.65in"}

# 5. Security {#security .unnumbered}

For more information Security and Roles, please see the Administration
Guide:

## [**http://gforge.nci.nih.gov/plugins/scmcvs/cvsweb.php/studycalendar/PhaseII/Construction/Iteration4/PSC_Admin_Guide.doc?cvsroot=studycalendar**](http://gforge.nci.nih.gov/plugins/scmcvs/cvsweb.php/studycalendar/PhaseII/Construction/Iteration4/PSC_Admin_Guide.doc?cvsroot=studycalendar) {#httpgforge.nci.nih.govpluginsscmcvscvsweb.phpstudycalendarphaseiiconstructioniteration4psc_admin_guide.doccvsrootstudycalendar .unnumbered}

## Roles {#roles .unnumbered}

Patient Study Calendar users are assigned one or more roles. These roles
are based on the roles described in our Use Case documents.

+----------+-----------------------------------------------------------+
| *        | -   Creates user accounts                                 |
| **System |                                                           |
| Administ | -   Grants users to role(s) and site(s) within the        |
| rator*** |     application                                           |
|          |                                                           |
| ***(S    | -   Configures the application                            |
| ysAd)*** |                                                           |
+----------+-----------------------------------------------------------+
| ***Study | -   Reviews completed study templates and approves them   |
| Administ |                                                           |
| rator*** | -   Imports and exports study templates                   |
|          |                                                           |
| **       | -   Makes studies available to each site                  |
| *(SA)*** |                                                           |
+----------+-----------------------------------------------------------+
| ***Study | -   Creates new study templates                           |
| Coordi   |                                                           |
| nator*** | -   Marks templates as being ready for review by Study    |
|          |     Administrator                                         |
| **       |                                                           |
| *(SC)*** |                                                           |
+----------+-----------------------------------------------------------+
| ***Site  | -   Determines which study templates are accessible by    |
| Coordi   |     each Subject Coordinator                              |
| nator*** |                                                           |
|          | -   Reassigns subject calendars to appropriate Subject    |
| ***      |     Coordinator                                           |
| (SiC)*** |                                                           |
+----------+-----------------------------------------------------------+
| **       | -   Assigns subjects to studies                           |
| *Subject |                                                           |
| Coordi   | -   Generates and manages calendars for subjects          |
| nator*** |                                                           |
|          |                                                           |
| ***(     |                                                           |
| SubC)*** |                                                           |
+----------+-----------------------------------------------------------+

## Authentication {#authentication .unnumbered}

The username and password are authenticated using CSM from credentials
stored in the application database. For more information on CSM, please
see: <http://ncicb.nci.nih.gov/infrastructure/cacore_overview/csm>.

## Authorization {#authorization .unnumbered}

Patient Study Calendar uses role-based authorization of two types. First
is access to URLs -- roles are assigned access permissions to the pages
they need to function. Second is attribute-based -- some pages mutate
based on the roles granted to the logged-in user. Certain links or forms
will only appear if a user has a role that grants him or her access to
the target page.

Patient Study Calendar also uses user-based authorization for specific
resources. For example, it is possible to limit access of an individual
template to specific users.

# 6. Patient Study Calendar APIs {#patient-study-calendar-apis .unnumbered}

Javadoc is provided for the domain classes as an informational
alternative to the published UML models and to document the public
dynamic API. Please see:
[http://gforge.nci.nih.gov/plugins/scmcvs/cvsweb.php/studycalendar/Final/PSC_API.tar.bz2?cvsroot=studycalendar](http://gforge.nci.nih.gov/plugins/scmcvs/cvsweb.php/studycalendar/Release2/PSC_R2_api.tar.bz2?cvsroot=studycalendar)

**Public API:**

**Interface PlannedCalendarService**

**registerStudy**

PlannedCalendar registerStudy(Study study)

Notify the PSC about the given study. The PSC will create a default
template for it. The study must include all site associations.

If the study has previously been registered, the existing template will
be returned. If a study is re-registered with different site
associations, any new site associations will be added. Attempting to
re-register with missing site associations is an error.

Parameters:

study --

Returns:

the newly created default template for the study.

**getPlannedCalendar**

PlannedCalendar getPlannedCalendar(Study study)

Retrieve the calendar template for the given study.

Parameters:

study - The study for which to return the calendar. For purposes of
matching, implementations are only required to consider the study\'s
grid ID.

Returns:

The full calendar template as it currently exists in the system.

**Interface ScheduledCalendarService**

**assignParticipant**

ScheduledCalendar assignParticipant(Study study,

Participant participant,

Site site,

Arm firstArm,

Date startDate)

Assign a participant to the given study from the given site.

Parameters:

study - The study to which the participant will be assigned. PSC must
already know about it.

participant - If the participant is unknown, it will be automatically
registered.

site - The site from which the participant is being assigned. The PSC
must already know about it and its association with the study.

firstArm - The arm of the template to which the participant should be
initially assigned

startDate -

Returns:

the newly created schedule

**getScheduledCalendar**

ScheduledCalendar getScheduledCalendar(Study study,

Participant participant,

Site site)

Retrieve the full schedule for a participant on a study at a site.
Implementations may consider only the grid IDs for the parameters.

Parameters:

study -

participant -

site -

Returns:

The full schedule, with all scheduled arms and scheduled events, as it
currently exists.

**getScheduledEvents**

Collection\<ScheduledEvent\> getScheduledEvents(Study study,

Participant participant,

Site site,

Date startDate,

Date endDate)

Return the events that exist for a schedule in the given date range. The
date range is matched by the actual date for events in the scheduled and
occurred states, and the ideal date for events in the canceled state.

Parameters:

study -

participant -

site -

startDate - The beginning of the range of dates to include. If null,
there is no early limit.

endDate - The end of the range of dates to include. If null, there is no
late limit.

**changeEventState**

ScheduledEvent changeEventState(ScheduledEvent event,

ScheduledEventState newState)

Change the state of the given event to the given new state. For
matching, implementations may consider only the grid ID of the event.

Parameters:

event -

newState -

Returns:

The same event, updated into the new state

**scheduleNextArm**

void scheduleNextArm(Study study,

Participant participant,

Site site,

Arm nextArm,

NextArmMode mode,

Date startDate)

Indicate the next arm for the participant\'s schedule.

Parameters:

study -

participant -

site -

nextArm -

mode -

startDate --

**RESTful API:**

The remainder of the API has been created using Representational State
Transfer (REST). The REST API allows you to programmatically create and
update templates, schedules, and activities using PSC\'s XML format and
the standard HTTP protocol. For more information about REST's
resource-oriented model, see
[Wikipedia](http://en.wikipedia.org/wiki/REST) (don\'t miss the list of
links at the end of the article). The book [RESTful Web
Services](http://www.oreilly.com/catalog/9780596529260/) also provides
an excellent introduction.

A detailed description of PSC's RESTful API is available in PDF format
from our GForge site:

# [**http://gforge.nci.nih.gov/plugins/scmcvs/cvsweb.php/studycalendar/PhaseII/Construction/Iteration4/PSC-RESTful-API.pdf?cvsroot=studycalendar**](http://gforge.nci.nih.gov/plugins/scmcvs/cvsweb.php/studycalendar/PhaseII/Construction/Iteration4/PSC-RESTful-API.pdf?cvsroot=studycalendar) {#httpgforge.nci.nih.govpluginsscmcvscvsweb.phpstudycalendarphaseiiconstructioniteration4psc-restful-api.pdfcvsrootstudycalendar .unnumbered}

For developers planning to leverage the RESTful API, please note:

-   A human readable, updated description of the API will be included
    within each release and will be available at
    <http://your.psc.server/studycalendar/api/v1/docs>. Resources that
    are not yet available will be marked as "Pending" in the
    documentation.

-   The machine readable version will be available at
    <http://your.psc.server/studycalendar/api/v1/docs/psc.wadl>

-   The full xml schema for your local version of PSC is available at
    <http://your.psc.server/studycalendar/api/v1/docs/psc.xsd>

-   The full xml schema for the current version of PSC is published
    publicly at <http://bioinformatics.northwestern.edu/ns/psc/psc.xsd>

# 7. Patient Study Calendar Grid Services {#patient-study-calendar-grid-services .unnumbered}

Grid services have been developed in PSC to consume messages from other
CTMS applications such as caAERS and C3PR. Currently there are four grid
services deployed

-   Adverse-event-consumer

-   Registration-consumer

-   Study-consumer

-   Study Service

**[adverse-event-consumer grid service]{.underline}**: This grid service
extends ctms adverse-event-consumer grid service. It consumes messages
related to adverse event happened to a patient on a study. Currently,
these messages are being generated by caAERS or any other application.
These messages are further processed and displayed on the calendar of
that patient

**Public API**

This grid service extends ctms adverse-event-grid service. Following is
the interface that ctms adverse-event-grid service provides

**Interface AdverseEventConsumer** {

> register(gov.nih.nci.cabig.ctms.grid.ae.beans.AENotificationType
> aeNotification)throws
> gov.nih.nci.cabig.ctms.grid.ae.stubs.types.InvalidRegistration,
> gov.nih.nci.cabig.ctms.grid.ae.stubs.types.RegistrationFailed;}
>
> Process the adverse event notification message sent by caAERS, and
> then create and register an adverse event for that patient for which
> adverse event happened. This message is further displayed on the
> calendar of that patient.

Following is an example of a SampleMessage.xml that can be consumed by
this grid service.

\<?xml version=\"1.0\" encoding=\"UTF-8\"?\>

> \<AENotification xmlns =
> \"http://semanticbits.com/aeNotification\"registrationGridId=\"48da4c0e-d3ce-4840-a3fa-3fb7c9aa146c\"\>
>
> \<detectionDate\>2007-10-23\</detectionDate\>
>
> \<description\>Grade 4 adverse event with\</description\>

\</AENotification\>

**[registration-consumer grid service]{.underline}**: This grid service
extends ctms registration-consumer grid service. It consumes messages
for registering a patient to a study. Currently, these messages are
being sent by C3PR. These messages are further processed and the patient
is registered on that study.

**Public API**

This grid service extends ctms registration-consumer-grid service.
Following is the interface that ctms registration-consumer-grid service
provides

**Interface RegistrationConsumer** {

> gov.nih.nci.ccts.grid.Registration
> register(gov.nih.nci.ccts.grid.Registration registration) throws
> RemoteException,
> gov.nih.nci.ccts.grid.stubs.types.InvalidRegistrationException,
> gov.nih.nci.ccts.grid.stubs.types.RegistrationConsumptionException ;
>
> Process the registration message sent by C3PR, and then register a
> subject on a study. It commits the message immediately.
>
> void commit(gov.nih.nci.ccts.grid.Registration registration) throws
> RemoteException,
> gov.nih.nci.ccts.grid.stubs.types.InvalidRegistrationException,
> gov.nih.nci.ccts.grid.stubs.types.RegistrationConsumptionException ;
>
> Its an empty implementation since registration messages are always
> commit immediately.
>
> void rollback(gov.nih.nci.ccts.grid.Registration registration) throws
> RemoteException,
> gov.nih.nci.ccts.grid.stubs.types.InvalidRegistrationException,
> gov.nih.nci.ccts.grid.stubs.types.RegistrationConsumptionException ;
>
> rollbacks (or delete) the existing subject only if subject is assigned
> to one study site. If subject are assigned to more than one study
> site, method assumes that the subject was created from ui and it only
> deletes the study-subject assignments not the subject.

Following is an example of a SampleRegistrationMessage.xml that can be
consumed by this grid service:

\<?xml version=\"1.0\" encoding=\"UTF-8\"?\>

\<registration xmlns=\"gme://c3pr.cabig/2.0/edu.duke.cabig.c3pr.domain\"
gridId=\"gridStudy\"\>

\<studySite gridId=\"gridSite\"\>

\<healthcareSite\>

\<nciInstituteCode\>code\</nciInstituteCode\>

\</healthcareSite\>

\<irbApprovalDate\>2007-09-27T17:29:04.390-04:00\</irbApprovalDate\>

\<startDate\>2007-09-27T17:29:04.390-04:00\</startDate\>

\</studySite\>

\<studyRef gridId=\"gridStudy\"\>

\<shortTitleText\>ShortTitleText1\</shortTitleText\>

\<longTitleText\>LongTitleText1\</longTitleText\>

\</studyRef\>

\<participant gridId=\"AAAAA11111GridID\"\>

\<firstName\>Rudolph\</firstName\>

\<lastName\>Clooney\</lastName\>

\<administrativeGenderCode\>M\</administrativeGenderCode\>

\<address\>

\<streetAddress\>12359 sunrise valley drive\</streetAddress\>

\<city\>Reston\</city\>

\<stateCode\>VA\</stateCode\>

\<postalCode\>20191\</postalCode\>

\<countryCode\>USA\</countryCode\>

\</address\>

\<birthDate\>0006-06-23\</birthDate\>

\<raceCode\>White\</raceCode\>

\<identifier xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"
xsi:type=\"SystemAssignedIdentifierType\"\>

\<type\>MRN\</type\>

\<value\>MRN-12A!2121\</value\>

\<primaryIndicator\>false\</primaryIndicator\>

\<systemName\>C3PR\</systemName\>

\</identifier\>

\</participant\>

\<startDate\>2007-09-27\</startDate\>

\<informedConsentFormSignedDate\>2007-09-27\</informedConsentFormSignedDate\>

\<informedConsentVersion\>1.0\</informedConsentVersion\>

\<regDataEntryStatus\>COMPLETE\</regDataEntryStatus\>

\<regWorkflowStatus\>REGISTERED\</regWorkflowStatus\>

\<scheduledEpoch xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"
gridId=\"81b1da04-5c75-4c94-9422-fddc9d112147\"
xsi:type=\"ScheduledTreatmentEpochType\"\>

\<startDate\>2007-09-27\</startDate\>

\<epoch gridId=\"715c0242-f2d6-4bf4-9d21\"
xsi:type=\"TreatmentEpochType\"\>

\<name\>epoch1\</name\>

\</epoch\>

\<scheduledArm\>

\</scheduledArm\>

\</scheduledEpoch\>

\<stratumGroup\>0:lets find out1\</stratumGroup\>

\</registration\>

**[Study-consumer grid service]{.underline}**: This grid service extends
ctms study-consumer grid service. It consumes messages for creating
studies on a site. Currently, these messages are being sent by C3PR.
These messages are further processed and studies are created on a site.

**Public API**

This grid service extends ctms study-consumer-grid service. Following is
the interface that ctms study-consumer-grid service provides

**Interface StudyConsumer** {

void createStudy(final gov.nih.nci.ccts.grid.Study studyDto) throws
RemoteException, InvalidStudyException, StudyCreationException

> Process the study creation message sent by C3PR, and than register a
> study on a site. It commits the message immediately.
>
> void commit(final gov.nih.nci.ccts.grid.Study studyDto) throws
> RemoteException, InvalidStudyException
>
> Its an empty implementation since study creation messages are always
> committed immediately.
>
> void rollback(final gov.nih.nci.ccts.grid.Study studyDto) throws
> RemoteException, InvalidStudyException
>
> rollback (delete) the existing study.

**[study-service grid service]{.underline}**: This grid service provide
functionality of importing or exporting templates.

**Public API**

Following is the interface in this grid service

**Interface StudyService**{

> edu.northwestern.bioinformatics.studycalendar.grid.Study
> retrieveStudyByAssignedIdentifier(String assignedIdentifier) throws
> RemoteException, StudyDoesNotExistsException;
>
> Retrieves a study by a given assigned identifier.
> StudyDoesNotExistsException is thrown if no study found for given
> assigned identifier.
>
> edu.northwestern.bioinformatics.studycalendar.grid.Study createStudy(
> edu.northwestern.bioinformatics.studycalendar.grid.Study study) throws
> RemoteException,
> edu.northwestern.bioinformatics.studycalendar.grid.stubs.types.StudyCreationException;
>
> Creates a new study. This method does not edit any existing study. It
> only creates a new study and throws StudyCreationException if a new
> study can not be created.

# 8. Information Models {#information-models .unnumbered}

Patient Study Calendar follows a code-driven modeling approach, whereby
UML is used for communication among developers, documentation for the
domain, and a guide for future harmonization, but is not used directly
to generate software.

For additional models, please see:
[[http://gforge.nci.nih.gov/plugins/scmcvs/cvsweb.php/studycalendar/PhaseII/Construction/Iteration4/PSC_UML-P2-R3.EAP?cvsroot=studycalendar]{.underline}](http://gforge.nci.nih.gov/plugins/scmcvs/cvsweb.php/studycalendar/Release2/PSC_draft_UML.EAP?cvsroot=studycalendar)

# 9. Customized Tools {#customized-tools .unnumbered}

## Bering -- Incremental database development {#bering-incremental-database-development .unnumbered}

In support of Patient Study Calendar development we have developed a
tool called Bering. It enables database-independent incremental schema
development in a manner similar to ActiveRecord migrations in Ruby on
Rails.

The basic idea is this: say developer Alice needs to change the
structure or content of the database (e.g., to add a column to a table
or change the values in a lookup table). She writes a Bering migration
script encapsulating that modification and commits it alongside whatever
code makes use of the revised database. After developer Bob updates his
local working copy and receives Alice's new code, he can execute Bering
as part of his rebuild process. Bering discovers that there is a new
script which hasn't been applied to Bob's development database and
updates it automatically.

Using database migration scripts is superior to a single project schema
SQL file because it makes it easy for each developer to maintain his or
her own development/test database(s) -- and since each developer doesn't
have to spend time tracking down and manually applying schema changes
after each update, there is more time to do useful work. And since the
process is automatic, it can be used (in conjunction with a unit test
suite) by a continuous integration server to verify that the schema
changes don't break existing functionality.

The migration scripts can also be used when the application is deployed
in production and a new version becomes available. Since the scripts are
incremental, they can update a database with existing data as easily as
a development database (where you don't care about the contents). And
since Bering keeps track of which scripts have been applied to the
database, no developer time has to be spent writing special upgrade
scripts for end users.

Bering has been developed in parallel with Patient Study Calendar and
should be suitable for use in other projects. Its source is available
from <https://svn.bioinformatics.northwestern.edu/bering/trunk> and
includes an Ant task and some examples of use.

# References {#references .Appendix1}

## Technical Manuals/Articles {#technical-manualsarticles .unnumbered}

1.  National Cancer Institute. \"caCORE 2.0 Technical Guide\",
    <ftp://ftp1.nci.nih.gov/pub/cacore/caCORE2.0_Tech_Guide.pdf>

2.  Java Bean Specification:
    <http://java.sun.com/products/javabeans/docs/spec.html>

3.  Foundations of Object-Relational Mapping:
    <http://www.chimu.com/publications/objectRelational/>

4.  Object-Relational Mapping articles and products:
    <http://www.service-architecture.com/object-relational-mapping/>

5.  Hibernate Reference Documentation:
    <http://www.hibernate.org/hib_docs/reference/en/html/>

6.  Basic O/R Mapping:
    <http://www.hibernate.org/hib_docs/reference/en/html/mapping.html>

7.  Java Programming: <http://java.sun.com/learning/new2java/index.html>

8.  Javadoc tool: <http://java.sun.com/j2se/javadoc/>

9.  JUnit: <http://junit.sourceforge.net/>

10. Extensible Markup Language: <http://www.w3.org/TR/REC-xml/>

11. XML Metadata Interchange:
    <http://www.omg.org/technology/documents/formal/xmi.htm>

# Glossary {#glossary .Appendix1}

.

  -------------------------------------------------------------------------------
  ***Term***       ***Definition***
  ---------------- --------------------------------------------------------------
  API              Application Programming Interface

  caBIG            cancer Biomedical Informatics Grid

  CSM              Common Security Module

  DAO              Data Access Objects

  HTTP             Hypertext Transfer Protocol

  JAR              Java Archive

  Javadoc          Tool for generating API documentation in HTML format from doc
                   comments in source code (<http://java.sun.com/j2se/javadoc/>)

  JDBC             Java Database Connectivity

  JSP              JavaServer Pages

  JUnit            A simple framework to write repeatable tests
                   (<http://junit.sourceforge.net/>)

  MVC              Refers to the separation of Model, View, and Controller

  POJO             [Plain Old Java Object](http://en.wikipedia.org/wiki/POJO)

  ORM              Object Relational Mapping

  RDBMS            Relational Database Management System

  REST             Representational State Transfer

  SDK              Software Development Kit

  SQL              Structured Query Language

  UML              Unified Modeling Language

  UPT              User Provisioning Tool

  URL              Uniform Resource Locators

  WAR              Web Application Archive

  XMI              XML Metadata Interchange
                   (<http://www.omg.org/technology/documents/formal/xmi.htm>) -
                   The main purpose of XMI is to enable easy interchange of
                   metadata between modeling tools (based on the OMG-UML) and
                   metadata repositories (OMG-MOF) in distributed heterogeneous
                   environments

  XML              Extensible Markup Language (<http://www.w3.org/TR/REC-xml/>) -
                   XML is a subset of Standard Generalized Markup Language
                   (SGML). Its goal is to enable generic SGML to be served,
                   received, and processed on the Web in the way that is now
                   possible with HTML. XML has been designed for ease of
                   implementation and for interoperability with both SGML and
                   HTML
  -------------------------------------------------------------------------------