caTissue Upgrade notes

== p5 -> v1.2 ==

The first deployed version of caTissue at the LCBRU was v1.1.p5 - in April 2011 v1.2 was released.

Notes from initial upgrade testing:

jboss must be stopped before upgrade takes place, or it will fail.

Initial upgrade command is 'ant upgrade_p5'

Once database is correctly migrated, further deployments of the caTissue to account for changes to the caTissueInstall.properties file can be made by 'ant deploy_app'.

== v1.2 -> CaTissuePlus ==

In January 2013 we began a move to CaTissuePlus, formally supported by Krishagni. This co-incided with migration from the legacy hardware to the University LAMP service. Work was conducted and validated on https://lcbru-catissue-dev.rcs.le.ac.uk/ including testing the API client 'sampler' app.

There were a number of issues:

* Initially the API client failed because barcodes were being automatically assigned by CaTissue - this is the default behaviour of the application but LCBRU deployment approach is to disable this feature and assign all barcodes manually. This requires editing the LabelGenerator.Properties file as per the installation guide.

* There was a backend java / hibernate error reported regarding a missing column 'WUSTLKEY' which related to users being identified at login time. This did not affect the functioning of the API client but was resolved with a database amendment anyway:
> alter table csm_migrate_user change MIGRATED_LOGIN_NAME WUSTLKEY  varchar(100);

* There were issues with the use of the load balancer on the LAMP service and mod_proxy being used to forward requests, which meant that secure addressing was not required in WEB-INF/flex/services-config.xml - the my-secure-amf channel endpoint class needed to be changed to AMFEndpoint not AMFSecureEndpoint.

* The API 'sampler' app did not work with CaTissuePlus v2.0 -  JBOSS returned "ERROR 2013-01-23 11:45:21,814 -catissuecore.client.__CaCoreAppServicesDelegator - Delegate Editnull, java.lang.NullPointerException". A patched version was supplied by Atul Kaushal on 25.1.2013 which was tested and found to work on 28.1.2013. Further testing was conducted in parallel with live data processing that week.

Repeated testing with various database dumps from the live CaTissue v1.2 system are possible by dropping the database and creating it again, then loading the dump before running 'ant upgrade_db' from the catissue home directory. The csm_migrate_user fix above will need to be re-run each time. However, 'ant upgrade_db' did not successfully upgrade the database. Trying further testing with "upgrade_db_from_suitev1.2_to_plus20" but jboss cache problems are awkward. Connections are held in jboss/server/default/deploy/catissuecore-ds.xml and don't necessarily get updated when a new war file is deployed - which is only a problem if you change the database target between deployments!

Successful deployment and upgrade required the following process:
Installed db from dump into catissuecore: "mysql -p database_name < dumpfilename"
Checked caTissueInstall.properties
ant deploy_app
ant upgrade_db_from_suitev1.2_to_plus20
change the column name for the wustlkey problem
check that the jboss/server/default/catissuecore-properties/LabelGenerator.Properties file doesn't have the extra definitions which force barcode generation (i.e. comment out 'specimenLabelGeneratorClass' and 'specimenBarcodeGeneratorClass'
move and expand the war file, change the flex configuration class to solve the https / load balancer problem, recompress the war file and copy back to jboss
run the patch as above
test - restart jboss

== v1.2 -> CaTissuePlus v3.0 ==

In July 2013 Krishagni released v3.0 of CaTissuePlus. We hadn't completed satisfactory testing of version 2.0, partly because of server problems and partly because of issues with the API client application, so we moved immediately to deploying version 3.0 on the LAMP v2 development server: www15.lamp.le.ac.uk which adopted the alias "catissue-dev.lcbru.le.ac.uk"

The flex issue had been resolved. Installing was relatively smooth, but the LabelGenerator.Properties file did need amending. This can be done after deployment, and only requires a JBoss restart.

The database upgrade required several fixes but Krishagni provided a revised build.xml - satisfactorily used this to run "ant upgrade_db_from_plusv1.2_to_plusv3.0" - it throws a non-fatal error about an index being already created, but apart from that it works to upgrade the database. Then run "ant deploy_app" to deploy the new version of the app into the JBoss directory.

Following deployment, comment out the necessary lines in jboss/server/default/catissuecore-properties/LabelGenerator.Properties and run JBoss.