The Audit API is being deprecated in a future release. When implementing new custom functionality, use the Audit Manager API that exposes HTTP services for REST built on a .NET interface. This interface is also available for use through .NET. For more information, see Audit (.NET).

Legacy Audit API

Audit API can be used to retrieve and search Relativity audit records stored in Data Grid. The API does not work with audit records stored in the SQL Server database. You can interact with both instance- and workspace-level audit records. The API uses RESTful HTTP services to enable you to build cross-platform browser-based applications.

Note: The Audit Relativity application must be installed in at least one workspace for the Audit API to function.

Before programmatically interacting with audit records, familiarize yourself with the Relativity user interface and review the information on the Audit page in the Relativity Documentation Site. The Audit application uses the same API, and you can examine the API calls and JSON requests and responses from the page using tools like Fiddler and Chrome developer console.

Here are some of the things that can be done using the API:

  • Retrieve audit data (for example, get last 100 most recent audits).
  • Aggregate audit data (for example, get top 10 most used action types).
  • Execute pivot.
  • Programmatically generate the reviewer statistics report.

This page contains the following information:

REST HTTP Service

The Audit API RESTful services are designed to help you transfer data to other applications and tools, such as a third-party software application or web-based visualization tool, for deeper analysis and reporting. You can use the service to implement an audit record query as part of a larger solution that captures query results and then manipulates the results using a visualization solution.

When using the Audit Log Manager REST service, every HTTP request header must include the following:

  • Authorization
  • Content-type
  • X-CSRF-Header
Authorization: Basic bXkudXNlckBrY3VyYS5jb206Q250VGNoVGhzMTIzNCE=
Content-Type: application/json
X-CSRF-Header: -

When using basic authentication over HTTPS, you should send authentication credentials with every request to the REST API, since the service doesn't include an explicit login method or track a session token. To include credentials in the HTTP header, you must supply a username and password that are concatenated into a string, using the format username:password. You must also compute the Base64 encoding for this string. You don't need to provide authorization if you are already logged into Relativity in the same browser session. For more information, see REST API authentication.

Query audit records

Audit record query uses the Relativity Object Manager query pattern. For more information, see Object Manager (REST).

The Audit API provides two endpoints for querying:

  • query - use this endpoint to get audits with full field information including filed Artifact IDs, names, etc.
  • queryslim - use this endpoint to return a smaller payload to save bandwidth. It returns only the values of the fields specified in the request without the detailed field information.

Query

Send a POST request to the query endpoint:

/Relativity.Rest/API/Relativity.Objects.Audits/workspaces/<Workspace Artifact ID>/audits/query/

The request must specify a workspace. If you want to return the instance-level audit records, specify -1:

/Relativity.Rest/API/Relativity.Objects.Audits/workspaces/-1/audits/query

The request body includes the following properties:

  • objectType – the Audit object type identified by the Artifact Type ID on the Object Type. The values will be different for each workspace and the instance-level object types. To programmatically return the Artifact Type ID, query the Relativity object types using the Services API.
  • fields – a collection of fields used like a SELECT statement in an SQL query. You must specify the field name.
  • condition – the search criteria used in the query. For more information, see System types supported by the Query() method. This field is optional.
  • rowcondition – the filtering condition criteria for the result set. This field is optional.
  • sorts – a collection of Sort objects. This field indicates whether the results are sorted in ascending or descending order, and identifies the field used to sort the results by name. This field is optional. See the Sort class in the kCura.Relativity.Client namespace.
  • relationalField – name of relational field to expand query results to related objects. This field is optional.
  • searchProviderCondition – use the searchProviderCondition parameter to specify a search index other than the default keyword search index. This field is optional.
  • includeIdWindow – reserved for future use.
  • convertNumberFieldValuesToString – convert response field values to strings. This field is optional.
  • isAdHocQuery – reserved for future use.
  • activeArtifactId – reserved for future use.
  • queryHint – set a QueryHint field to optimize the view. For example, you can use the hashjoin setting with the value of true or false, or you can use the waitfor setting with a value, such as waitfor:5. This field is optional. For more information about general query options, see Query for resources.
  • executingViewId – reserved for future use.
  • start – the index of the first artifact in the result set.
  • length – the number of items to return in the query result, starting with index in the start field.
  • auditQueryOptions – additional query options:
    • ReturnRawDetails - toggles the Details field to contain an escaped JSON string instead of HTML.

