Anchor_GoBack_GoBackBioMS 1.0 Setup and Admin Guide

Purpose

...

Introduction

...

Deployment

...

Pre-requisites

...

1. One Oracle 10g/11g Schema with permissions for creating table and sequences
2. 3 Server machine with the following minimum configuration
   1. Dual core, 4GB RAM, 50 GB HDD x 2 – for BioMS cluster nodes and caTissue on BIoMS. One of these machines should have oracle client installed on it. This is required for installing caTissue.
   2. Dual Core, 1GB RAM, 50 GB HDD x 1 – for the apache load balancer
3. OS : RHEL 5.0+
4. JBoss 5.1

Setup caTissue2.0A on BioMS

...

Setup BioMS on Bioms-node1

1. Get the BioMS 1.0 distribution from files.cbmi.wucon.wustl.edu: /files/bioms/1.0/RC1/bioms-1.0.zip and unpack into a folder (lets call this folder BIOMS_INSTALL_HOME)
2. Get JBoss 5.1 from here and unpack into a folder (lets call this JBOSS_HOME).
3. Copy the folder JBOSS_HOME/server/all/ to JBOSS_HOME/server/bioms-node1
4. Copy the contents of BIOMS_INSTALL_HOME/jboss-overlay onto JBOSS_HOME/server/bioms-node1/
5. Copy BIOMS_INSTALL_HOME/war/bioms.war to JBOSS_HOME/server/bioms-node1/deploy
6. Edit JBOSS_HOME/bin/run.conf and replace the JAVA_OPTS variable with the following

JAVA_OPTS="-Xms128m –Xmx2048m -XX:MaxPermSize=1024m -Dorg.jboss.resolver.warning=true -Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000 -Dgov.nih.nci.security.configFile=$HOME/.bioms/conf/ApplicationSecurityConfig.xml"

1. Edit JBOSS_HOME/server/bioms-node1/cong/login-config.xml and update the database connection details under the application-policy element with name 'bms' to point to the BioMS database schema.
2. Copy BIOMS_INSTALL_HOME/.bioms to users home folder ($HOME)
3. Edit $HOME/.bioms/ApplicationSecurityConfig.xml and replace ${user.home} with the home directory path of the user.
4. Edit $HOME/.bioms/bioms-config.groovy, and update the datasource section with the database connection details for the BioMS database schema.
5. Start the JBoss Server bioms-bioms-node1

run.sh –b0.0.0.0 –cbioms-node1 -u 239.255.100.100 –gBioMSPartition -Djboss.messaging.ServerPeerID=1
This will start the server and the BioMS application deployed. Try accessing the BioMS application at url http://<bioms-node1-server>:8080/bioms. Login to the application using credentials admin@bms.com/Passw0rd and we should see a page similar to the following snapshot.

S Setup BioMS on Bioms-node2

...

Setup the Apache load balancer

...

CTEP Authentication Setup

TODO

Mayo Authorization data Sync Setup

TODO

Participant Registration Sync Setup

TODO

Repository Sync

...

BioMS to caTissue Sync (forward Sync)

...

Study

...

• Coincident Epoch
• Coincident CPE
• Alternate Specimen
• Equivalent Specimen
• SpecimenRequirement. tubeType
• SpecimenRequirement.repository
• SpecimenRequirement.shippingType
• SpecimenRequirement.specimenForms
• SpecimenRequirement.preparationInstruction
• SpecimenRequirement.shippingInstruction

...

Participant

...

• firstname
• middleName
• lastName
• DOB
• race
• Ethnicity
• gender
• genomeType

Study Registration

StudyRegistration data comes from the Mayo RandoNode. Registration message contains a registration of a participant to Study and participant is automatically registered to all Epochs and Arms of the study. Participant registration messages are synced to those repositories where the study was originally synced. The following attributes of participarnt registration are synced

• protocolParticipantID (PPID)
• registrationDate
• participant
• protocol

When study registration is synced, all SCG and anticipated specimens for the participant stud registration is created in the caTissue repository. In each repository, specimen targeted (shipped to) that repository are mapped in the entity mapping table and all other anticipated specimens are marked 'Closed' and not mapped. The repository staff is not supposed to modify the specimen's marked closed, any modifications to those closed unmapped specimens will not be synced back to BioMS.
Note: For testing participant registration can be created in BMS using the temporary patientRegistration page. The participant registration page can be accessed at <bioms- base-url>/participantRegistration.

