+

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 +
    • +
  • + Add config table from install d/t so many new vars. +
    • +
  • +
    • +
+
+ + + +

+ 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. Create deploy.properties, using the same values as in your previous + installation and set values for the new variables. The following table + shows the default properties for deploy.properties with new V1.2 properties in + blue. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Property Name + + Example Value +
+ Default namespace: VIVO installations make their RDF resources available + for harvest using linked data. Requests for RDF resource URIs redirect to HTML + or RDF representations as specified by the client. To make this possible, + VIVO's default namespace must have certain structure and begin with the public + web address of the VIVO installation. For example, if the web address of a VIVO + installation is "http://vivo.example.edu/" the default namespace must be set to + "http://vivo.example.edu/individual/" in order to support linked data. Similarly, + if VIVO is installed at "http://www.example.edu/vivo" the default namespace must be + set to "http://www.example.edu/vivo/individual/" +

* The namespace must end with "individual/" (including the trailing slash).

+
+ Vitro.defaultNamespace + + http://vivo.mydomain.edu/individual/ +
+ Directory where Vitro code is located. In most deployments, this is set to + ./vitro-core, but it commonly points elsewhere during development. +
+ vitro.core.dir + + ./vitro-core +
+ Directory where tomcat is installed. +
+ tomcat.home + + /usr/local/tomcat +
+ Name of your VIVO application. +
+ webapp.name + + vivo +
+ Directory where uploaded files will be stored. You must create this directory ahead of time. +
+ upload.directory + + /usr/local/vivo/data/uploads +
+ Directory where the Lucene search index will be built. Depending on your + permissions and who Tomcat is running as, you may need to create this directory + ahead of time. +
+ LuceneSetup.indexDir + + /usr/local/vivo/data/luceneIndex +
+ Specify an SMTP host that the form will use for sending e-mail (Optional). If + this is left blank, the contact form will be hidden and disabled. +
+ Vitro.smtpHost + + smtp.servername.edu +
+ Specify the JDBC URL of your database. Change the end of theURL to reflect + your database name (if it is not "vivo"). +
+ VitroConnection.DataSource.url + + jdbc:mysql://localhost/vivo +
+ Change the username to match the authorized user you created in MySQL. +
+ VitroConnection.DataSource.username + + username +
+ Change the password to match the password you created in MySQL. +
+ VitroConnection.DataSource.password + + password +
+ Specify the Jena triple store technology to use. SDB is Jena's + SPARQL database; this setting allows RDF data to scale beyond the + limits of the JVM heap. Set to RDB to use the older Jena RDB + store with in-memory caching. +
+ VitroConnection.DataSource.tripleStoreType + + SDB +
+ Specify the maximum number of active connections in the database + connection pool to support the anticipated number of concurrent + page requests. It is not necessary to adjust this value when + using the RDB configuration. +
+ VitroConnection.DataSource.pool.maxActive + + 40 +
+ Specify the maximum number of database connections that will be + allowed to remain idle in the connection pool. Default is + 25% of the maximum number of active connections. +
+ VitroConnection.DataSource.pool.maxIdle + + 10 +
+ Change the dbtype setting to use a database other than MySQL. + Otherwise, leave this value unchanged. + Possible values are DB2, derby, HSQLDB, H2, MySQL, Oracle, + PostgreSQL, and SQLServer. + Refer to http://openjena.org/wiki/SDB/Databases_Supported + for additional information. +
+ VitroConnection.DataSource.dbtype + + MySQL +
+ Specify a driver class name to use a database other than MySQL. + Otherwise, leave this value unchanged. + This JAR file for this driver must be added to the the webapp/lib + directory within the vitro.core.dir specified above. +
+ VitroConnection.DataSource.driver + + com.mysql.jdbc.Driver +
+ Change the validation query used to test database connections + only if necessary to use a database other than MySQL. + Otherwise, leave this value unchanged. +
+ VitroConnection.DataSource.validationQuery + + SELECT 1 +
+ Specify the name of your first admin user for the VIVO application. + This user will have an initial temporary password of 'defaultAdmin'. + You will be prompted to create a new password on first login. +
+ initialAdminUser + + defaultAdmin +
+ The name of a property that can be used to associate an Individual + with a user account. When a user logs in with a name that matches + the value of this property, the user will be authorized to editthat Individual. +
+ selfEditing.idMatchingProperty + + http://vivo.mydomain.edu/ns#networkId +
+ Temporal Graph Visualization is used to compare different + organizations/people within an organization on different parameters like + number of publications, grants. This parameter will be used as a default + in case a URI is not provided. It will be also used whenever this + visualization is to be rendered for top level organization. + In absence of this parameter a SPARQL query will be fired which will + attempt to provide a top level organization. The name of a property that + can be used to associate an Individual with a user account. When a user + logs in with a name that matches the value of this property, the user + will be authorized to edit that Individual. +
+ visualization.topLevelOrg + + http://vivo-trunk.indiana.edu/individual/topLevelOrgURI +
+

+

+ 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. If you had modified web.xml + to configure the Pellet Reasoner (as described + in the installation instructions), repeat that modification. +

+

+ 5. Stop Apache Tomcat and run ant by typing: ant all +

+

+ 6. 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.2 comes with a new theme called "wilma" that uses the FreeMarker template + engine for generating web pages. The theme is located in /vivo/themes/wilma and + the FreeMarker files 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 V1.0 or V1.1, but used + the 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. +

+

I THINK THIS SECTION NEEDS MAJOR CHANGING AND I NEED HELP WITH IT, Por Favor

+

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

+
+
+ 1. Templates +
+
+
+
+ a. Copy the directory /vivo/themes/vivo-basic/templates + into your theme directory /vivo/themes/[your-theme-name]. +
+
+
+
+ b. Follow step i or ii below, whichever is applicable to your theme. +
+
+
    +
  1. + 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. +
    2. +
  2. +

    + 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 the file to which you 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. +

    +
    3. +
+
+
+ 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.1 theme into the site_icons folder in + your 1.2 theme. +
+
+