The response includes the following properties:

  • TotalCount – the total number of objects in Relativity that meet the criteria of the query. For example, you may request 100 objects, but 115 objects satisfy the query. The ResultCount is 100, while the TotalCount is 115.
  • Objects – a collection of audit objects.
    • Name – the ID of the audit record.
    • FieldValues – an array containing FieldValuePair objects. See Object Manager (.NET).
      • Field – a field associated with a specific value. The Field object includes:
        • ArtifactID – a unique identifier for the field, which is represented as an integer.
        • FieldType – the data type of the field.
        • FieldCategory – indicates the specific functionality assigned to a field, such as stores descriptive text, acts as a relational field, represents grouping for batching, and others.
        • Guids – an array of GUIDs used to identify the field.
        • Name – a user-friendly name for the field.
        • ViewFieldID – a unique identifier used to reference a view field.
      • Value – the field value.
  • IDWindow – reserved for future use.
  • CurrentStartIndex – the index of the first artifact in the result set.
  • ResultCount – the number of objects returned by the current query. Also, see the description of TotalCount in this list.
  • ObjectType – reserved for future use.
  • RankWindow – reserved for future use.

The following is the equivalent of the API call in the Audit user interface:

Results from calling the query endpoint displayed in the Relativity UI

Queryslim

Send a POST request to the queryslim endpoint:

/Relativity.Rest/API/Relativity.Objects.Audits/workspaces/<Workspace Artifact ID>/audits/queryslim

The request must specify a workspace. If you want to return the instance-level audit records, specify -1:

/Relativity.Rest/API/Relativity.Objects.Audits/workspaces/-1/audits/queryslim

The request body is the same as for the query endpoint.

Note: The AuditQueryOptions property is not available for the queryslim endpoint.

The response includes the following properties:

  • TotalCount – the total number of objects in Relativity that meet the criteria of the query. For example, you may request 100 objects, but 115 objects satisfy the query. The ResultCount is 100, while the TotalCount is 115.
  • Objects – a collection of audit objects.
    • Artifact ID – the Artifact ID of the .
    • Values – a collection of values for the fields specified in the request.
  • IDWindow – reserved for future use.
  • CurrentStartIndex – the index of the first artifact in the result set.
  • ResultCount – the number of objects returned by the current query. Also, see the description of TotalCount in this list.
  • ObjectType – reserved for future use.
  • RankWindow – reserved for future use.
  • Fields – the fields corresponding to the values.

Condition

You can specify condition for the audit query as the condition or rowCondition properties. This is equivalent to using conditions and list filtering in the Relativity user interface.

List filtering in the Relativity UI

The condition syntax is the same as in Object Manager API queries.

Note that the syntax also applies to filtering charts described below.

The following are examples of conditions.

Audit record ID

"rowCondition": "(('Audit ID' == 393901))"

Timestamp

(('Timestamp' >= 2017-11-01T00:00:00.00Z AND 'Timestamp' <= 2017-11-23T23:59:00.00Z))

Action

 (('Action' IN CHOICE [1048406, 1048444]))

Note: Audit actions are Relativity choices. You can find the value of Artifact IDs of the choices on the Data Grid Audit Field Mapping tab (Relativity Choice ID Column). You can also query the choices for the Action field programmatically.

Object Type

(('Object Type' == CHOICE 1048471))

Note: Object Type values are Relativity choices. You can find the value of Artifact IDs of the choices on the tab by filtering for Data Grid Audit object type and the Object Type field. You can also query the choices for the Object Type field programmatically.

Execution Time (in milliseconds)

(('Execution Time (ms)' > 1000))

Artifact ID (the ID of the Relativity artifact associated with the audit record)

(('Artifact ID' == 1003663))

Old Value/New Value

(('New Value' LuceneSearch 'oil OR gas'))

Complex condition (date + ObjectType + Action)

