diff --git a/doc/upgrade-1.2.txt b/doc/upgrade-1.2.txt new file mode 100644 index 00000000..792090b2 --- /dev/null +++ b/doc/upgrade-1.2.txt @@ -0,0 +1,249 @@ + +------------------------------------------------------------------------------- + +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/. + + 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. \ No newline at end of file