VIVO Release 1 v1.2 Upgrade Guide

January 28, 2011 - Upgrading from Release 1 v1.1 to Release 1 v1.2

Missing pieces and fixes

Link to install pdf online at SF

Release announcement for V1.2
Upgrade process for V1.2

This document provides a short description of the steps involved in upgrading your installation of VIVO from Release 1, Version 1.1 to Version 1.2. This and other documentation can be found on the support page at VIVOweb.org

If you need to do a fresh install, please consult VIVO Release 1 v1.2 Installation Guide or the install.html file located in the doc directoy of the VIVO source code distribution.

Release anouncement for V1.2

Text from the wiki page

Verify Ontology upgrade process
Ontology knowledge base manual review

Theme Modifications

I. Before Performing the Upgrade

Please ensure that backups are created of the:

Tomcat webapps directory
Original source directory
MySQL database (mysqldump)

The upgrade process is similar to the original install process with the following EXCEPTIONS:

DO NOT reinstall MySQL or recreate the MySQL database. Please ensure that you back-up the MySQL database.
It is not necessary to add RDF data.
First-time login of the administrator account after the upgrade process is complete will use the password previously set, NOT the default password used on the first login after the initial installation.
The first time Apache Tomcat starts up after the upgrade, it will initiate a process that modifies the knowledge base to align the data with the revised ontology. See the section on the Ontology Upgrade below for more information.

The Upgrade Process

Download the new distribution file and unpack it into a new source directory.
Create deploy.properties, using the same values as in your previous installation and set values for the new variables.
Apply any previous changes you have made to the new source directory.
Special notes regarding source files
- This process assumes any changes made to the application were made in the source directory and deployed, and were not made directly within the Tomcat webapps directory.
- In many cases, simply copying the modified files from your original source directory will not work since the files on which they are based have changed. It will be necessary to inspect the new source files and add any changes to them at that time.
- NIH-funded VIVO Implmentations will need to apply the Google Analytics Tracking Code (GATC) to googleAnalytics.ftl in the theme:
```
[new_source_directory]/themes/[theme_dir]/templates/googleAnalytics.ftl
```
  A sample googleAnalytics.ftl is included in the built-in theme. This file serves only as an example, and you must replace the tracking code shown with your institution's own tracking code. For additional information about the GATC for the NIH-funded VIVO implementation sites and a copy your institution's tracking code, see the VIVO Google Analytics wiki page.
- If you had used the vivo/contrib/FLShibboleth code in your previous release, you should stop using it. Consult install.html or VIVO Release 1 v1.2 Installation Guide on "Using an External Authentication System with VIVO".
If you had modified web.xml to configure the Pellet Reasoner (as described in the installation instructions), repeat that modification.
Stop Apache Tomcat and run ant by typing: ant all
Start Apache Tomcat and log in to VIVO.



-------------------------------------------------------------------------------

III. Ontology Changes

A. Verify Ontology upgrade process

After Apache Tomcat is started, these files should be reviewed to verify that
the automated upgrade process was executed successfully.  The ontology alignment 
process will create the following files in the Tomcat webapps/vivo/WEB-INF directory:

ontologies/update/logs/knowledgeBaseUpdate.log 
    A log of a summary of updates that were made to the knowledge base and notes 
    about some recommended manual reviews. This file should end with
    "Successfully finished processing ontology changes".
    
ontologies/update/logs/knowledgeBaseUpdate.error.log 
    A log of errors that were encountered during the upgrade process. This file
    should be empty if the upgrade was successful.
    
ontologies/update/changedData/removedData.n3
    An N3 file containing all the statements that were removed from the knowledge base.
    
ontologies/update/changedData/addedData.n3
    An N3 file containing all the statements that were added to the knowledge base.

B. Ontology knowledge base manual review

Changes to the VIVO core ontology may require corresponding
modifications of the knowledge base instance data and local ontology
extensions.

