Track document field edits by reviewer

Note: Some of the recipes listed below now exist as knowledge base articles on the Relativity Community. When you click those links, you must enter valid Community credentials to access those articles. The remaining recipes will soon be integrated into their corresponding feature documentation so that they'll show up either as new topics or new headings within existing topics. Once this relocation is complete, we will be deprecating this home page, and all of the content below will be accessible via search on our sites.

You must have valid Relativity Community credentials in order to download any Community file linked to the documentation site. You'll need to enter those credentials on the Community login screen if you're not already logged in. If you're already logged in to the Community at the time you click a link, the file is automatically downloaded in the bottom left corner of your screen. If you get an error message stating "URL No Longer Exists" after clicking a Community link, it may be due to a single sign-on error related to the SAML Assertion Validator, and you should contact your IT department.

The Track Document Field Edits by Reviewer solution tracks the first or most recent change to a field that you specify and it populates two other fields, Reviewed By (User) and Reviewed On (Date), with information about those changes.

A new script will be included in the application. The script shows the User type fields as first input and the disabled Users as second input. Once executed, it will show the Document ArtifactID, Control Number and the date the "Track Document Field Edits" app registered the coding decision. This new script can also filter on users that no longer have access to the workspace.

To download the solution files, visit the Relativity Community.

A new script will be included in the application. This new script can filter on users that no longer have access to the workspace. The script shows the User type fields as first input and the disabled Users as second input. Once executed, it will show the Document ArtifactID, Control Number and the date the "Track Document Field Edits" app registered the coding decision.

This page contains the following sections:

Before you begin

The Track Document Field Edits by Reviewer solution tracks the first or most recent change to a field that you specify and it populates two other fields, Reviewed By (User) and Reviewed On (Date), with information about those changes. The Reviewed By field stores the name of the user who made the change. The Reviewed On field stores the time when the user made the change. This solution can track Single Choice, Multiple Choice, and Yes/No fields. In addition, you can specify whether you want to track only the initial change or all changes to the field.

Supported versions

This solution is supported in Relativity 8.0 – Server 2021 and RelativityOne.

Click on any of these links to download the appropriate version from the Relativity Community:

Solution version Supported Relativity version
5.7 9.5.162.111 - 10.0
5.6 9.5.41.87 - 9.5.133.118
5.5 8.0 - 9.4

Components

This solution consists of the following components:

  • Relativity application
  • Relativity object
  • Event handler
  • Relativity script that runs at the workspace level

RelativityOne Considerations

Considerations

  • This script should only be run by a system admin. If you are not a system admin, we recommend you do not run this script.
  • This solution doesn't support the client domains (multi-tenancy) and Data Grid features of Relativity.
  • The Reviewed By and Reviewed On fields are not created upon application import. These fields must be created per Field to Monitor.
  • You can specify the Field to Monitor setting only once. If you set multiple tracking entries on one Field to Monitor item, Relativity displays an error.
  • If a user is deleted, you cannot search for them by using the User field to filter the view, although you can see the user's name in the field at the document level.
  • This solution does not track changes made using mass operations or propagation. Neither the event handler nor the script reports on mass operations or propagation.
  • If a system admin changes the User field, the field is blank in the layout but is populated with and displays the correct information in a view.
  • Audit records are created only if the Reviewed By and Reviewed On fields are on the layout. They are not created when those fields are updated by the script.
  • This script only populates historical data for users who coded documents and still have access to the workspace.

Deploying and configuring the solution

To deploy this solution, you start by adding it to the Application Library as a Relativity application. How you deploy and configure it depends on whether you are installing the solution for the first time or upgrading an earlier version of the solution. The current version of this solution is 5.7. Follow the appropriate set of steps below to install or upgrade the solution in your Relativity instance.

Installing the solution for the first time

To install the solution:

  1. Log in to Relativity.
  2. Click the user drop-down menu in the upper right corner of Relativity, and then click Home.
  3. Navigate to the Application Library tab.
  4. Click Upload Application.
  5. Click Browse, select the Track Document Field Edits by Reviewer.rap file, and then click Open.
  6. Click Save.
  7. Click Install in the Workspaces Installed section to install the application on workspaces.
  8. Click in the Workspaces field to display the Select Workspaces dialog.
  9. Select the workspaces where you want to install the application, and then click Ok.
  10. Click Clear to remove a workspace from the list.
  11. Click Save to install the application to the selected workspaces. These workspaces now contain the application. Relativity lists the workspaces in the Workspaces Installed section on the detail view of the application.

Upgrading an earlier version of the solution

To upgrade from an earlier version:

  1. Log in to Relativity.
  2. Click the user drop-down menu in the upper right corner of Relativity, and then click Home.
  3. Navigate to the Applications & Scripts tab, and then select the Application Library tab.
  4. Click the name of the Track Document Field Edits by Reviewer application.
  5. Click Edit.
  6. Click Clear to clear the application file for the earlier version of the solution.
  7. Click Browse, select the Track Document Field Edits by Reviewer. file, and then click Open.
  8. Click Save.
  9. If you receive a message asking if you want to update workspaces automatically, click Yes.
  10. Using the Workspaces Installed section of the application page, ensure that the upgrade is applied to every workspace where the application has already been installed.
  11. Navigate to the Server & Agent Management tab, and then select the Agents tab.
  12. Verify that the Application Deployment Manager agent is running.