Specimen

...

Specimen Collected

...

• availableQuantiy
• initialQuantity
• collectionStatus (set to Collected)
• createdOnDate

...

• performedBy ( set to CRA who collected the specimen)
• timestamp
• container (set to the TubeType specified in the SpecimenRequirement)
• collectionProcedure (set to Not Specified)

The specimen would put in a storage position create on the BMS_Site_Container. BMS_Site_Container will hold the specimen until the specimen is moved to a 'InTransit' container, which happens when the specimen is shipped by collection site to a repository.

Specimen Pending

...

• availableQuantiy (set to 0)
• initialQuantity (set to 0)
• collectionStatus (set to Pending)

All other attribute will remain same including the collection event parameter.

Specimen Not Collected

...

• collectionStatus (set to Not Collected)
• comment (capturing the reason for not collected)

Shipment

...

• label (set to 'BMS shipment <shipment id>' )
• sendDate
• senderSite
• receiverSite
• senderContactPerson
• receiverContactPerson
• specimens
• activiityStatus (set to 'In Transit')

Specimen Forms

...

User

Whenever a CRA User is created/updated in BioMS as part of Sync of user data from Mayo DB, the user is synced to all the repositories. The user is synced to repository only for referential integrity and the CRA users will not be able login to repository caTissue. The User is used in reference for collected user, shipped by User etc. The CRA user won't have any role or privileges assigned in caTissue. The following attributes (all) of the User are synced.

• loginName
• lastName
• firstName
• emailAddress
• Institution
• Adrress
• activityStatus

Site

When a new collection site is created/update in BMS as part of sync of Site data from Mayo DB, the Site data is synced to all repositories. All the sites from mayo DB are created as Collection Site is BMS and caTissue. The following (all) attributes of Site are synced.

• name
• type
• Address
• activityStatus

CaTissue to BMS Sync (reverse Sync)

...

Study

...

Participant

Participants are created in BMS as part of processing RandoNode registrations. Reverse syncing of modifications (e.g participant name) to Participant should not be synced back to BMS because that could cause conflicts in BMS when multiple repositories change the values. Also the source of record for the participant data should be the registration system and the data should not be changes either in BMS or repository.
Question: Should we allow repositories to register participants to study via caTissue? If this is allowed then we would need to reverse sync participants to BMS. Any such reverse synced participant might needs to be synced to other repositories based on the study the participant is getting registered to.

Study Registration

Study registrations are creates in BioMS as part of processing RandoNode registrations. Modifications (e.g PPID) to registration should not be synced back to BioMS because that could cause conflicts in BioMS when multiple repositories change the values.

Specimen

...

...

Aliquots and Derivatives

All aliquots and derivatives of specimens that were synced from BMS will be reverse synced. All the attribute of those child specimens would be reverse synced. BMS users will not be able to see those child specimens in BMS, but can be seen through the associated caTissue instance.

Shipment

When a shipment sent from BMS is received at a repository, the status of the Shipment is updated and synced back to BMS.
The activityStatus of the shipment and all specimens contained in the shipment is set to 'Received' in BMS.

Specimen Collection Group

Specimen collection groups are created in caTissue during the participant registration sync. Repository users should not be creating any new collection groups.
Repository users can make modifications to Specimen Collection Group and the modifications would be synced back. The following attributes of the SCG will be synced back.

• activityStatus
• collectionStatus
• encounterTimeStamp

...

User

Any new user created in the repository or any updates to any existing users would be synced back to BioMS. Only the basic user information (i.e User and Address) information would be synced back to BioMS. No authentication or authorization information would be synced back to BioMS. This syncing of users created in caTissue is required to maintain the referential integrity for references to repository users that gets synced back to BioMS.

1. Purpose

This document is meant for the administrators of the BioMS application. This document describes the process of deploying the BioMS application and regular administration activities to be performed on the BioMS application.

2. Introduction

TODO

3. Deployment

The picture below shows the deployment model for the BioMS application with a two node Jboss cluster.

Image Added