(('Timestamp' >= 2017-11-01T00:00:00.00Z AND 'Timestamp' <= 2017-11-23T23:59:00.00Z)) AND (('Object Type' == CHOICE 1048471)) AND (('Action' IN CHOICE [1048406, 1048444]))

Paging

Query tokens are not supported for audit record result set paging. Examine the value of the TotalCount property on the initial response. If it is greater than the specified Length parameter, adjust the value of the Start parameter on the subsequent query requests to page through results.

Note that 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 the Deep Paging Exception.

Read an audit record

To read a single audit record, issue a POST request to this service endpoint:

/Relativity.Rest/API/kCura.AuditUI2.Services.AuditLog.IAuditLogModule/Audit%20Log%20Manager/GetAuditLogItemAsync

The request body includes the following properties:

  • workspaceId – the Artifact ID of the target workspace. To return the instance level audit records, specify -1.
  • request – the request with the ID of the audit record.

Sample request:

{
  "workspaceId": 2551025,
  "request": {
    "Id": 7435
  }
}

The response includes the following properties:

  • ID – the ID of the audit record.
  • TimeStamp – the date and time of the audit action.
  • ArtifactName – the name of the audited artifact, for example, document control number.
  • ActionName – the audit action name, for example, Create or Update.
  • ActionID – the audit action ID.
  • ObjectTypeName – the object type of the audited artifact, for example, Document.
  • ObjectTypeID – the object type ID of the audited artifact.
  • ArtifactID – the Artifact ID of the audited artifact.
  • UserName – the user name associated with the audit record.
  • UserID – the Artifact ID of the user associated with the audit record.
  • Details – the detailed audit action information.
  • OldValues – the values of the fields that have been changed by the action.
  • NewValues – the values of the fields that have been set by the action.
  • Fields – the fields that have been changed by the action.
  • WorkspaceId – the workspace ID associated with the audit record.
  • WorkspaceName – the workspace name associated with the audit record.

The following is a sample response from an audit record for a document designation change (choice value changed from "Non-Responsive" to "Needs Further Review"):

{
  "ID": 7435,
  "TimeStamp": "2018-03-23T20:19:46.607",
  "ArtifactName": "AZIPPER_0008588",
  "ActionName": "Update",
  "ActionID": 3,
  "ObjectTypeName": "Document",
  "ObjectTypeID": 10,
  "ArtifactID": 1039365,
  "UserName": "Smith, Jane",
  "UserID": 1000000130,
  "Details": {
    "auditElement": {
      "field": {
        "@name": "Responsive Designation",
        "@type": "5",
        "setChoice": "1035916",
        "@id": "1035357",
        "@formatstring": ""
      }
    }
  },
  "OldValues": [
    {
      "artifactID": 7435,
      "name": " ",
      "isNull": true,
      "fieldArtifactID": "1035357"
    }
  ],
  "NewValues": [
    {
      "artifactID": 7435,
      "name": "Technical Issue (1035916)",
      "isNull": false,
      "choiceArtifactID": "1035916",
      "fieldArtifactID": "1035357"
    }
  ],
  "Fields": [
    {
      "artifactID": 7435,
      "name": "Responsive Designation",
      "isNull": false,
      "fieldArtifactID": "1035357",
      "fieldTypeID": "5"
    }
  ],
  "WorkspaceId": 2551025,
  "WorkspaceName": "Salt vs Pepper"
}

This is how the API call is rendered in the Relativity user interface:

Execute pivot

You can also run pivot queries on audit data. After the results are returned, they can be rendered as graphs and charts with third-party visualization tools. Audit record pivots use the same query pattern as Relativity Pivot. For more information, seePivot Manager (REST).

To run an audit pivot query, send a request to the following URL:

Relativity.Rest/API/kCura.AuditUI2.Services.ExternalData.ExternalAuditLogModule/External%20Audit%20Log%20Manager/ExecuteAsync

