Structured Analytics Job Manager (.NET)

You can select the following structured analytics operations through the Relativity UI:

• Email threading - groups related email messages and performs other tasks.
• Textual near duplicate identification - identifies the level of similarity between documents.
• Language identification - identifies primary and secondary languages in the documents.
• Repeated content identification - identifies content reused in documents, such as footers.
• Name normalization - identifies aliases within email headers, such as a proper name, email address, and other items. It then assigns these aliases to entities that are imported into Relativity and linked to document fields. This process simplifies the identification of senders and recipients of email messages, because multiple aliases are frequently used for them.

For more information, see Structured analytics on the RelativityOne Documentation site.

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:

• CancelAsync() method - stops an analysis of a structured analytics set. This method returns control to the caller. See Cancel an analysis.
• CancelCopyToLegacyAsync() method - cancels a job for copying the results of an analysis to legacy document fields. This method returns an OperationResult object. See Cancel copy to legacy fields.
• GetDocumentErrorsAsync() method - retrieves information about an error that occurred during the analysis of a specific document, such as the Artifact ID of the document. It returns a DocumentError object. See Retrieve document errors for an analysis.
• GetErrorsAsync() method - retrieves information about an error at the level of the structured analytics set, such as the name of the agent server where the error occurred. It returns a StructuredAnalyticsSetError object. See Retrieve analysis errors for a structured analytics set.
• GetStatusAsync() method - retrieves the status of an analysis on a structured analytics set. This method returns a Status object. See Check the status of an analysis.
• GetValidTasksAsync() method - retrieves valid operations for a structured analytics set, such as retrying errors, running an analysis, and others. This method returns a ValidTaskResult object. See Retrieve valid operations for a structured analytics set.
• RetryErrorsAsync() method - attempts to resolve transient errors that occurred during an analysis by running the operation again. See Retry errors in an analysis .
• RunAsync() method - executes an analysis of a structured analytics set. This method returns an OperationResult object. See Run an analysis of a structured analytics set.
• RunCopyToLegacyAsync() method - copies the results of an analysis to legacy document fields. This method returns an OperationResult object. See Copy to legacy document fields.
• RunAnalysisPreparationAsync() method - generates fields for storing results before you run an analysis on a new structured analytics set. This method returns an OperationResult object. See Generate result fields before running an analysis.

• AnalysisSettings class - represents a configuration used for running an analysis. The RunAsync() method takes an instance of this class as an argument.
• DocumentError class - represents an error at the level of a document. Its properties provide the Artifact ID of the document with errors, a detailed error message, and status information based on the DocumentErrorStatus enumeration. The GetDocumentErrorsAsync() method returns this object type.
• DocumentErrorStatus enumeration - indicates whether a document with errors remains in structured analytics set during an analysis, and whether it is included in the result set. For example, these constants include RemovedFromSet, IncludedInSet, and DataWarning. The DocumentError class has a Status property that references a DocumentErrorStatus constant.
• OperationResult class - indicates whether the analysis was successful and provides a detailed message about the operation. The CancelAsync(), CancelCopyToLegacyAsync(), RetryErrorsAsync(), RunAnalysisPreparationAsync(), RunAsync(), and RunCopyToLegacyAsync() methods return an OperationResult object.
• ValidTaskResult class - represents the operations that are valid to perform on a structured analytics set, such as retrying errors, running an analysis, and others. The GetValidTasksAsync() method returns an object of this type.
• StructuredAnalyticsTask enumeration - contains members used to indicate that an operation is valid for a structured analytics set, such as CANCEL_ANALYSIS, RETRY_ERRORS, RUN_ANALYSIS and others. The ValidTaskResult class has a ValidTasks property, which is a list of StructuredAnalyticsTask enums.
• StructuredAnalyticsSetError class - represents an error at the level of the structured analytics set. Its properties provide a detailed error message, the name of the agent server where the error occurred, and the source of the error. The GetErrorsAsync() returns a StructuredAnalyticsSetError object.

• EmailThreadingStatistics class - provides the number of email messages analyzed, and the number of inclusive messages. The JobResults class has the EmailThreadingStatistics property that references this object type.
• JobResults class - provides information about the number of documents analyzed, and statistics for email threading and textual near duplicates. The JobResults class has properties that reference EmailThreadingStatistics, NameNormalizationStatistics, and TextualNearDuplicatesStatistics and objects.
• JobState class - indicates whether the analysis job is completed, canceled, or running, the phase of the job, the time elapsed, and other information. The Status class has a property that references a JobState object.
• NameNormalizationStatistics class - provides information about the number of aliases in a group of email messages. It contains the AliasesIdentified property that represents a count of all aliases in the group, and the NewAliasesImported property that represents the number of new aliases added to Relativity. An alias may be a proper name, email address, or other item.
• Status class - provides information about the state of the job, the operations assigned to it, the operations currently executing on it, and other information. The GetStatusAsync() method returns a Status object.
• TextualNearDuplicatesStatistics class - provides the average similarity of textual near duplicates as a percentage, and the total number of textual near duplicate groups. The JobResults class has the TextualNearDuplicatesStatistics property that is set to this class.
• OperationState class - provides information about an operation, including the time associated with the last activity, the operation such as email threading, and the phase such as exporting or setup.
• JobOperation enumeration - lists specific analysis types that can be performed on a structured analytics set. For example, these types include EmailThreading, TextualNearDuplicateId, and others. The Status class has a SelectedOperations property that is set to a JobOperation constant.
• JobPhase enumeration - lists specific phases in an analysis. For example, phases include Setup, RunningOperations, and others. The JobState class has a Phase property that is set to a JobPhase constant.

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}");
        }
    }
}

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.");
        }
    }
}

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}");
        }
    }
}

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}");
        }
    }
}

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}");
        }
    }
}

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}");
        }
    }
}

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("-----");
            }
        }
    }
}

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("-----");
            }
        }
    }
}

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}");
        }
    }
}

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}");
        }
    }
}