Audit

Audit is an application that you can use to monitor and run reports on audited user activity. With Audit, you can use pivots and visualizations to quickly identify audit activity in your Relativity instance.

Some of the benefits of using Audit include:

  • Building multiple widgets and lists to create custom dashboards for reporting.
  • Viewing audit records that occur at the instance level through the Relativity UI.
  • Easily searching through millions of audits to identify actions ranging from reviewer coding decisions to users logging in and out of Relativity for monitoring activity
  • Quickly exporting audits to meet stakeholder requests for reporting on user activity in Relativity.

For information about common Audit workflows, see Reporting and Monitoring using Audit.

You must have Elasticsearch configured to use the Audit application. In RelativityOne, audits are automatically stored in Elasticsearch. Once you migrate your workspace into RelativityOne, you cannot keep audit data in SQL.

Supported Audit tab functionality

The following lists supported and unsupported functionality on the Audit tab as compared to the history tab.

Supported functionality Currently unsupported functionality
  • ARM – Archive & Restore
  • Dashboards
  • Group By/Pivot On functionality (limited number of fields)
  • Item list
  • Filtering
  • Views
  • Widgets
  • Reverting/mass revert document edits
  • Error reporting
  • Exporting data from lists
  • Exporting dashboard widgets as image
  • Custom scripts
  • Export of dashboards
  • Exporting from the History tab

Installing and configuring Audit

In order to use Audit, you must complete the following:

  1. Install and configure Elasticsearch. For more information, see Installing Elasticsearch.
  2. Install the Audit application to your workspace(s). For more information on installing applications, see Installing applications.
  3. Install the Audit agents. See Audit agents.

Audit agents

The Audit application includes the agents described below:

Agent name Requirement information Function Agent type
Data Grid Audit Migrator Only 1 per core on the agent server. Up to 16 agents per environment. A Data Grid Audit Migrator agent migrates audit data from SQL to Elasticsearch for any workspace that has Audit installed. The frequency with which this agent checks for migrations and runs the migrations is controlled by the agent run interval value. Multiple-installation
Data Grid Audit Deleter 1 per environment required. Up to 4 agents per environment.

The Data Grid Audit Deleter agent is an off-hour agent that deletes all audits from SQL that have been successfully migrated to Elasticsearch. Along with un-migrated audits, it will leave other existing audits in SQL for a configurable number of days for billing purposes.

 Single-installation
Data Grid Audit Reporter (Optional) 1 per environment The Data Grid Audit Reporter agent reviews the audit queue for errors that occurred during migration from SQL to Elasticsearch. This agent triggers a Relativity error based on the agent's run interval. This agent is set to an hourly run interval by default. Single-installation
Data Grid Audit Manager Only 1 per environment Populates filters in the Audit application. Single-installation
Data Grid Manager Only 1 per environment

A Data Grid Manager agent is an off-hours agent responsible for Data Grid enabled workspace management, including deleting outdated search results cache tables and monitoring Data Grid index conditions.

Note: If you've already installed this agent with Data Grid installation, you don't need to add another.

 Single-installation
Audit Export Agent Only 1 per environment The Audit Export Agent is activated whenever a user exports data to CSV or XLSX in the Audit tab (Mass Export). This agent then retrieves data from a storage location and streams it into a file. Single-installation
Audit Reviewer Statistics Agent Only 1 per environment The Audit Export Agent is activated whenever a user generates a Reviewer Statistics report (either by running the Reviewer Statistics script or by using the Case Metrics application). This agent retrieves data from a storage location, aggregates it, and saves it as a materialized view in the temporary tables of the workspace database. Single-installation

For more information on installing agents, see Adding and editing agents.

Audit tab

You can use the Audit tab to build custom widgets and design dashboards to meet workflow needs by utilizing the same Group By and Pivot On functionality available in Relativity. The default view on the Audit dashboard shows the last 7 days of Audit activity.

Note: You cannot add the Security, Edit, Name, System Last Modified On, System Last Modified By, System Created By, or System Created On fields to an Audit list view. In addition, you should not add the Artifact ID field to any views from the Audit tab.

Audit tab display

The following functionality is also available:

  • Searching on Field, Old Value, and New Value columns in list view.
  • Creating and customizing views on the Audit tab.
  • Applying filters and conditions to sort through audit records.
  • Exporting audit data from list views and widgets.

