• Release announcement for V1.3
• Upgrade process for V1.3

1. Before Performing the Upgrade
2. Noteworthy Changes
   
1. Triple Store
2. Theme
3. Template
4. List View
5. Authorization
3. The Upgrade Process
4. Ontology
   1. Verify Ontology upgrade process
   2. Ontology knowledge base manual review

I. Before Performing the Upgrade

Please ensure that backups are created of the:

• Tomcat webapps directory
• Original source directory
• MySQL database (mysqldump)

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

• If you are still in RDB mode, it is required that you move your triple store to SDB while still at V1.2 (see Triple Store info below). 
  
• DO NOT reinstall MySQL or recreate the MySQL database. Please ensure that you back-up the MySQL database. Also note that VIVO 1.2 will not run on older versions of MySQL that may have worked with 1.1.1. Be sure to run VIVO 1.2 with MySQL 5.1 or higher. Using unsupported versions may result in strange error messages related to table formatting or other unexpected problems.
• 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. With V1.3 there is also a new root user. Please see the section on Authorization changes for more information.
• 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 the Ontology Upgrade below for more information.

II. Noteworthy Changes

i. Triple store changes

VIVO 1.3 now requires you to use Jena's SPARQL database (SDB) for the triple store technology.  Jena's legacy relational database store (RDB) was used by VIVO 1.1.1 and earlier.  Both SDB and RDB were available in VIVO 1.2 and 1.2.1.  It is required that you move your triple store to SDB while still at V1.2.

SDB mode caches only a fraction of the RDF data in memory. Most queries are issued directly against the underlying database. This allows VIVO installations to display data from large RDF models while requiring only a small amount of server memory to run the application. There is a tradeoff in response time: pages may take slightly longer to load in SDB mode, and performance will depend on the configuration parameters of the database server. Additionally, advanced OWL reasoning (not enabled by default in either mode) is not possible in SDB mode. With SDB, only the default set of inferences (inferred rdf:type statements) are generated, and they are generated as soon as data is edited rather than in a background process.

A conversion from RDB to SDB mode can take a number of hours to complete if the installation contains a large amount of RDF data (roughly a million triples or more).  You can start the conversion process in the background while the RDB system is running. This will reduce the delay in initial startup after the application is redeployed with deploy.properties set for SDB. Note that it is important not to edit any data anywhere in the application while this background conversion is running.

