Agents

Agents are process managers and workers that run in the background of Relativity to complete jobs that you or another user scheduled in your environment. Different agents exist for each type of job. To run a job, you must have the agent for that job type installed in the resource pool to which your workspace is assigned. For example, you must have at least one Branding Manager agent and one Production Manager agent to run a production in Relativity.

Relativity agents are installed to your agent server during the Relativity installation process. You can have multiple agent servers in your Relativity environment, but one server generally functions as your primary agent server, which stores a full set of agents, and possibly an additional agents that support multiple installation. Depending on the agent type, you may add multiple instances of it to a secondary agent server.

In the Agents tab, you can manually add an agent type to a server to enable and/or improve the performance of a number of Relativity features.

Note: Relativity developers can also build custom agents to handle scheduled jobs. See the Build agents for more information.

This page contains the following information:

See these related pages:

Agent installation requirements

The installation requirements for Relativity agents include:

  • Installation drive - Relativity installs agents in the following directory by default: [Installation drive]:\Program Files\kCura Corporation\Relativity\Agents\Processing.
  • Total agents per server - a default Relativity installation includes a set of core feature agents. You can install additional agents on a Relativity server but the total number of additional agents shouldn't exceed the number of processor cores available on the server.

    Note: You need to ensure that each server has the required minimum number of processor cores. For minimum hardware requirements, see System requirements.

  • Agent instances - the recommended number of instances of each Relativity agent vary per feature and per environment setup. You should run at least one agent of each type in your environment. For a description of each agent and the recommended number of instances, see the List of agents.

Note: If you're working in a large environment and need agent use recommendations to manage a large database, contact Relativity Client Services.

List of agents

Relativity supports multiple agents to execute a variety of different processes. These agents can be divided into different categories based on the number of an agent type allowed per environment, the location where the agents run, and the number of type of resources that they require. The different categories of Relativity agents include:

Single agent per environment

For specific Relativity agent types, you are required to add one agent per environment. These agents execute during the off-hours that you configure for them to run. In addition, they require minimal resources so you run these agents on a virtual server that has four CPUs and four GB of RAM. If you don't meet these minimal requirements, your Relativity environment may experience a performance impact. These agents aren't specific to a resource pool and are available across your Relativity environment.

Note: If you add more than one of the agents in the following list, your Relativity application may not work properly or key components may not function properly. If you delete any of these agents, Relativity displays warning messages.

For the following agent types, Relativity requires a single agent per environment:

Description

Responsible for sending daily ARM Adoption / Job Usage metrics to NewRelic.
Description

Oversees the Assisted Review primary job and project deletion. For more information, see Assisted Review .
Description This agent is deprecated and should not be added to any environment.
Description

Marks files as Dirty and adds the entries to a deletion queue, regardless of the cache clean up logic used. Deleted files include outdated temporary native, image, and production files used by the viewer from the ConvertedCacheFile table. The Dirty flag indicates that a cache entry isn’t valid.

The Cache Manager uses this workflow to clear the cache:

  1. Starts running on all cache locations in your environment during off hours, and continues until complete.

    Note: Off hours refers to time not during the standard working day. We recommend setting certain agents to run during off hours due to performance considerations. See AgentOffHourStartTime and AgentOffHourEndTime.

  2. Deletes the files with the oldest last used date from the cache if the disk space usage on the cache location exceeds the CacheLocationUpperThreshold instance setting.
  3. Deletes as many files as required to reduce the disk space usage on cache location to less than or equal to the lower limit defined in the CacheLocationLowerThreshold instance setting. (Additional instance settings that influence agent behavior include FileDeletionManagerBatchAmount and CacheManagerFileDeletionRetry.)
  4. When files can't be deleted from the cache reducing the disk space usage to the lower threshold, the agent logs an error and triggers the display of an alert in the Relativity UI. For general information, see Errors and Alerts.
  5. Sends an email notification to a specified recipient for each cache location that it failed to delete.