The request body includes the following properties:

  • workspaceId – the Artifact ID of the target workspace. To return the instance level audit records, specify -1.
  • settings – pivot settings including:
    • ArtifactTypeID – the Artifact ID of the Data Grid Audit object type.
    • GroupBy – the artifact ID of the object to group by, for example, audit action or user name.
    • PivotOn – the artifact ID of the field to use as the Pivot On value in the query and result set, for example, audit action, object type, or user name. Pivot functionality must be enabled for a field before the field can be used as a PivotOn field.
    • PivotOnDateGrouping – the time interval to use when calculating results for a PivotOn field, if the PivotOn field is a Date field.
    • ObjectSetQuery – defines the base set of documents or objects to run a Pivot query against.
  • cancel – use a null object.
  • progress – use a null object.

Sample request:

{
  "workspaceId": 2551025,
  "settings": {
    "ArtifactTypeID": 1000045,
    "GroupBy": {
      "ArtifactID": 1039516
    },
    "PivotOn": {"ArtifactID": 1039516},
    "ObjectSetQuery": {
      "Condition": "(('Object Type' == CHOICE 1039667))",
      "SearchProviderCondition": null,
      "SampleParameters": null
    }
  },
  "cancel": {},
  "progress": {}
}

The response includes the following properties:

  • Results – a collection of data that meets the criteria specified in the pivot.
  • TotalCount – the total number of results returned by the pivot.
  • QueryToken – reserved for future use.
  • Success – a Boolean value indicating success or failure.
  • Message – a message that indicates the status of a Pivot query, after the query stops running. If the query failed, the message contains information about the errors that occurred.
  • PivotIdToDisplayValueMap – if a PivotOn field is specified in the request, the object maps the system-generated pivot item IDs to display value for visualization.

The following is a sample response:

{
  "Results": [
    {
      "Action": "38",
      "KCURA_GROUPBYDISPLAY_10EFAE7FB4F74354B59A340F09DF7E4F": "Run",
      "_x0033_8": 11,
      "_x0034_6": 0,
      "_x0031_": 0,
      "_x0033_": 0,
      "Grand Total": 11
    },
    {
      "Action": "46",
      "KCURA_GROUPBYDISPLAY_10EFAE7FB4F74354B59A340F09DF7E4F": "Conversion Complete",
      "_x0033_8": 0,
      "_x0034_6": 11,
      "_x0031_": 0,
      "_x0033_": 0,
      "Grand Total": 11
    },
    {
      "Action": "1",
      "KCURA_GROUPBYDISPLAY_10EFAE7FB4F74354B59A340F09DF7E4F": "View",
      "_x0033_8": 0,
      "_x0034_6": 0,
      "_x0031_": 10,
      "_x0033_": 0,
      "Grand Total": 10
    },
    {
      "Action": "3",
      "KCURA_GROUPBYDISPLAY_10EFAE7FB4F74354B59A340F09DF7E4F": "Update",
      "_x0033_8": 0,
      "_x0034_6": 0,
      "_x0031_": 0,
      "_x0033_": 8,
      "Grand Total": 8
    }
  ],
  "TotalCount": 4,
  "QueryToken": "",
  "Success": true,
  "Message": "SUCCESS",
  "PivotIdToDisplayValueMap": [
    [
      "Action",
      "Action"
    ],
    [
      "KCURA_GROUPBYDISPLAY_10EFAE7FB4F74354B59A340F09DF7E4F",
      "KCURA_GROUPBYDISPLAY_10EFAE7FB4F74354B59A340F09DF7E4F"
    ],
    [
      "_x0033_8",
      "Run"
    ],
    [
      "_x0034_6",
      "Conversion Complete"
    ],
    [
      "_x0031_",
      "View"
    ],
    [
      "_x0033_",
      "Update"
    ],
    [
      "Grand Total",
      "Grand Total"
    ]
  ]
}

Revert actions

You can use the Audit API to revert the document update actions. For example, this can be used as a programmatic shortcut for reverting incorrect coding decisions.

Actions can reverted individually and en mass. The API also allows you to validate the reversal before actually performing it.

Revert a single action

Before reverting an action, always validate whether it can be reverted successfully.

To validate a reversal, send a POST request to this service endpoint:

Relativity.Rest/API/Relativity.Objects.Audits/workspaces/<Workspace Artifact ID>/audits/revert/validate

The request must include the ID of the action:

{
  "request": {
    "AuditId": 3266861
  }
}

The IsRevertable property in the response indicates whether the action can be reverted:

{
"AuditId": 7435,
"Timestamp": "2018-03-23T20:19:46.607",
"IsRevertable": true
}

If the action cannot be reverted, the response also contains the Message property with a detailed explanation.

{
   "AuditId": 7431,
   "IsRevertable": false,
   "Message": "Action 'Conversion Complete' on object Document cannot be reverted."
}

To revert an action, issue a POST request to this service endpoint:

/Relativity.Rest/API/Relativity.Objects.Audits/<Workspace Artifact ID>/audits/revert

The request must include the ID of the action:

{
  "request": {
    "AuditId": 3266861
  }
}

The Success property on the response indicates whether the reversal is successful:

{
  "Success": true,
  "ValidationResponse": {
    "AuditId": 3266861,
    "Timestamp": "2017-09-22T17:21:45.943",
    "IsRevertable": true
  }
}

Mass revert

To mass-revert actions, issue a POST request to this service endpoint:

/Relativity.Rest/API/Relativity.Objects.Audits/workspaces/<Workspace Artifact ID>/audits/massrevert

The request must identify the actions:

{
  "request": {
    "revertAuditRequests": [
      {
        "AuditId": 7457
      },
      {
        "AuditId": 7433
      }
    ]
  }
}

The Success property on the response indicates whether the reversal is successful:

{
  "Success": false,
  "ValidationResponses": [
    {
      "AuditId": 7457,
      "Timestamp": "2018-03-23T20:20:07.350",
      "IsRevertable": false,
      "Message": "This audit does not represent the most recent change to this document."
    },
    {
      "AuditId": 7433,
      "Timestamp": "2018-03-23T20:19:41.800",
      "IsRevertable": true
    }
  ]
}

Reviewer statistics report

You can use the Audit API to return reviewer statistics data. The statistics provide a count of reviewed documents over a certain period of time. You must specify the time zone of the reviewers, and whether specify whether to include or exclude system admin statistics from the data.

Note: The report doesn't return correct results in the current RelativityOne production and preview environments.

This is a programmatic equivalent of the Reviewer Statistics report. For more information about the report, see Relativity Documentation site.

To get reviewer statistics, send a POST request to this service endpoint:

Relativity.Rest/API/Relativity.Objects.Audits/workspaces/<Workspace Artifact ID>/reviewerstatistics/query

The request body contains the reviewerStatsDataRequest object with following properties:

  • startDate – the start time of the reporting period.
  • endDate – the end time of the reporting period.
  • timeZone – the time zone of the review specified as a UTC offset.
  • downTimeThreshold – the expected downtime (in seconds) between audit records. This is by default set to 900 seconds (15 minutes).
  • nonAdmin – indicates whether the report is for non-admin users only.
  • additionalActions – indicates whether to include statistics for Mass Edits and Propagation actions. The values are as follows:
    • None - include View and Update actions.
    • Mass Edits - include View, Update, and Mass Edit actions.
    • Propagation - include Propagation action.
    • Mass Edits and Propagation - include View, Update, Mass Edit, and Propagation actions.
{
    "reviewerStatsDataRequest": {
    "startDate": "2010-11-01T00:00:00Z",
    "endDate": "2018-11-30T00:00:00Z",
    "timeZone": "-06.0",
    "downTimeThreshold": "900",
    "nonAdmin": false,
    "additionalActions": "Mass Edits"
    }
}