To start the SDB conversion, log in as a system administrator and request /sdbsetup (For example, if your VIVO is installed at http://vivo.myuniversity.edu/ you would type http://vivo.myuniversity.edu/sdbsetup into your browser).

Click the button that appears on this page.

During the course of the SDB setup, which may take several hours on a large database, subsequent requests to /sdbsetup will display a message that the operation is still in progress. When a request for this page shows a message that the SDB setup has completed successfully, shut down Tomcat, set deploy.properties to SDB mode, redeploy, and restart Tomcat. VIVO will now be running from the SDB store.

ii. Theme changes

The vivo-basic theme was deprecated with VIVO V1.2 and is no longer present in the V1.3 release as it does not support V1.2 or V1.3 features. It is highly recommended that you use the wilma theme or modify the wilma theme for branding or to create a custom look and feel. Please see the Site Administration Guide for more information about customizing your theme.

• The ${stylesheets}, ${scripts}, and${headScripts} add() methods now take the full tag as an argument. This will require a change to all calls to these methods in the templates. This change allows for specification of attributes such as media directly in the tag. For example:

  1.2: ${stylesheets.add("/css/individual/individual.css")}
  1.3: ${stylesheets.add('<link rel="stylesheet" href="${urls.base}/css/individual/individual.css" />')}

  Note the inclusion of ${urls.base} in the 1.3 example. The add() method no longer prefixes the context path to the url, so the full url must be specified in the tag.

• The addFromTheme() methods of the ${stylesheets},${scripts}, and${headScripts} objects have been deleted. Substitute as shown in the preceding example.
• propertyGroups.getPropertyAndRemoveFromList() in the individual templates has been deprecated. The replacement method ispropertyGroups.pullProperty(). There is no change in functionality.

In release 1.3, the VIVO authorization system has some extensive changes. In summary, these are:

• Each user will have a user account, even if the user logs in by Shibboleth or some other external authentication system.
• E-mail is used to notify user's when an account is created for them, or when an administrator edits their account.
• A "root" user account exists which has access to all pages and all data fields. This is a powerful tool that can hold some surprises.

a. User Accounts are created for externally authenticated users

With release 1.3, each authenticated user will have a user account. If someone logs in using an external authentication system, and no user account matches their external login credentials, an account will be created.

The user will be prompted to enter information for the account being created: first name, last name, and e-mail address.

b. E-mail address becomes an important part of User Accounts

Prior to release 1.3, each user account was identified by a Username field. This field was labeled as "E-mail address" on some pages in VIVO, but no mail was ever sent. In release 1.3, this has changed, so the e-mail address is fully used, both for identification and for communication with the user.

Prior to release 1.3, the Username field (also referred to as 'e-mail address') was used for several purposes:

• Idenfiying the user account.
• Part of the user's credentials when logging in (along with a password).
• Connecting the user account to an external authentication system, like Shibboleth or CUWebAuth.
• Connecting the user account to a personal Profile page.

With release 1.3, these functions are handled by two separate fields called EmailAddress field and ExternalAuthId.

• EmailAddress is used when logging in (along with a password).
• EmailAddress is used to send notifications to the user about changes to his/her account (see below).
• The ExternalAuthId is used when logging in using an external authentication system.
• The ExternalAuthId is used to connect the user account to a personal Profile page.

  Note: With release 1.3, the ExternalAuthId can now be matched against either an untyped literal or a string literal in the Profile page.

There are other changes to the internal structure of the user accounts data, but they are important mostly to the VIVO software developers, and you are not likely to notice them.

If you are upgrading to VIVO release 1.3 from an existing VIVO installation, the user accounts in your system will be migrated into the new data structures. When migrating an account, both the EmailAddress field and the ExternalAuthId field will be set to the value of the Username field in the old account. The new account should behave as the old account did.

When creating a new user account, or editing an existing one, the system requires that your e-mail address be in a valid form, like somebody@somewhere.edu. You should plan for this as part of your migration to release 1.3

With release 1.3, VIVO users receive e-mail notifications when an account is created or modified for them or by them.

When an administrator creates a user account, the user will receive an e-mail notification, telling them that the account has been created, and providing a link to VIVO that will allow them to set a password on the account.

Note: when creating the account, the administrator may indicate that it will only be used with an external authentication system like Shibboleth or CUWebAuth. In this case, the account will not require a password, and the e-mail notification message to the user will not provide a password link.

When an administrator edits a user account, he may choose to reset the password. As with a new account, the user will receive notification with a link to VIVO that will allow them to set a new password.

If a user changes the e-mail address on his account, he will receive a notification message to that effect.

If a user account is auto-created for a user with external authentication credentials, the user will receive a notification message.

The e-mail notification relies on two configuration properties:email.smtpHost and email.replyTo. If either of these properties is missing or empty, VIVO will not attempt to send e-mail notifications to users.

This can be useful for small or experimental installations of VIVO, or where e-mail notification is not desired.

If e-mail notifications are disabled, an administrator must set a password on each new account, since the user will have no way of setting it. When the user logs in for the first time, VIVO will require them to change their password to one of their own choosing.

c. Each VIVO installation will have a 'root' account.

Prior to release 1.3, each VIVO installation was created with a default administrator's account. In release 1.3, there is no such account. Instead, each VIVO installation will have a "root" account.

The email address for the root account is specified in deploy.properties, like this:

rootUser.emailAddress = vivo_root@mydomain.edu

The password for this account is automatically set to rootPassword, but you will be required to change the password the first time you log in.

Note: theinitialAdminUser is no longer use.

The root account is not a site administrator's account — it is more powerful than a site administrator's acocunt. The root account is permitted to visit any page in a VIVO application. It is permitted to see any data property, and to enter data into any field. As such, the root account can be very useful and rather dangerous. It can also give you a distorted view of what your VIVO site looks like, since data is shown which other accounts cannot see.

The root account is not intended for routine, every day use. The best way to use the root account is to create a site administrator's account. After that, use the root account only when necessary.

III. The Upgrade Process

1. Download the new distribution file and unpack it into a new source directory.

2. Create a new deploy.properties using the same values as in your previous installation and set values for the new variables as described below (vitro.local.solr.url, vitro.local.solr.ipaddress.mask, vitro.home.directory, email.smptHost, email.replyTo, rootUser.emailAddress)

 scheme + servername + port + vivo_webapp_name + "solr"

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 implementations 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 of 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 from your VIVO source directory, run ant by typing: ant all

6. Start Apache Tomcat and log in to VIVO.

IV. Ontology Changes

i. 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.(timestamp).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 "Finished knowledge base migration". If this file contains any warnings they should be reviewed with your implementation team representative to see whether any corrective action needs to be taken.

ontologies/update/logs/knowledgeBaseUpdate.(timestamp).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.

ii. 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 type assertions of 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.