Beginning in Relativity 9.4.254.2, you can also choose to have the Cache Manager clear based on time rather than using drive usage threshold using the following workflow:

Note: The Cache Manager agent logic looks at the document's last accessed date time rather than the creation date time.

  1. Starts running on all cache locations in your environment during off hours, and continues until complete.

    Note: Off hours refers to time not during the standard working day. We recommend setting certain agents to run during off hours due to performance considerations. See AgentOffHourStartTime and AgentOffHourEndTime.

  2. Deletes all files older than the HoursToRetainConvertedDocuments instance setting in batches according the FileDeletionManagerBatchAmount.
  3. Sends an email notification to a specified recipient for each cache location that it failed to delete.
Description Responsible for cleaning up all files in the repository, as well as the actual workspace database, when you delete an entire workspace. Also deletes AuthenticationToken entries older than three (3) days. This agent runs during off-hours and doesn't use the DeleteFile queue.
Description

Collects usage metrics, as well as creates and send reports. The CaseStatisticsManager requires that the Case Manager has successfully completed processing.

Note: If the Case Statistics Manager is disabled for seven consecutive days, Relativity access becomes restricted.

See Case Statistics Manager for details on this agent.

Description Populates filters in the Data Grid for Audit application.
Maximum number One agent per environment
Agent type Reporter
Description The Data Grid Audit Reporter agent reviews the audit queue for errors that occurred during migration from SQL to Data Grid. This agent triggers a Relativity error based on the agent's run interval. This agent is set to an hourly run interval by default.
Description This agent is deprecated and should not be added to any environment.
Description A Data Grid Manager agent is an off-hours agent responsible for Data Grid enabled workspace management, including delete outdated search results cache tables and monitoring Data Grid index conditions.
Description Identifies all documents with extracted text stored in SQL for any workspace with the Data Grid Text Migration application installed.
Description Creates and coordinates tasks for jobs that act across multiple databases. This agent is currently used only for adding and removing users from groups.
Description Updates the document volume count in the ECA Dashboard.
Description Deletes files from Relativity repositories once they’re deleted from a workspace, using the DeleteFile queue on the EDDS database. This agent runs during off-hours.
Minimum number

Requires 1 per environment.

Maximum number Do not install more than 1 agent.
Description

The agent ensures that Imaging is functioning properly. This includes tasks such as cleaning up stuck imaging jobs and deleting Imaging Warnings that are no longer linked to Documents.

The default interval is 3600 seconds. Do not modify the interval.

This agent was added in Relativity 9.7.229.5.
Minimum number

Requires 1 per environment.

Maximum number Do not install more than 1 agent.
Description The agent responsible for configuring the necessary artifacts for a newly created PDF job and also batching larger PDF jobs into smaller units in the mass PDF operations. This agent runs every 5 seconds by default, and should not be modified. If the Australian workflow is enabled in the instance, the PDF manager can also delete PDFs stored in Relativity.
Description Reserved for future use.
Description Updates Relativity with version and job status information from Analytics servers and worker manager servers.
Description Transmits metric data from the EDDSMetrics.Metrics table to Relativity. Maintains the Metrics table after transmitting the data.
Description

Looks for workspaces that are pending application upgrade and delegates work to the application installation manager agent, if necessary.

Definitive number of agents per resource pool

For specific Relativity agent types, you are required to add one agent per resource pool. These agent types are grouped into the following categories:

  • Job coordinators - these agent coordinate work that other processes perform. You can add multiple worker agents to a resource pool but usually only one job coordinator agent.
  • Worker-managers - these agents manage the worker agents. You only add one manager agent to each resource pool on a server. Your server doesn't require any dedicated resources for them, since manager and worker agents don't run in performance-intensive operations at the same time.

Note: You must include one of agents in the following table per resource pool. If a resource pool doesn't include one of these agents, key Relativity components may not function properly. You may not receive an error message if the resource pool doesn't include each of these agents.

For the following agent types, Relativity requires one of these agents per resource pool:

Maximum number One per resource pool.
Agent type Worker-manager
Description Responsible for performing Active Learning tasks such as managing the Classification Index population and Index builds, Review Queues and updating the Review Statistics in the Active Learning Project.
Maximum number Add up to four agents per resource pool.
Agent type Job coordinator
Description Clears any previous job results from the population table, and then it categorizes the specific group of documents in the categorization set.
Maximum number One agent per resource pool.
Agent type Worker-manager
Description Orchestrates the process of moving Analytics data using ARM. The corresponding worker is Analytics Core ARM Worker.
Maximum number One agent per Analytics server per resource pool.
Agent type Job coordinator
Description Enables and facilitates automation of the Analytics index building process from population to activation.
Maximum number One agent per resource pool.
Agent type Job coordinator
Description Runs existing batch jobs marked as auto-batch in pre-configured intervals.
Maximum number One agent per resource pool.
Agent type Job coordinator
Description Clusters documents based on the Analytics index settings.
Maximum number One agent per Analytics server per resource pool.

Note: If your environment includes more than one Analytics server, then you would need additional Relativity Analytics Index Manager agents.
Agent type Job coordinator
Description Populates Analytics indexes and pushes them to the Analytics server.
Maximum number Only one agent per resource pool.
Agent type Worker-manager
Description Creates population tables and manages the indexing queue (i.e., it checks to see if workers have completed their work). During incremental build, it also does the work to balance the population tables and manages the status updates on sub-index tables.
Minimum number One agent per resource pool
Description

Responsible for monitoring Integration Points jobs to see if they are in good health, as well as performing maintenance tasks such as purging data from deleted jobs. This agent is optional, meaning you don't need it to execute an Integration Points job, but it is recommended.

This agent was added in Relativity 9.5.253.62.
Minimum number At least one agent per resource pool. We recommend having one OCR Set Manager agent per agent server in the resource pool.
Agent type Worker-manager
Description Converts the options configured in an OCR set into individual jobs (by building tables, inserting records, and handling SQL queries), and then compiles output from the OCR Worker into a single result set for the user. It also recovers orphaned OCR jobs from dead agent servers.
Minimum number One agent per resource pool.
Agent type Job coordinator
Description Manages the running of processing archive jobs in ARM.
Maximum number We recommend at least one agent per resource pool.
Agent type Worker-manager
Description Creates production numbers and applies them to productions. This is also responsible for creating branding jobs and populating the branding queue. The Branding Manager agent is the corresponding worker.
Maximum number One agent per resource pool.
Agent type Job coordinator
Description Runs a search against an existing dtSearch index, and returns a count of matching terms found in this index.
Maximum number One agent per resource pool.
Agent type Job coordinator
Description Oversees the Structured Analytics Worker agents by keeping the structured data analytics primary job up-to-date and creating worker jobs. For more information, see Analytics servers.
Maximum number One agent per resource pool.
Description Extracts the text from files associated with dynamic objects, and adds it to text fields on the file fields of the dynamic objects. When you create a File field for a custom object, an accompanying Long Text field is also created. When you upload a file to that file field, the Text Extraction Manager reads the text from that file's name and writes it into the long text field.
Maximum number One agent per resource pool.
Description Updates or adds headers and footers to a valid transcript.
Maximum number One agent per resource pool.
Description Runs transform jobs for domain parsing and conversation indexes by parsing regular expressions, and outputs these results to a Dynamic Object that has a destination field with a relation on the document object type.

Scalable agents

Relativity includes agents that you can scale to the appropriate number for your environment needs. You can add any number of these agents, but you must include at least one per resource pool. Depending on your environment, you may need more than one agent. For example, you may need several worker agents to handle very large documents or Data Grid jobs. You can run these agents on a server with one CPU core per agent, and 1 GB of RAM. You may want to double these memory requirements to accommodate heavy workloads in your Relativity environment.