The response includes the following properties:

  • FullName – the reviewer’s full name.
  • UserId – the reviewer's Relativity user Artifact ID.
  • TotalUsageTime – the total usage time is calculated as the difference between the time the user first views or edits any document in the workspace and the time the user last views or edits any document in the workspace per session. A session is anytime the user has logged in to Relativity. All sessions for the selected date range are then totaled per user.
  • Views – the total number of documents a reviewer looked at over the reported period.
  • DistinctViews – the number of unique documents a reviewer looked at over the reported period.
  • Edits – the total number of editing/coding decisions made over the reported time period.
  • DistinctEdits – the total number of documents edited, excluding repeated edits of the same document. The "distinct" classification is meant to account for duplicate actions performed against unique documents.
  • EditsPerHour – the number of edits per hour based on the reviewer’s total usage time.
  • EditsPerDay – the number of edits performed per day over the period reported on.
  • DistinctEditsPerHour – the number of distinct edits per hour based on the reviewer’s total usage time.
  • DistinctEditsPerDay – the number of distinct edits performed per day over the period reported on.
  • MassEdits – the total number of document edits using the Mass Edit action.
  • DistinctMassEdits – the total number of distinct document edits using the Mass Edit action.
  • DistinctMassEditsPerHour – the number of distinct Mass Edits per hour based on the reviewer's total usage time.
  • DistinctMassEditsPerDay – the number of distinct Mass Edits per day over the period reported on.
  • MassEditsPerHour – the number of Mass Edits per hour based on the reviewer's total usage time.
  • MassEditsPerDay – the number of Mass Edits per day over the period reported on.
  • Propagations – the total number of documents that were updated via propagation.
  • DistinctPropagations – the total number of unique documents that were updated via propagation.
  • DistinctMassPropagationsPerHour – the number of unique documents that had propagations applied per hour based on the reviewer's total usage time.
  • DistinctMassPropagationsPerDay – the number of unique documents that had propagations applied per day based on the period reported on.
  • PropagationsPerHour – the number of propagations applied per hour based on the reviewer's total usage time.
  • PropagationsPerDay – the number of propagations applied per day based on the period reported on.
[
    {
        "FullName": "Admin, Relativity",
        "UserId": 9,
        "TotalUsageTime": "0:04:00",
        "Views": 0,
        "DistinctViews": 0,
        "Edits": 0,
        "DistinctEdits": 0,
        "EditsPerHour": 0,
        "EditsPerDay": 0,
        "DistinctEditsPerHour": 0,
        "DistinctEditsPerDay": 0,
        "MassEdits": 0,
        "DistinctMassEdits": 0,
        "DistinctMassEditsPerHour": 0,
        "DistinctMassEditsPerDay": 0,
        "MassEditsPerHour": 0,
        "MassEditsPerDay": 0,
        "Propagations": 0,
        "DistinctPropagations": 0,
        "DistinctMassPropagationsPerHour": 0,
        "DistinctMassPropagationsPerDay": 0,
        "PropagationsPerHour": 0,
        "PropagationsPerDay": 0
    },
    {
        "FullName": "Smith, Jane",
        "UserId": 1020759,
        "TotalUsageTime": "0:12:00",
        "Views": 5,
        "DistinctViews": 3,
        "Edits": 0,
        "DistinctEdits": 0,
        "EditsPerHour": 0,
        "EditsPerDay": 0,
        "DistinctEditsPerHour": 0,
        "DistinctEditsPerDay": 0,
        "MassEdits": 0,
        "DistinctMassEdits": 0,
        "DistinctMassEditsPerHour": 0,
        "DistinctMassEditsPerDay": 0,
        "MassEditsPerHour": 0,
        "MassEditsPerDay": 0,
        "Propagations": 0,
        "DistinctPropagations": 0,
        "DistinctMassPropagationsPerHour": 0,
        "DistinctMassPropagationsPerDay": 0,
        "PropagationsPerHour": 0,
        "PropagationsPerDay": 0
    },
    {
        "FullName": "Smith, Jane",
        "UserId": 1020759,
        "TotalUsageTime": "1:03:00",
        "Views": 5,
        "DistinctViews": 4,
        "Edits": 1,
        "DistinctEdits": 1,
        "EditsPerHour": 0.95,
        "EditsPerDay": 0.03,
        "DistinctEditsPerHour": 0.95,
        "DistinctEditsPerDay": 0.03,
        "MassEdits": 3,
        "DistinctMassEdits": 3,
        "DistinctMassEditsPerHour": 2.86,
        "DistinctMassEditsPerDay": 0.1,
        "MassEditsPerHour": 2.86,
        "MassEditsPerDay": 0.1,
        "Propagations": 0,
        "DistinctPropagations": 0,
        "DistinctMassPropagationsPerHour": 0,
        "DistinctMassPropagationsPerDay": 0,
        "PropagationsPerHour": 0,
        "PropagationsPerDay": 0
    }
]

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