

Last date modified: March 20 2025
In Relativity, you can execute SQL scripts through the UI that act on the databases backing an instance. You can implement these scripts to customize and extend Relativity functionality. For more information, see Scripts on the Relativity
The Relativity Script Manager API exposes methods for interacting with scripts as follows:
Use this API to create standalone applications that manage scripts across multiple environments or across workspaces in a single environment.
You can also use the Script service through REST. For more information, see Script service.
Note: For a script to be run (once queued) a Script Run Manager agent must be running in the environment.
Methods - the following gives a brief list of the methods available in the service
Models - the following lists data models used in the Script Manager service.
For more complicated scripts, it is often easier to implement and debug the script body using SQL Server Management Studio directly.
To add a script to Relativity, call the CreateAsync method by passing in the following parameters:
This method returns the Artifact ID of the new 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
public async Task CreateNewScriptAsync()
{
string 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>";
using (Relativity.Extensibility.V1.Scripts.IScriptManager scriptManager = serviceFactory.CreateProxy<Relativity.Extensibility.V1.Scripts.IScriptManager>())
{
try
{
Relativity.Extensibility.V1.Scripts.Models.ScriptRequest scriptRequest = new Relativity.Services.Interfaces.Scripts.Models.ScriptRequest
{
ScriptBody = scriptBody,
RelativityApplications = null
};
int workspaceID = 1015024;
int scriptID = await scriptManager.CreateAsync(workspaceID, scriptRequest);
}
catch (Exception ex)
{
Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
}
}
}
Note: Method is overloaded for optional metadata and action data.
The ReadAsync method retrieves basic metadata for a script, including its name, body and other parameters.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
public async Task ReadScriptAsync()
{
using (Relativity.Extensibility.V1.Scripts.IScriptManager scriptManager = serviceFactory.CreateProxy<Relativity.Extensibility.V1.Scripts.IScriptManager>())
{
try
{
int workspaceID = -1;
int scriptID = 1021467;
ScriptResponse response = await scriptManager.ReadAsync(workspaceID, scriptID);
}
catch (Exception ex)
{
Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
}
}
}
The UpdateAsync () method modifies a script by passing the following parameters to it:
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
public async Task UpdateScriptAsync()
{
string 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].[Field]
]]></action>
</script>";;
using (Relativity.Extensibility.V1.Scripts.IScriptManager scriptManager = serviceFactory.CreateProxy<Relativity.Extensibility.V1.Scripts.IScriptManager>())
{
try
{
Relativity.Extensibility.V1.Scripts.Models.ScriptRequest scriptRequest = new Relativity.Extensibility.V1.Scripts.Models.ScriptRequest
{
ScriptBody = scriptBody,
RelativityApplications = null
};
int workspaceID = -1;
int scriptID = 1021467;
await scriptManager.UpdateAsync(workspaceID, scriptID, scriptRequest);
}
catch (Exception ex)
{
Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
}
}
}
The DeleteAsync method deletes a script by passing it the following parameters:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
public async Task DeleteScriptAsync()
{
using (Relativity.Extensibility.V1.Scripts.IScriptManager scriptManager = serviceFactory.CreateProxy<Relativity.Extensibility.V1.Scripts.IScriptManager>())
{
try
{
int workspaceID = -1;
int scriptID = 123456;
await scriptManager.DeleteAsync(workspaceID, scriptID);
}
catch (Exception ex)
{
Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
}
}
}
The ImportAsync method imports a script from the admin library to the workspace script library when you pass it the following parameters:
The method returns the Artifact ID of the imported script in the workspace.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
public async Task ImportScriptAsync()
{
using (Relativity.Extensibility.V1.Scripts.IScriptManager scriptManager = serviceFactory.CreateProxy<Relativity.Extensibility.V1.Scripts.IScriptManager>())
{
try
{
int workspaceID = 1015024;
ScriptImportRequest importRequest = new ScriptImportRequest
{
LibraryScript = new ObjectIdentifier
{
// artifact ID of script in admin script library
// to import into workspace script library.
ArtifactID = 1021467
}
};
int workspaceScriptID = await scriptManager.ImportAsync(workspaceID, importRequest);
}
catch (Exception ex)
{
Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
}
}
}
The GetScriptParametersAsync method retrieves a list of the input parameters defined in a given script when you pass it the following parameters:
The method returns a list of ScriptParameterDetail objects containing information about the inputs for 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
public async Task GetScriptParametersAsync()
{
using (Relativity.Extensibility.V1.Scripts.IScriptManager scriptManager = serviceFactory.CreateProxy<Relativity.Extensibility.V1.Scripts.IScriptManager>())
{
try
{
int workspaceID = -1;
int scriptID = 123456;
List<ScriptParameterDetails> response = await scriptManager.GetScriptParametersAsync(workspaceID, scriptID);
// Construct script inputs based on parameter detail response.
// See PreviewScriptAsync and EnqueueRunJobAsync methods that take ScriptInput objects as parameters.
List<ScriptInput> scriptInputs = new List<ScriptInput>();
foreach (var scriptParameter in response)
{
ScriptInput input = new SingleScriptInput()
{
ID = scriptParameter.Id,
Value = GetScriptInputValueByName(scriptParameter.Name) // <-- Hypothetical method providing valid input value.
};
scriptInputs.Add(input);
}
}
catch (Exception ex)
{
Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
}
}
}
The PreviewScriptAsync method is used to examine a script body (with input values applied) before running it, by passing it the following parameters:
The method returns a string representing the SQL query that will be executed when the script is run (with input values applied).
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
public async Task GetScriptPreviewAsync()
{
using (Relativity.Services.Interfaces.Script.IScriptManager scriptManager = serviceFactory.CreateProxy<Relativity.Services.Interfaces.Script.IScriptManager>())
{
try
{
int workspaceID = -1;
int scriptID = 1022818;
List<ScriptInput> inputs = new List<ScriptInput>()
{
new SingleScriptInput()
{
ID = "count",
Value = "7"
}
};
string scriptBody = await scriptManager.PreviewScriptAsync(workspaceID, scriptID, inputs);
}
catch (Exception ex)
{
Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
}
}
}
The EnqueueRunJobAsync method queues a script to be run when you pass it the following parameters:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
public async Task RunScriptAsync()
{
using (Relativity.Extensibility.V1.Scripts.IScriptManager scriptManager = serviceFactory.CreateProxy<Relativity.Extensibility.V1.Scripts.IScriptManager>())
{
try
{
int workspaceID = -1;
int scriptID = 1022744;
List<ScriptInput> inputs = new List<ScriptInput>()
{
new SingleScriptInput()
{
ID = "count",
Value = "7"
}
};
EnqueueRunJobResponse enqueueResponse = await scriptManager.EnqueueRunJobAsync(workspaceID, scriptID, inputs, 0);
}
catch (Exception ex)
{
Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
}
}
}
Note: You should call the CleanupRunJobAsync method once querying the results of your script job has finished.
The ReadRunJobAsync method returns the status of the script run job and each action contained in the script when you pass it the following parameters.
The method returns the status of each action in the queued script.
Run Job Status:
Action Job Status:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
public async Task ScriptRunStatusAsync()
{
using (Relativity.Extensibility.V1.Scripts.IScriptManager scriptManager = serviceFactory.CreateProxy<Relativity.Extensibility.V1.Scripts.IScriptManager>())
{
try
{
int workspaceID = -1;
Guid runJobID = new Guid("0d2d724b-999e-47dc-a206-2dcf17f910b3");
RunJob statusResponse = await scriptManager.ReadRunJobAsync(workspaceID, runJobID);
}
catch (Exception ex)
{
Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
}
}
}
The QueryActionJobResultsAsync method returns completed script action results that match query filter and sort criteria when you pass in the following parameters:
The method returns results from script actions matching query criteria and pagination values.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
public async Task QueryScriptActionResultsAsync()
{
using (Relativity.Extensibility.V1.Scripts.IScriptManager scriptManager = serviceFactory.CreateProxy<Relativity.Extensibility.V1.Scripts.IScriptManager>())
{
try
{
int workspaceID = -1;
Guid runJobID = new Guid("0d2d724b-999e-47dc-a206-2dcf17f910b3");
ActionQueryRequest queryRequest = new ActionQueryRequest()
{
ColumnNames = new List<string>() { "Name", "ArtifactID" },
Condition = "'Name' LIKE 'important'",
Sorts = new List<ActionColumnSort>() { new ActionColumnSort() {ColumnName = "Name"}}
};
ActionResultsQueryResponse actionQueryResponse = await scriptManager.QueryActionJobResultsAsync(workspaceID, runJobID, 0, queryRequest, 0, 20);
}
catch (Exception ex)
{
Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
}
}
}
The ExportActionResultsAsync method returns completed script action results that match query filter/sort conditions when you pass in the following parameters:
The method exports a stream containing results from script action matching query criteria and pagination values to a CSV formatted text file.
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
public async Task ExportScriptActionResultsAsync()
{
using (Relativity.Extensibility.V1.Scripts.IScriptManager scriptManager = serviceFactory.CreateProxy<Relativity.Extensibility.V1.Scripts.IScriptManager>())
{
try
{
int workspaceID = -1;
Guid runJobID = new Guid("0d2d724b-999e-47dc-a206-2dcf17f910b3");
ExportActionResultsRequest actionExportRequest = new ExportActionResultsRequest() {
QueryRequest = new ActionQueryRequest()
{
ColumnNames = new List<string>() { "Name", "ArtifactID" },
Sorts = new List<ActionColumnSort>() { new ActionColumnSort() { ColumnName = "Name" } }
}
};
IKeplerStream exportStream = await scriptManager.ExportActionResultsAsync(workspaceID, runJobID, 0, actionExportRequest);
using (FileStream file = File.Create(@"C:\ScriptActionResults.csv"))
{
await exportStream.GetStreamAsync().Result.CopyToAsync(file);
}
}
catch (Exception ex)
{
Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
}
}
}
The ExportScriptReportAsync method returns completed script results (for all actions) that match query filter/sort conditions when you pass in the following parameters:
The method returns a stream containing script results in the specified file format.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
public async Task ExportScriptResultsAsync()
{
using (Relativity.Extensibility.V1.Scripts.IScriptManager scriptManager = serviceFactory.CreateProxy<Relativity.Extensibility.V1.Scripts.IScriptManager>())
{
try
{
int workspaceID = -1;
Guid runJobID = new Guid("0d2d724b-999e-47dc-a206-2dcf17f910b3");
ExportScriptReportRequest exportRequest = new ExportScriptReportRequest()
{
FileType = ExportFileType.PDF
};
IKeplerStream exportStream = await scriptManager.ExportScriptReportAsync(workspaceID, runJobID, exportRequest);
using (FileStream file = File.Create(@"C:\ScriptResults.pdf"))
{
await exportStream.GetStreamAsync().Result.CopyToAsync(file);
}
}
catch (Exception ex)
{
Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
}
}
}
The CleanupRunJobAsync method cleans up all temporary tables created as part of a script run job when you pass in the following parameters:
Note: Once this method has been called the script results are no longer available for querying or export.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
public async Task CleanUpScriptAsync()
{
using (Relativity.Services.Interfaces.Script.IScriptManager scriptManager = serviceFactory.CreateProxy<Relativity.Services.Interfaces.Script.IScriptManager>())
{
try
{
int workspaceID = -1;
Guid runJobID = new Guid("0d2d724b-999e-47dc-a206-2dcf17f910b3");
await scriptManager.CleanupRunJobAsync(workspaceID, runJobID);
}
catch (Exception ex)
{
Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
}
}
}
On this page
Why was this not helpful?
Check one that applies.
Thank you for your feedback.
Want to tell us more?
Great!
Additional Resources |
|||
DevHelp Community | GitHub | Release Notes | NuGet |