Structured Analytics Manager service in REST

The Structured Analytics API provides an HTTP service, which you can use to automate operations on structured analytics sets through Representational State Transfer (REST). The REST endpoints expose functionality similar to that available through the .NET interface for the Structured Analytics API. You can use these endpoints on the Structured Analytics Manager 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.

The Structured Analytics API supports the use of progress indicators and cancellation tokens, when you use it through .NET. The service doesn't support these features through REST. For more information, see Get started with the Structured Analytics API.

Note: You must install the Analytics application in your Relativity environment to automate workflows with the Structured Analytics Manager service. For more information, see Upgrading or installing your Analytics server on the Relativity Documentation site.

This page includes the following information:

See this related page:

Guidelines for the Structured Analytics Manager service

Use the following guidelines when working with the Structured Analytics Manager service:

Client code sample

To use the Structured Analytics Manager service, send an HTTP request that makes a POST method call. See the following base URL for this service:

<host>/Relativity.REST/api/Relativity.StructuredAnalytics.Services.Interfaces.StructuredAnalytics.IStructuredAnalyticsModule/Structured%20Analytics%20Manager/

You can use the following .NET code as a sample REST client for performing any of the operations available in the Structured Analytics Manager service. This code sample illustrates how to perform the following tasks:

public bool ExecuteRunAsync(int workspaceId, int sasArtifactId, bool analyzeAllDocs, bool repopulateAllDocuments)
{
    using (var httpClient = new System.Net.Http.HttpClient())
    {
 
        httpClient.BaseAddress = new Uri("http://localhost/Relativity.REST/API/");
        httpClient.DefaultRequestHeaders.Add("Accept", "application/json");
        httpClient.DefaultRequestHeaders.Add("X-CSFRF-Header", string.Empty);
        httpClient.DefaultRequestHeaders.Add("Authorization", "Basic bXkudXNlckBrY3VyYS5jb206Q250VGNoVGhzMTIzNCE=");
 
        //Initialize the parameters for the workspace and structured analytics set.
        var parameters = new
        {
            workspaceId = workspaceId,
            sasArtifactId = sasArtifactId,
            settings = new
                {
                    AnalyzeAll = analyzeAllDocs,
                    PopulateAll = repopulateAllDocuments
                }
        };
 
        System.Net.Http.StringContent parametersJson = new System.Net.Http.StringContent(Newtonsoft.Json.JsonConvert.SerializeObject(parameters), System.Text.Encoding.UTF8, "application/json");
 
        //Define the REST endpoint called RunAsync on the Structured Analytics Manager service.
        String sasManagerRunUrl = "Relativity.StructuredAnalytics.Services.Interfaces.StructuredAnalytics.IStructuredAnalyticsModule/Structured Analytics Manager/RunAsync";
 
        //Make the HTTP request against the RunAsync endpoint of the Structured Analytics Manager service.
        System.Net.Http.HttpResponseMessage response = httpClient.PostAsync(sasManagerRunUrl, bool).Result;
 
        bool success = response.StatusCode == System.Net.HttpStatusCode.OK;
        String result = response.Content.ReadAsStringAsync().Result;
 
        if (success)
        {
            Newtonsoft.Json.Linq.JObject results = Newtonsoft.Json.Linq.JObject.Parse(result);

            if(results.Value&lt;bool&gt;("IsSuccess") == true)
            {
                return true;
            }
            else
            {
                throw new Exception($"Call to run Analysis on SAS {sasArtifactId} on workspace {workspaceId} failed.  Error message: {results.Value&lt;string&gt;("Message")}");
            }
        } else {
            return false;
        }
    }
}

Generate result fields before running an analysis

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 request to this URL for the Structured Analytics Manager service:

<host>/relativity.rest/api/Relativity.StructuredAnalytics.Services.Interfaces.StructuredAnalytics.IStructuredAnalyticsModule/Structured Analytics Manager/RunAnalysisPreparationAsync

The request must contain the following fields:

{
   "workspaceId":1234567,
   "sasArtifactId":7654321
}

The response contain the following fields:

{
   "IsSuccess":true,
   "Message":"Analysis Preparation has been successfully started for Structured Analytics Set 7654321 in Workspace 1234567"
}

Retrieve valid operations for a structured analytics set

Use the GetValidTasksAsync endpoint to retrieve an array of valid operations for a structured analytics set, such as retrying errors, running an analysis, and others. Send a request to this URL for the Structured Analytics Manager service:

<host>/relativity.rest/api/Relativity.StructuredAnalytics.Services.Interfaces.StructuredAnalytics.IStructuredAnalyticsModule/Structured Analytics Manager/GetValidTasksAsync

The request must contain the following fields:

{
   "workspaceId":1234567,
   "sasArtifactId":7654321
}

The response contain the following fields:

{
   "ValidTasks":[
      "RUN_ANALYSIS",
      "COPY_TO_LEGACY",
      "PREPARE_ANALYSIS"
   ],
   "CopyToLegacyQualified":true
}

Run an analysis of a structured analytics set

Use the RunAsync endpoint to analyze documents in a structured analytics set. Send a request to this URL for the Structured Analytics Manager service:

<host>/relativity.rest/api/Relativity.StructuredAnalytics.Services.Interfaces.StructuredAnalytics.IStructuredAnalyticsModule/Structured Analytics Manager/RunAsync

