Advanced functionality for the application framework

You can further enhance your applications by learning about how to use advanced functionality, such as versioning. In addition, you can fine-tune your applications with an understanding of other advanced features.

This page contains the following information:

Application versions

You can use application versions to manage the development, installation, and upgrading of Relativity applications. Relativity uses the format Major.Minor.Build.Revision to version applications. It automatically assigns a version number to an application if you don't specify one during creation. The default version number is 0.0.0.1. See Create an application in Relativity.

You can edit an application version by modifying the major, minor, or build number. The new version number must be greater than the current version. However, you can't change the revision number in a version. During the export, Relativity automatically increments the revision number if the application has undergone any modifications. It increments the revision number if you performed any of the following actions:

  • Unlocked the application since the last export.
  • Added or updated any resource files attached to your application.
  • Exported your application for the first time. For example, Relativity increments the version number of 0.0.0.1 to 0.0.0.2 when you export the application.

In addition, the following application components use these versioning practices:

  • Mass operations currently aren't versioned. When you import an application, Relativity overwrites any existing mass operations that match those in the imported application. Otherwise, it creates a new mass operation based on the components of the imported application.
  • Modifying a saved search in a locked application causes Relativity to increment the version when you export the application. For more information, see Locking and unlocking applications on the Relativity Documentation site.

Upgrades and application versions

During an upgrade, Relativity uses the following criteria to determine whether to perform a full or incremental installation of an application.

Full upgrades

Relativity performs a full upgrade when the following conditions are true:

  • Unlocked state – Relativity considers unlocked applications to be in an unknown state so it performs a full upgrade.
  • applicationIsDirty state – Relativity sets this flag to True when you unlock an application. If you unlock and then lock an application, Relativity considers it to be in an unknown state and performs a full installation.
  • Mismatched origin signatures – Relativity determines if application that you are upgrading originates from the same workspace as the application that you are installing. If it detects mismatching origin signatures, then it performs a full installation.

Incremental upgrades

Relativity performs an incremental upgrade by installing only new or modified application objects and dissociating obsolete objects. Incremental upgrades run faster because they only perform updates to address changes that exist between the current version of the application and the new version that you are installing.

It performs this type of upgrade when the following conditions are true:

  • Version number differences – The version number of the application being installed is greater than that of the one being upgrade.
  • Unlocked state – Target application hasn't been unlocked.
  • Matching origin signatures – The source workspace is the same in both the application that you are in stalling and the one being upgraded.

Tab behavior during installations and upgrades

The following rules control tab behavior during initial installation and upgrades:

  • First-time installations use these rules to control tabs:
    • If no tab exists in the workspace with the name of the application you are installing, all tabs in the application are placed under a tab named after the application.
    • If a tab exists in the workspace with the name of the application you are installing, all tabs in the application are placed under that existing tab.
  • Upgrades use these rules to control tabs
    • If a tab already exists with the name of the application you are installing, Relativity adds new tabs under it.
    • If a tab with the name of the application you are installing doesn't exist, and all original application tabs are spread across multiple parent tabs or live on the root level, a new tab is created with the name of the application you are installing.

Note: If you previously built an application with a parent tab, upgrading to Relativity 6.10 or above automatically removes the tab.

Object type event handler behavior during upgrades

Depending on the version of Relativity, Relativity treats object type event handlers differently during application upgrades.

When upgrading an application to a newer version, if the new version of the application no longer contains the event handler (but previously did), Relativity removes the event handler from the object type. You don't have to write custom code to remove the event handler association from the object type.

If the new version of the application no longer contains an object type event handler, the event handler is removed from the application but the object type association persists. You can remove the event handler from the object type by writing a post install event handler.

Application resource file purge

Before July 2017, the files associated with older versions of applications remained in place following upgrade and required special programming logic to delete. This complicated development and the upgrade process.

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 Custodian.
  • 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 (for example, fields, views, and layouts)
  • Scripts
  • Saved searches
  • Dashboards

You can also manually delete DLL resource files from the Resource Files tab in Developer Mode without having to unlink your objects from all workspaces.