File validation agent

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 File Validation Agent solution determines whether any document files are missing from a file server. The solution performs the following tasks:

  • Searches for document files on a file server. For example, it searches for natives, images, production images, and transcripts.
  • Uses a field that you specify to indicate whether any of those files are missing from the server.
  • Provides a report containing a detailed list of the missing files.

To download the solution files, visit the Relativity Community.

This page contains the following sections:

Before you begin

The File Validation Agent solution determines whether the files associated with documents in a workspace are missing. It searches for those files on a file server. It sets the value of a Yes/No field called the missing files indicator field. The value in this field indicates whether the files were found. Finally, the solution generates a report with detailed information about each missing file.

The solution validates document files in batches of 1,000. It validates only those documents where the value of the missing files indicator field is Null. You can this report to determine which files to restore on the file server.

Supported versions

This solution is supported in Relativity 9.0 – 11.2 and Relativity One.

Solution version Supported Relativity version
6.10 9.0 - 10.2
7.14 10.3 - 11.2
8.0 RelativityOne

Components

This solution consists of the following components:

  • Relativity application
  • Event handlers
  • Custom agents
  • Custom object
  • Relativity script that runs at the workspace level

Configuration

To use this solution, the Relativity Services API must be configured on your web and agent servers. To verify that Relativity Services API is configured correctly, contact Relativity Client Services.

Considerations

Review the following considerations for this solution before running it:

  • 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 validate files for documents where the missing files indicator field is set to Yes or No. It also doesn't reset the value of the field each time that it's run. Running the solution multiple times for a workspace won't necessarily produce comprehensive results. When running the solution a subsequent time, complete one of these tasks before each run:
    • Clear all existing values in the missing files indicator field.
    • Create and use a new missing files indicator field.
  • This solution doesn't support the client domains (multi-tenancy) and Data Grid features of Relativity.

Deploying and configuring the solution

To deploy and configure the solution, add it to the Application Library as a Relativity application. Next, create and enable File Validation agents. These agents monitor and perform the file validation tasks.

Adding the solution to the Application Library

Complete the following steps to add the solution to the Application Library:

  1. Log in to Relativity.
  2. Click the user drop-down menu in the upper-right corner of Relativity.
  3. Click Home.
  4. Click the Applications & Scripts > Application Library tabs.
  5. Click Upload Application.
  6. Click Browse.
  7. Select the File Validation Agent (Relativity v9.0 - 11.0).rap file. This file is currently the most recent version of the solution for Relativity v9.0 and above.
  8. Click Open.
  9. Click Save.

Adding File Validation agents

After adding the solution to the Application Library, you can create and enable a File Validation Manager agent. The agent monitors file validation tasks. One or more File Validation Worker agents perform file validation tasks. Only one File Validation Manager agent can be enabled at a time. To optimize performance, create and enable multiple File Validation Worker agents.

Complete the following steps to create and enable the File Validation Manager agent:

  1. Click the Server & Agent Management tab, and then click the Agents tab.
  2. Click New Agent.
  3. Enter or select values in the following fields:
    • Agent Type - Click Ellipsis (...) button, select File Validation Manager - KCD_1035966 (v6), and then click OK.
    • Agent Server - Click Ellipsis (...) button, select the server where you want to run the agent, and then click OK.
    • Run interval - Enter 5.
    • Logging level - Select the information logged for the agent.
    • Status - Click Yes to enable the agent.
  4. Click Save and Back. The "File Validation Manager - KCD_1035966 (v6)" agent now appears in the list of agents.

Complete the following steps to create and enable a File Validation Worker agent:

  1. Click the Agents tab.
  2. Click New Agent.
  3. Enter or select values in the following fields:
    • Agent Type - Click Ellipsis (...) button, select File Validation Worker - KCD_1035966 (v6), and then click OK.
    • Agent Server - Click Ellipsis (...) button, select the server where you want to run the agent, and then click OK.
    • Run interval - Enter 5.
    • Logging level - Select the information logged for the agent.
    • Status - Click Yes to enable the agent.
  4. Click Save and Back. The "File Validation Worker - KCD_1035966 (v6)" agent now appears in the list of agents.

