Building An Extension

Relativity Review Extensions provide you with the ability to customize user workflows in the document viewer. The process for developing an extension includes completing these tasks:

• Create a Relativity application.
• Create an extension script.
• Upload your extension script as a resource file to your Relativity application.

Use the detailed instructions on this page to learn more about implementing custom extensions.

This page contains the following information:

• Step 1 - Create a Relativity application
• Step 2 - Create an extension script
• Step 3 - Upload your extension script to Relativity
• Step 4 - Optionally upload other static files to Relativity
• Additional considerations

Step 1 - Create a Relativity application

A Review Extension must be associated a Relativity application:

• Use existing application - if you already have a Relativity application, you can associate your extension with it. You don't need to create a new application.

• Create new application - for detailed instructions, see Create an application in Relativity on the Relativity Developers site.

Step 2 - Create an extension script

You define the custom behavior for a Relativity Extension in an extension script. The Review Interface application retrieves and parses the extension script at startup. It acts as the entry point to your custom Relativity extension. You can divide your extension into multiple assets, such as JavaScript, HTML, CSS, and image files.

See the following sections for information about creating a script:

• Extension script requirements
• Extension script parameters
• Extension script example

Extension script requirements

Extension scripts are JavaScript files that meet the following requirements:

• File name - must begin with review.index.
• File contents - must meet the following requirements:
  • Contains valid JavaScript. See ECMAScript Requirements.
  • Contains JavaScript implemented as an immediately-invoked function expression (IIFE). See IIFE on the MDN web site.
  • Must be an IIFE that returns an object that implements IExtensionConfig.
  • Doesn't contain code that exists outside of the IIFE.
  • Doesn't contain any long running operations performed by the IIFE that would slow down the application startup.

Extension script parameters

The Review Interface application exposes an IExtensionParameters object that your extension script can access through the params object. Your extension script can use the properties on this object to dynamically determine whether to register an extension. See Conditionally Registering Extensions.

Extension script example

The following sample code illustrates the general format for an extension script but it doesn't perform any actions.

(function (params) {
  var config = {
    id: "examplecompany.testextension",
    name: "Example Company Test Extension",
  };

  return config;
})(params);

Step 3 - Upload your extension script to Relativity

When you want to test or deploy your extension script, you need to upload it to your Relativity application as a resource file. For more information, see Resource files on the Relativity Documentation site.

Step 4 - Optionally upload other static files to Relativity

Extension scripts commonly require other static assets, such as images, fonts, CSS, HTML, and other JavaScript files.

Use one of the following methods to host static files so they are available to your Review extension:

• Host static files in a Relativity custom page

  If your Relativity application already has a custom page, you can include static files in it. The Relativity platform hosts these files making them available to your extension via HTTP at runtime.

• Add static files as application resource files

  If your Relativity application doesn't have a custom page, you can upload these static assets as resource files. Add the prefix review to their file names.

  Uploading resource files with the review prefix automatically results in them being hosted at the following endpoint for access by your extension:

  https://<host>/Relativity/RelativityApplicationWebResourceFile/<application_guid>/<application_version>/<file_name>

  For example, a file called review.sample.json added to an application with the GUID cd441ba7-7d47-4626-aaf2-ebbbb2843271 and the version 1.2.3.4 is accessible at this endpoint:

  https://<host>/Relativity/RelativityApplicationWebResourceFile/cd441ba7-7d47-4626-aaf2-ebbbb2843271/1.2.3.4/review.sample.json

Additional considerations

Use a defensive development approach when implementing a Relativity Review extension:

• Consider how your extension interact with other Relativity Review extensions. Avoid modifying the URL to store information for your extension. Additionally, don't rely on the URL to use a particular format or to contain any specific data.

• Implement your Relativity Review extension to be resilient even when other extensions don't follow best practices.