Managing agents in Relativity

You may need to monitor, edit, or disable agents for troubleshooting or to meet your environment's changing needs. Use the following best practices when working with agents:

• Perform agent modifications while agents are idle to minimize any potential issues.
• Only one person should be building, modifying, or interacting with any particular agent at a time.
• Understand how agent actions are handled by the Agent Manager Windows Service. See Agent Manager service.

If you're working with agents in a very large Relativity workspace, contact Relativity Support.

Agent Manager service

When you add a new agent from the Relativity interface, the agent is immediately created on the server. Agent information is stored in the EDDS database, and the Agent Manager Windows Service manages the agents on your server.

When you modify agents from the Agents tab in the Relativity interface, values are updated in the database. The Agent Manager service reads this information from the database every five seconds. If agents have been created, updated, or deleted during the previous five seconds, the Agent Manager Windows Service retrieves this information from the database and makes the changes to the agents on your server.

The following sections describe how agent actions are handled by the Agent Manager Windows Service.

Agent edits

Agent edits are as follows:

• Agent Server - if an agent is moved to another server in the database, the agent will finish the job that it's currently working on before the change takes effect.
  • For example, if you move the agent from Server A to Server B, the Agent Manager service running on Server A checks to see whether the agent is executing any jobs. If the agent is currently executing a job, then it's not moved from Server A. The Agent Manager service will continue to check the agent at five-second intervals, and if the agent is finished executing its job, then it's removed from Server A and placed on Server B.
• Run interval- when you modify an agent’s interval, the interval is updated immediately on the server. Any time elapsed from the previous interval is applied toward the new interval. For example, if four minutes have elapsed on a five-minute interval, and you increase the interval to 10 minutes, then the agent will run again in six minutes.
• Logging level-when you change an agent’s logging level, it's updated immediately on the server.
• Enabled status -if an agent's Enabled status is changed to No, the agent will finish the job that it's currently working on before it is disabled.

Agent deletes

When the Agent Manager Windows Service runs, any agents marked for deletion are checked to see if they're executing a job. If an agent marked for deletion is executing a job, then it's not deleted. The Agent Manager service will continue to check the agent at five-second intervals, and when the agent is finished executing its job, it is deleted.

Pending updates

The Pending Action field on the agent item list indicates whether an agent is pending a change. The available statuses for this column include the following:

• Deleting - the agent will be deleted once the current job completes.
• Disabling - the agent will be disabled once the current job completes.
• Moving - the agent will be moved to the new server once the current job completes.
• Updating - the agent has been modified, but the change won't be made until the Agent Manager Windows Service runs again.

Mass agent operations

Using the mass operations menu, you can copy, edit, or delete multiple agents at once. See also Adding and editing agents.

Mass copy

To mass copy agents, complete the following steps:

1. From Home, select the Agents tab.
2. Select the agents you want to copy and select Copy from the drop-down menu.
3. Click Go. The new agent instances display in the Agents list, numbered incrementally.

   For example, if you copy the Branding Manager agent, Branding Manager (1) and Branding Manager (2) will display in your agents list.

If completing the mass copy operation would cause one or more agents to exceed their maximum agents per server value, then none of the selected agents will be copied and you'll receive an error message.

Mass edit

Using the Edit mass operation, you can make the same change(s) to multiple agents at once. The following settings can be edited using this operation:

• Run interval
• Logging level of event details
• Status

To change the agent server, you must edit the agent manually. See Editing or disabling agents for more information.

To edit multiple agents at once using the mass operation menu, complete the following steps.

1. From Home, select the Agents tab.
2. Select the agents to edit and choose Edit from the drop-down menu.
3. Click Go. The Edit Agents dialog displays.
4. Select the check box to the left of the component to be edited, and enter or select the corresponding new value. See Fields for details.
5. Click Save to apply the change and return to the Agents list.

Mass delete

To delete one or more agents using the mass operation menu, complete the following steps.

1. From Home, select the Agents tab.
2. Select the agents you want to delete and select Delete from the drop-down menu.
3. Click Go to flag the agents for delete from your environment.

Uploading an assembly containing agent types

You can upload an assembly that contains agent types to Relativity. See Resource files for steps to upload an assembly to Relativity.

When you upload an assembly that contains agent types, those agent types become available for selection when you create a new agent. When you click from the Agent Type field, any agent types contained in an assembly uploaded to Relativity will be accessible from the Select Agent Type dialog.

Consider the following when working with assemblies that contains agent types:

• The details view for each assembly displays the agent types (if any) associated with that assembly.
• If an agent type is contained in an assembly, and you deploy agents using that agent type in your environment, you must delete all agents of that type before you can delete the assembly.
• If you remove an agent type from an assembly and then re-upload that assembly to Relativity, the agent type will be deleted from your environment.

Viewing logged agent events

You can view logging information about Relativity agents in the Event Viewer on your primary or secondary agent server.

1. To open the Event Viewer in Windows, click the Start > Programs > Administrative Tools > Event Viewer.
2. In the Event Viewer, open Windows Logs > Application.

Separating mass conversion workloads with a dedicated Conversion Agent - Mass Convert

Relativity supports four conversion agent types, each of which listens to a specific queue priority:

Agent type	Queue priority	Job type handled
Conversion Agent	Priority 1 (on-the-fly) and Priority 2 (convert ahead)	Standard conversions: documents opened in the viewer and convert-ahead requests
Conversion Agent - Mass Convert	Priority 3 (mass convert)	Mass Convert mass operation jobs only
Conversion Agent - On the Fly	Priority 1	On-the-fly conversions only
Conversion Agent - Convert Ahead	Priority 2	Convert-ahead conversions only

• By default, a general Conversion Agent listens to all three priority queues (Priority 1, Priority 2, and Priority 3). This means that in an environment with only general Conversion Agents, those agents handle both standard viewer conversions and mass conversion jobs from the same queue, which can cause mass convert jobs to compete with reviewer-facing conversions for agent resources.
• When you deploy a Conversion Agent - Mass Convert, it listens exclusively to the Priority 3 (mass convert) queue. General Conversion Agents in the same environment continue to listen to Priority 1 and Priority 2 but stop picking up Priority 3 jobs when a dedicated Mass Convert agent is present in the resource pool. This separation allows you to run large-scale mass conversions without affecting the responsiveness of on-the-fly conversions for active reviewers.

Setting up a dedicated Conversion Agent - Mass Convert

Use the following steps to add a Conversion Agent - Mass Convert to an environment that already has general Conversion Agents, without disrupting ongoing standard conversions.

Before you begin, deploy the Conversion Agent - Mass Convert on its own dedicated agent server. Do not share the server with other conversion agents or other agent types. Conversion jobs are multi-threaded and one conversion agent may use all available processor cores on a server.

1. In Relativity, navigate to the Agents tab.
2. Click New Agent.
3. In the Agent Type field, select Conversion Agent - Mass Convert.
4. In the Agent Server field, select the dedicated agent server you have provisioned for this agent.
5. Assign the agent to the appropriate Resource Pool.
6. Click Save.

After you deploy the Conversion Agent - Mass Convert:

• Mass Convert jobs route exclusively to the Priority 3 queue and are handled only by the new dedicated agent.
• Your existing general Conversion Agents continue to handle Priority 1 (on-the-fly) and Priority 2 (convert ahead) jobs without interruption.
• No reconfiguration of existing general Conversion Agents is required.

How conversion queue priorities work

Relativity routes conversion jobs using a three-level priority queue on the Relativity Service Bus (RabbitMQ). The `conversions_rp<Resource Pool Artifact ID>` topic in RabbitMQ contains three subscriptions:

• ConversionAgent_Priority1 — On-the-fly conversions. These are triggered when a reviewer opens a document in the viewer. This queue has the highest priority.
• ConversionAgent_Priority2 — Convert-ahead conversions. These are background conversions that pre-convert nearby documents while a reviewer is active.
• ConversionAgent_Priority3 — Mass Convert conversions. These are batch jobs submitted through the Mass Convert mass operation.

A general Conversion Agent subscribes to all three queues and processes jobs from any of them. A Conversion Agent - Mass Convert subscribes only to Priority 3. Because the dedicated agent takes ownership of that subscription when present, general agents no longer process Priority 3 jobs, even if the Mass Convert agent is temporarily busy.

Verifying the configuration in RabbitMQ

After deploying the Conversion Agent - Mass Convert, confirm that the subscriptions are correctly established in RabbitMQ (or Service Bus Explorer if you are running Service Bus for Windows Server):

1. Open the RabbitMQ management portal.
2. Navigate to the Queues tab and locate the `conversions_rp<Resource Pool Artifact ID>` topic.
3. Verify the following subscriptions exist:
   • `ConversionAgent_Priority1`
   • `ConversionAgent_Priority2`
   • `ConversionAgent_Priority3`

Confirm that `ConversionAgent_Priority3` is associated with the Conversion Agent - Mass Convert agent server.

If any subscription is missing, delete and redeploy the affected conversion agent.