When Apache Tomcat starts up following the upgrade, it will initiate 
a process to examine the knowledge base and apply necessary changes.
Not all of the modifications that may be required can be automated,
so manual review of the knowledge base is recommended after the
automated upgrade process. The automated process will make only 
the following types of changes:

  Class or Property renaming
    All references to the class (in the subject or object position) will
    be updated to the new name. References to the property will be
    updated to the new name.
  
  Class or Property deletion
    All individuals in a deleted class will be removed.
   
    All statements using a deleted property will be changed
    to use the nearest available superproperty. If there is no available
    superproperty then the statement will be deleted from the
    knowledge base. Note that all removed and added data
    is recorded in the files in the changedData directory.
    
  Property addition
    If a newly added property is the inverse of a previously
    existing property, the inverse of any statements using the
    pre-existing property will be asserted.

  Annotation property default values
    If a site has modified the value of a vitro annotation (such as
    displayRankAnnot or displayLimitAnnot) so that it is
    no longer using the default, then that setting will be left unchanged.
    If a site is using the default value of a vitro annotation, and the
    default has been changed in the new version of the ontology, then
    the new default value will be propagated to the knowledge base.

-------------------------------------------------------------------------------

IV. Theme Changes

VIVO 1.1 introduces the first step in a transition from JavaServer Pages (JSPs)
to the FreeMarker template engine for generating web pages. As part of this 
process, the JSP files that were used for theme customization in earlier 
versions of VIVO have been replaced by a set of FreeMarker templates. 
In the 1.1 install package, these files are located in 
/vivo/themes/vivo-basic/templates and have an ftl (for FreeMarker Template
Language) extension.

Follow step A or B below, whichever is applicable to your site:

A. If you did not create a customized theme for your site in VIVO 1.0, but used
the 1.0 vivo-basic theme in its original directory, you need not take any 
action in order to convert your site to the VIVO 1.1 theme.

B. If you created your own theme directory in VIVO 1.0, follow the steps below
under sections "Templates," "Stylesheets,"  and "Site Icons" to upgrade your 
theme to VIVO 1.1.

    1. Templates

       a. Copy the directory /vivo/themes/vivo-basic/templates into your theme
          directory /vivo/themes/.

       b. Follow step i or ii below, whichever is applicable to your theme. 

           i. If you did not apply any customizations to the JSPs in your VIVO  
              1.0 theme, then you do not need to apply any additional changes 
              to the VIVO 1.1 theme templates during the upgrade process.

           ii. If you did apply customizations to the JSPs in your VIVO 1.0  
               theme,you will need to hand-replicate those modifications in the 
               new theme template files. 
           
               The theme template content that was previously contained in 
               three JSP files is now contained in five FTL files. The 
               correspondence between the 1.0 JSPs and the 1.1 FTLs is as 
               follows:
               
                   identity.jsp => identity.ftl
                   menu.jsp => menu.ftl and search.ftl
                   footer.jsp => footer.ftl and googleAnalytics.ftl
    
               googleAnalytics.ftl is a new file to which you will add
               your site's Google Analytics Tracking Code (see section II).
           
               Because the FreeMarker Template Language uses many syntactic 
               conventions that will be familiar to template authors from JSP 
               or other common templating systems, the translation of your JSP 
               changes into the new FTLs should be relatively straightforward. 
   
               Consult the FreeMarker Template Author's Guide at 
               http://freemarker.org/docs/dgui.html and the Reference at 
               http://freemarker.org/docs/ref.html for complete documentation  
               of the syntax and available built-in constructs. Template 
               authors need  not be concerned with the Programmer's Guide or 
               Java API documentation.

       c. Remove the jsp directory from your themes directory.
    
    2. Stylesheets
        
       VIVO 1.1 includes changes to vivo-basic stylesheets. If you modified 
       styles in your VIVO 1.0 theme, you will not be able to simply copy the  
       1.0 stylesheets into your 1.1 theme, because you will then lose 1.1 
       style upgrades that your theme should pick up.  Instead, you should 
       use the vivo-basic 1.1 stylesheets as a starting point, and manually
       merge your 1.0 style modifications in as needed.
    
    3. Site Icons
    
       Copy the site icons from your 1.0 theme into the site_icons folder in
       your 1.1 theme.