Script Manager (REST)

To create a new relativity script in the specified workspace, send a POST request with a URL in the following format:

1
<host>/Relativity.Rest/api/relativity-extensibility/{versionNumber}/workspaces/{workspaceID}/scripts

The request must contain the following fields:

• ScriptRequest - a request object containing the data required to create a new script.
  • ScriptBody - the body of Relativity script to create in XML format.
  • RelativityApplications - a list of applications, identified by Artifact ID or GUID, to associate with the new script.
    • ArtifactID - the Artifact ID of an application.
    • Guids - a list of GUIDs used to identify the application.

1
2
3
4
5
6
7
8
9
10
11
{
    "ScriptRequest":
    {
        "ScriptBody": "<script><name>My script Name</name><description>About my script</description><category></category><input> <constant id=\"count\" name=\"Rows\" type=\"number\" /></input><display type =\"itemlist\"/><action returns =\"table\"><![CDATA[ SELECT TOP(10) * FROM[eddsdbo].[Artifact] ]]></action></script>",
        "RelativityApplications": [
            {
                "ArtifactID": 123456
            }
        ]
    }
}

The response is an integer representing the Artifact ID of the created script.

1
123456

To retrieve information, including script body, about specified script, send a GET request with a URL in the following format:

1
<host>/Relativity.Rest/api/relativity-extensibility/{versionNumber}/workspaces/{workspaceID}/scripts/{scriptID}

If you would need to retrieve metadata and actions in addition to the script information, you can modify the endpoint as follows:

1
<host>/Relativity.Rest/api/relativity-extensibility/{versionNumber}/workspaces/{workspaceID}/scripts/{scriptID}/true/true

The body of the request is empty.

The response contains the following fields:

• Category - contains any text specified in the category section of the script body.
• Description - contain any text specified in the description section of the script body.
• IsLinkedScript - indicates whether this script is linked to a script in the admin script library.
• Key - the value used to lock a script within Relativity. You cannot modify a locked script.
• ReportGroupURL - a custom page URL used to create new tabs for displaying scripts of the same category.
• ScriptBody - the XML body of script.
• Version - the internal version of the script.
• CreatedOn - the date and time when the script was created.
• CreatedBy - the name and unique identifier for the user who created the script.
• LastModifiedBy - the name and unique identifier for the user who last updated the script.
• LastModifiedOn - the date and time when the script was last updated.
• Meta - provides additional information available as extended metadata. It includes the following fields:
  • Unsupported - a listed of fields not supported on the current instance of this user.
  • ReadOnly - an array of user properties that cannot be modified.
• Actions - an array of Action objects indicating operations that you have permissions to perform on this user. Each Action object contains the following fields that are available as extended metadata:
  • Name - the name of an operation available through REST for the user, such as delete, update, and others.
  • Href - the URL used to make an HTTP request for the operation.
  • Verb - the name of the HTTP method for the operation.
  • IsAvailable - a Boolean value indicating whether you have permissions to perform the operation on this user.
  • Reason - provides an explanation for the unavailability of an action.
• Name - the name of the script as specified in the script body.
• ArtifactID - the Artifact ID of script.
• Guids - a list of GUIDs associated with the script.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
{
    "Category": "",
    "Description": "About my script",
    "IsLinkedScript": false,
    "Key": "",
    "ReportGroupURL": "%ApplicationPath%/Case/RelativityScript/Run.aspx?%AppID%&%SystemID%&category=",
    "ScriptBody": "<script>\r\n\t<name>My script Name</name>\r\n\t<description>About my script</description>\r\n\t<category></category>\r\n\t<input />\r\n\t<display type=\"itemlist\" />\r\n\t<action returns=\"table\"><![CDATA[\n\t\t\t\t\t\t\n\t\t\t\t\t\t\tSELECT TOP(10) * FROM [eddsdbo].[Artifact]\n\t\t\t\t\t\t]]></action>\r\n</script>",
    "Version": "",
    "CreatedOn": "2020-06-12T19:51:49.79",
    "CreatedBy": {
        "Name": "Admin, Relativity",
        "ArtifactID": 9,
        "Guids": []
    },
    "LastModifiedBy": {
        "Name": "Admin, Relativity",
        "ArtifactID": 9,
        "Guids": []
    },
    "LastModifiedOn": "2020-06-12T19:51:49.79",
    "Meta": {
        "Unsupported": [
            "RelativityApplications"
        ],
        "ReadOnly": []
    },
    "Actions": [
        {
            "Name": "Delete",
            "Href": "relativity-extensibility/{versionNumber}/workspaces/-1/scripts/1021654",
            "Verb": "DELETE",
            "IsAvailable": true,
            "Reason": []
        },
        {
            "Name": "Update",
            "Href": "relativity-extensibility/{versionNumber}/workspaces/-1/scripts/1021654",
            "Verb": "PUT",
            "IsAvailable": true,
            "Reason": []
        }
    ]
    "Name": "My script Name",
    "ArtifactID": 1021654,
    "Guids": []
}

