Audit APIs

The Audit APIs available through .NET include methods 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 APIs provide methods for this functionality:

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

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

Additionally, you can access the Audit API services through REST. These services support the same functionality as the .NET interfaces. For more information, see Audit services in REST.

This page contains the following information:

Prerequisites for using the Audit APIs

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

Fundamentals for Audit APIs

Click the following drop-down links to learn about the methods and classes used by the Audit APIs.

Guidelines for the Audit APIs

Review the following guidelines for working with the Audit APIs.

Operations supported by the Audit APIs

The following table lists a summary of operations that you can perform using the Audit APIs.

API name Method name Code samples
Audit Metrics GetWorkspaceAuditMetricsAsync() Retrieve the total number and size of audits
Audit Revert ValidateRevertAuditAsync() Validate a revert operation for an audit
RevertAuditAsync() Revert an audit
MassRevertAuditAsync() Mass revert a list of audits
Audit Pivot PivotAsync() Query with Pivot on audit data
Reviewer Statistics GetDocumentActionCountsAsync() Retrieve action counts for updated documents
GetUsageTimesAsync() Retrieve the usage time per reviewer
GetTotalReviewedDocumentSizesAsync() Retrieve extracted text size of reviewed documents
GetDocumentActionsPerHourOfDayAsync() Retrieve an aggregate of user actions by hour
GetReviewerChoicesAsync() Retrieve choices reviewed by users
GetReviewerStatsAsync() Retrieve a summary report of reviewer statistics
Audit Query GetAuditAsync() Query for an audit record
Audit Object Manager UI QueryAsync() Query on audit fields
QuerySlimAsync() Query on audit fields and return a smaller payload

Admin-level context

To work with audits at the admin-level context, set the workspace ID in a method call -1. For example, the workspaceID the following code could be set to -1, so this call would retrieve number and size of the audits for a Relativity instance. See Retrieve the total number and size of audits.

AuditMetricsAggregateResponse workspaceMetrics = await auditMetricsService.GetWorkspaceAuditMetricsAsync(workspaceId);

Query conditions

You can specify conditions for an audit query in the Condition or RowCondition properties of a request object. Setting these properties is equivalent to using conditions and list filtering in the Relativity UI. For information about rendering audit details in the Relativity UI, see Audit in the Relativity One Documentation site.

Audit Metrics API

The Audit Metrics API 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

To retrieve the total count of all audits in a workspace, and the total size of the audits in bytes, call the GetWorkspaceAuditMetricsAsync() method by pass the Artifact ID of a workspace. This method returns an AuditMetricsAggregateResponse object. See the following code sample:

using (var auditMetricsService = proxy.GetClient<IAuditMetricsService>()) {
    AuditMetricsAggregateResponse workspaceMetrics = await auditMetricsService.GetWorkspaceAuditMetricsAsync(workspaceId);
}

Audit Revert API

The Audit Revert API supports reverting document update actions. It provides methods 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 a method on this service as a programmatic shortcut for reverting incorrect coding decisions.

Validate a revert operation for an audit

To confirm that an audit action can be reverted, call the ValidateRevertAuditAsync() method by passing the Artifact ID of a workspace and an RevertAuditRequest object to it. It returns a ValidateRevertAuditResponse object that contains the IsRevertable property, which indicates whether the operation can be completed. See the following code sample:

using (var revertService = proxy.GetClient<IAuditRevertService> ()) {
var request = new RevertAuditRequest
{
    AuditId = "1409184",
    Timestamp = "2019-05-22T15:10:42.877"
};
    ValidateRevertAuditResponse validateResponse = await revertService.ValidateRevertAuditAsync(workspaceId, request);
}

Revert an audit

To revert an audit action, call the RevertAuditAsync() method by passing the Artifact ID of a workspace and an RevertAuditRequest object to it. It returns a RevertAuditResponse object, which contains a Success property indicating the status of the operation.

See the following code sample:

using (var revertService = proxy.GetClient<IAuditRevertService>())
{
    var request = new RevertAuditRequest
    {
        AuditId = "1409184",
        Timestamp = "2019-05-22T15:10:42.877"
    };
    RevertAuditResponse revertResponse = await revertService.RevertAuditAsync(workspaceId, request);
}

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.

The following code sample illustrates how to instantiate a list of RevertAuditRequest objects, and then call the MassRevertAuditAsync() method by passing the Artifact ID of a workspace and the request object. This method returns a MassRevertAuditResponse object.

