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. An event handler will monitor the tracked fields and update the Reviewed On and Reviewed By fields based on the tracker's settings.

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
2021.6.13 10.1 - Server 2021, RelativityOne
5.7 9.5.162.111 - 10.0
5.6 9.5.41.87 - 9.5.133.118
5.5 8.0 - 9.4

Note: If you are upgrading this application from 5.7 or below to 2021.6.1 or above, ensure that you upgrade the Track document field edits by reviewer application in each workspace so that the newer version of the application works properly.

Components

This solution consists of the following components:

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

Relativity Server considerations

  • Service Bus or RabbitMQ must be installed and enabled in your Relativity instance to perform historical population.

Considerations

  • All dates/times for Reviewed On & Reviewed By fields will now be in UTC due to Relativity software requirements.
  • This solution doesn't support the client domains (multi-tenancy).
  • 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 Populate Historical Data mass operation take mass edits into account.
  • Audit records are created only if the Reviewed By and Reviewed On fields are on the layout.
  • The Populate Historical Data mass operation 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. 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.

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.

Populating Historical Records

The population of historical data can now be done across multiple Document Field Edits Tracker objects and run against a single saved search.

Note: Audit must be available for the tracker to be able to populate it as the source. If Audit is not restored/enabled, population will not occur.

To populate history, do the following:

  1. Ensure that the Document Field Edits Tracker Historical Processor Agent is enabled.

  2. Navigate to the list of Document Field Edit Trackers.

  3. Select the Document Field Edit Trackers you wish to run from the list.

  4. Click on the mass operations toolbar and select Populate Historical Data. You must have the Populate Historical Data mass operation permission to view and select this option.

  5. Select the Saved Search you wish to run the Document Field Edit Trackers against.
    (Click to expand)

  6. Click Ok.

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.