Scripts

Scripts are Relativity artifacts. This means they have the same features as standard Relativity objects, allowing them to be secured and audited.

Note: Relativity Scripts are a tool to access and modify data stored in Relativity SQL databases. Not all data is available in SQL, and data currently in SQL may be migrated to other storage systems. The recommended integration mechanism is to use APIs/Services instead of scripts to avoid future migration or interruption.
You should only use scripts when an appropriate API is not available. Relativity will add new and updated APIs over time - review the available APIs periodically to determine if you can replace a script with an API or REST service call.

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.

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 scripts must be tested and revalidated before you run them. Remember that the recommended integration mechanism is to use APIs instead of scripts to avoid potential disruption if the data schema or storage mechanism changes.

Note: If you use a Relativity script in a custom development project, it is recommended to make a copy of the script and use the copied script in your project. Software updates may modify the scripts provided by Relativity, which could cause unintended results if you use the Relativity-provided scripts directly in your custom development projects.

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.