Basic concepts for agents

Review these basic concepts to learn more about implementing agents, uploading them to Relativity, logging events, and other agent functionality.

Common implementation tasks for agents

Complete these common implementation tasks when developing custom agents. You can also use a template to create an agent. For more information, see Visual Studio templates for Relativity.

  • Add NuGet packages - ensure your Visual Studio project has installed the relevant NuGet packages, including at a minimum the Relativity.EventHandler, Relativity.Api, and Relativity.Agent packages.
  • Inherit from the kCura.Agent.AgentBase class – ensure that your agent extends this base class.
  • Set the CustomAttribute.Name attribute – specify a name for the agent that you want displayed in the Relativity UI.
  • Add a GUID for the agent – add a unique GUID to identify the agent by setting the System.Runtime.InteropServices.Guid to a unique GUID identifying your new agent type. To ensure the value is unique you may use the GUID generator in Visual Studio.
  • Override the Execute() method – use the override modifier in your method signature, and add your custom code to this method. This method is triggered on the regularly scheduled interval set up in the Relativity UI. This method doesn't return a response.
  • Override the Name property – use the override modifier in your property declaration. Specify the value that you want displayed through the Winform debugging application. This name appears when running the agent from the kCura manager executable and when raising and logging messages from the agent in the Event viewer.

Establish a database connection from an agent

Use Relativity API Helpers to interact with a database through the IDBContext interface. You can access methods on this interface by adding a reference to the Relativity.API.dll when you create new agent classes. In Visual Studio, you can easily reference these methods through IntelliSense.

Connect to the Services API with the client-side proxy

You can log in to the Services API by with the client-side proxy and authenticate with the System account. Review the following guidelines:

  • Use the methods on IEHHelper class in the Relativity API Helpers to return a connection to the Services API.
  • Use System on the ExecutionIdentity enumeration when logging in with an agent.
  • Reference the Relativity.API.dll when you create new agent classes.

The following code sample illustrates how to log in to the Services API using System account and the Relativity API helper class.

Copy
using (IObjectManager objectManager = Helper.GetServicesManager().CreateProxy<IObjectManager>(ExecutionIdentity.System))
{
  // Proxy created.
  // Add your custom code for working with the ObjectManager.
}

Upload agents to Relativity

If you develop a custom agent, you can add it to a RelativityOne instance by uploading the assembly as a Resource File. An instance of the agent will be added automatically when the file is uploaded. For more information, see Resource files on the RelativityOne Documentation site.

Note: If you remove an agent type from an assembly and upload the updated assembly to Relativity, that agent will be deleted from your environment. For more information, see Remove agents from Relativity.

Add an assembly containing an agent

Use the following steps to upload your custom agent:

  1. Open Relativity.
  2. Select the Resource Files tab. For more information, see Resource files on the RelativityOne Documentation site.
  3. Click New Resource File to upload a file.
  4. Click Choose File in the Resource File field, and select the .dll file that contains your agent code.
  5. Click ellipsis button in the Application field and select the application that you want associated with .dll file.

    Note: Ensure that you select the application that you want associated with the agent when uploading it as a resource file. Don't select the default application if you want to use the agent in your custom application.

  6. Click OK and then click Save.

Note: The details view of the application in a workspace no longer lists an "Agent Type" section.

Remove agents from Relativity

Complete the following workflows to remove an agent after it has been added to a Relativity environment.

Note: Removing agents via the Agents tab is no longer supported. You must remove the reference to the agent within its Resource File.

Remove one agent from an application

Use the following steps to remove one agent from an application by creating a version of your application without the agent in your development environment or Next Gen Sandbox.

  1. Delete the agent code from your project in Visual Studio.
  2. If applicable, remove the agent's Workload Discovery Kepler API endpoint.
  3. Build the application's assemblies.
  4. Replace the existing Resource Files with the newer version of the assemblies.
  5. Export this newer version of the application without the agent.
  6. Upgrade any environments that have the older version to remove the agent.

If this is the last agent in the application, first remove the agent class from the project and build it. Upload the newer Resource File that contains no agent, wait 5 minutes for the existing agent to be removed. The Resource File can now be deleted and the agent project can be removed from the solution in Visual Studio.

Remove an entire application that contains agents

To remove the agent from the environment, the Resource File that contains it must be removed. Deleting the application from the Application Library does not remove the Resource Files. To uninstall the application entirely (including removal of the Resource Files and their agents) please contact our Support team through our Support page, please include the application name and GUID in your request.

Agent runs

By default, agents run at a one hour time interval. The agent's interval can be customized to fit the needs of the agent, or can be triggered to run on demand. See Execution patterns for agents for more details.

Logging for agent events

You can capture information about unexpected behavior that occurs when agents are running jobs in Relativity. When you create a custom agent, your new class must inherit from the AgentBase class. The following table lists methods on this class for capturing information about agent behavior. The event type indicates the information logged in the Event Viewer.

Method Logging level Event type
RaiseError() 1 Error
RaiseMessage() Level passed into the method Information
RaiseWarning() 1 Warning

Note: You can also log from agents using the IAPILog interface in the Relativity API Helpers. The interface provides Error, Information, Warning, Verbose, and Debug-level logging. For more information, see Log from a Relativity application and Basic concepts for Relativity API Helpers.

Logging levels

The integer values for logging levels can be set programmatically through the application.xml file. The logging level controls only the message types that the system logs in the Event Viewer.

Logging level Integer equivalent
Log critical errors only Log level <= 1
Log warnings and errors Log level <= 5
Log all messages Log level <= 10

Currently, errors and warnings are raised as level 1, so they are always logged. If you want to implement an agent that raises only messages as opposed to errors and warning, then you need pass the logging level of 10 as a parameter to the RaiseMessage() method. For example, implement this code as RaiseMessage(“MESSAGE”, 10). For more information, see Agents on the RelativityOne Documentation site.