BioMS 1.0 application is deployed with an instance of caTissue 2.0A  (shown as caTissue 2.0A on BioMS on the diagram above) which run against the same database schema BioMS is running on. This instance of caTissue is used for building specimen forms for use in BioMS, for generating reports on the specimen data stored in the BioMS DB and for performing some other administration activities.

BioMS application should be deployed in a JBoss cluster with minimum 2 nodes and front-ended by Apache http load balancer. BioMS application requires Oracle 10.3 Enterprise or above for database.
The sections below describe the steps for deploying the BioMS application.

4. Pre-requisites

Make sure the following pre-requisites are satisfied before starting the deployment of BioMS.

1. One Oracle 10g/11g Schema with permissions for creating table and sequences
2. 3 Server machine with the following minimum configuration
   
   1. Dual core, 4GB RAM, 50 GB HDD x 2 – for BioMS cluster nodes and caTissue2.0A on BioMS. One of these machines should have oracle client installed on it. This is required for installing caTissue.
   2. Dual Core, 1GB RAM, 50 GB HDD x 1 – for the apache load balancer
3. OS : RHEL 5.0+
4. JBoss 5.1

5. Setup caTissue2.0A on BioMS

Get the caTissue 2.0A installer from file.cbmi.wucon.wustl.edu:/files/bioms/1.0/RC1/caTISSUE_Suite_v2.0_Installable.zip and unpack in BioMS Node 1 server. Follow the caTissue 2.0 installation instruction to install caTissue to the BioMS database. This caTissue should be installed with all caTissue external system integrations like GSID, CTRP and C3PR disabled in install.properties. Also choose a different set of JBOSS port numbers to avoid conflict with the BioMS JBoss node running on the same server.

6. Setup BioMS on Bioms-node1

1. Get the BioMS 1.0 distribution from files.cbmi.wucon.wustl.edu:/files/bioms/1.0/RC1/bioms-1.0.zip and unpack into a folder (lets call this folder BIOMS_INSTALL_HOME)
2. Get JBoss 5.1 from here and unpack into a folder (lets call this JBOSS_HOME).
3. Copy the folder JBOSS_HOME/server/all/ to JBOSS_HOME/server/bioms-node1
4. Copy the contents of BIOMS_INSTALL_HOME/jboss-overlay onto JBOSS_HOME/server/bioms-node1/
5. Copy BIOMS_INSTALL_HOME/war/bioms.war to JBOSS_HOME/server/bioms-node1/deploy
6. Edit JBOSS_HOME/bin/run.conf and replace the JAVA_OPTS variable with the following

JAVA_OPTS="-Xms128m –Xmx2048m -XX:MaxPermSize=1024m -Dorg.jboss.resolver.warning=true -Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000 -Dgov.nih.nci.security.configFile=$HOME/.bioms/conf/ApplicationSecurityConfig.xml"

1. Edit JBOSS_HOME/server/bioms-node1/cong/login-config.xml and update the database connection details under the application-policy element with name 'bms' to point to the BioMS database schema.
2. Copy BIOMS_INSTALL_HOME/.bioms to users home folder ($HOME)
3. Edit $HOME/.bioms/ApplicationSecurityConfig.xml and replace ${user.home} with the home directory path of the user.
4. Edit $HOME/.bioms/bioms-config.groovy, and update the datasource section with the database connection details for the BioMS database schema.
5. Start the JBoss Server bioms-bioms-node1

run.sh –b0.0.0.0 –cbioms-node1 -u 239.255.100.100 –gBioMSPartition -Djboss.messaging.ServerPeerID=1
This will start the server and the BioMS application deployed. Try accessing the BioMS application at url http://<bioms-node1-server>:8080/bioms. Login to the application using credentials admin@bms.com/Passw0rd and we should see a page similar to the following snapshot.

7. Setup BioMS on Bioms-node2

Follow the same steps give in Section 3.3 substituting all bioms-bioms-node1 with bioms-bioms-node2 to setup second node of the BioMS cluster.
Start the BioMS Node with the command
run.sh –b0.0.0.0 –cbioms-bioms-node2 -u 239.255.100.100 –gBioMSPartition -Djboss.messaging.ServerPeerID=2
Once the bioms-node2 server is started make sure bioms-node2 bioms is accessible at http://<bioms-node2-server>:8080/bioms

