------------------------------------------------------------------------------- Upgrading NIH VIVO Steps to Upgrade from Release 1 Version 1.0 to Release 1 Version 1.1 This file provides a short description of the steps involved in upgrading your installation of NIH VIVO from Release 1 Version 1.0 to Release 1 Version 1.1. 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 Changes IV. File Storage Changes V. 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 or reconfigure the Apache HTTP Server. * First-time login of the administrator account will use the password previously set, NOT the password in deploy.properties. * 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 Changes" below for more information. * The first time Apache Tomcat starts up after the upgrade, it will initiate a process that modifies the uploads directory (images), to align the uploaded files with the revised file storage scheme. See the section on "File Storage Changes" 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 changes you have made to the new source directory. Note: 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. Note: At a minimum it will be necessary to apply the Google Analytics Tracking Code 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 and a copy your institution's tracking code, see the Google Analytics wiki page. https://confluence.cornell.edu/display/ennsrd/Google+Analytics+for+UI Note: This process assumes any changes made to the application were made in the source directory and deployed, and were not made directly within Apache Tomcat webapp. 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. If you have set up the Apache Tomcat Connector using mod_jk and modified your tomcat/conf/server.xml file, you will need to add a line to your context section specifying a "Manager" tag; see examples below. Context section before: Context section after: 8. Start "Apache Tomcat" and log in to VIVO. ------------------------------------------------------------------------------- III. Ontology Changes 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 It 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. 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. After Apache Tomcat is started, these files should be reviewed to verify that the automated upgrade process was executed successfully. ------------------------------------------------------------------------------- IV. File Storage Changes Changes to the File Storage system in VIVO result in new properties to describe the relationships involving files, and a new directory structure in which to store the files. Uploaded files are stored in the VIVO upload directory, as defined in the deploy.properties file. Previously, images were stored in the "images" folder of the upload directory. Now, all uploaded files will be stored in the "file_storage_root" folder of the upload directory. Previously, image files were served from the images directory within the web application, within Tomcat, and copied to the upload directory for backup purposes. Now, image files are stored only in the upload directory, and served directly from there. The image directory within the web application is no longer used. When Apache Tomcat starts up following the upgrade, it will initiate a process which makes the required changes: Initializing the file storage system Each file will now be assigned a unique ID, in addition to its filename. Both the ID and filename are used to store the file within the system. Uploading two images with identical filenames will not cause a conflict. Pruning dead image references Previous versions allowed manual editing of file paths, sometimes resulting in erroneous information. Any image properties that refer to non-existent files will be removed. Removing unreferenced images Any uploaded image which is no longer referred to by an Individual will be removed. Generating main images and/or thumbnails Each image will be represented by both a main image file and a thumbnail image file. If either of these is missing for a particular individual, it will be created. Converting image properties on Individuals Image properties previously were simple data properties, referring to the filename and path. These are replaced by object properties, which refer to the file by its unique ID. Translating images into the new directory structure Each image file will be copied to its new location in the upload directory. Cleaning the old image directory. All image files are removed from their old locations in the upload directory. The File Storage upgrade process will create these files in the Vivo upload directory: upgrade/upgradeLog.2010-00-00T00-00-00.txt A log of the upgrade process. The actual filename includes a timestamp that tells when the upgrade executed. This file should be inspected for warnings or errors. The file should end with "File Storage update is complete." upgrade/translatedImages Contains the images that were translated to the new file storage system. upgrade/unreferencedImages Contains the images which were in the "images" directory, but were no longer referred to by any Individual. file_storage_root A directory where the uploaded images are stored. Within the root, the path to the image is derived from its unique ID and its filename. file_storage_namespaces.properties Contains the URL prefix used when serving the image files. If, for any reason, the File Storage upgrade process is not successful, VIVO will not start. Attempts to open VIVO in the browser will result in a 404 error. Tomcat's "localhost" log file will contain an exception listing with more information. Once you are satisfied that the File Storage upgrade process is successful, you may delete the "images" folder and the "upgrade" folder from the upload directory. You may also delete the WEB-INF/images directory from within your Tomcat web application. ------------------------------------------------------------------------------- V. 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 to upgrade your theme to VIVO 1.1. 1. Copy the directory /vivo/themes/vivo-basic/templates into your theme directory /vivo/themes/. 2. Follow step a or b below, whichever is applicable to your theme: a. 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. b. 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 googleAnalytics.ftl is a new file included from footer.ftl 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. 3. 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.