See these related pages:

Searching on the Details column

To display the query text of an audit record, click the expand details icon Expand details icon in the Details column for that record. You can toggle between a table view and JSON view of audit details.

Audit Details Table Tab

Audit Details JSON Tab

Exporting workspace audits

Note: Exporting audits is not available at the instance level.

You can export audit data from list views and widgets. The export respects the data made on the filters in the list view, and the results are filterable.

Note: When you export audit data, the Field, Old Value, and New Value are not displayed in separate columns but are preserved within the Details column. For the following field types, the choices names are included in the export in addition to IDs: Single Choice Field, Multiple Choice Field, Single Object Field, Multiple Object Field, and User Field.

To export audit data, complete the following:

  1. From the mass operations bar, click Export.
  2. Select the format you want to export your audits in (either .csv or .xlsx).
    Export audits - options
  3. Click Run.
    4. Note: Currently, when you sort on the Audit table and then export it, the sort order you specified is not retained. Only filter conditions are retained when you export.

Instance audits

The Audit tab is available at the instance level upon upgrade. You must have Elasticsearch installed and configured to use the Audit tab. If you do not have Elasticsearch installed, you can hide this tab. For information about hiding tabs, see Tabs.

Note: You must be a system admin to view audits at the instance level.

The Audit tab functions the same at the instance level. You can build custom widgets and design dashboards by utilizing the same Group By and Pivot On functionality available in workspace audits. However, exporting audits is not available. For a list of admin-level audited actions, see Audited actions.

Audited actions - last 7 days

Filtering on multi-workspace audits

System admins can view workspace audits at the instance level.

You can filter on the Workspace Name column to view audits for specific workspaces. By default, the Audit application displays audit information for the first 10 workspaces, sorted by Artifact ID. You can configure this number using the MaxAggregatedWorkspaces instance setting.

Filtering on multi-workspace audits

Reverting audited actions

System admins can revert a coding decision made by a user on a document from the Audit list. Reverting the coding decision will edit the choice back to the previous selection. This action can only be performed at the workspace level.

You can revert the most recent Document Update, Mass Update, or Propagate action on the Document object.

Only the latest update action made to the following field types can be reverted:

  • Currency
  • Date
  • Decimal
  • Fixed Length Text
  • Single choice
  • Single object
  • User
  • Whole number
  • Yes/No
    Notes:
  • You cannot revert a required field if it would result in returning that field to a blank (null) value. The system does not permit empty (null) values. For example, if a required field was blank at the time an update was applied and you then attempt to revert it, you will not able to do so.
  • By default, the maximum number of audits you can run the mass revert operation on at one time is 5000. Attempting to run more than 5000 results in an error message.

Let’s assume that the Coding layout has two fields to edit: Responsiveness and Privilege. Neither of them is required. Below are the actions of two reviewers in order of execution:

  1. Reviewer1 updates Document1 to set Responsiveness field to “Not Responsive.”
  2. Reviewer1 updates Document2 to set Responsiveness field to “Responsive” and Privilege field to “Privileged.”
  3. Reviewer1 updates Document3 to set Privilege field to "Privileged."
  4. Reviewer2 updates Document1 to set Responsiveness field to "Responsive."
  5. Reviewer2 updates Document2 to set Responsiveness field to "Not Responsive."

If you execute a mass revert on all actions above, then only actions 3, 4, and 5 will be reverted, because they are the last updates made to the documents.

Using the same example above, now let's assume that the Privilege field is required. In that case, only actions 4 and 5 will be revertible. Operation 3 cannot be reverted because it would result in a blank (null) value, which is not allowed by the system.

To revert a coding decision:

  1. From the mass operations bar, select Revert in the drop-down menu.
  2. Audit scans the list of audits in the current view to determine how many are revertible. Once it finishes, click Run.
  3. Click Close to close the pop-up window.

Similar to reverting a single audit, each reverted audit generates a new audit record.

Audit Migration Reports tab

The Audit Migration Reports tab provides you with the option of generating a migration error and migration status report for you to monitor the status of audit data as you migrate it into Elasticsearch. You also have the option of running a migration error retry script.

Migration Error Report

The Migration Error Report generates a report that provides information on all errors that have occurred while migrating audit data into Elasticsearch, including batch and document errors.

