Build your first agent

This tutorial illustrates how to create a simple agent that raises the message: Hello World! The current time is: <time>. It describes how to write the source code for this agent by completing these tasks:

  • Adding references to your Visual Studio project.
  • Inheriting from the agent base class.
  • Overriding the Execute() method with your business logic and performing other key development tasks.
  • Adding the compiled .dll files for the agent to Relativity and view the messages that the agent raises.

This page contains the following information:

Before you begin

Complete the following tasks to before you begin implementing an agent:

  • Set up your development environment. This tutorial uses Visual Studio to illustrate development tasks.
  • Install the Relativity Visual Studio templates. For more information, see Visual Studio templates for Relativity.
  • Obtain access to an instance of Relativity used for development purposes. In Relativity, confirm that you have the appropriate system admin permissions. For more information, see Security and Permissions on the Relativity Documentation site.

Build an agent

Follow these steps to build a simple agent in Visual Studio:

  1. Open Visual Studio.
  2. Click File > New > Project.
  3. In the New Project dialog, expand Relativity and select Agent.
  4. Enter BasicSampleAgent in the Name field and click OK.

    5. (Click to expand)

    New Project dialog

  5. To view the references in the project, right-click on References in the Solution Explorer. The references are added to the project as part of the template.

    6. (Click to expand)

    References

  6. In the Solution Explorer, right-click on the Relativity Agent.cs file. This file displays the template code for an agent.
  7. Update the kCura.Agent.CustomAttributes.Name to Basic Sample Agent. The class attribute which determines the name of the agent displayed in Relativity.

    8. (Click to expand)

    Attributes

    Review the additional features of this code:

    • The GUID attribute added above the class name in the code.
    • The class is derived from the AgentBase class.
  8. Override the Name property and enter Basic Sample Agent as the name that you want returned for the agent. Only the WinForm debugging tool uses this property to identify the agent.

    9. code for overriding Name property

  9. Update the time message in the Execute() method. You must override the Execute() method inherited from the base class. The current method raises the message: Hello World! The time is: <time>. In the Relativity UI, you set an interval that specifies when this method is called. See step 22.

    10. (Click to expand)

    Execute() method

  10. On the Build tab for your project properties, ensure that you select Active (x64) in the Platform field. Relativity libraries require this setting.

    11. (Click to expand)

    Build tab

  11. To compile your agent source code, click Build > Build Solution. After your agent assembly builds successfully, you can upload it to Relativity.

    (Click to expand)

    Build Solution menu option

  12. Open the Relativity instance used for development.

    Note: You can create a new workspace or use an existing one when you deploy your agent.

  13. Search for the Resource Files tab at the instance level.
  14. Click New Resource File.
  15. In the Application field, click Select to choose Default as the application. This action links your agent assembly to the default application. In general, you link your assemblies to a custom application that you are developing.
  16. In the Resource File field, click Select File to choose the BasicSampleAgent.dll from the directory where you built the project.

    17. (Click to expand)

    Resource File Information

  17. Click Save. You now have a new agent type available for use as an agent in Relativity. To run the agent, you need to add it to an agent server.
  18. Search for the Agents tab at the instance level.
  19. Click the New Agent button.
  20. In the Agent Type field, click Select to choose the Basic Sample Agent that you created.
  21. In the Agent Server field, click Select to choose the agent server. Your agent runs on this server.
  22. Set the Run Interval to 5.
  23. Click Log All Messages to view all messages that the agent raises in Relativity. Click Save.

    (Click to expand)

    dialog to add new agent

    Because you created your agent in Relativity, the agent server detects that you have assigned a new agent to it. It loads the necessary assemblies required to trigger the Execute() method on your agent.

  24. To view your agent execution, click the Agents tab and locate your new agent.

    25. Hello World! The current time is: <time>

    (Click to expand)

    Agent message