BioMS Adaptor for caTissue 2.0A Setup Guide

1. Introduction

BioMS Adaptor component of the BioMS application is deployed with and linked to the repository management software (e.g. caTissue) and handles synchronization of data between the repository software and the BioMS application. BioMS adaptor periodically pulls data from the BioMS application via HTTPS connection to the BioMS and updates the repository database. Also any modifications to specimen data happening in the repository are reverse synced to BioMS application by the BioMS Adaptor.

The data that is synchronized from BioMS to repository is

1. Study definition
2. Patient registration
3. Specimen collection data (Collection date, quantity, collection event parameters)
4. Shipment (sent from BioMS to repository)
5. BioMS user data
6. Collection Site data

Data that is synchronized to BioMS from repository are

1. Updates to specimens synced from BioMS
   
   1. Label, barcode, quantity changes, bio hazards, external identifiers event parameters created/updates
   2. aliquots and derivatives created and any updates to them
2. Changes to status of shipment received from BioMS
3. New users created in repository (only user data not authn/authz) data

The remaining of this document describes the process of deploying and configuring the BioMS Adaptor for caTissue 2.0A. Given below is block diagram depicting the various components in a BioMS Application eco system.

BioMS Adaptor for caTissue 2.0A is basically a war file that should to be deployed on the same JBoss server where the caTissue 2.0A is deployed. The adaptor accesses and modifies the caTissue data via caTissue client API. The adaptor maintains a mapping of the bioms id to local caTissue id for every object that gets synced across BioMS and caTissue. This mapping is maintained in the BMS_ENTITY_MAPPING table in the caTissue databas and is very crucial for the sync to work.

Please refer to the BioMS Repo Sync design document for more details on the repository sync functions.

2. Install caTissue 2.0A

Get the caTissue 2.0A installer from the location shared by the BioMS team.

Follow the caTissue 2.0 installation instructions to install caTissue web application. 

Typical installation involves changi the following properties in the install.properties

application.base.path.linux=/usr/local/bms/catissue20A-webapp

# Required for local installs
database.re-create=false
database.system.user=    (this property should be left empy)
database.system.password=(this property should be left empy)
database.system.url=<db connection url>

# Require for all installs
database.drop-schema=true
database.type=oracle
database.server=<DB SERVER NAME>
database.port=1521
database.name=<DB NAME>
database.user=<DB USER NAME>
database.password=<DB PASSWORD>
database.url=<DB URL>
oracle.tns.name=<TNS NAME>

#CSM DATABASE CREDENTIALS

csm.database.type=oracle

csm.database.host=<DB SERVER NAME>

csm.database.port=1521

csm.database.name=<DB NAME>

csm.database.username=<DB USER NAME>

csm.database.password=<DB_PASSWORD>

gsid.isEnabled=false

ccts.integration.isEnabled=false

ctrp.isEnabled=false

gridgrouper.isEnabled=false

load.balancer.url=<base catissue url at which the users would access the catissue instance, e.g if there is a front end http server the URL of the loadbalance will be set here>

To install run ant install from the installer unpack folder


To upgrade an existing installation to a newer build , update the install.properties as detailed above and run ant upgrade:jboss from the installer unpack folder. Make sure the database properties in the install.properties is pointing to the database where the current catissue is running.

Lets assume caTissue was installed at CATISSUE_HOME folder in the above step.Once the installation is complete, edit CATISSUE_HOME/jboss-5.1.0.GA/bin/run.conf and replace the JAVA_OPTS value with

JAVA_OPTS="-Xms128M -Xmx2024M -XX:MaxPermSize=1024M -Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false"

Note: No new Users or Sites should be created in caTissue until the BioMS Adaptor is setup and linked to BioMS. Follow the steps below to deploy the BioMS Adaptor and link with BioMS.

3. Deploy BioMS Adaptor for caTissue 2.0A

Note: Deploy of BioMS Adaptor needs to be done in coordination with some configuration in BioMS application. Contact BioMS application administrator before starting BioMS Adaptor setup.

Download the BioMS Adaptor installable zip from the location shared by the bioms team and unpack to a folder.This will create a folder bioms-adaptor and will be referred as BA_HOME in the remaining of this document.

The BioMS Adaptor would be deployed on the same JBoss server were the repository caTissue 2.0A is deployed. Follow the steps given below to deploy BioMS Adaptor.

1. Create BMS Site and BMS Admin User entities in the repository caTissue2.0A  seup above

1. 1. Follow the steps below to create a User named BMS Admin with Super Administrator privileges and set a password
      
      1. Login to catissue as a super admin user (e.g. admin@admin.com)
      2. Go to menu Administrative Data-> User - > Add and enter the following details and click Submit.

email id : admin@bms.com

Last Name : BMS , First Name : Admin

City : Other, State : Other, zipcode: 0, Phone Number: 0

Institution : Other_Institution, Department: Other_Department,  Cancer Research Group : Other_CancerResearchGroup

Role : Super Administrator

iii. Once the user is created,  update the password for the user and click 'Submit' again. 

Note down the emailid and the password set in the above step as catissue.username and catissue.password, these would be required in the BioMS adaptor configuration later.
Note: This is service user account and would be used by BioMS adaptor to sync data from BioMS to catissue and repository users will not usually login with this user id.

b.  Follow the steps below to create a Site named BMS Repo of type Repository and select BMS Admin user created above as the site coordinator

1. 1. 1. Login to catissue as a super admin user (e.g. admin@admin.com)
      2. Go to menu Administrative Data-> Site- > Add and enter the following details and click Submit.