Note: You can also run this script on all environments in your workspace from the Relativity Script Library tab. Click the user drop-down menu in the upper-right corner of Relativity, and then click Home. Navigate to the Applications & Scripts > Relativity Script Library tab, and then search for the name of the script.

To preview the script, select the radio button for this script and click Preview. To run this report, click Run. The following results populate the bottom of the window.

Note: Audit automatically retries certain audit migration errors, like SQL timeouts, invalid XML, and inability to connect to Elasticsearch. With this improvement, the migration error report may display a total of 0 errors because the system automatically retried and resolved those common errors. In this situation, there is no need to run the Migration Error Retry Script.

Audit migration reports

  • Total Error Counts—this section provides a summary of all errors that occurred during migration.
    • Batch Errors—the total number of batch errors that occurred during migration.
    • Document Errors—the total number of document errors that occurred during migration.
  • Batch Errors—this section provides a summary of all batch errors that occurred during migration.
    • Batch ID—the batch ID number of the batch that received an error.
    • Audit ID Range—the first and last Audit ID numbers contained in the batch that received an error.
    • Time Stamp—the time at which the error occurred.
    • Error Message—the text of the batch error.
  • Document Errors—this section provides a summary of all document errors that occurred during migration.
    • Audit ID—the audit ID number of the document that received an error.
    • Batch ID—the batch ID number of the batch in which the document that received an error was contained.
    • Time Stamp—the time at which the error occurred.
    • Error Message—the text of the document error.

Migration Error Retry Script

After identifying errors with the Migration Error Report, an admin can investigate and fix specific audit issues. Once the issues have been fixed, this script will resubmit audit records with errors to be migrated into Elasticsearch.

Note: You can also run this script on all environments in your workspace from the Relativity Script Library tab. Click the user drop-down menu in the upper-right corner of Relativity, and then click Home. Navigate to the Applications & Scripts > Relativity Script Library tab, and then search for the name of the script.

Migration error retry script

In the Error type to retry drop-down list, select from the following options:

  • Batch Errors—retries all batches with errors as reported in the Migration Error Report.
  • Document Errors—retries all documents with errors as reported in the Migration Error Report
  • All Errors—retries all batch errors and document errors as reported in the Migration Error Report.

Click Preview to see a sample of the report, or select the appropriate option and click Run to execute the script.

Migration Status Report

The Migration Status Report generates a report that shows the progress of the migration of audit data into Elasticsearch. This includes audits in SQL, audits pending migrations, and migration errors. To preview the script, select the radio button for this script and click Preview.

Migration status report

Click Run to generate this report and display the following information:

  • Audits in SQL—lists the number of audits in the SQL database.
  • Audits Pending Migration—lists the number of audits in queue for migration into Data Grid.
  • Migration Errors—lists the number of errors that occurred during migration.

Audit Workspace Settings tab

Use the Audit Workspace Setting tab to configure settings specific to the Audit application. The Audit Workspace Setting tab contains two settings, DisplayAuditDataSource and HistoryTabVisibleOnUpgrade.

Note: You must have permission to view this tab in order to configure the setting.

DisplayAuditDataSource

The DisplayAuditDataSource setting configures whether Relativity displays audits from SQL or Data Grid on the document history pane in the viewer and the View Audit button on object layout pages. In RelativityOne, audits are automatically stored in Data Grid.

If you set audits to display from Data Grid, there may be a slight delay in viewing the most recent audits. A "Last Updated" value next to audits indicates the last time all audits were verified as migrated for that object. This lets you know that several of a document's most recent audits might not be migrated yet.

Audit workspace setting - SQL and Data Grid

You can configure the DisplayAuditDataSource setting with one of three values:

  • 0 - displays audits from SQL until the first point that the audit migration has no more audits to migrate. At this point, the system automatically updates this value to "1," and audits are displayed from Data Grid going forward.
  • 1 - displays audits from Data Grid only.
  • 2 - displays audits from SQL only.

HistoryTabVisibleOnUpgrade

The HistoryTabVisibleOnUpgrade tab configures whether the History tab is visible when upgrading the Audit application.

History Tab settings

You can configure the HistoryTabVisibleOnUpgrade setting with one of two values:

  • True - displays the History tab upon upgrade.
  • False - hides the History tab upon upgrade.

