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

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:

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

The Audit API provides two endpoints for querying:

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:

The response includes the following properties:

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:

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:

Sample request:

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

The response includes the following properties:

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

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:

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:

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:

{
    "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": "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