249 lines
11 KiB
Text
249 lines
11 KiB
Text
|
|
||
|
|
-------------------------------------------------------------------------------
|
||
|
|
|
||
|
|
Upgrading VIVO
|
||
|
|
|
||
|
|
Steps to Upgrade from Release 1 Version 1.1.1 to Release 1 Version 1.2
|
||
|
|
|
||
|
|
This file provides a short description of the steps involved in upgrading your
|
||
|
|
installation of VIVO from Release 1 Version 1.1.1 to Release 1 Version 1.2.
|
||
|
|
This and other documentation can be found at:
|
||
|
|
|
||
|
|
http://vivoweb.org/support
|
||
|
|
|
||
|
|
Installation:
|
||
|
|
If you need to do a fresh install, please consult the install.txt in this
|
||
|
|
directory.
|
||
|
|
|
||
|
|
-------------------------------------------------------------------------------
|
||
|
|
|
||
|
|
I. Before Performing the Upgrade
|
||
|
|
II. The Upgrade Process
|
||
|
|
III. Ontology Upgrade
|
||
|
|
A. Verify Ontology upgrade process
|
||
|
|
B. Ontology knowledge base manual review
|
||
|
|
IV. Theme Changes
|
||
|
|
|
||
|
|
-------------------------------------------------------------------------------
|
||
|
|
|
||
|
|
I. Before Performing the Upgrade
|
||
|
|
|
||
|
|
Please read the bullet points below BEFORE beginning the upgrade.
|
||
|
|
|
||
|
|
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 "Ontology Upgrade"
|
||
|
|
below for more information.
|
||
|
|
|
||
|
|
-------------------------------------------------------------------------------
|
||
|
|
|
||
|
|
II. The Upgrade Process
|
||
|
|
|
||
|
|
|
||
|
|
1. Ensure that backups are created of the Tomcat webapps directory, the
|
||
|
|
original source directory, the MySQL database, and the uploaded files
|
||
|
|
directory (images).
|
||
|
|
|
||
|
|
2. Download the new distribution file and unpack it into a new source
|
||
|
|
directory.
|
||
|
|
|
||
|
|
3. Create deploy.properties, using the same values as in your previous
|
||
|
|
installation.
|
||
|
|
|
||
|
|
4. 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.
|
||
|
|
|
||
|
|
At a minimum it will be necessary 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:
|
||
|
|
https://confluence.cornell.edu/display/ennsrd/Google+Analytics+for+UI
|
||
|
|
|
||
|
|
If you had used the vivo/contrib/FLShibboleth code in your previous release,
|
||
|
|
you should stop using it. Consult install.txt for instructions on
|
||
|
|
"Using an External Authentication System with VIVO".
|
||
|
|
|
||
|
|
************************************************************************
|
||
|
|
|
||
|
|
5. If you had modified web.xml to configure the Pellet Reasoner (as described
|
||
|
|
in the installation instructions), repeat that modification.
|
||
|
|
|
||
|
|
6. Stop Apache Tomcat and run ant by typing: ant all
|
||
|
|
|
||
|
|
7. 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 changed to
|
||
|
|
belong to the nearest available superclass (which may be owl:Thing).
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
Class or Property addition
|
||
|
|
If a newly added class has a superclass and there are
|
||
|
|
individuals in that superclass, then a note will be
|
||
|
|
added to the log file suggesting review of those individuals to
|
||
|
|
see if they should be reasserted in the newly added class.
|
||
|
|
|
||
|
|
If a newly added property has a superproperty and there are
|
||
|
|
statements using the superproperty, then a note will be added to
|
||
|
|
the log file suggesting review of those statements to see if they
|
||
|
|
should be reasserted using the newly added property.
|
||
|
|
|
||
|
|
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/<your-theme-name>.
|
||
|
|
|
||
|
|
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.
|