

Last date modified: June 17 2025
The Structured Analytics Job Manager API supports the automation of various structured analytics workflows. It provides functionality for running an analysis of a structured analytics set, checking the status of the analysis, retrieving document and set errors, and performing other tasks. It also supports the use of progress indicators and cancellation tokens by provided overloaded methods with these options.
For example, you may want to use the Structured Analytics Job Manager API to implement a custom workflow for running structured analytics sets. With this API, you can automate the process for the analysis and monitoring of these sets. It provides an alternative to manually performing these tasks through the Relativity UI.
You can also use the Structured Analytics Job Manager service through REST. However, this service doesn't support cancellation tokens or progress indicators through REST. For more information, see Structured Analytics Job Manager (REST).
Review the following information to learn more about structured analytics.
The Analytics application includes functionality that you can use to run structured analytics operations. These operations identify differences and similarities between documents added to a structured analytics set. You create a structured analytics set by selecting a saved search with the documents for analysis, the operations that you want to execute, the Analytics server used for this process, and other options.
You can select the following structured analytics operations through the Relativity UI:
For more information, see
The Structured Analytics Job Manager API includes the following namespaces that contain the methods, classes, and enumerations needed to automate the analysis of structured analytics sets.
The <VersionNumber> variable in the namespace indicates the version number of the API. The version number uses the format uppercase V and an integer version number, such as V1 or V2 in .NET.
This namespace contains the IStructuredAnalyticsManager interface provides you with access to Structured Analytics Job Manager service. The following methods also support progress monitoring and cancellation tokens:
Review the following guidelines for working with this API.
When implementing your custom code, follow these guidelines:
To get a list of valid operations, make a call with the GetValidTasksAsync() method. The ValidTaskResult object returned from this call contains a valid list of operations. If you attempt to execute an invalid operation, you receive 400 status response.
Use the code samples in the following sections to learn about calling the methods available in the Structured Analytics Job Manager API. These code samples illustrate the following best practices for working with the API:
Use these steps to set up your Relativity environment:
You can optionally call the RunAnalysisPreparationAsync() method when you want to generate fields for storing results before you run an analysis on a new structured analytics set. For example, you might use the following workflow in this case:
To generate these results fields, call the RunAnalysisPreparationAsync() method by passing the Artifact ID for the structured analytics set, and the workspace that contains it. You can also optionally pass ProgressReport or CancellationToken objects to this method.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
public void RunSample()
{
int workspaceId = Constants.WORKSPACE_ID;
int sasArtifactId = Constants.SAS_ARTIFACT_ID;
using (IJobManager sasManager = ServiceProxyHelper.CreateProxy<IJobManager>())
{
OperationResult results = sasManager.RunAnalysisPreparationAsync(workspaceId, sasArtifactId).GetAwaiter().GetResult();
if (results.IsSuccess)
{
System.Diagnostics.Debug.WriteLine($"Call to run Analysis Preparation on SAS {sasArtifactId} on workspace {workspaceId} succeeded");
}
else
{
throw new Exception($"Call to run Analysis Preparation on SAS {sasArtifactId} on workspace {workspaceId} failed. Error message: {results.Message}");
}
}
}
You can use the GetValidTasksAsync() method to retrieve all valid operations that you can run for a specific structured analytics set, such as retrying errors, running an analysis, and others.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
public void RunSample()
{
int workspaceId = Constants.WORKSPACE_ID;
int sasArtifactId = Constants.SAS_ARTIFACT_ID;
using (IJobManager sasManager = ServiceProxyHelper.CreateProxy<IJobManager>())
{
ValidTaskResult results = sasManager.GetValidTasksAsync(workspaceId, sasArtifactId).GetAwaiter().GetResult();
if (results != null)
{
System.Diagnostics.Debug.WriteLine($"Call to get valid tasks on SAS {sasArtifactId} on workspace {workspaceId} succeeded. Copy to legacy is legal: {results.CopyToLegacyQualified}, Valid tasks: {string.Join(",", results.ValidTasks.Select(t => t.ToString()))}");
}
else
{
throw new Exception($"Call to get valid tasks on SAS {sasArtifactId} on workspace {workspaceId} failed.");
}
}
}
To analyze documents in a structured analytics set, call the RunAsync() method by passing the Artifact ID for the structured analytics set, the Artifact ID for the workspace that contains it, and an AnalysisSettings object. This object has properties that you can use to specify whether all documents are updated with the analysis results and repopulated or just new ones undergo these processes. You can also optionally pass ProgressReport or CancellationToken objects to this method.
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
public void RunSample()
{
int workspaceId = Constants.WORKSPACE_ID;
int sasArtifactId = Constants.SAS_ARTIFACT_ID;
using (IJobManager sasManager = ServiceProxyHelper.CreateProxy<IJobManager>())
{
AnalysisSettings runAnalysisSettings = new AnalysisSettings();
//This AnalysisSettings configuration will run the equivalent of a Pre-Smart Ingestion Full Analysis
runAnalysisSettings.AnalyzeAll = true;
runAnalysisSettings.PopulateAll = true;
//This AnalysisSettings configuration will run the equivalent of a Pre-Smart Ingestion Incremental Analysis
//runAnalysisSettings.AnalyzeAll = false;
//runAnalysisSettings.PopulateAll = false;
//This AnalysisSettings configuration will add new documents to staging area, remove documents from staging area
//that no longer exist in the target saved search, and run a full analysis.
//runAnalysisSettings.AnalyzeAll = true;
//runAnalysisSettings.PopulateAll = false;
//This AnalysisSettings configuration is illegal and will throw a validation error
//runAnalysisSettings.AnalyzeAll = false;
//runAnalysisSettings.PopulateAll = true;
OperationResult results = sasManager.RunAsync(workspaceId, sasArtifactId, runAnalysisSettings).GetAwaiter().GetResult();
if (results.IsSuccess)
{
System.Diagnostics.Debug.WriteLine($"Call to run analysis on SAS {sasArtifactId} on workspace {workspaceId} succeeded");
}
else
{
throw new Exception($"Call to run analysis on SAS {sasArtifactId} on workspace {workspaceId} failed. Error message: {results.Message}");
}
}
}
The CancelAsync() method makes a request to cancel the analysis of the structured analytics set that is currently running. It then returns control immediately to the caller. This request only initiates an asynchronous cancel request. The job for the structured analytics set job run isn't guaranteed to be canceled on the response of this request. Poll the GetStatusAsync() method after completing this request to monitor the progress of your cancel request.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
public void CancelSample()
{
int workspaceId = Constants.WORKSPACE_ID;
int sasArtifactId = Constants.SAS_ARTIFACT_ID;
using (IJobManager sasManager = ServiceProxyHelper.CreateProxy<IJobManager>())
{
OperationResult results = sasManager.CancelAsync(workspaceId, sasArtifactId).GetAwaiter().GetResult();
if (results.IsSuccess)
{
System.Diagnostics.Debug.WriteLine($"Call to run Cancel Analysis on SAS {sasArtifactId} on workspace {workspaceId} succeeded");
}
else
{
throw new Exception($"Call to run Cancel Analysis on SAS {sasArtifactId} on workspace {workspaceId} failed. Error message: {results.Message}");
}
}
}
Use the GetStatusAsync() method to return a Status object. This object contains information about the state of job and current operations. For more information, see Fundamentals for the Structured Analytics Job Manager API
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
public void GetStatusSample()
{
int workspaceId = Constants.WORKSPACE_ID;
int sasArtifactId = Constants.SAS_ARTIFACT_ID;
using (IJobManager sasManager = ServiceProxyHelper.CreateProxy<IJobManager>())
{
SASModels.Status.Status results = sasManager.GetStatusAsync(workspaceId, sasArtifactId).GetAwaiter().GetResult();
System.Diagnostics.Debug.WriteLine($"SAS Name: {results.JobName}");
System.Diagnostics.Debug.WriteLine($"SAS Status: {results.JobState.Status}");
if (results.JobState.IsCompleted)
{
System.Diagnostics.Debug.WriteLine($"SAS Docs Analyzed: {results.JobResults.DocumentsAnalyzed}");
}
}
}
Use the RetryErrorsAsync() method to resolve transient errors that occurred during an analysis.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
public void RetryErrorsSample()
{
int workspaceId = Constants.WORKSPACE_ID;
int sasArtifactId = Constants.SAS_ARTIFACT_ID;
using (IJobManager sasManager = ServiceProxyHelper.CreateProxy<IJobManager>())
{
OperationResult results = sasManager.RetryErrorsAsync(workspaceId, sasArtifactId).GetAwaiter().GetResult();
if (results.IsSuccess)
{
System.Diagnostics.Debug.WriteLine($"Call to run Retry Errors on SAS {sasArtifactId} on workspace {workspaceId} succeeded");
}
else
{
throw new Exception($"Call to run Retry Errors on SAS {sasArtifactId} on workspace {workspaceId} failed. Error message: {results.Message}");
}
}
}
The GetErrorsAsync() method retrieves set errors. These are errors aren't document specific and they cause an analysis to stop. For example, a set error may be a validation error for a structured analytics set, or it may occur when the Analytics server is disabled or goes down. This method returns a StructuredAnalyticsSetError object. For more information, see Fundamentals for the Structured Analytics Job Manager API.
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
public void GetErrorsSample()
{
int workspaceId = Constants.WORKSPACE_ID;
int sasArtifactId = Constants.SAS_ARTIFACT_ID;
int indexOfFirstError = 0;
int maxNumberOfErrorsToReturn = 1000;
using (IJobManager sasManager = ServiceProxyHelper.CreateProxy<IJobManager>())
{
List<StructuredAnalyticsSetError> results = sasManager.GetErrorsAsync(workspaceId, sasArtifactId, indexOfFirstError, maxNumberOfErrorsToReturn).GetAwaiter().GetResult();
System.Diagnostics.Debug.WriteLine($"Call to GetErrors (Get Set Errors) on {sasArtifactId} on workspace {workspaceId} returned {results.Count} record(s).");
if (results.Any())
{
System.Diagnostics.Debug.WriteLine("Errors:");
foreach (var error in results)
{
System.Diagnostics.Debug.WriteLine(error.Message);
System.Diagnostics.Debug.WriteLine("-----");
}
}
}
}
The GetDocumentErrorsAsync() method retrieves errors that are associated with the processing of a specific document. For example, this type of error occurs when a document is too large to be extracted or ingested in the Analytics engine, or when Analytics engine fails to process a document due to corruption. This method returns a list of DocumentError objects.
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
public void GetDocumentErrorsSample()
{
int workspaceId = Constants.WORKSPACE_ID;
int sasArtifactId = Constants.SAS_ARTIFACT_ID;
int indexOfFirstError = 0;
int maxNumberOfErrorsToReturn = 1000;
using (IJobManager sasManager = ServiceProxyHelper.CreateProxy<IJobManager>())
{
List<DocumentError> results = sasManager.GetDocumentErrorsAsync(workspaceId, sasArtifactId, indexOfFirstError, maxNumberOfErrorsToReturn).GetAwaiter().GetResult();
System.Diagnostics.Debug.WriteLine($"Call to GetDocumentErrors on {sasArtifactId} on workspace {workspaceId} returned {results.Count} record(s).");
if (results.Any())
{
System.Diagnostics.Debug.WriteLine("Errors:");
foreach (var error in results)
{
System.Diagnostics.Debug.WriteLine(error.Message);
System.Diagnostics.Debug.WriteLine("-----");
}
}
}
}
As of Relativity 9.5.196.102, structured analytics stopped writing results for email threading and textual near duplicate identification to Document fields. Instead, it writes results to fields on the Structured Analytics Results object. However, you can copy these results to the legacy document result fields by calling the RunCopyToLegacyAsync() method. It copies the results from the newly created fields to the legacy document fields from pre 9.5.196 versions of Relativity. For more information, see
To copy analysis results to legacy document fields, call the RunCopyToLegacyAsync() method by passing the Artifact ID for the structured analytics set and the workspace that contains it. You can also optionally pass ProgressReport or CancellationToken objects to this method.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
public void CopyToLegacySample()
{
int workspaceId = Constants.WORKSPACE_ID;
int sasArtifactId = Constants.SAS_ARTIFACT_ID;
using (IJobManager sasManager = ServiceProxyHelper.CreateProxy<IJobManager>())
{
OperationResult results = sasManager.RunCopyToLegacyAsync(workspaceId, sasArtifactId).GetAwaiter().GetResult();
if (results.IsSuccess)
{
System.Diagnostics.Debug.WriteLine($"Call to run CopyToLegacy on SAS {sasArtifactId} on workspace {workspaceId} succeeded");
}
else
{
throw new Exception($"Call to run CopyToLegacy on SAS {sasArtifactId} on workspace {workspaceId} failed. Error message: {results.Message}");
}
}
}
To cancel a copy operation, call the CancelCopyToLegacyAsync() method by passing the Artifact ID for the structured analytics set and the workspace that contains it. You can also optionally pass ProgressReport or CancellationToken objects to this method.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
public void CancelCopyToLegacySample()
{
int workspaceId = Constants.WORKSPACE_ID;
int sasArtifactId = Constants.SAS_ARTIFACT_ID;
using (IJobManager sasManager = ServiceProxyHelper.CreateProxy<IJobManager>())
{
OperationResult results = sasManager.CancelCopyToLegacyAsync(workspaceId, sasArtifactId).GetAwaiter().GetResult();
if (results.IsSuccess)
{
System.Diagnostics.Debug.WriteLine($"Call to cancel CopyToLegacy on SAS {sasArtifactId} on workspace {workspaceId} succeeded");
}
else
{
throw new Exception($"Call to cancel CopyToLegacy on SAS {sasArtifactId} on workspace {workspaceId} failed. Error message: {results.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 |