

Last date modified: April 15 2025
The Structured Analytics Job Manager service is an HTTP service, which you can use to automate operations on structured analytics sets through Representational State Transfer (REST). You can use the endpoints on this service to run an analysis of a structured analytics set, check the status of the analysis, retrieve document and other errors, and perform additional tasks. For general information about REST, see the REST API.
You can implement custom workflows for programmatically running structured analytic sets using the REST endpoints. For example, you can automate an analysis of a structured analytics set after performing only minor setup tasks in the Relativity UI. You could also implement a custom page that uses these endpoints to display the status of an analysis or errors that may have occurred.
You can find the REST Service reference documentation and download the OAS specification file in this topic. You can also use the Structured Analytics Job Manager service API through .NET. The API supports the use of progress indicators and cancellation tokens in .NET. For more information, see Structured Analytics Job Manager (.NET).
Note: You must install the Analytics application in your Relativity environment to automate workflows with the Structured Analytics Job Manager service. For more information, see
Review the following guidelines for working with this service.
The URLs for REST endpoints contain path parameters that you need to set before making a call:
For example, you can use the following URL to retrieve valid operations for a structured analytics set:
1
<host>/relativity.rest/api/relativity-structured-analytics/{versionNumber}/workspaces/{workspaceId}/sets/{sasArtifactId}/jobs/valid-tasks?
Set the path parameters as follows:
When implementing your custom code, follow these guidelines:
To get a list of valid operations, make a call with the GetValidTasksAsync() endpoint. 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.
You can use the Postman sample file to become familiar with making calls to endpoints on the Error Manager service. To download the sample file, click Structured Analytics Postman file.
To get started with Postman, complete these steps:
To use the Structured Analytics Job Manager service, send an HTTP request that makes a POST method call. See the following base URL for this service:
1
<host>/relativity.rest/api/relativity-structured-analytics/v1/workspaces/{workspaceId}/sets/{sasArtifactId}/jobs
You can use the following .NET code as a sample REST client for performing any of the operations available in the Structured Analytics Job Manager service. This code sample illustrates how to perform the following tasks:
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
47
public bool ExecuteRunAsync(int workspaceId, int sasArtifactId, bool analyzeAllDocs, bool repopulateAllDocuments)
{
string url = "http://localhost/relativity.rest/api/relativity-structured-analytics/ + "v1/workspaces/" + workspaceId + "/sets/" + sasArtifactId + "/jobs";
var HttpWebRequest request = HttpWebRequest.CreateHttp(url)
request.Method = "POST";
request.ContentType = "application/json";
request.KeepAlive = false;
request.Headers.Add("Authorization", GetBase64AuthHeader());
request.Headers.Add("X-CSRF-Header", "-");
request.Headers.Add("X-Kepler-Version", "2.0");
//Initialize the parameters for the structured analytics set.
string requestPayload= Newtonsoft.Json.JsonConvert.SerializeObject(new
{
settings = new
{
AnalyzeAll = analyzeAllDocs,
PopulateAll = repopulateAllDocuments
}
});
using (var requestContent = new System.IO.StreamWriter(request.GetRequestStream()))
{
//write request payload to stream
requestContent.Write(requestPayload);
requestContent.Flush();
}
var response = request.GetResponse();
string responsePayload = null;
using (var streamReader = new System.IO.StreamReader(response.GetResponseStream()))
{
responsePayload = streamReader.ReadToEnd();
}
JObject results = JObject.Parse(responsePayload);
if (results.Value<bool>("IsSuccess") == true)
{
System.Diagnostics.Debug.WriteLine($"Call to Run on SAS {sasArtifactId} on workspace {workspaceId} succeeded");
}
else
{
throw new Exception($"Call to Run on SAS {sasArtifactId} on workspace {workspaceId} failed. Error message: {results.Value<string>("Message")}");
}
}
You can optionally call the RunAnalysisPreparationAsync endpoint 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:
Send a POST request with a URL in the following format:
1
<host>/relativity.rest/api/relativity-structured-analytics/{versionNumber}/workspaces/{workspaceId}/sets/{sasArtifactId}/jobs/prep
The response contains the following fields:
1
2
3
4
{
"IsSuccess":true,
"Message":"Analysis Preparation has been successfully started for Structured Analytics Set 7654321 in Workspace 1234567"
}
Use the valid-tasks endpoint to retrieve an array of valid operations for a structured analytics set, such as retrying errors, running an analysis, and others.
Send a GET request with a URL in the following format:
1
<host>/relativity.rest/api/relativity-structured-analytics/{versionNumber}/workspaces/{workspaceId}/sets/{sasArtifactId}/jobs/valid-tasks?
The response contains the following fields:
1
2
3
4
5
6
7
8
{
"ValidTasks":[
"RUN_ANALYSIS",
"COPY_TO_LEGACY",
"PREPARE_ANALYSIS"
],
"CopyToLegacyQualified":true
}
Use the jobs endpoint to run analysis on documents in a structured analytics set.
Send a POST request with a URL in the following format:
1
<host>/relativity.rest/api/relativity-structured-analytics/{versionNumber}/workspaces/{workspaceId}/sets/{sasArtifactId}/jobs
The request body must contain the following fields:
1
2
3
4
5
6
{
"settings":{
"AnalyzeAll":true,
"PopulateAll":true
}
}
The response contains the following fields:
1
2
3
4
{
"IsSuccess":true,
"Message":"Analysis has been successfully started for structured analytics set 7654321 in Workspace 1234567"
}
You can make a request to cancel the analysis of a structured analytics set that is currently running. After this request, control immediately returns to the caller.
To cancel an analysis of a structured analytics set, send a DELETE request with a URL in the following format:
1
<host>/relativity.rest/api/relativity-structured-analytics/{versionNumber}/workspaces/{workspaceId}/sets/{sasArtifactId}/jobs
The response contains the following fields.
1
2
3
4
{
"IsSuccess":true,
"Message":"The cancel analysis request has successfully started for structured analytics set 134890 in workspace 123456."
}
To retrieve the status of an analysis for a structured analytics set, send a GET request with a URL in the following format:
1
<host>/relativity.rest/api/relativity-structured-analytics/{versionNumber}/workspaces/{workspaceId}/sets/{sasArtifactId}/jobs
The response contains the following JSON objects with their related fields:
The NameNormalizationStatistics field isn't listed in the following sample.
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
{
"JobName":"Sample Analytics",
"JobState":{
"IsRunning":false,
"IsCompleted":true,
"Status":"Completed analysis with errors",
"Phase":"Completed",
"PhaseProgressPercentage":0,
"JobTimeElapsed":0,
"OperationTimeElapsed":0
},
"SelectedOperations":[
"EmailThreading",
"TextualNearDuplicateId",
"LanguageId",
"RepeatedContentId"
],
"ValidOperations":[
"RUN_FULL_ANALYSIS",
"RUN_INCREMENTAL_ANALYSIS",
"GET_DOCUMENT_ERRORS"
],
"JobResults":{
"DocumentsAnalyzed":4798,
"EmailThreadingStatistics":{
"EmailsAnalyzed":4698,
"InclusiveEmails":4645
},
"TextualNearDuplicatesStatistics":{
"AverageSimilarityPercentage":98,
"TextualNearDuplicateGroupsCount":12
}
}
}
You can attempt to resolve errors that occurred during an analysis of a structured analytics set by rerunning the failed items with the retry endpoint.
Send a POST request with a URL in the following format:
1
<host>/relativity.rest/api/relativity-structured-analytics/{versionNumber}/workspaces/{workspaceId}/sets/{sasArtifactId}/jobs/retry
The response contains the following fields:
1
2
3
4
{
"IsSuccess":true,
"Message":"The retry errors request has successfully started for structured analytics set 134890 in workspace 123456."
}
You can retrieve errors for a structured analytics set. 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.
To retrieve set errors, send a POST request with a URL in the following format:
1
<host>/relativity.rest/api/relativity-structured-analytics/{versionNumber}/workspaces/{workspaceId}/sets/{sasArtifactId}/jobs/errors?{start}&{length}
The request URL can optionally include the following query parameters:
The response contains the following fields for each error:
This JSON sample illustrates an array of errors retrieved by the endpoint.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
[
{
"Fulltext":"This is the full text of the error message",
"Message":"This is a shortened version of the error message...",
"Server":"SERVER_LOCATION",
"Source":"ERROR_SOURCE"
},
{
"Fulltext":"This is the full text of the error message",
"Message":"This is a shortened version of the error message...",
"Server":"SERVER_LOCATION",
"Source":"ERROR_SOURCE"
}
]
You can retrieve 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.
To retrieve document errors for a structured analytics set, send a GET request with a URL in the following format:
1
<host>/relativity.rest/api/relativity-structured-analytics/{versionNumber}/workspaces/{workspaceId}/sets/{sasArtifactId}/jobs/doc-errors?{start}&{length}
The request URL can optionally include the following query parameters:
The response contains the following fields for each document error:
This JSON sample illustrates an array of the document errors retrieved by the endpoint.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
[
{
"DocumentArtifactId":1383924,
"DocumentIdentifier":"Document_1",
"Message":"An error occurred during processing of email",
"Status":"DataWarning",
"DateErrored":"2017-01-06T11:33:00.357"
},
{
"DocumentArtifactId":1383925,
"DocumentIdentifier":"Document_2",
"Message":"Processing failed for the given document",
"Status":"RemovedFromSet",
"DateErrored":"2017-01-06T11:33:00.357"
},
{
"DocumentArtifactId":1383926,
"DocumentIdentifier":"EmailThreadingTaskProblemDoc5",
"Message":"A network error occurred.",
"Status":"IncludedInSet",
"DateErrored":"2017-01-06T11:33:00.357"
}
]
As of Relativity 9.5.196, 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 endpoint. 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
Use the RunCopyToLegacyAsync endpoint to copy the results of an analysis to existing document fields.
Send a POST request with a URL in the following format:
1
<host>/relativity.rest/api/relativity-structured-analytics/{versionNumber}/workspaces/{workspaceId}/sets/{sasArtifactId}/jobs/copy-to-legacy
The response contains the following fields:
1
2
3
4
{
"IsSuccess":true,
"Message":"Copy To Legacy Fields has been successfully started for structured analytics set 7654321 in Workspace 1234567"
}
To cancel a job for copying the results of an analysis to existing document fields, send a DELETE request with a URL in the following format:
1
<host>/relativity.rest/api/relativity-structured-analytics/{versionNumber}/workspaces/{workspaceId}/sets/{sasArtifactId}/jobs/copy-to-legacy
The response contains the following fields:
1
2
3
4
{
"IsSuccess":true,
"Message":"Cancel Copy to Legacy Fields has been successfully started for structured analytics set 7654321 in Workspace 1234567"
}
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 |