Preparing the workspace

After deploying the solution, you can install and configure it in a workspace by completing these tasks:

  1. Install the solution application from the Application Library. See Installing the solution application.
  2. Create a new missing files indicator field. This field stores the results generating by running the solution. It indicates whether any files are missing for a document. See Creating the missing files indicator field.

Installing the solution application

Complete these steps to install the application:

  1. Click the user drop-down menu in the upper-right corner of Relativity.
  2. Click Home.
  3. Click the Applications & Scripts > Application Library tabs.
  4. Click the name of the File Validation application.
  5. In the Workspaces Installed section, click Install.
  6. Click Ellipsis (...) button in the Workspaces section.
  7. Select the check box for each workspace where you want the solution installed.
  8. Click OK.
  9. Click Save.

Creating the missing files indicator field

Complete these steps to create the missing files indicator field:

  1. In a workspace, click the Workspace Admin > Fields tabs.
  2. Click New Field.
  3. Create a new field with the following settings:
    • Object Type - Document
    • Name - Enter Missing Files or any other name that you want for this field.
    • Field Type - Yes/No
  4. Select any other settings that you want for the field.
  5. Click Save.

Running the solution

You can run the solution by creating and executing a File Validation job for the workspace. By default, you can only run the File Validation job once for a workspace. It validates files only for documents where the missing files indicator field is Null. The solution skips documents where the missing files indicator field is Yes or No. When running the solution a subsequent time, complete one of these tasks before each run:

  • Clear all existing values in the missing files indicator field.
  • Create and use a new missing files indicator field.

Complete these steps to create and run a File Validation job:

  1. In a workspace, click the File Validation tab.
  2. Click New File Validation Job.
  3. Enter a name for the job in the Name box.
  4. Click Ellipsis (...) button in the Missing File Indicator field.
  5. Select the Yes/No field that you created to indicate whether any files are missing
  6. Click OK.

    Settings for the File Validation job

  7. Click Save. The solution creates the job with a status of New.
  8. Click Submit to run the job.

    The job status changes to Waiting. When the File Validation Manager agent begins running the job, its status changes to In Progress. The agent runs the jobs based on the order used to submit them.

    After the job is complete, its status changes to New. The Messages section displays the date and time when the job completed.

    The Messages section of the job page indicates when a job completed.

Canceling a job

To cancel a File Validation job after submitting it, click Cancel in the console. The job stops after the agent finishes validating the current set of document files. The job status changes to New. Additionally, the Messages section displays the date and time when the job was canceled.


The Messages section of the job page indicates when a job was cancelled.

Viewing the results

While executing a job, the File Validation Worker agent validates document files in batches of 1,000. It validates files only for those documents where the missing files indicator field is Null. If a document’s files don't exist on the file server, the agent sets the missing file indicator field Yes. If all of a document’s files exist on the file server, the agent sets the missing file indicator field to No. You refer to the values in the missing file indicator field to determine which documents are missing files.

In addition to populating the missing files indicator field, a File Validation job generates a missing files report. The report contains a detailed list of files that weren't found on the file server. When you subsequently run a File Validation job, the agent clears and repopulates the missing files report with the results from that run.

Complete the following steps to view the missing files report:

  1. In a workspace, click the Case Admin > Scripts tabs.
  2. Click the name of the View Missing Case Files script.
  3. Click Run Script. The script page displays the report.

    A Missing Case Files report that displays a list of detailed information about each document that is missing files and which files are missing.

The following table describes the columns in the report.

Column Description
File Validated On The date and time when the agent validated the document files.
Document Identifier The identifier of the document with one or more missing files.
Document Identifier ID The artifact ID of the document with one or more missing files.
File Path The path to the file that is missing from the file server.
File Type The type of file that is missing from the file server. For example, the file types include Native, Image, Production Image, or Transcript.

Handling errors

If errors occur after you submit a File Validation job, its status changes to Error. The Messages section displays the errors that occurred. To rerun the job, click Retry/Resolve Errors in the console.