To modify an existing script, send a PUT request with a URL in the following format:

1
<host>/Relativity.Rest/api/relativity-extensibility/{versionNumber}/workspaces/{workspaceID}/scripts/{scriptID}

See the following sample JSON request:

1
2
3
4
5
6
7
8
9
10
11
{
    "ScriptRequest":
    {
        "ScriptBody": "<script><name>My script Name</name><description>About my script</description><category></category><input /><display type =\"itemlist\"/><action returns =\"table\"><![CDATA[ SELECT TOP(10) * FROM[eddsdbo].[Artifact] ]]></action></script>",
        "RelativityApplications": [
            {
                "ArtifactID": 123456
            }
        ]
    }
}

When the script is successfully updated, the response contains the status code of 200. If an error occurred parsing the script body or the Artifact ID is invalid, a status code of 400 is returned.

To delete an existing script, send a DELETE request with a URL in the following format:

1
<host>/Relativity.Rest/api/relativity-extensibility/{versionNumber}/workspaces/{workspaceID}/scripts/{scriptID}

Note: Deleting a script from the admin library also removes delete any copies imported into workspaces.

The request body is empty.

When the script is successfully deleted, the response contains the status code of 200. If the workspace ID or the Artifact ID is invalid, a status code of 400 is returned.

To import a script from the admin library to the workspace script library, send a POST request with a URL in the following format:

1
<host>/Relativity.Rest/api/relativity-extensibility/{versionNumber}/workspaces/{workspaceID}/scripts/import

The request must contain the following fields:

• ScriptImportRequest - contains information needed for script import.
• LibraryScript - identifies the script in the admin script library by Artifact ID or GUID. This script is imported into workspace script library.
• RelativityApplications - identifies applications that you want to associate with the script by Artifact ID or GUID.

1
2
3
4
5
6
7
8
9
10
11
12
{
    "ScriptImportRequest":{
        "LibraryScript":{
            "ArtifactID": 123456
        },
        "RelativityApplications": [
            {
                "ArtifactID": 789123
            }
        ]
    }
}

When a script is successfully imported, the response contains the Artifact ID of the script in the target workspace that was specified in the endpoint.

1
456789

To retrieve a list of the input parameters defined a script, send a GET request with a URL in the following format:

1
<host>/Relativity.Rest/api/relativity-extensibility/{versionNumber}/workspaces/{workspaceID}/scripts/{scriptID}/parameters

The request body is empty.

The response contains the following fields:

• Name - the name of the input parameter. The Relativity UI displays this name when it prompts the user for a value required to run the script.
• Identifier - the parameter identifier. In the SQL body, the identifier refers to a parameter.
• IsRequired - indicates whether a user must provide a value when running the script.
• Type - indicates type of parameter.
• Attributes - information specific to the parameter type.
• PossibleValues - a set of values the user must select when running the script. List these values in this field.
  • Identifier - the identifier for the script parameter as defined in the script body.
  • DisplayValue - the name of the value selection displayed in the UI when script runs.