8. Setup the Apache load balancer

Install apache HTTP server and configure mod_jk module and use the following mod_jk worker configuration

 # Define list of workers that will be used
 # for mapping requests
 worker.list=loadbalancer,status
 
 # Define Bioms-node1
 # modify the host as your host IP or DNS name.
 worker.bioms-bioms-node1.port=8009
 worker.bioms-node1.host=<bioms-node1-host> 
 worker.bioms-node1.type=ajp13
 worker.bioms-node1.lbfactor=1
 worker.bioms-node1.cachesize=10
 
 # Define Bioms-node2
 # modify the host as your host IP or DNS name.
 worker.bioms-node2.port=8009
 worker.bioms-node2.host=<bioms-node2-host> 
 worker.bioms-node2.type=ajp13
 worker.bioms-node2.lbfactor=1
 worker.bioms-node2.cachesize=10
 
 # Load-balancing behaviour
 worker.loadbalancer.type=lb
 worker.loadbalancer.balance_workers=bioms-node1,bioms-node2
 worker.loadbalancer.sticky_session=1
 #worker.list=loadbalancer
 
 # Status worker for managing load balancer
 worker.status.type=status

9. CTEP Authentication Setup

TODO

10. Mayo Authorization data Sync Setup

TODO

11. Participant Registration Sync Setup

TODO

12. Repository Sync

BioMS application run integrated with tissue repository caTissue application. When the BioMS application is integrated with repository caTissue application it automatically synchronizes specimen data and shipment data between BioMS and caTissue to keep the data in sync across the two application. BioMS application can be configured to sync with multiple repository caTissue instances.

The sections below lists out all the data that gets synced between BioMS and caTissue.

Administration

This section describes various ongoing administrative tasks to be performed on the BioMS application.

...

1. Assign a unique name for the repository (<repo-name>)caTissue instance. E.g pco-repo.
2. Assign a secret authorization key (<authkey>) for the repository

3. Add new row to the BMS_REMOTE_REPOSITORY table in the BioMS database with the following data.

   ID	NAME	JMS_QUEUE_NAME	AUTHKEY	STATUS
   1 (max (id) +1)	<repo-name>	<repo-name>	<authkey>	1

   
   Securely share the <repo-name> and <authkey> with the repository caTissue admin. They would need to update the bioms-adaptor.properties with these details.
   Once the bioms-adaptor is setup properly at the repository caTissue and started you should see message like
   controller.RepoSyncMessageController 2012-10-08 09:59:11,996 Sending 204 (no message available) to repo <repo-name>
   in the bioms log.
   Also messages like the following would be there on the BioMS adaptor log file.
   5:01:14,745 INFO [STDOUT] 2012-10-08 15:01:14 SyncMessageReceiver [DEBUG] No mssage received, sleep for 10sec before trying again...

   Setup a new Repository Site

...

1. Request the caTissue Admin to create Repository Site and the repository coordinator user with the same details like name and address and note the ids of the Site and User created.
2. Get the details of the Repository Site and the Coordinator user details from the repository caTissue admin.
3. Create a Site of type Repository in BioMS via the 'caTissue2.0A on BioMS' and select the coordinator user created by the caTissue admin as the coordinator (this user would have been synced to BioMS automatically). Note the id of the site as <bms_repo_site_id> just created from caTissue2.0A on BioMS.

4. Link the repository site created above with the caTissue remote repository created in step 5.1. For this insert a new row into the BMS_REMOTE_REPOSITORY_SITE table as shown below.

   REMOTE_REPOSITORY_ID	SITE_ID
   <id of the remote repo entry for the remote repo>	<site_id>

5. Map the new Site created in BioMS with the Repository with the same name in caTissue. For this request the repository caTissue admin to insert the following row into BMS_CATISSUE_ENTITY table in the repository caTissue data base

   ID	ENTITY_TYPE	BMS_ID	CATISSUE_ID
   1 (or the next available id)	edu.wustl.catissuecore.domain.Site	<bms_repo_site_id>	<id_of_repo_site_in_catissue >

   
   
   We should now be able to create studies with the new repository as the ship to site for specimen and sync the studies. When the study is synced study should show up in the caTissue.

   Building and rolling out new Study

...