Structured Analytics Job Manager (.NET)

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).

The Relativity.StructuredAnalytics.SDK contains this API. For compatibility and package installation instructions, see Download the SDKs and NuGet packages.

Fundamentals for the Structured Analytics Job Manager API

Review the following information to learn more about structured analytics.

Structured analytics overview

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.

API namespaces

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.

Note: 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.

Guidelines for the Structured Analytics Job Manager API

Review the following guidelines for working with this API.

Custom code implementation

When implementing your custom code, follow these guidelines:

  • Execute only valid operations for the state of a structured analytics set - Only certain operations are valid for the current state of your structured analytics set. See the following examples:
    • A call to the CancelAsync() method is only valid when an analysis is currently running.
    • A call to the RetryErrorsAsync() method is only valid when a structured analytics set is in an errored state.

    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.

  • Monitor the analysis progress - After making a successful call to the RunAsync() method, make calls to GetStatusAsync() method to monitor the progress of your analysis.
  • Use structured analytics set RDOs - The Structured Analytics Job Manager API doesn't expose standard CRUD operations for structured analytics set RDOs. Use the Object Manager service to create RDOs. For more information, see Object Manager (.NET) or Object Manager (REST).

Code samples

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 helper classes to create the proxy and select an appropriate authentication type. See Relativity API Helpers.
  • Create the Services API proxy within a using block in your code.
  • Call specific methods on the Structured Analytics Job Manager API within a try-catch block.
  • Use await/async design pattern.
  • Use the logging framework for troubleshooting and debugging purposes. See Log from a Relativity application .

Relativity environment setup

Use these steps to set up your Relativity environment:

  • Obtain access to an instance of Relativity 12.3 used for development purposes.
  • Install the Relativity Analytics application on this Relativity instance. Make sure that your Analytics server is configured properly. For more information, see Upgrading or installing your Analytics server on the Relativity Documentation site.
  • Add the Relativity Analytics application to your workspace. For more information, see Installing applications on the RelativityOne Documentation site.
  • Enable Developer mode in your development instance of Relativity to simplify troubleshooting.
  • Create the structured analytics sets that you want include in the automated analysis. See the following resources:

Generate result fields before running an analysis

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:

  • Create a new structured analytics set.
  • Call the RunAnalysisPreparationAsync() method to generate fields used to store results from an analysis.
  • Use the fields generated by the RunAnalysisPreparationAsync() method to create views and saved searches. You can also use this process to add a structured analytics set to a template workspace.
  • Poll the GetValidTasksAsync() method until StructuredAnalyticsTask.RUN_ANALYSIS is reported as a valid task to run.
  • Call the RunAsync() method to complete the analysis of the structured analytics set, and store results in the fields that you generated.

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.

Retrieve valid operations for a structured analytics set

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.

Run an analysis of a structured analytics set

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.

Cancel an analysis

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.

Check the status of an analysis

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

Retry errors in an analysis

Use the RetryErrorsAsync() method to resolve transient errors that occurred during an analysis.

Retrieve analysis errors for a structured analytics set

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.

Retrieve document errors for an analysis

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.

Work with legacy document fields

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

Copy to legacy document fields

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.

Cancel copy to legacy fields

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.