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.

...

1. One Oracle 10g/11g Schema with permissions for creating table and sequences
2. 4 Server machine with the following minimum configuration
   
   1. Dual core, 4GB RAM, 50 GB HDD x 2 – for BioMS cluster nodes
      
      1. Software required on these machines : RHEL 5.0+, Oracle Client (sqlldr, tnsping, sqlplus), ftp , p7zip, jboss 5.1
   2. Dual core, 4GB RAM, 50 GB HDDx1 -for caTissue 2.0A on BioMS, this machine should have oracle client installed on it. This is required for installing caTissue.
      
      1. Software required on this machine : RHEL 5.0+, Oracle Client (tnsping, sqlplus)
   3. Dual Core, 1GB RAM, 50 GB HDD x 1 – for the apache load balancer
      
   OS
   1. 1. Software required on this machine : RHEL 5.0+,apache
   JBoss

5.

...

5. Setup caTissue2.0A on BioMS

...

gridgrouper.isEnabled=false

load.balancer.url=<url at which users will be accessing this catissue, e.g url of the loadbalancer apache server, or external url of the catissue>

To install run ant install from the installer unpack folder


...

Follow the same steps give in Section 3.3 substituting all bioms-node1 with bioms-node2 to setup second node of the BioMS cluster on server BioMS node2

In node2 perform the following additional configuration.

1 Edit Edit $HOME/.bioms/bioms-config.groovy and update the following configuration

In the quartz section set autoStartup=false

Start the BioMS Node with the command

...

 # 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-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
 
 # Status worker for managing load balancer
 worker.status.type=status

Configure the worker uri map in Apache load balancer.Add the following uriworkermap.properties file in apache config

/bioms=loadbalancer

/bioms/*=loadbalancer

...

This will run the Mayo auth data sync every night at 10PM and output of the run would be logged to a file of the $HOME/.bioms/mayo-auth-sync/log/mayo-auth-sync.log.YYMMDD-HHmmSS

10. CTEP Authentication Setup

In QA and Production setup of BIoMS users of BioMS will be authenticated against the CTEP user registry. To enable CTEP authentication perform the following steps in both bioms nodes

1. Set the following environment variable in $HOEM/.bash_profile

      export CTSU_HOME=To test the sync job and trigger an immediate sync of the auth data run

$HOME/.bioms/mayo-auth-sync/sync-mayo-auth-data.sh > $HOME/.bioms/

...

mayo-auth-sync/log/mayo-auth-sync.log.`date +\%y\%m\%d-\%H\%M\%S` 2>&1

Once the execution is complete check the log file at $HOME/.bioms/bioms-config.groovy and in ctep section set enabled=true

    3. Restart the bioms JBOSS server.

To verify CTEP authentication is enabled, go to the bioms home page and it should show the CTEP login screen.

Image Removed

11. Participant Registration Sync Setup

Participant study registrations are pushed to bioms from the Mayo Rando Node application. Mayo Rando node invokes a BioMS url to push registration to BioMS. The invocation is protected by an authorization key shared with the Rando Node application. The authorization key for the rando node invocation is set by the property registration.webservice.user configured in the ~/.bioms/bioms-config.groovy. 

Securely share the value of this property and the registration service url which is <bms.baseURL>/integration/participantRegistration (eg. https://biomstest.wustl.edu/integration/participantRegistration)

12. Repository Sync

...

More details on the repository sync can be found here.

13. Administration

...

13.1. 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. Identify people who need to be informed when this repository connection to bioms breaks and the comma separated list of the emails of these people need to be set  in the COTACT column should below (<contact_emails>), e.g. admin@bioms.com, admin@pco.com

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

...

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 /mayo-auth-sync/log/mayo-auth-sync.log.nnnnnnnn and make sure there are no errors in the log.

10. CTEP Authentication Setup

In QA and Production setup of BIoMS users of BioMS will be authenticated against the CTEP user registry. To enable CTEP authentication perform the following steps in both bioms nodes

1. Set the following environment variable in $HOEM/.bash_profile

      export CTSU_HOME=$HOME/.bioms/conf/CTEP

    2. Edit $HOME/.bioms/bioms-config.groovy and in ctep section set enabled=true

    3. Restart the bioms JBOSS server.

To verify CTEP authentication is enabled, go to the bioms home page and it should show the CTEP login screen.

Image Added

11. Participant Registration Sync Setup

Participant study registrations are pushed to bioms from the Mayo Rando Node application. Mayo Rando node invokes a BioMS url to push registration to BioMS. The invocation is protected by an authorization key shared with the Rando Node application. The authorization key for the rando node invocation is set by the property registration.webservice.user configured in the ~/.bioms/bioms-config.groovy. 

Securely share the value of this property and the registration service url which is <bms.baseURL>/integration/participantRegistration (eg. https://biomstest.wustl.edu/integration/participantRegistration)

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.

More details on the repository sync can be found here.

13. Administration

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

13.1. 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. Identify people who need to be informed when this repository connection to bioms breaks and the comma separated list of the emails of these people need to be set  in the CONTACT column should below (<contact_emails>), e.g. admin@bioms.com, admin@pco.com

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

Here is the SQL for the inserting the repository data into the DB

Insert into BMS_REMOTE_REPOSITORY (ID,NAME,JMS_QUEUE_NAME,AUTHKEY,STATUS,LAST_HEART_BEAT_TIME,CONTACT) values ((select max(id)+1 from BMS_REMOTE_REPOSITORY),'<repo-name>','<repo-name>','<authkey>',1,SYSDATE,'<contact_emails>');

Securely share the <repo-name> and <authkey> and the bioms application url (the loadbalancer url) 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...

...

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 along with the coordinator user in the catissue and note the identifier of the Repository Site.
2. Get the details of the Repository Site and the Coordinator user Name 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 13.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>	<bms_repo_site_id>

   Here is the SQL command for this insert:

   Insert into BMS_REMOTE_REPOSITORY_SITE (REMOTE_REPOSITORY_ID,SITE_ID) values ((select id from BMS_REMOTE_REPOSITORY where name=<repo-name>),<bms_repo_site_id>

   just created from caTissue2.0A on BioMS.

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

6. 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)

   );

    

7. 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
   BMS_CATISSUE_ENTITY_MAP_SEQ.nextval	edu.wustl.catissuecore.domain.Site	<bms_repo_site_id>	<id_of_repo_site_in_catissue>

   Here is the SQL insert command for the same.

   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>

   <id_of

   ,<catissue_repo_site_

   in_catissue >

   id>);

   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.

   13.3. Building and rolling out new Study

...