For the following agent types, Relativity requires at least one agent per resource, but you also have the option of adding multiple agents depending on your current needs:

Minimum number At least one agent per resource pool. We recommend one agent for every 15 - 20 active reviewers in your resource pool.
Agent type Job coordinator
Description Responsible for managing the documents in the review queues in Active Learning projects.
Minimum number Requires at least 1 agent
Maximum number Add up to 4 agents per resource pool
Description Responsible for moving Analytics conceptual and classification indexes using ARM.
Minimum number Requires at least 1 agent
Description Detects applications that need to be installed or upgraded in a workspace. For more information, see Upgrading workspaces.
Minimum number Requires at least 1 agent.
Description Performs ARM backup, restore and move job functions.
Minimum number Requires at least 1 agent
Description Facilitates Assisted Review project creation, sample set creation, document review, overturns, saving project results, report generation, and error recovery. For more information, see Assisted Review .
Minimum number May require more than 1 agent
Description Creates production images and applies endorsements.
Minimum number Requires at least one agent
Maximum number Add up to two agents per instance
Description

Writes to cache documents converted by the Conversion Agent and notifies the Relativity front end when conversion jobs are ready. This agent is created after a new Relativity installation. Upon upgrade, you must created the agent manually. We do not recommend putting this agent on the Conversion Agent server, as that server should be dedicated to the Conversion Agent, not the Conversion Complete Agent.

Note: This Agent is not resource pool aware.
Maximum number Any number of agents per resource pool.
Agent type Worker-manager
Description Off-hour agent that deletes all audits from SQL that have been successfully migrated to Data Grid. The agent will only delete audits in SQL older than the PostMigrationPersistencePeriod Instance setting value in days.
Maximum number Any number of agents per resource pool. However, an excessive number of these agents may cause functionality issues with Data Grid.
Agent type Worker-manager
Description Migrates audit data from SQL to Data Grid for any workspace that has Data Grid for Audit installed. The frequency with which this agent checks for migrations and runs the migrations is controlled with the agent run interval value. Do not run the Data Grid Audit Deleter agent at the same time as the Data Grid Audit Migrator agent, as migration and deletion can conflict.
Minimum number Requires at least 1 agent. If you have a multi-workspace text migration, you can add a worker agent for each workspace being migrated. Adding multiple agents for a single-workspace text migration does not make the migration run any faster.
Description Migrates extracted text from SQL to Data Grid for any workspace with the Data Grid Text Migration application installed.
Minimum number Requires a minimum of 1 agent per environment.
Description Execute tasks created for jobs that act across multiple databases. This agents is currently used only for adding and removing users from groups.
Minimum number May require more than 1 agent. You can add multiple agents as necessary. The maximum is four agents per server. We recommend using 1 core and 2 GB of RAM for each additional agent.
Description Performs the indexing operation for each sub-index. Additionally, workers are responsible for compression and copying steps at the end of the indexing. During incremental build, the workers are responsible for removing documents that are no longer in the saved search.
Minimum number

1 agent thread per 8 Imaging Worker threads. You can add multiple agents as necessary.

By default, the thread count for the agent is 2 threads per Processor Count of the server on which the agent is running. You can change the default agent thread count on the MaxImagingResponseThreads instance setting in Relativity.Imaging section. Since we support adding multiple instances of this agent, modifying that instance setting is not required.

Description

Picks up imaging set, mass imaging and image-on-the-fly messages from Service Bus (as published by Workers) and directs them to the proper finalization logic in Relativity.

This agent was added in Relativity 9.5.370.136.
Minimum number At least 1 per environment. You can add multiple agents as necessary.
Description

Handles all submissions of Imaging Set, Mass Imaging, and Image on the Fly requests. It picks up a message from Service Bus, and based on the type of Imaging Job will execute the appropriate logic and submit the Documents to Invariant.