using (var revertService = proxy.GetClient<IAuditRevertService>())
{
    var request = new MassRevertAuditRequest
    {
        RevertAuditRequests = new List<RevertAuditRequest>
        {
            new RevertAuditRequest
            {
                AuditId = "1409184",
                Timestamp = "2019-05-22T15:10:42.877"
            },
            new RevertAuditRequest
            {
                AuditId = "1409411",
                Timestamp = "2019-05-22T15:35:01.947"
            },
        }
    };
    MassRevertAuditResponse massRevertResponse = await revertService.MassRevertAuditAsync(workspaceId, request);
}

Audit Pivot API

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

Query with Pivot on audit data

The following code sample illustrates how to instantiate a PivotSettings object by setting the pivot and query conditions. Call the PivotAsync() method by passing the Artifact ID of a workspace, and the PivotSettings, CancellationToken, and IProgress objects. This method returns a PivotResultSet. For more information, see Query conditions.

Note: The method signature for the PivotAsync() method includes the CancellationToken and IProgress<ProgressReport> objects. However, they aren't supported but must be passed to the method as required.

using (var pivotService = proxy.GetClient<IAuditPivotService>())
{
    var cancellationToken = new CancellationToken(); // required but not supported
    var progressToken = new Progress<string>(); // required but not supported
    var settings = new PivotSettings
    {
        // Field Artifact ID
        GroupBy = new FieldRef(1039619),
        PivotOn = new FieldRef(1039617),
        ObjectSetQuery = new global::Relativity.Services.Query
        {
            // Filter conditions
            Condition = "((('Audit ID' LIKE ['1413541'])))",
            RowCondition = ""
        },
        ConvertNumberFieldValuesToString = true,
        MaximumNumberOfColumns = 10,
        MaximumNumberOfRows = 10,
        Timeout = 10,
        RawDataOnly = false,
        TimeZone = "America/Chicago"
    };
    Console.WriteLine(JsonConvert.SerializeObject(settings));
    PivotResultSet pivotResponse = await pivotService.PivotAsync(workspaceId, settings, cancellationToken, progressToken);
}

Reviewer Statistics API

The Reviewer Statistics API provides methods 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.

Review the following guidelines for setting properties on the request objects:

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.

The following code sample illustrates how to instantiate DocumentActionCountCriteria object, and then call the GetDocumentActionCountsAsync() method by passing the Artifact ID of a workspace and the request object.

using (var reviewerStats = proxy.GetClient<IReviewerStatisticsService>())
{
    var request = new DocumentActionCountCriteria
    {
        AuditActionIds = new int[] { 1, 2, 3},
        UserIds = new int[] {9, 777},
        StartDate = new DateTimeOffset(DateTime.Now.AddDays(-5)),
        EndDate = new DateTimeOffset(DateTime.Now),
        TimeZone = "America/Chicago"
    };
 
    DocumentActionCountResponse actionCounts = await reviewerStats.GetDocumentActionCountsAsync(workspaceId, request);
}

Retrieve the usage time per reviewer

Use the GetUsageTimesAsync() method to compute the total usage time in seconds per reviewer.

Note: In the request, the Downtime property indicates the number of seconds used to determine whether a null session action should be joined to a non-null session action. If the time difference for the performance of a null session action is larger than this maximum duration, the null session is counted as one minute.

The following code sample illustrates how to instantiate UsageTimeCriteria object, and then call the GetUsageTimesAsync() method by passing the Artifact ID of a workspace and the request object.

using (var reviewerStats = proxy.GetClient<IReviewerStatisticsService>())
{
    var request = new UsageTimeCriteria
    {
        AuditActionIds = new int[] { 1, 2, 3 },
        UserIds = new int[] { 9, 777 },
        StartDate = new DateTimeOffset(DateTime.Now.AddDays(-5)),
        EndDate = new DateTimeOffset(DateTime.Now),
        TimeZone = "America/Chicago",
        DownTimeThresholdSeconds = 900 // seconds
    };

    UsageTimeResponse usageTime = await reviewerStats.GetUsageTimesAsync(workspaceId, request);
}

Retrieve extracted text size of reviewed documents

Use the GetTotalReviewedDocumentSizesAsync() method to retrieve the size of the extracted text for all documents reviewed per reviewer.

The following code sample illustrates how to instantiate ReviewedDocumentSizeCriteria object, and then call the GetTotalReviewedDocumentSizesAsync() method by passing the Artifact ID of a workspace and the request object.

using (var reviewerStats = proxy.GetClient<IReviewerStatisticsService>())
{
    var request = new ReviewedDocumentSizeCriteria
    {
        AuditActionIds = new int[] {1, 2, 3},
        UserIds = new int[] {9, 777},
        StartDate = new DateTimeOffset(DateTime.Now.AddDays(-5)),
        EndDate = new DateTimeOffset(DateTime.Now),
        TimeZone = "America/Chicago",
        ExtractedTextFieldArtifactId = 1003668,
    };
 
    ReviewedDocumentSizeResponse documentSize = await reviewerStats.GetTotalReviewedDocumentSizesAsync(workspaceId, request);
}

