Audit (REST)

The Audit services available through REST include multiple endpoints that you can use to programmatically revert, retrieve, and search Relativity audit records stored in Elasticsearch. These services support interactions with both instance-level and workspace-level audit records. The following services provide endpoints for this functionality:

  • Audit Metrics service - includes an endpoint for retrieving information about the number and size of the audits in a specific workspace.
  • Audit Revert service - includes endpoints for reverting document update actions. It provides endpoints for reverting a single action or list of actions, and for verifying whether the revert operation can be performed on an action.
  • Audit Pivot service - includes endpoints for running pivot queries on audit data. It supports querying with group by and pivot on operations for object type, action, username, and timestamp fields.
  • Reviewer Statistics service - includes endpoints for retrieving information about reviewer actions, such as the number of actions performed by a reviewer on a document, the usage time per review, a summary report of reviewer actions, and others.
  • Audit Query service - includes an endpoint for querying on a specific audit record.
  • Audit Object Manager UI service - includes endpoints for querying on audit details to display in the Relativity UI, including filtering on the returned data.

Note: These APIs don't support working with audit records stored in an SQL Server database.

Sample use cases for the Audit services include building custom applications to perform the following tasks:

  • Transfer data to other applications and tools for analysis and reporting, such as a third-party software applications or web-based visualization tools.
  • Implement an audit record query as part of a larger solution that captures query results and then manipulates the results using a visualization solution.
  • Programmatically generate a reviewer statistics report.
  • Retrieve or aggregate audit data, or execute pivot queries on the data.

You can access the Audit API services through .NET interfaces. These interfaces support the same functionality as available through REST. For more information, see Audit (.NET).

This page contains the following information:

Prerequisites for using the Audit services

To begin developing with the Audit services, complete the following prerequisites:

  • Audit API SDK - Download the NuGet package called Relativity.Audit.Services.SDK.<version>. You can easily add this NuGet package to your project through Visual Studio. For more information, see Quickstart: Install and use a package in Visual Studio on the Microsoft website. See the following compatibility matrix:
    Relativity versionNuGet version
    RelativityOne 10.2.170.2 and aboveRelativity.Audit.Services.SDK 15.2.3
  • Audit DLL - After you install the NuGet package, locate the DLL in the following directory:
    <PathToYourSolution>\packages\Relativity.Audit.Services.SDK.<version>\lib\net<version>Relativity.Audit.Services.Interface.dll

    Note: You must install the Relativity Audit application in at least one workspace to use the audit services.

Guidelines for Audit services

Review the following guidelines for working with the Audit services.

Operations supported by the Audit services

The following table list operations that you can perform using the Audit services.

Service name Endpoints available for these operations
Audit Metrics Retrieve the total number and size of audits
Audit Revert Validate a revert operation for an audit action
Revert an audit
Mass revert a list of audits
Audit Pivot Query with Pivot on audit data
Reviewer Statistics Retrieve action counts for updated documents
Retrieve the usage time per reviewer
Retrieve size of the extracted text for reviewed documents
Retrieve an aggregation of user actions by hour
Retrieve choices reviewed by users
Retrieve a summary report of reviewer statistics
Audit Query Query for an audit record
Audit Object Manager UI Query on audit fields
Query for a specific audit object
Query with additional query options
Query on audit fields and return a smaller payload

Admin-level context

To work with audits at the admin-level context, set the {{workspaceID}} variable in the URL for an endpoint to -1. For example, the {{workspaceID}} variable in following URL is set to -1, so this endpoints retrieves number and size of the audits for a Relativity instance. See Retrieve the total number and size of audits.

<host>/Relativity.REST/api/relativity.audit.metrics/workspaces/-1/audit-metrics/

Query conditions

You can specify conditions for an audit query in the condition or rowCondition fields in a JSON request. Setting these fields is equivalent to using conditions and list filtering in the Relativity UI. For information about rendering audit details in the Relativity UI, see Audit on the RelativityOne Documentation site.

Audit Metrics service

The Audit Metrics service supports the retrieval of information about the number and size of the audits in a specific workspace.

Retrieve the total number and size of audits