This agent was added in Relativity 9.5.342.116.
Minimum number May require more than 1 agent. The number of workers to one manager depends on how large the data set is, what any relevant batch sizes are, and whether a bottleneck occurs when you add more workers. We recommend managing any manager:worker relationship using these considerations.
Description Takes an OCR job created by the OCR Set Manager, and translates the images into text.

Minimum

number

 Multiple agents per environment. We recommend starting with 2 and adding more agents as needed.
Agent type Job coordinator
Description Manages the running of processing sets by handling the SQL queries involved in the job; retrieves errors encountered while sets are running; picks up processing set deletion jobs and submits them to the worker manager server. For more information, see Installing and configuring Processing.
Minimum number

Requires at least 1 agent. However, you can also scale this agent as necessary. The maximum number allowed per instance is 4.

Relativity Integration Points agents operate on a single agent per job basis. If you have 4 agents enabled and only 1 job running in your workspace, only 1 agent will be performing work while the other 3 agents will be idle until additional jobs are started. Likewise, if you have 4 agents enabled and 3 jobs running, 3 agents will be doing work - 1 for each job - and 1 will be idle waiting for an additional job to start.
Description

Responsible for batching up data from the source provider and pulling it into Relativity fields. Also responsible for stopping an integration points job when the user clicks Stop on the console.
Minimum number Requires at least 1 agent. However, you can also scale this agent as necessary.
Description Sends emails (including reminder and escalation), pulls emails in from custodian responses, and purges custodians from a project.
Minimum number May require more than 1 agent
Description Performs all structured data analytics tasks, including setting up staging, exporting document information from Relativity, monitoring the Analytics Engine, importing document information into Relativity, and creating reports. For more information, see Analytics servers.
Minimum number Requires at least 1 agent
Description

Runs the script required to update the workspace databases and Invariant stores. On an SQL Server profile, you can edit the Workspace Upgrade Limit field, which controls the number of agents accessing the server during an upgrade. The setting entered in this field can’t exceed the setting in the GlobalWorkspaceUpgradeLimit instance setting value. If you enter a number that exceeds this instance setting value, an error occurs that cancels your update. For more information, see Instance settings' descriptions and Upgrading workspaces.

Web agents

For specific Relativity agent types, you are required to add one agent per web server. If you add more than one of the agents in the following list, your Relativity application may not work properly.

If you experience the following issues, verify that these agents are running in your installation:

  • Custom pages aren't working properly - verify that the Custom Page Deployment Manager is running.
  • Poor application performance - verify that the Platform Status agent is running.

For the following agent types, Relativity requires one agents per web server:

Description Polls the LibraryApplication and ApplicationServer tables in the EDDS database according to a configurable time interval to check for new versions of any application installed in the ApplicationLibrary table.If a new version is discovered, the Custom Page Deployment Manager runs and installs the updated version of the application's custom pages on that web server. The Application Server table in the EDDS database is then updated to reflect the new version number. This agent is installed on the kCura Web Processing Windows Service, which runs on each web server in your Relativity installation.
Description Enables the diagnostics of the Relativity Services API. The results of the diagnostic tests run by the agent are displayed on the Platform Status tab.

Isolated scalable agents

Relativity includes isolated scalable agents which you can customize for your environment needs. This type of agent needs to be on its own agent server with no other Relativity agents on the server. These agents are multi-threaded and will use all resources on the server when needed. Depending on your environment, you may wish to scale the server up for better performance. Monitor both CPU and RAM during normal usage as well as during jobs. If needed, add more CPU and RAM to the server. You may also add another server with another agent by itself. You can add any number of these agents, but you must include at least one per resource pool.

Description Works with the service bus to complete document conversion for the document viewer. Deploy each Conversion agent on its own server. Don't use the server for any other purpose but running this agent.
Description Works with the service bus to complete document conversion when the user is on the document viewer. Deploy each Conversion agent on its own server. Don't use the server for any other purpose but running this agent.
Description Works with the service bus to complete document conversion when using the mass convert action. Deploy each Conversion agent on its own server. Don't use the server for any other purpose but running this agent.
Description Works with the service bus to complete document conversion for the current document opening. Deploy each Conversion agent – On the fly on its own server. Don't use the server for any other purpose but running this agent.
Minimum number description