Retrieve an aggregate of user actions by hour

Use the GetDocumentActionsPerHourOfDayAsync() method to aggregate the total distinct document actions performed by each reviewer, grouped by the hour of the day in which the action was performed.

The following code sample illustrates how to instantiate DocumentActionPerHourOfDayCriteria object, and then call the GetDocumentActionsPerHourOfDayAsync() method by passing the Artifact ID of a workspace and the request object.

using (var reviewerStats = proxy.GetClient<IReviewerStatisticsService>())
{
    var request = new DocumentActionPerHourOfDayCriteria
    {
        AuditActionIds = new int[] { 1, 2, 3 },
        UserIds = new int[] { 9, 777 },
        StartDate = new DateTimeOffset(DateTime.Now.AddDays(-5)),
        EndDate = new DateTimeOffset(DateTime.Now),
        TimeZone = "America/Chicago",
    };
 
    DocumentActionPerHourOfDayResponse documentActionPerHourOfDayResponse = await reviewerStats.GetDocumentActionsPerHourOfDayAsync(workspaceId, request);
}

Retrieve choices reviewed by users

Use the GetReviewerChoicesAsync() method to retrieve information about choices reviewed by users in a specific workspace. This method supports retrieving statistics for single choice fields, multiple choice fields, and Yes/No fields. Set the FieldIds property to the Artifact IDs of the fields that you want used to compute the choices selected by reviewers.

Note: If you pass an empty array for the UserIdsToExcludeInReport or the UserIdsToIncludeInReport field, the report is computed for all the users in the workspace.

The following code sample illustrates how to instantiate ReviewerChoicesCriteria object, and then call the GetReviewerChoicesAsync() method by passing the Artifact ID of a workspace and the request object.

using (var reviewerStats = proxy.GetClient<IReviewerStatisticsService>())
{
    var request = new ReviewerChoicesCriteria
    {
        FieldIds = new int[] { 1035357 },
        UserIdsToIncludeInReport = new int[]{9},
        UserIdsToExcludeInReport = new int[]{777},
        StartDate = new DateTimeOffset(DateTime.Now.AddDays(-5)),
        EndDate = new DateTimeOffset(DateTime.Now),
        TimeZone = "America/Chicago",
    };
 
    ReviewedFieldChoicesPerUserResponse reviewerChoice = await reviewerStats.GetReviewerChoicesAsync(workspaceId, request);
}

Retrieve a summary report of reviewer statistics

Use the GetReviewerStatsAsync() method to 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.

On the ReviewerStatsDataRequest object, set the NonAdmin to false if you want to include system admin statistics in the data. Additionally, set the AdditionalActions property to one of the following values:

The following code sample illustrates how to instantiate ReviewerStatsDataRequest object, and then call the GetReviewerStatsAsync() method by passing the Artifact ID of a workspace and the request object.

using (var reviewerStats = proxy.GetClient<IReviewerStatisticsService>())
{
    var request = new ReviewerStatsDataRequest
    {
        StartDate = "2019-01-01T00:00:00Z",
        EndDate = "2019-10-05T00:00:00Z",
        TimeZone = -6.0,
        NonAdmin = false,
        AdditionalActions = "Mass Edits"
    };
 
    IEnumerable<ReviewersStats> reviewerMetrics = await reviewerStats.GetReviewerStatsAsync(workspaceId, request);
}

Audit Query API

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

Note: You must set both the Timestamp and Id properties on the request to uniquely identify the audit record.

Query for an audit record

The following code sample illustrates how to instantiate a GetAuditRequest object, and then pass the GetAuditAsync() method the Artifact ID of a workspace and the request object. This method returns an AuditLogItem object. See the following code sample:

using (var auditQueryService = proxy.GetClient<IAuditQueryService>())
{
    var request = new GetAuditRequest
    {
        Id = "484127",
        Timestamp = "2019-04-26T15:56:53.427"
    };
    AuditLogItem queryResults = await auditQueryService.GetAuditAsync(workspaceId, request);
}

Audit Object Manager UI API

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

Review the following guidelines for Audit Object Manager UI API:

Query on audit fields

The overloaded QueryAsync() method takes the following arguments:

Query on audit fields and return a smaller payload

The overloaded QuerySlimAsync() method takes the following arguments:

Note: The method signatures for the overloaded QuerySlimAsync() method include the CancellationToken and IProgress<ProgressReport> objects. However, they aren't supported but must be passed to the methods as required.

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