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
• Build an agent

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. See Set up your development environment.

  Note: You can also use a template to create an agent. For more information, see Visual Studio templates for Relativity.

• Ensure that you have the Relativity SDK installed. See Install the Relativity SDK.
• 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. Create a new Class Library project called Relativity.BasicSamples.

   

3. In the Solution Explorer, right-click on the Relativity.BasicSamples project.
4. Click Add > New Item.
5. Create a new class in the project called BasicAgent.

   

6. To add references to the project, right-click on References in the Solution Explorer.
7. Click Add Reference. You need to add references to the .dll files that contain the Relativity classes and interfaces used to build your agent.

   

8. Click Browse and select kCura.Agent.dll in your SDK installation directory. If you used the default installation path, you can find the .dll file in this folder:

   ...\Program Files\kCura Corporation\Relativity SDK\Agents\Client

9. Click Browse and select Relativity.API.dll in your SDK installation directory. If you used the default installation path, you can find the .dll file in this folder:

   ...\Program Files\kCura Corporation\Relativity SDK\Relativity API\Lib

10. Click Browse and select kCura.Relativity.Client.dll in your SDK installation directory. If you used the default installation path, you can find the .dll file in this folder:

    ...\Program Files\kCura Corporation\Relativity SDK\Services API\Client

11. In the BasicAgent class, add the code to inherit from the kCura.Agent.AgentBase class.

    

12. Right-click on kCura.Agent.AgentBase, and select Implement Abstract Class from the menu.

    

13. Override the Name property and enter the name that you want returned for the agent. Only the WinForm debugging tool uses this property to identify the agent.

    

14. Add the following code to implement 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 28.

    

15. Add a class attribute which determines the name of the agent displayed in Relativity.

    

16. To create a GUID for the agent, click Tools > Create GUID.

    

17. Select the 5. [Guid("xxxxxxx-xxxx...xxxx")], and then click Copy.

    

18. Paste the new GUID attribute above the class name in the code. You may need to type the System.Runtime.InteropServices namespace in your code, and than paste in the GUID.

    

    Your code for this simple agent should be similar to the following sample. However, the GUID for the agent is unique because you generated through the Create GUID tool.

    using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.Text;
    using System.Threading.Tasks;
    
    namespace Relativity.BasicSamples
    {
          [kCura.Agent.CustomAttributes.Name("Basic Sample Agent")]
          [System.Runtime.InteropServices.Guid("41537AF5-0771-4320-84CE-930AC4C917AC")]
          class BasicAgent : kCura.Agent.AgentBase
          {
                public override void Execute()
                {
                      String currentTimeStr = DateTime.Now.ToLongTimeString();
                      RaiseMessage("Hello World! The current time is: " + currentTimeStr, 1);
                }
    
                public override string Name
                {
                      get
                      {
                            return "Basic Agent Sample";
                      }
                }
          }
    }

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

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

    

20. Open the Relativity instance used for development.

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

21. Navigate to the Resource File tab, and click New Resource File.
22. In the Resource File field, click Choose File to navigate to select Relativity.BasicSamples.dll from the directory where you built the project.
23. In the Application field, click to select 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.

    

24. 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.
25. Click the Agents tab, and then click the New Agent button.
26. In the Agent Type field, click to select the Basic Sample Agent that you created.
27. In the Agent Server field, click to select the agent server. Your agent runs on this server.
28. Set the Run Interval to 5.
29. Click Log All Messages to view all messages that the agent raises in Relativity.

    

    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.

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

Hello World! The current time is: <time>