By default, the HistoryTabVisibleOnUpgrade setting is set to hide the History tab when upgrading the Audit application. To configure HistoryTabVisibleOnUpgrade, click the Edit link and modify the Value field in the subsequent layout.

Audited actions

The following table lists audited actions in Relativity:

Note: If you perform a job while previewing a user's security settings, the audit action will be credited to your username and not to the user whose security you were previewing when you started the job.

Action name Description of activity
CaseMap - Add Document A document was sent to CaseMap.
CaseMap - Add Fact A selection of text from the viewer was sent to CaseMap as a fact.
Conversion Complete A file was converted by way of a user clicking on a file link in the document list, running an imaging set, imaging on the fly, running a mass image operation, or switching to text or production mode in the viewer.
Create An item was created.
Delete An item was deleted.
Document Query A query was run on a list of documents, or a document query was canceled. (A message indicating that a query was canceled is displayed in the details and on the Query Text pop-up.)
Export The contents of a production set, saved search, folder, or subfolder were exported.
Images - Created Images were created.
File Download A file was downloaded through the Single Simple File Upload application. For example, a user clicked Download File on the Error Actions console of an individual processing error layout.
File Upload A file was uploaded through the Single SimpleFile Upload application. For example, a user clicked Upload Replacement File on the Error Actions console of an individual processing error layout.
Images - Created for Production Images corresponding to a production outside of Relativity were imported into the system.
Images - Deleted Images were deleted.
Import Content associated with a load, production, or image file was imported.
Markup - Image - Created Redactions or highlights were added to an image.
Markup - Image - Deleted Redactions or highlights were removed from an image.
Markup - Image - Modified Redactions or highlights were moved, resized or edited on an image.
Markup - Native - Created Redactions or highlights were added. This audit entry applies to transcripts only.
Markup - Native - Deleted Redactions or highlights were removed. This audit entry applies to transcripts only.
Markup - Native - Updated Redactions or highlights were moved, resized or edited. This audit entry applies to transcripts only.
Move A document was moved from one folder to another.
Native - Created A native file was loaded into Relativity.
Native - Deleted A native file was removed from Relativity.
Pivot Query A Pivot report was run, or a Pivot report was canceled. (A message indicating that a query was canceled is displayed in the details and on the Query Text pop-up.)
Print A document was printed. (ActiveX viewer only)
Production - Add Document A document was added to a production.
Production - Remove Document A document was removed from a production.
Query A process ran a query (such as categorization), or a query was canceled. (A message indicating that a query was canceled is displayed in the details and on the Query Text pop-up.)
RelativityScriptExecution A Relativity script was run.
ReportQuery A summary report was run.
Run A file was imaged, saved as a PDF, or otherwise converted for viewing
Search Cache Table Creation A search cache table was created. (Search cache tables are created the first time you search for a term or phrase using dtSearch or Relativity Analytics.)
Security Security rights were assigned or changed
Tally/Sum/Average The mass operation Tally/Sum/Average was run in the workspace.
Update Document metadata was updated on a single-document basis. In addition, filters on information related to applications installed through the workspace or by an agent.
Update - Mass Edit Document metadata was updated on a mass basis.
Update - Mass Replace Document metadata was edited using a text mass replacement.
Update - Propagation Document metadata was edited according to a propagation rule.
View A document was viewed.
Workspace Upgrade Details about scripts run on a workspace during an upgrade.

The following actions are audited at the admin-level. These admin-level actions are recorded against the Admin Case (workspace name). If you filter on the actual workspace name when searching for the Login action, you will not see any results.

Action name Description of activity
Create An item was created.
Update An item was updated
Delete An item was deleted.
Security An owner of a saved search was set during creation or edit.
Login A user logged in to Relativity.
Logout A user logged out of Relativity.
Export Data was exported from a tab at the instance level. For example, a workspace list, list of users, list of groups, etc.
RelativityScriptExecution A Relativity script was executed.
Password Reset Request - Submitted A password reset request was submitted.
Password Reset Request - Opened A password reset request was opened.
Password Reset Request - Successful A password reset request was successful.
Security Preview Started A security preview started on a user or group.
Security Preview Ended A security preview ended on a user or group.
Workspace Upgrade Upgrade script run on the workspace (details can be viewed in the JSON tab of the Details).
Login - Failed A login attempt to Relativity failed.