File validation agent

Note: 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:

  • Checks existence on a file share of all files linked to documents in RelativityOne. This includes Data Grid.
  • 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.

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 use this report to determine which files to restore on the file server.

Supported versions

This solution is supported in the following versions, as well as previous versions that no longer receive technical support:

  • RelativityOne (use latest version)
  • Server 2024 (use version 24000.0.0)
  • Server 2023 (use version 10.2.7)
  • Server 2022 (use version 10.0.1)

You can find all versions of this solution on the Community via this File Validation Agent search string. You must be logged in to the Community for that string to return results.

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 Customer Support.

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.
  • The File Validation Agent verifies Data Grid files when the script is run.

Deploying and configuring the solution

To deploy and configure the solution, download it from Relativity Community and add it to the Application Library as a Relativity application. These agents monitor and perform the file validation tasks.

Downloading the application

Complete the following steps to download the solution:

  1. Log in to the Community and click this File Validation Agent search string.

  2. Select the version that is compatible with your Relativity instance.

    Note: The solutions in the Relativity Applications folder are sorted from most recently modified to oldest. As a result, solutions at the top of the page are normally the newest versions of the respective solutions. If you see more than one version of the solution, select the .rap file with the higher version number to ensure you're deploying the most up-to-date solution.

  3. Click Download.

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 .rap file.
  8. Click Open.
  9. Click Save.

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