Upgrading applications

You can upgrade an existing application by using the Upgrade Application option available on its detail view.

This page contains the following information:

Upgrading an application

Before you upgrade an application, review the following information:

  • Some Relativity applications are pre-populated with instances of object types used to store settings, which you can modify to control application functionality. Upgrading the application resets these instances, so any modifications made to them are lost. As a best practice, create new instances of these object types in your application instead of modifying the default settings. For example, you might create a new profile with your custom settings in the Imaging application.

    Note: You can avoid resetting instances of object types by developing applications that use Post Install event handlers set to run only once. Using these event handlers, you can create instances of objects and set default values on them during the initial application installation, but not on subsequent upgrades. See Post Install event handlers on the Relativity Server 2021 Developers site.

  • Relativity preserves modifications made to saved searches included in locked applications. For more information, see Customizing locked applications.
  • Confirm that any existing application jobs have completed before upgrading out-of-the-box Relativity applications, such as OCR, search terms report, transform set, or imaging. You may interrupt the current job if you upgrade the application while it is running.

Use the following procedure to upgrade an application:

  1. Confirm that you have the appropriate system admin permissions to install an application in Relativity. For more information, see Workspace security.
  2. Select the Relativity Applications tab in the target workspace.
  3. Click the name of the application that you want to upgrade.
  4. Click Upgrade Application in the Relativity Application console. If you don't see this button, then you don't have the appropriate system admin permissions.
  5. Select Import from file in the Application Type field.
  6. Click Browse to select a application file.
  7. Click Open on the browse dialog.
  8. Click Upload to initiate upgrade script.

Application resource file purge

Beginning in July 2017, the application upgrade process purges assembly resource files (DLLs) no longer associated to the newer application version:

  • Physically deletes all DLL resource files that were part of the original application version.
  • Removes event handler associations on objects types such as Document or Entities.
  • Remaps object references in the workspace database to reference the new DLL.
  • Eliminates workspace references to resources that no longer exist.
  • If an agent of a removed type is currently running, it will complete its work and then self-destruct.

The following application components are not deleted by the upgrade process:

  • Object types (fields, views, layouts, etc.)
  • Scripts
  • Saved searches
  • Dashboards

Troubleshooting application upgrades

You can use the following information to identify and resolve issues that may occur when upgrading your applications.

Applications from older versions not available after upgrading to Relativity 7.0

If you have Relativity 6.8 or below installed on a workspace, and you upgraded the server to Relativity 7.0, your application is no longer available. It continues to exist in the database, but the Relativity Applications tab no longer includes it. You can't export or upgrade the application.

Including object rules when upgrading from Relativity 6.10

If you have an application created in Relativity 6.10 installed on a workspace, and then you upgrade the server to Relativity 7.0 or above, you must manually add any Object Rules that you want included in the application after completing the upgrade.

Making older applications compatible with Relativity 7.0 or above

If you have applications from Relativity 6.8, 6.9 , or 6.10 that were both exported through the ADS, you can make them compatible with Relativity 7.0 or above by running the Upgrade Legacy Applications script. This script is available in the Relativity Script Library.

Exporting choices attached to single or multiple choice fields

When you update an existing application with a single or multiple choice field, you can make the choices attached to these fields available for export by setting the Auto Add Choices field property to Yes. If you have a single or multiple choice field that was added to an application prior to upgrading to Relativity 7.2 or above, that field still has all the choices added to the application by default.

Custom pages not working properly when multiple application versions exist on the same server

If you have an application with custom pages in Workspace A, and import a new version of the same application to Workspace B on the same server, then the custom pages may not function as expected since they are outdated. However, they continue to display as components of the application.

Applications can't be downgraded

You can't import an application with an earlier version number into the Relativity applications library. However, an application with an earlier version number can exist in a workspace even though the application in the environment's library has a higher version number.