+

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

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

+

Upgrade process for V1.2

+

+ +
    +
  1. + Before Performing the Upgrade +
    2. +
  2. + The Upgrade Process +
    3. +
  3. + Ontology Upgrade +
    4. +
      +
    1. + Verify Ontology upgrade process +
      2. +
    2. + Ontology knowledge base manual review +
      3. +
    +
  4. + Theme Modifications +
    5. +
+ +

I. Before Performing the Upgrade

+

+ Please ensure that backups are created of the: +

+ +

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

+ +

The Upgrade Process

+
    +
  1. + Download the new distribution file and unpack it into a new source + directory. +
    2. +
  2. + Create deploy.properties, using the same values as in your previous + installation and set values for the new variables. +
    3. +
  3. + 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". +
      • +
    +
    +
    4. +
  4. + If you had modified + + web.xml + + to configure the Pellet Reasoner (as described + in the installation instructions), repeat that modification. +
    5. +
  5. + Stop Apache Tomcat and run ant by typing: + + ant all + +
    6. +
  6. + Start Apache Tomcat and log in to VIVO. +
    7. +
+ 
+
+
+-------------------------------------------------------------------------------
+
+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.		
+		
+		
+		
+		
+		
+
+