1
2
3
4
5
6
7
8
9
10
11
12
13
[
    {
        "Name": "Rows",
        "Identifier": "count",
        "IsRequired": true,
        "Type": "Number",
        "Attributes": {
            "precision": "18",
            "scale": "0"
        },
        "PossibleValues": []
    }
]

To preview a script body with input values before running it, send a GET request with a URL in the following format:

1
<host>/Relativity.Rest/api/relativity-extensibility/{versionNumber}/workspaces/{workspaceID}/scripts/{scriptID}/preview

The request must contain the following fields:

• Inputs - an array of data providing a value for each parameter defined in the script.
  • Identifier - an input parameter identifier. This value is case-sensitive.
  • Value - value to use for parameter when generating SQL preview.

1
2
3
4
5
6
7
8
{
    "Inputs": [
        {
            "Identifier": "count",
            "Value": "25"
        }
    ]
}

When a preview request is successful, the response contains a string representing the SQL executed when the script runs, and the input parameters applied.

1
"EXECUTE sp_executesql N'SELECT TOP(CAST(@count AS INT)) * FROM [eddsdbo].[Artifact]', N'@count DECIMAL(18,0)', 22"

To queue a script for running, send a POST request with a URL in the following format:

1
<host>/Relativity.Rest/api/relativity-extensibility/{versionNumber}/workspaces/{workspaceID}/scripts/{scriptID}/run

The request must contain the following fields:

• Inputs - an array of data with a value for each parameter defined in the script.
  • Identifier - an input parameter identifier. This value is case-sensitive.
  • Value - a value used for specifying an input parameter.
• TimeZoneOffset - the time zone offset for use in the script. Reference this value in the script body using the format #TimeZoneOffset#.

1
2
3
4
5
6
7
8
9
{
    "Inputs": [
        {
            "Identifier": "count",
            "Value": "25"
        }
    ],
    "TimeZoneOffset": 0
}

When an enqueue request is successful, the response contains a unique script run job identifier used for checking job status, and querying and exporting script results.

1
"RunJobID": "a081c453-ae0d-44f4-a204-def5e556a396"

To return the status of the script run job and each action contained in the script, send a GET request with a URL in the following format:

1
<host>/Relativity.Rest/api/relativity-extensibility/{versionNumber}/workspaces/{workspaceID}/scripts/run-jobs/{runJobID}

Note: The runJobID is a GUID.

The request body is empty.

The response contains the following fields about the state of the script job and the individual actions:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
    "Status": "Completed",
    "ActionJobs": [
        {
            "Name": "",
            "ReturnType": "Table",
            "AllowHtmlTagsInOutput": false,
            "ErrorMessage": "",
            "Columns": [
                {
                    "Name": "ArtifactID",
                    "DataType": "Number"
                },     
            ...
            ],
            "RowsAffected": 0,
            "Status": "Completed"
        }
    ],
    "ErrorMessage": ""
}

To return completed script action results that match query filter and sort criteria, send a POST request with a URL in the following format:

1
<host>/Relativity.Rest/api/relativity-extensibility/{versionNumber}/workspaces/{workspaceID}/scripts/run-jobs/{runJobID}/actions/{actionIndex}/query-results

Set the path parameters as follows:

• workspaceID - the Artifact ID of the workspace containing the script.
• runJobID - a GUID identifying the job.
• actionIndex - the zero-based index of the script action to query. All scripts contain at least one action section, but they can multiple action sections that execute in sequence. A value of 0 refers to the first action in the script, 1 refers to the second action, and so on. The action 0 always works. An error is returned when a value of 1 is entered for a script with only a single action section.

The request must contain the following fields:

• Inputs - an array of data providing a value for each parameter defined in the script.
  • Condition - criteria used to filter returned results.
  • Sorts - criteria used to sort results.
  • ColumnNames - specific column names to return in results. Use an asterisk ("*") to return all columns.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
    "ActionQueryRequest":
    {
        "Condition":"'TextIdentifier' LIKE 'important'",
        "Sorts":
            [
                {
                    "ColumnName": "TextIdentifier",
                    "Direction": "Ascending"
                }
            ],
        "ColumnNames":
            [
                "TextIdentifier"
                "ArtifactID"
            ]
    },
    "Start": 0,
    "Length": 10
}