You can retrieve the total count of all audits in a workspace, and the total size of the audits in bytes. Send a POST request to the following URL:

<host>/Relativity.REST/api/relativity.audit.metrics/workspaces/{{workspaceID}}/audit-metrics/

Set the {{workspaceID}} variable to the Artifact ID of a workspace.

The body of the request is empty.

The response contains the following fields:

  • Count - the number of audits existing in the specified workspace.
  • SizeInBytes - the total size of the all the audits in bytes.
{
  "Count": 1579490,
  "SizeInBytes": 813470096
}

Audit Revert service

The Audit Revert service supports reverting document update actions. It provides endpoints for reverting a single action or list of actions, and for verifying whether the revert operation can be performed on an action.

For example, you can use an endpoint on this service as a programmatic shortcut for reverting incorrect coding decisions.

Validate a revert operation for an audit action

To validate that an audit action can be reverted, send a POST request to the following URL:

<host>/Relativity.REST/api/relativity.audit.revert/workspaces/{{workspaceID}}/audits/revert/validate/

Set the {{workspaceID}} variable to the Artifact ID of a workspace.

Revert an audit

To revert an audit action, send a POST request to the following URL:

<host>/Relativity.REST/api/relativity.audit.revert/workspaces/{{workspaceID}}/audits/revert/

Set the {{workspaceID}} variable to the Artifact ID of a workspace.

Note: Before reverting an action, consider calling the ValidateRevertAuditAsync() method to verify that the revert operation can succeed.

Mass revert a list of audits

You can control the maximum number of Audits that can be reverted during a mass operation by updating the RevertMaxAuditCount instance setting. For more information, see Instance settings descriptions on the Relativity Documentation site.

Note: This endpoint validates that each action can be successfully reverted before performing this operation.

To revert a list of audit actions, send a POST request to the following URL:

<host>/Relativity.REST/api/relativity.audit.revert/workspaces/{{workspaceID}}/audits/massrevert/

Set the {{workspaceID}} variable to the Artifact ID of a workspace.

Audit Pivot service

The Audit Pivot service supports running pivot queries on audit data. You can query with the group by and pivot on operations for object type, action, username, and timestamp fields.

After the call returns the pivot results, you can render them as graphs and charts with third-party visualization tools. Pivot queries on audit records use the same query pattern as Relativity Pivot. For more information, see Pivot Manager (REST).

Query with Pivot on audit data

To query on audit pivot data, send a POST request to the following URL:

<host>/Relativity.REST/api/relativity.audit.pivot/workspaces/{{workspaceID}}/pivot/

Set the {{workspaceID}} variable to the Artifact ID of a workspace, or use -1 to indicate the admin-level context.

Reviewer Statistics service

The Reviewer Statistics service provides endpoints for returning information about reviewer actions, such as the number of action performed by a reviewer on a document, the usage time per review, a summary report of reviewer actions, and others.

See the following subsections for more information:

Retrieve action counts for updated documents

You can retrieve the total action counts for all the updated documents in a workspace for a specified time frame. Additionally, you can list specific actions that you want counted per document. Send a POST request to the following URL:

<host>/Relativity.REST/api/relativity.audit.reviewer-statistics/workspaces/{{workspaceID}}/document-action-counts/

Set the {{workspaceID}} variable to the Artifact ID of a workspace.

Retrieve the usage time per reviewer

To compute the total usage time in seconds per reviewer, send a POST request to the following URL:

<host>/Relativity.REST/api/relativity.audit.reviewer-statistics/workspaces/{{workspaceID}}/usage-time/

Set the {{workspaceID}} variable to the Artifact ID of a workspace.

Retrieve size of the extracted text for reviewed documents

To retrieve the size of the extracted text for all documents reviewed per reviewer, send a POST request to the following URL:

<host>/Relativity.REST/api/relativity.audit.reviewer-statistics/workspaces/{{workspaceID}}/total-reviewed-text-size/

Set the {{workspaceID}} variable to the Artifact ID of a workspace.

Retrieve an aggregation of user actions by hour

You can aggregate the total distinct document actions performed by each reviewer, grouped by the hour of the day in which the action was performed. Send a POST request to the following URL:

<host>/Relativity.REST/api/relativity.audit.reviewer-statistics/workspaces/{{workspaceID}}/distinct-document-actions-per-hour-of-day/

Set the {{workspaceID}} variable to the Artifact ID of a workspace.

Retrieve choices reviewed by users

You can retrieve information about the choices reviewed by users in a specific workspace. This endpoint supports retrieving statistics for single choice fields, multiple choice fields, and Yes/No fields. Send a POST request to the following URL:

<host>/Relativity.REST/api/relativity.audit.reviewer-statistics/workspaces/{{workspaceID}}/reviewer-choices/

Set the {{workspaceID}} variable to the Artifact ID of a workspace.

Retrieve a summary report of reviewer statistics

You can programmatically generate a report similar to the reviewer statistics report available through the Relativity UI. For more information, see Reviewer statistics on the RelativityOne Documentation site.

You must specify the time zone of the reviewers, and indicate whether to include system admin statistics in the data.

To generate a summary report, send a POST request to the following URL:

<host>/Relativity.REST/api/relativity.audit.reviewer-statistics/workspaces/{{workspaceID}}/summary-report/

Set the {{workspaceID}} variable to the Artifact ID of a workspace.

Audit Query service

The Audit Query service supports querying for a specific audit record.

Query for an audit record

To read a single audit record, send a POST request to the following URL:

<host>/Relativity.REST/api/relativity.audit.query/workspaces/{{workspaceID}}/audit/

Set the {{workspaceID}} variable to the Artifact ID of a workspace, or use -1 to indicate the admin-level context.

Audit Object Manager UI service

The Audit Object Manager UI service supports querying on audit details for display in the Relativity UI. It provides two endpoints for querying:

  • query - This endpoint returns detailed information about the field-value pairs returned by the query on the audit, including complete field details. For samples, see Query endpoint.
    <host>/Relativity.REST/api/relativity.audit.query/workspaces/<workspaceId>/audit/UI/query
  • queryslim - This endpoint returns a smaller payload to save bandwidth. It returns only the values of the fields specified in the request without the detailed field information. For samples, see Query on audit fields and return a smaller payload.
    <host>/Relativity.REST/api/relativity.audit.query/workspaces/<workspaceId>/audit/UI/queryslim

Review the following guidelines for Audit Object Manager UI service:

  • Sorting is only supported for Timestamp and ExecutionTime fields.
  • Use condition and rowCondition properties on the request object for filtering. For more information, see Query conditions.
  • Review the following information about paging:
    • Query tokens aren't supported for audit record result set paging.
    • Check the value of the TotalCount field on the initial response. If it is greater than the specified Length field in the request, adjust the value of the Start field on the subsequent query requests to page through results.

      Note: In Relativity instances with a very large number of audit records (1,000,000 or more), paging towards the end of the result set can cause a Deep Paging Exception.

  • The Audit record query uses the Relativity Object Manager query pattern. For more information, see Legacy Object Query Manager (REST).
  • Use the endpoint with the auditQueryOptions field if you want to perform additional analysis on the audit data. This endpoint returns the data as an escaped JSON string instead of HTML. For more information, see Query with additional query options.

Query endpoint

To use the query endpoint, send a POST request to the following URL:

<host>/Relativity.REST/api/relativity.audit.query/workspaces/<workspaceId>/audit/UI/query

Set the {{workspaceID}} variable to the Artifact ID of a workspace, or use -1 to indicate the admin-level context.

Query on audit fields

You can query for specific fields in an audit as illustrated in the following example.

Query for a specific audit object

You can query on a specific audit object as illustrated in the following example.

Query with additional query options

You can set additional query options so that the Details field in the Relativity UI contains an escaped JSON string instead of HTML.

Query on audit fields and return a smaller payload

To use the queryslim endpoint, send a POST request to the following URL:

<host>/Relativity.REST/api/relativity.audit.query/workspaces/<workspaceId>/audit/UI/queryslim

Set the {{workspaceID}} variable to the Artifact ID of a workspace, or use -1 to indicate the admin-level context.

Note: The AuditQueryOptions field isn't available for the queryslim endpoint. For more information, see Query with additional query options.

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