The request must contain the following fields:

{
   "workspaceId":1234567,
   "sasArtifactId":7654321,
   "settings":{
      "AnalyzeAll":true,
      "PopulateAll":true
   }
}

The response contain the following fields:

{
   "IsSuccess":true,
   "Message":"Analysis has been successfully started for Structured Analytics Set 7654321 in Workspace 1234567"
}

Cancel an analysis

The Structured Analytics Manager service provides two endpoints that you can use to cancel an analysis of structured analytics set:

The request must contain the following fields:

{
   "workspaceId":123456,
   "sasArtifactId":134890
}

The response returns the following fields.

{
   "IsSuccess":true,
   "Message":"The cancel analysis request has successfully started for structured analytics set 134890 in workspace 123456."
}

Check the status of an analysis

To retrieve the current status of an analysis for a structured analytics set, use the GetStatusAsync endpoint. Send a request to this URL for the Structured Analytics Manager service:

<host>/Relativity.REST/api/Relativity.StructuredAnalytics.Services.Interfaces.StructuredAnalytics.IStructuredAnalyticsModule/Structured%20Analytics%20Manager/GetStatusAsync

The request must contain the following fields:

{
   "workspaceId":123456,
   "sasArtifactId":134890
}

The response returns the following JSON objects with their related fields:

{
   "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
      }
   }
}

Retry errors in an analysis

You can attempt to resolve errors that occurred during an analysis of a structured analytics set by rerunning the failed items with the RetryErrorsAsync endpoint. Send a request to this URL for the Structured Analytics Manager service:

<host>/Relativity.REST/api/Relativity.StructuredAnalytics.Services.Interfaces.StructuredAnalytics.IStructuredAnalyticsModule/Structured%20Analytics%20Manager/RetryErrorsAsync

The request must contain the following fields:

{
   "workspaceId":123456,
   "sasArtifactId":134890
}

The response returns the following fields:

{
   "IsSuccess":true,
   "Message":"The retry errors request has successfully started for structured analytics set 134890 in workspace 123456."
}

Retrieve analysis errors for a structure analytics set

The GetErrorsAsync endpoint 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. To retrieve set errors, send a request to this URL for the Structured Analytics Manager service:

<host>/Relativity.REST/api/Relativity.StructuredAnalytics.Services.Interfaces.StructuredAnalytics.IStructuredAnalyticsModule/Structured%20Analytics%20Manager/GetErrorsAsync

The request must contain the following fields:

{
   "workspaceId":123456,
   "sasArtifactId":134890,
   "start":0,
   "length":1000
}

The response returns the following fields for each error:

This JSON sample illustrates an array of errors retrieved by the GetErrorsAsync endpoint.

[
   {
      "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"
   }
]

Retrieve document errors for an analysis

The GetDocumentErrorsAsync endpoint 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. To retrieve document errors for a structured analytics set, send a request to this URL for the Structured Analytics Manager service:

<host>/Relativity.REST/api/Relativity.StructuredAnalytics.Services.Interfaces.StructuredAnalytics.IStructuredAnalyticsModule/Structured%20Analytics%20Manager/GetDocumentErrorsAsync

The request must contain the following fields:

{
   "workspaceId":123456,
   "sasArtifactId":134890,
   "start":0,
   "length":1000
}

The response returns the following fields for each document error:

This JSON sample illustrates an array of the document errors retrieved by the GetDocumentErrorsAsync endpoint.

[
   {
      "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"
   }
]

Work with legacy document fields

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 Copy to Legacy Document Fields on the RelativityOne Documentation site.

Copy results to legacy document fields

Use the RunCopyToLegacyAsync endpoint to copy the results of an analysis to existing document fields. Send a request to this URL for the Structured Analytics Manager service:

<host>/relativity.rest/api/Relativity.StructuredAnalytics.Services.Interfaces.StructuredAnalytics.IStructuredAnalyticsModule/Structured Analytics Manager/RunCopyToLegacyAsync

The request must contain the following fields:

{
   "workspaceId":1234567,
   "sasArtifactId":7654321
}

The response contain the following fields:

{
   "IsSuccess":true,
   "Message":"Copy To Legacy Fields has been successfully started for Structured Analytics Set 7654321 in Workspace 1234567"
}

Cancel a job for copying content to legacy fields

Use the CancelCopyToLegacyAsync endpoint to cancel a job for copying the results of an analysis to existing document fields. Send a request to this URL for the Structured Analytics Manager service:

<host>/relativity.rest/api/Relativity.StructuredAnalytics.Services.Interfaces.StructuredAnalytics.IStructuredAnalyticsModule/Structured Analytics Manager/RunCopyToLegacyAsync

The request must contain the following fields:

{
   "workspaceId":1234567,
   "sasArtifactId":7654321
}

The response contain the following fields:

{
   "IsSuccess":true,
   "Message":"Cancel Copy to Legacy Fields has been successfully started for Structured Analytics Set 7654321 in Workspace 1234567"
}

Community Updates

Aero Developer FAQ Evolving the Platform Most recent release notes
Learn more Learn more Learn more

Additional Resources

   
Access Third-Party Tools with GitHub     Create .NET Apps Faster with NuGet
Visit github     visit nuget