If you're upgrading version 3.2 or earlier, you also need to run a Relativity script to complete the upgrade process for the Relativity instance. The script is included with this version of the solution. If you're not sure whether you need to run the script or have any questions, contact Relativity Client Services at support@relativity.com.

To run the script:

  1. Using a text editor or similar application, open the Track Documents Field Edits by Reviewer - Event Handler Maintenance.krs file included in the solution, and then select and copy all the text in the file to your clipboard.
  2. On the Applications & Scripts tab in your Relativity instance, click the Relativity Script Library tab.
  3. Click New Relativity Script.
  4. Under Script Body, delete all the text in the script field, and then paste the text that you copied from the .krs file.
  5. Click Save.
  6. In the console, click Run Script, and then click Run in the pop-up window that appears.

Preparing the workspace

After you add the solution to the Application Library, you will need to add your Admin user account to a non-admin group. Once your user account has been added, we recommend that you test to make sure that the changes show up in the Reviewed By/On field (or whichever normal tracking fields you usually use).

Once this testing has been completed, you're ready to install and configure it in a workspace.

To do this:

  1. Create two new fields to store user and date data for the field you want to track.
  2. Configure the application to track and store data in the appropriate fields.

Creating the tracking fields

To create fields to store data about changes to the field that you want to track:

  1. In the workspace, click the Workspace Admin tab, and then click the Fields tab.
  2. Create a new User field named "Reviewed By".
    • Object type: Document
    • Name: Reviewed By
    • Field Type: User
  3. Create a new Date field named "Reviewed On".
    • Object type: Document
    • Name: Reviewed On
    • Field Type: Date

Configuring the application

Now that you've created fields to store the tracking data, you're ready to configure the application to use those fields and capture the changes that you want to track.

To configure the application:

  1. In the workspace, navigate to the Track Document Field Edits by Reviewer tab, and then select the Document Field Edits Tracker tab.
  2. Click New Document Field Edits Tracker.
  3. Enter the following settings:
    • Field to Monitor - click Ellipsis (...) button and select the field that you want to track changes to. The field must be a single choice, multiple choice, or Yes/No field. When a user changes the field that you select, the Reviewed By and Reviewed On fields are updated to indicate the name of the user who made the change and when they made the change.

      Note: Specify a Field to Monitor setting only once. If you set multiple tracking entries on one Field to Monitor item, you'll receive an error.

    • Reviewed On Date Field - click Ellipsis (...) button and select the Reviewed On (Date) field that you created to store data about when a user changes the field being tracked.
    • Reviewed By User Field - click Ellipsis (...) button and select the Reviewed By (User) field that you created to store data about which user changed the field being tracked.
    • Track Initial Change Only - select this check box to update the Reviewed On and Reviewed By fields only when a user changes the tracked field from "not set" to a specific choice. If set to Yes, the selected Reviewed By User and Reviewed On Date fields will be updated with the first edit that was made on the document in the selected field. If set to No, the selected Reviewed By User and Reviewed On Date fields will be updated with the last edit that was made on the document in the selected field.

      The New Document Field Edits Tracker page provides options for specifying which field to track, which fields to populate with reviewer data, and which changes to track.


  4. Click Save.

Running the solution

After you configure the application, it starts monitoring changes to the tracked field and populates the Reviewed On and Reviewed Date fields with that data. You don't need to take any additional steps to run the solution.

Note that this solution doesn't automatically capture and report data about changes that users made to the field before you installed and configured the application in the workspace. To capture historical data in the Reviewed On and Reviewed Date fields, you can run a Relativity script that's included in the solution.

To run the script:

  1. In the workspace, create or locate a saved search that returns the group of documents you want to run the script against.
  2. Navigate to the Administration tab, and then select the Scripts tab.
  3. Click the name of the Populate Reviewed By/On fields for Historical Edits script.
  4. In the console, click Run.
  5. Under Inputs, specify the settings you want:
    • Saved Search - click the name of the saved search that you created or identified in step 1.
    • Field to Monitor - click the name of the field that you're tracking changes to. The field must be a Single Choice, Multiple Choice, or Yes/No field.
    • Reviewed By User Field - click the name of the Reviewed By (User) field that you created to store data about which user changed the field being tracked.
    • Reviewed On Date Field - click the name of the Reviewed On (Date) field that you created to store data about when a user changes the field being tracked.
    • Track Initial Change Only - click Yes to update the Reviewed On and Reviewed By fields with data about the first time the tracked field was set (changed from "not set") for a document. To update those fields with data about the last time the tracked field was changed, click No.
  6. Click Run.

When the script runs, it populates the specified Reviewed By and Reviewed On fields with historical data about changes to the field that you're tracking. When the script finishes running successfully, Relativity displays an Update Complete message.

Note: This script only populates historical data for users who coded documents and still have access to the workspace.

Viewing the results

To view the results of running the solution, navigate to any view, layout, or other area that contains the Reviewed By and Reviewed On fields.

The documents list displays the tracking data in the Reviewed By and Reviewed On fields.