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 to 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.

Key properties on IExtensionParameters:

• applicationContext — The context the application is running in (reviewinterface, preview, externalstandalone, mobile). Use this to skip registration in unsupported contexts.

• version — Application version information for compatibility checks.

• extensionDetails.source — Whether the extension is loaded from a CDN (cloud) or a RAP resource file (ads-application). Use this to choose between getResourceUrl and getResourceFileUrl when resolving asset URLs.

• getResourceUrl(fileName) — Resolves a URL for a file co-deployed alongside the extension on the CDN. Use this for CDN-deployed extensions (source === 'cloud').

• getResourceFileUrl(fileName) — Resolves a URL for a RAP resource file. Use this for RAP-deployed extensions (source === 'ads-application').

• foundationInstance — An optional pre-initialized relativity-foundation instance. When the extension uses the assetResolution deployment strategy, the asset resolver may provide a Foundation instance here so the extension does not need to initialize its own. This property may be undefined even when using assetResolution — for example, when the entry point URL is served from the browser's LocalStorage cache, the resolver is not invoked and no instance is provided. Extensions must always fall back to creating their own Foundation instance:

  Copy

  import { createFoundation } from 'relativity-foundation';
  
  isEnabled: async () => {
    const foundation = parameters.foundationInstance ?? await createFoundation({
      name: 'my-extension',
      version: '1.0.0',
      teamId: 'PTCI-12345',
      flags: { envKey: { /* LD SDK keys per environment */ } },
    });
    await foundation.waitUntilReady();
    return foundation.flags.variation('my-feature-flag', false);
  },
  

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:

  Copy

  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:

  Copy

  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.