Script Manager (REST)
Relativity Scripts allow for the execution of SQL scripts in the database(s) backing a Relativity instance. The Relativity Script Manager API exposes endpoints allowing for the programmatic interaction with scripts including:
- Add script
- Delete a script
- Modify a script
- Retrieve script input parameters
- Preview a script
- Import a script
- Queue a script to run
- Retrieve status of a script
- Query action results
- Export action results
- Export script report
- Clean up script results
The service may be used to create a standalone application that manages scripts across multiple environments or among workspaces in a single environment.
Contracts and data models related to the API are contained in the following NuGet packages:
- Relativity.Services.SDK
You can also use the Script service through the .NET API. For more information, see Script Manager API.
This page contains the following information:
Fundamentals for managing resource pools
Client code sample
public async Task<int> CreateScriptAsync() { int scriptID = 0; using (Relativity.Services.Interfaces.Script.IScriptManager scriptManager = serviceFactory.CreateProxy<Relativity.Services.Interfaces.Script.IScriptManager>()) using (HttpClient client = new HttpClient()) { client.DefaultRequestHeaders.Add("X-CSRF-Header", "-"); client.DefaultRequestHeaders.Add("Authorization", "Basic " + Convert.ToBase64String(Encoding.GetEncoding("ISO-8859-1").GetBytes("<user login>:<user password>"))); client.DefaultRequestHeaders.Add("X-Kepler-Version", "2.0"); client.BaseAddress = new Uri("http://<host name>/"); string inputJSON = @"{""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(CAST(#count# AS INT)) * FROM [eddsdbo].[Artifact] ]]></action></script>"",""RelativityApplications"": []}}"; string url = "/Relativity.rest/api/relativity.scripts/workspace/-1/scripts"; HttpResponseMessage response = await client.PostAsync(url, new StringContent(inputJSON, Encoding.UTF8, "application/json")); response.EnsureSuccessStatusCode(); string content = await response.Content.ReadAsStringAsync(); scriptID = Int32.Parse(content); } return scriptID; }
Add a script
To create a new relativity script in the specified workspace, send a POST request with a URL in the following format:
POST: <host>/Relativity.Rest/api/Relativity.Scripts/workspace/<workspaceID>/scripts
Note: The workspace ID is a route parameter.
The request must contain the following fields:
- ScriptRequest - this object contains data required to create new script.
- ScriptBody - body of relativity script to create (xml format).
- RelativityApplications - list of applications, identified either by artifact ID or GUID, to associate with new script.
- ArtifactID - Artifact ID of application.
- Guids- list of GUIDs per application.
{ "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 a single integer representing the artifact ID of the created script.
123456
Read script
To retrieve information, including script body, about specified script, send a GET request with a URL in the following format:
GET: <host>/Relativity.Rest/api/Relativity.Scripts/workspace/<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:
GET: <host>/Relativity.Rest/api/Relativity.Scripts/workspace/<workspaceID>/scripts/<scriptID>/true/true
There is no request body.
Note: Both the workspace ID and the script ID are route parameters.
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 the script is linked to a script in the admin script library.
- Key - the value used to lock a script within Relativity. A locked script cannot be modified.
- ReportGroupURL - a custom page URL that can be used to create new tabs for displaying scripts of the same category.
- ScriptBody - XML body of script.
- Version - internal version of the script.
- CreatedOn - date and time of script creation.
- CreatedBy - information about the user who created the script
- LastModifiedBy - information about user who last modified the script.
- LastModifiedOn - information about when script was last modified.
- 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 can't 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 - name of an operation available through REST for the user, such as delete, update, and so on.
- 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 - name of script as specified in the script body.
- ArtifactID - Artifact ID of script.
- Guids - list of GUIDs associated with the script.
{ "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.Scripts/workspace/-1/scripts/1021654", "Verb": "DELETE", "IsAvailable": true, "Reason": [] }, { "Name": "Update", "Href": "Relativity.Scripts/workspace/-1/scripts/1021654", "Verb": "PUT", "IsAvailable": true, "Reason": [] } ] "Name": "My script Name", "ArtifactID": 1021654, "Guids": [] }
Update script
To modify an existing script, send a POST request with a URL in the following format:
POST: <host>/Relativity.Rest/api/Relativity.Scripts/workspace/<workspaceID>/scripts/<scriptID>
Note: Both the workspace ID and the script ID are route parameters.
{ "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 } ] } }
There is no response body. A successful update will return a 200 status code. A 400 status code will be returned if there is an error parsing the script body or the artifact ID is invalid.
Delete script
To delete an existing script, send a DELETE request with a URL in the following format:
DELETE: <host>/Relativity.Rest/api/Relativity.Scripts/workspace/<workspaceID>/scripts/<scriptID>
Note: Deleting a script from the admin library will delete any copies that have been imported into workspaces.
There is no request body.
Note: Both the workspace ID and the script ID are route parameters.
There is no response body. A successful delete will return a 200 status code. A 400 status code will be returned if the workspace ID or the artifact ID is invalid.
Import script
To import a script from the admin library to the workspace script library, send a POST request with a URL in the following format:
POST: <host>/Relativity.Rest/api/Relativity.Scripts/workspace/<workspaceID>/scripts/import
Note: The target workspace ID is a route parameter.
The request must contain the following fields:
- ScriptImportRequest - contains information needed for script import.
- LibraryScript - identifies admin script library script by artifact ID or GUID to import into workspace script library.
- RelativityApplications - identifies applications, by artifact ID or GUID to associate with the script.
{ "ScriptImportRequest":{ "LibraryScript":{ "ArtifactID": 123456 }, "RelativityApplications": [ { "ArtifactID": 789123 } ] } }
A successful script import will return the artifact ID of the script in the target workspace. (ID of target workspace is specified in the route.)
456789
Get script parameters
To retrieve a list of the input parameters defined in a given script, send a GET request with a URL in the following format:
GET: <host>/Relativity.Rest/api/Relativity.Scripts/workspace/<workspaceID>/scripts/<scriptID>/parameters
There is no request body.
Note: Both the workspace ID and the script ID are route parameters.
The response contains the following fields:
- Name - name of the input parameter. The name is used in the UI when a user is prompted for provide a value when running the script.
- Id - parameter identifier. The identifier is how the parameters is referred to in the SQL body.
- IsRequired - whether or not a value must be provided when running the script.
- Type - indicates type of parameter.
- Attributes - information specific to the parameter type.
- PossibleValues- if the script specifies a set of values the user must select from when running the script they will be listed here.
- Id - identifier of the script parameter as defined in the script body.
- DisplayValue - name of the value selection displayed in the UI when script is run.
[ { "Name": "Rows", "Id": "count", "IsRequired": true, "Type": "Number", "Attributes": { "precision": "18", "scale": "0" }, "PossibleValues": [] } ]
Preview script
To preview a script body (with input values applied) before running it, send a GET request with a URL in the following format:
GET: <host>/Relativity.Rest/api/Relativity.Scripts/workspace/<workspaceID>/scripts/<scriptID>/preview
Note: Both the workspace ID and the script ID are route parameters.
The request must contain the following fields:
- Inputs- an array of data providing a value for each parameter defined in the script.
- ID - input parameter identifier. (case-sensitive)
- Value - value to use for parameter when generating SQL preview.
{ "Inputs": [ { "ID": "count", "Value": "25" } ] }
A successful script preview request will return a string representing the SQL (with input parameter values applied) that will be executed when script is run.
"EXECUTE sp_executesql N'SELECT TOP(CAST(@count AS INT)) * FROM [eddsdbo].[Artifact]', N'@count DECIMAL(18,0)', 22"
Enqueue run job
To queue a script to be run, send a POST request with a URL in the following format:
POST: <host>/Relativity.Rest/api/Relativity.Scripts/workspace/<workspaceID>/scripts/<artifactID>/run
Note: Both the workspace ID and the script ID are route parameters.
The request must contain the following fields:
- Inputs- an array of data providing a value for each parameter defined in the script.
- ID - input parameter identifier. (case-sensitive)
- Value - value to use for specified input parameter.
- TimeZoneOffset - time zone offset for use in the script. (Can be referenced in the script body using #TimeZoneOffset#.)
{ "Inputs": [ { "ID": "count", "Value": "25" } ], "TimeZoneOffset": 0 }
A successful script enqueue request will return a unique script run job identifier that will be used for checking job status as well as querying and exporting script results.
"RunJobID": "a081c453-ae0d-44f4-a204-def5e556a396"
Read run job
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:
GET: <host>/Relativity.Rest/api/Relativity.Scripts/workspace/<workspaceID>/scripts/run/<runJobID>
There is no request body.
Note: Both the workspace ID and the run job ID are route parameters.
A successful script read run job request will return a information about the state of the overall script run job, as well information about the individual actions.{ "Status": "Completed", "ActionJobs": [ { "Name": "", "ReturnType": "Table", "AllowHtmlTagsInOutput": false, "ErrorMessage": "", "Columns": [ { "Name": "ArtifactID", "DataType": "Number" }, ... ], "RowsAffected": 0, "Status": "Completed" } ], "ErrorMessage": "" }
Query action job results
To return completed script action results that match query filter and sort criteria, send a POST request with a URL in the following format:
POST: <host>/Relativity.Rest/api/Relativity.Scripts/workspace/<workspaceID>/scripts/runs/<runJobID>/actions/<actionIndex>/query-results
Note: Both the workspace ID, run job ID, and action index are route parameters.
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 "*" to return all columns."
{ "ActionQueryRequest": { "Condition":"'TextIdentifier' LIKE 'important'", "Sorts": [ { "ColumnName": "TextIdentifier", "Direction": "Ascending" } ], "ColumnNames": [ "TextIdentifier" "ArtifactID" ] }, "Start": 0, "Length": 10 }
A successful query action job request will return all the results from the specified script run action that meet the query criteria in the request.
{ "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 }
Export action results
To export completed script action results that match query filter/sort conditions, send a POST request with a URL in the following format:
POST: <host>/Relativity.Rest/api/Relativity.Scripts/workspace/<workspaceID>/scripts/runs/<runJobID>/actions/<actionIndex>/export
Note: Both the workspace ID, run job ID, and action index are route parameters.
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 "*" to return all columns."
{ "ActionExportRequest": { "QueryRequest": { "Condition": "", "Sorts": [ { "ColumnName": "TextIdentifier", "Direction": "Ascending" } ], "ColumnNames": [ "*" ] } } }
A successful export action job request will return all the specified results from the script action as a CSV text file.
"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",
Export script report
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:
POST: <host>/Relativity.Rest/api/Relativity.Scripts/workspace/<workspaceID>/scripts/runs/<runJobID>/export
Note: Both the workspace ID, and run job ID are route parameters.
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.
{ "ScriptExportRequest": { "FileType": "PDF" } }
A successful export script report request will return the script results in the specified file format.
Clean up run job
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:
DELETE: <host>/Relativity.Rest/api/Relativity.Scripts/workspace/<workspaceID>/scripts/runs/<runJobID>
There is no request body.
Note: Both the workspace ID and run job ID are route parameters.
There is no response body.
Note: Once this method has been called the script results are no longer available for querying or export. Any results tables not cleaned up explicitly using this method will be automatically removed after 7 days.