BioMS 1.0 Setup and Admin Guide

Purpose

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

Introduction

TODO

Deployment

The picture below shows the deployment model for the BioMS application with a two node Jboss cluster.
BioMS 1.0 Deployment ModelJBoss 5.1
BioMS node 1BioMS ORACLE DBJBoss 5.1
BioMS node2BioMS clusterApache http server load balancercaTissue2.0A on BioMSFrom BioMS adaptorCRAs, SM, AdminStudy Manager, BioMS Admin
BioMS 1.0 application is deployed with an instance of caTissue 2.0A which run against the same database schema BioMS is running on. This instance of caTissue is used for configuring specimen forms for use in BioMS and 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 load balancer. BioMS application requires Oracle 10.3 Enterprise or above for database.
The sections below describe the steps for deploying the BioMS application.

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 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

Get the caTissue 2.0A installer from files. cbmi.wucon.wustl.edu: /files/bioms/1.0/RC1 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 should be 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.

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

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

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 requestsworker.list=loadbalancer,status # Define Bioms-node1# modify the host as your host IP or DNS name.worker.bioms-bioms-node1.port=8009worker.bioms-node1.host=<bioms-node1-host> worker.bioms-node1.type=ajp13worker.bioms-node1.lbfactor=1worker.bioms-node1.cachesize=10 # Define Bioms-node2# modify the host as your host IP or DNS name.worker.bioms-node2.port=8009worker.bioms-node2.host=<bioms-node2-host> worker.bioms-node2.type=ajp13worker.bioms-node2.lbfactor=1worker.bioms-node2.cachesize=10 # Load-balancing behaviourworker.loadbalancer.type=lbworker.loadbalancer.balance_workers=bioms-node1,bioms-node2worker.loadbalancer.sticky_session=1#worker.list=loadbalancer # Status worker for managing load balancerworker.status.type=status

CTEP Authentication Setup

TODO

Mayo Authorization data Sync Setup

TODO

Participant Registration Sync Setup

TODO

Repository Sync

BioMS application can be integrated with tissue repository caTissue application. 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 BioMS and repository caTissue. The sections below lists out all the data that gets synced between BioMS and caTissue.

BioMS to caTissue Sync (forward Sync)

A general rule applied on the sync of entities from BMS to Catissue is that entities are only synced to caTissue hosting those repositories where the entity would physically belong or is referenced by an entity that physically belong. E.g Specimen status updates are synced only to those caTissue repositories where the specimen would be shipped to.

Study

A study built in BMS will be synced to repositories on an explicit sync action from the Study Manager. When a study is completely built and is ready to be send to repositories Study manger will initiate a sync action by clicking the 'Synchronize Study' on build study UI. All study data except the following will be synced. These attributes/relations could not be synced because they are not captured in the caTissue domain model.

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

Note: A Study would be synced (in its entirety) to only those repositories which receive at least one specimen from the study.

Participant

Participant data comes from the mayo RadoNode as part of the participant registration message. Whenever a new registration message is received from the RandoNode and new participant data is inserted into BioMS, the participant is synced to all the repositories. All the attributes (listed below) of the participant would be synced to all repositories linked to BioMS.

• 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

Whenever specimen status changes in BioMS the updated specimen data is synced to the repository caTissue to which the specimen would be shipped to.

Specimen Collected

When a specimen is marked Collected by a CRA in BioMS, the following attributes of the specimen would be synced to the repository which would hold the specimen

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

Specimen CollectionEventParameter also will be added to the specimen with the following information.

• 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

When the specimen is moved back to Pending state from collected in BMS the following attributes of the specimen would be updated

• 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

When a specimen is marked Not Collected in BMS , the specimen status and the comment that captures the reason for not collected are synced to repository.

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

Shipment

Shipments created in BioMS are synced to the repository were the shipment is addressed to. The shipment is synced to repository when the CRA sends the shipment in BioMS. The following attributes of the shipment are synced.

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

Specimen Forms

Specimen form definition sync is not yet implemented. So whenever a Study Manager(SM) defines specimen form for BioMS via caTissue running on BioMS DB, SM manager has to share the form details to all the repository caTissue admins. Repository caTissue admins should define the forms in their caTissue and run generate:cacore:all build target to complete the form definition in caTissue. The form name and form attribute names, type and other constraints should match exactly with the form created in the BioMS.
Whenever a CRA, enter data on the specimen form in the checklist view, the form data is synced to repository to which the specimen gets synced. All attributes of the specimen form are synced and attached to the specimen via SpecimenRecordEntry. Once the form is synced from BioMS, repository users would be able to see the form data in the Annotations tab for the specimen in the caTissue.

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)

Whenever specimen data originally synced from BioMS changes in the repository, the updates are synced back to BioMS to keep the data in sync. But Study , Participant and Participant Registration data doesn't get synced back to BioMS because, BioMS is the source of record for that data and repository users are not allowed to change that data.

Study

Studies that were created in caTissue as sync from BMS are not reverse synced because the BMS should be source of record for the Study definition and repositories should not be changing the study. If we allow reverse sync study modifications it could cause conflicts in BMS when different repositories make different kinds of modifications to the 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

Any modifications to Specimens that are originally synced from BMS or their derivatives are reverse synced to BMS. Here are the attributes that are reverse synced to BMS. Since each specimen is held only at one repository all the changes should come from only one repo and should not cause any conflicts in BioMS. Here are the list of attributes that are reverse synced to BMS.

Once the specimen is received at the repository label, barcode, availableQuantity, initialQuantity, globalSpecimenIdentifier (if assigned at caTissue) and ReceivedEventParameters will be synced to BMS. BMS wont have these values assigned until the shipment containing the specimen is received at repository.

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

Issue: If multiple repositories changes the SCG it would cause a conflict in BMS and data across BMS and repositories will become out of sync.

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.

Administration

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

Setup sync with a repository caTissue 2.0A

Given below are steps for linking a new repository caTissue instance to BioMS for data synchronization.

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

Once the repository caTissue instance is linked with BioMS as described above the follow the steps below to setup a new Repository Site for sync. A single caTissue instance can host multiple independent repository sites and BioMS can handle that.

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

Note: This section needs to be revised based on the business process
This section describes the steps for building and rolling out a new Study in BioMS.

1. Identify the specimen form requirements for the study and if there is any specimen form required, build the form using the Local Extensions feature in the caTissue2A on BioMS. The form needs to be added to the form group with name bmsforms. Only these forms in this group will be available for selection in BioMS study builder.

The current version of BioMS has some restrictions on form fields and constraints and doesn't support all the capabilities of forms that could be created in caTissue. Given below is the summary of what is supported in the BioMS specimen forms.
Textfield (string ,numeric,URL datatypes and width, max length, min and max constraints are supported)TextArea ( width, max length and rows constraints are supported)CheckboxRadion ButtonListBox ComboBoxDate picker (Date only) File picker is not supported at this time.Also form inheritance and forms associations are not supported .

Watching for Sync issues

BioMS admin can see if there are any happening during syncing of data between BioMS and repository caTissue at <bioms-base-url>/syncError . This page lists all the erros occurred during the sync with the sync message and the error details including any stack trace.
BioMS admin should review this list of error at least once in a day to make sure sync functions are working properly.