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.

This page contains the following sections:

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

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.

Creating a script tab

To create a script tab, see Creating and editing tabs and use the following information.

  • Name- Scripts
  • Tab Order - enter desired order
  • Link Type - Object
  • Parent - leave blank
  • Object Type - Relativity Script
  • Is Default - No

Note: By default, newly created tabs are visible only to system admins. This applies even if the creating user’s group has access to see all other tabs. Edit workspace permissions to assign rights to the new tab.

Once the tab is available, you are able to execute existing scripts, add scripts from the Script Library and create new scripts if you have the appropriate permission settings. See Relativity Script Library.

Creating and editing a script

Beginning in 9.4.398.62, you must enable the AllowAddOrEditScripts instance setting in order for users to create or edit scripts. For more information, see AllowAddOrEditScripts.

Note: You can still use the New Script button on the script page, without enabling this instance setting, to add scripts that already exist in the Relativity Script Library.

Creating and editing a script in a workspace

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 script, follow these steps:

  1. Click the Scripts tab under the Administration tab.
  2. Click New Relativity Script. If you want to edit an existing script, click the Edit link next to the script name.
  3. Fill out the fields on the form. See Fields.
  4. Click Save.

Fields

The script fields are:

Edit script page

  • Script Type - select one of the following:
    • Create New Workspace Script - select to create and edit your own environment and workspace scripts via the Script tab. You can enter or paste the script into the Script Body section.
    • Select from Script Library - select to choose from a list of predefined Relativity scripts. The Script Library tab is created when Relativity is deployed.
  • 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 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.

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. Click the Script tab under the Administration tab.
  2. Click New Relativity Script.
  3. Choose Select from Script Library on the Script Type field.
  4. In the Scripts field, click ellipsis button 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. Click the Script tab under the Administration tab.
  2. Click the script name that you want to run.
  3. Click Run Script in the Script console.
    The script runs. When it's complete:
  4. Click Preview to display a pop-up of the SQL script, or click Run to execute the script.