Scripts

You can use Relativity scripts to create and execute flexible SQL-based scripts to customize and augment Relativity functionality. Scripts are Relativity artifacts. This means they have the same features as standard Relativity objects, allowing them to be secured and audited.

Caution: Changes to SQL fields executed by Relativity Scripts do not produce Audit logs.

Only users who are members of groups with the appropriate permissions can write scripts. System admins have permissions to preview, edit, and create scripts. See Security and permissions.

If a script is locked, it appears as read only, and you can't edit it. If a script is unlocked it's available for editing.

The following table represents the script permissions allowed for each group.

  Locked Script Unlocked Script  
  View Run Edit Preview Edit Preview Write Link
System Admin x x   x x x x x
Standard User x* x*           x**

* With view rights
** With add rights

Using scripts

You're a system admin and you've been facilitating a document review project for your client, a large construction company, who’s involved in litigation regarding the use of materials that they weren’t informed were potentially environmentally damaging when they purchased them from a major supplier.

This morning you learned that the other party involved in this litigation, the material supplier, provided evidence that they weren’t actually responsible for supplying your client with one of the materials in question, namely the asphalt your client used to pave the driveways in a housing development. You immediately performed a mass operation to remove all documents from the issues view that had been tagged with the “Asphalt” choice so that reviewers didn't waste any more time on those documents in a second-pass review.

Because the same documents you removed were part of at least two separate dtSearch indexes you set up for reviewers, you now need to perform an incremental build on those indexes, as well as any others you may have altered when you performed the mass delete. There's a script for that called dtSearch Index Auto Incremental Build. You go to the Scripts tab, find it in the Relativity Script Library, and run it.

All dtSearch indexes that once returned documents containing references to the inappropriately associated term are removed.

Relativity Script Library

Relativity houses a library of commonly-used scripts that you can run at any time. It's important to note that, depending on your Relativity version, certain scripts may not be available to you.

By default all Relativity scripts are secured and aren't available for editing. See Relativity Script Library.

Script compatibility and updates

To improve system performance, architecture improvements are often applied to Relativity’s SQL tables for new versions.

When upgrading, your personally created existing scripts must be tested and revalidated before you run them. The only exception to this is Relativity Library scripts, which are automatically updated with any changes affecting the new version.

When upgrading your environment, the unique script key is referenced to determine if an update is required. If so, this is performed automatically.

Selecting a library script

Due to the complexity and impact a script can have, only Relativity, SQL, and XML expert users should create and run them.

To select a library script and add it to your workspace, perform the following steps:

  1. Navigate to and select the Scripts tab.
  2. Click New Relativity Script. If you want to edit an existing script, click the Edit link next to the script name.
  3. Complete the following fields:

    • Script Type - select Select from Script Library to choose from a list of predefined Relativity scripts. The Script Library tab is created when Relativity is deployed. Note that this is the only option available for the Script Type field if the AllowAddOrEditScripts instance setting is set to its default value of False.
    • Relativity Script - select the script from the script library.
    • Relativity Applications - associates the script with an application created on the Relativity Applications tab. All existing applications are available when you click the ellipsis. This is only available for those who have the Manage Relativity Applications permission under Admin Operations. For information on applications, see the Applications GuideFor information on applications, see the Applications Guide

  4. Click Save.

Creating a new workspace script

You must set the AllowAddOrEditScripts instance setting to True to make the Create New Workspace Script option available. For more information, see AllowAddOrEditScripts.

Due to the complexity and impact a script can have, only Relativity, SQL, and XML expert users should create and run them.

To create a new workspace script, follow these steps:

  1. Navigate to and select the Scripts tab.
  2. Click New Relativity Script. If you want to edit an existing script, click the Edit link next to the script name.
  3. Complete the following fields:
    (Click to edit)

    • Script Type - select Create New Workspace Script.
    • Relativity Applications - associates the script with an application created on the Relativity Applications tab. All existing applications are available when you click the ellipsis. This is only available for those who have the Manage Relativity Applications permission under Admin Operations. For information on applications, see the Applications GuideFor information on applications, see the Applications Guide
    • Script Body - enter the script code into this area. For information on how to format a Relativity script, see Script properties on our Relativity Developers site..

  4. Click Save.

Adding a library script to the script tab

In order for scripts to appear in your Script tab for your users to run, you must add them. To add a library script to the Script tab, follow these steps:

  1. Navigate to and select the Scripts tab.
  2. Click New Relativity Script.
  3. Choose Select from Script Library on the Script Type field.
  4. In the Relativity Script field, click Select, and choose the library script you want to add.
  5. Click Save.
    The script information screen appears.
  6. In the Script console, click Run Script.
    The script appears in your Script tab. In addition, Relativity adds the Is Link column to the view and sets it to Yes. When you add a library script to a workspace, it remains linked to the Script Library as indicated in the Is Link column. This column displays No if you add your own custom script to the workspace.

Running a library script

To run a script, follow these steps:

  1. Navigate to and select the Scripts tab.
  2. Click Run next to the script you want to run or open the script and click Run Script on the Actions console.
  3. Configure the required fields on the script layout.
  4. Click Preview to display a pop-up of the SQL script, or click Run to execute the script.