A successful query action job request returns all the results from the specified script run action that meet the query criteria in the request.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{
    "TotalCount": 25,
    "Rows": [
        {
            "Values": [
                "Active",
                662
            ]
        },
        {
            "Values": [
                "Admin Mode",
                -1
            ]
        },
    ...
        {
            "Values": [
                "WorkspacesOnPicker",
                359
            ]
        }
    ],
    "Columns": [
        {
            "Name": "TextIdentifier",
            "DataType": "Text"
        },
        {
            "Name": "ArtifactID",
            "DataType": "Number"
        }
    ],
    "CurrentStartIndex": 0,
    "ResultCount": 25
}

To export completed script action results that match query filter/sort conditions, send a POST request with a URL in the following format:

1
<host>/Relativity.Rest/api/relativity-extensibility/{versionNumber}/workspaces/{workspaceID}/scripts/run-jobs/{runJobID}/actions/{actionIndex}/export-results

Set the path parameters as follows:

• workspaceID - the Artifact ID of the workspace containing the script.
• runJobID - a GUID identifying the job.
• actionIndex - the zero-based index of the script action to query. All scripts contain at least one action section, but they can multiple action sections that execute in sequence. A value of 0 refers to the first action in the script, 1 refers to the second action, and so on. The action 0 always works. An error is returned when a value of 1 is entered for a script with only a single action section.

The request must contain the following fields:

• Inputs- an array of data providing a value for each parameter defined in the script.
  • Condition - criteria used to filter returned results.
  • Sorts - criteria used to sort results.
  • ColumnNames - specific column names to return in results. Use an asterisk ("*") to return all columns.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
    "ActionExportRequest": {
        "QueryRequest": {
            "Condition": "",
            "Sorts": [
                {
                    "ColumnName": "TextIdentifier",
                    "Direction": "Ascending"
                }
            ],
            "ColumnNames": [
                "*"
            ]
        }
    }
}

A successful export action job request returns all the specified results from the script action as a CSV text file.

1
2
3
4
5
6
7
"ArtifactID","ArtifactTypeID","ParentArtifactID","AccessControlListID","AccessControlListIsInherited","CreatedOn","LastModifiedOn","LastModifiedBy","CreatedBy","TextIdentifier","ContainerID","Keywords","Notes","DeleteFlag",
"662","7","62","1","True","1/1/2007 12:00:00 AM","1/1/2007 12:00:00 AM","9","9","Active","62"," "," ","False",
"'-1","8","62","1","False","9/29/2014 3:32:47 PM","9/29/2014 3:32:47 PM","9","9","Admin Mode","62","","Admin Workspace - to be used for admin permissions only","False",
 
...
 
"359","4","62","1","True","1/1/2007 12:00:00 AM","8/5/2008 12:38:34 AM","9","9","WorkspacesOnPicker","62","","","False",

To return completed script results (for all actions) that match query filter/sort conditions, send a POST request with a URL in the following format:

1
<host>/Relativity.Rest/api/relativity-extensibility/{versionNumber}/workspaces/{workspaceID}/scripts/run-jobs/{runJobID}/export-report

Note: The runJobID is a GUID.

The request must contain the following fields:

• Inputs - an array of data providing a value for each parameter defined in the script.
  • FileType - format of returned file. Available options are HTML, CSV, PDF, XLS, XLSX, RTF, PNG.

1
2
3
4
5
6
{
    "ScriptExportRequest":
    {
        "FileType": "PDF"
    }
}

A successful export script report request returns the script results in the specified file format.

To clean up all temporary tables created as part of a script run job, send a DELETE request with a URL in the following format:

1
<host>/Relativity.Rest/api/relativity-extensibility/{versionNumber}/workspaces/{workspaceID}/scripts/run-jobs/{runJobID}

Note: The runJobID is a GUID.

The request body is empty.

There is no response body.

Note: After you call this endpoint, the script results are no longer available for query or export.