Requires at least 1 agent per resource pool. The agent must be on its own server with no other Relativity agents. The server should not be used for any other role (i.e. Web, Analytics, etc.). Hosts the search service and executes search requests that users submit. This agent is multi-threaded and will use all resources on the server when needed. Follow these guidelines for this agent:

  • Monitor CPU, RAM, and disk I/O during normal usage and during Search Terms Report jobs.
  • Disk I/O on the dtSearch Index Share may also become a bottleneck – monitor and configure as needed.
  • If performance issues occur, add more server resources.
  • You may also add another agent server with only the dtSearch Search agent. However, it is often preferred to scale up rather than out.

Minimum

number

 Requires 2 agents per environment. However, you may add more agents as needed.
Description Responsible for the document/image to PDF conversion. It will also do the packaging of results into a ZIP/Portfolio/Single PDF if Download is selected for mass PDF operations. This agent runs every 5 seconds by default and should not be modified.

Agents change log

This change log summarizes changes made to agents.

Agent name Change Description of change Version
Agent name Change Description of change Version
Analytics Core ARM Manager Added Orchestrates the process of moving Analytics data using ARM. The corresponding worker is Analytics Core ARM Worker. Server 2021
Analytics Core ARM Worker Added Responsible for moving Analytics conceptual and classification indexes using ARM. Server 2021
PDF Manager Agent Added Responsible for configuring the necessary artifacts for a newly created PDF job and also batching larger PDF jobs into smaller units in the mass PDF operations. This agent runs every 5 seconds by default, and should not be modified. If the Australian workflow is enabled in the instance, the PDF manager can also delete PDFs stored in Relativity. Server 2021
PDF Worker Agent Added Responsible for the document/image to PDF conversion. It will also do the packaging of results into a ZIP/Portfolio/Single PDF if Download is selected for mass PDF operations. This agent runs every 5 seconds by default and should not be modified. Server 2021
Active Learning Synchronization Manager Removed This agent was removed in Relativity 10.0.318.5. 10.0.318.5
Imaging Manager Added The agent immediately restarts itself if something fails. Should have its interval set to 60 minutes. 9.7.229.5
Distributed Job Manager Modified This agent now creates and coordinates tasks for jobs that act across multiple databases. This agent is currently used only for adding and removing users from groups. 9.6.50.31
Distributed Job Worker Modified This agent now executes tasks created for jobs that act across multiple databases. This agents is currently used only for adding and removing users from groups. 9.6.50.31
Active Learning Manager Added Responsible for managing the documents in the review queues in Active Learning Projects. 9.6.50.31
Active Learning Synchronization Manager Added Manages the reporting statistics for Active Learning Projects. 9.6.50.31
Imaging Request Agent Added Responsible for performing background tasks when any imaging request is submitted via mass imaging, image on the fly, or imaging set. 9.5.342.116
Distributed Job Manager Added Reserved for future development purposes. 9.5.342.116
Distributed Job Worker Added Reserved for future development purposes. 9.5.342.116
Secret Agent Added The agent is reserved for future use. 9.5.342.116
Analytics Categorization Manager Modified Renamed to Relativity Analytics Categorization Manager. 9.5.69.85
Analytics Index Progress Manager Modified Renamed to Relativity Analytics Index Progress Manager. 9.5.69.85
Content Analyst Cluster Manager Modified Renamed to Relativity Analytics Cluster Manager. 9.5.69.85
Content Analyst Index Manager Modified Renamed to Relativity Analytics Index Manager. 9.5.69.85
Data Grid Worker Modified Lockout period duration is now 1 minute instead of 15 minutes. 9.5.69.85
Integration Points Manager Added Monitors Integration Points jobs to see if they are in good health, as well as perform some maintenance tasks, such as purging data from deleted jobs. 9.5.253.62