Site Name: BMS Site

Type: Repository

Coordinator : BMS, Admin

Street : Other

c.  Follow the steps below to a Create Shipment Container BMS_Site_Container

1. 1. 1. Login to catissue as admin@admin.com
      2. Go to menu Administrative Data-> Site Container- > Add and enter the following details and click Submit.

Type : Shipment Container

Parent Location Details : Site , BMS Repo Site

No. of containers : 1

Temperature : -80

X: 1

Y: 1

keep the default values for every thing else

1. 1. 1. Click on Submit.
      2. On the next page, update the Name field of the container to BMS_Site_Container and click Submit.
         
         

2. Stop caTissue2.0A JBoss server.

3. Run the following sql scripts on the caTissue DB

Insert into CSM_USER (USER_ID,LOGIN_NAME,FIRST_NAME,LAST_NAME,EMAIL_ID,UPDATE_DATE) values (CSM_USER_USER_ID_SEQ.NEXTVAL,'dummy','dummy','dummy','dummy@bms.com',SYSDATE);

Select user_id from csm_user where login_name='dummy';

Note down the value of the user_id returned by the select command output as 'catissue.dummyCSMUserId', this would be required in the BioMS adaptor configuration later.

Note: This CSM user will be linked to all the users that gets pushed to repository caTissue from BioMS.

4. Create a new folder CATISSUE_HOME/ jboss-5.1.0.GA/server/default/deploy/deploy.last

5. Copy $BA_HOME/war/bioms-adaptor.war to deploy.last folder created above

6. Copy the $BA_HOME/.bioms folder to the home folder ($HOME) of the user who will be starting the caTissue2.0A JBoss

7. Edit $HOME/.bioms/bioms-adaptor.properties and set the properties as explained in the Section 4, below. Values for some of the properties need to be provided by the BioMS administrator.

8. Edit $HOME/.bioms/log4j.properties and replace ${user.home} with the actual value of home directory path of the user who will be starting the jboss (e.g. /home/catissue)

9. Start JBoss server. Take a look at the BioMS adaptor log file at $HOME/.bioms/logs/bioms-adaptor.log. You should notice messages like the following in the log without any errors

18:11:55,852 INFO  [STDOUT] 2012-10-08 18:11:55 SyncMessageReceiver [DEBUG] No mssage received, sleep for 10sec before trying again...

18:11:58,113 INFO  [STDOUT] 2012-10-08 18:11:58 CaTissueChangeListener [DEBUG] Fetching record from Catissue event
 

10. Once, bioms Adaptor has started successfully, run the following sql scripts on the caTissue DB after replacing the <bms_bmsadmin_id> and <catissue_bmsadmin_id> with the appropriate values as described below.

<bms_bmsadmin_id> : Identifier of the BMS Admin user from the BoiMS server (to be obtained from BioMS admin)

<catissue_bmsadmin_id> : Identifier of the BMS Admin user created in the repository caTissue per step 1.a above. The id can be obtained by by going to caTissue menu Administrative Data -> User -> Edit and click on Search, note the Identifier column value for the line with loginname=admin@bms.com

Insert into BMS_CATISSUE_ENTITY_MAP (ID,ENTITY_TYPE,BMS_ID,CATISSUE_ID) values (BMS_CATISSUE_ENTITY_MAP_SEQ.NEXTVAL,'edu.wustl.catissuecore.domain.User',1,1);

Insert into BMS_CATISSUE_ENTITY_MAP (ID,ENTITY_TYPE,BMS_ID,CATISSUE_ID) values (BMS_CATISSUE_ENTITY_MAP_SEQ.NEXTVAL,'edu.wustl.catissuecore.domain.User',<bms_bmsadmin_id>,<catissue_bmsadmin_id>);

4.BioMS Adaptor properties

Note : The properties marked bold needs to be obtained from the BioMS administrator.

6. Setup Repository Site for Synchronization with BioMS

Setting up new Repository Site and enabling data synchronization for the repository is a process requiring co-ordination between the repository caTissue admin and BioMS admin. Contact the BioMS administrator to setup a new repository site in caTissue for sync with BioMS.

6.1 Creating a repository site in caTissue

caTissue administrators can create repository sites in caTissue by going to menu Administrative Data - > Site -> Add. Enter the following details for the Site

Site Name: <your repository name>

Type: Repository

Coordinator : Select the co-ordinator user if already there or create a new user by clicking on 'Add New'. If the coordinator is known at the time of creating the Repository, create a temporary co-ordinator user, e.g coord@<repo-domain>. This can be changed to actual co-ordinator when an actual co-ordinator is assigned to the repository and the user has signed up in the caTissue.

The address and contact details will be populated from the user details, correct it if required and enter the Street address of the repository.

Click on submit.

Refer caTissue documentation for more details for creating a Site in caTissue.

6.2 Linking the repository site for sync

Go to menu Administrative Data - > Site ->Edit and note down the Identifier of the repository just created as <catissue_repo_site_id> and inform BioMS administrator about the new repository creation. At this point BioMS administrator has to create the repository Site in BioMS and get the id of the repository as <bms_repo_site_id>. Execute the following SQL insert command on the repository catissue DB to map the repository sites just created.

Insert into BMS_CATISSUE_ENTITY_MAP (ID,ENTITY_TYPE,BMS_ID,CATISSUE_ID) values (BMS_CATISSUE_ENTITY_MAP_SEQ.NEXTVAL,'edu.wustl.catissuecore.domain.Site',<bms_repo_site_id>,<catissue_repo_site_id>);