Lesson 5 - Build a cron job

Custom agents perform background processing within your application without interfering with user activities performed through the Relativity UI. You can implement agents as managers that monitor tasks or workers that perform specific jobs in your environment.

In this lesson, you will learn how to complete these tasks:

  • Create an agent that runs on a set time interval.
  • Debug an agent.
  • Add an agent to your Relativity instance.
  • Implement an agent for creating and updating documents using the Kepler Service constructed in Lesson 3 - Create a RESTful API.
  • Test your agent.

Estimated completion time - 1 hour

Note: This lesson describes all the steps necessary to build the agent but you can also download the completed code from WikipediaAgent.zip.


Step 1 - Create a basic agent

A cron job is the process of scheduling tasks to be executed at a future time. The agent framework in Relativity follows a similar approach when handling long running tasks.

Use the following steps to create an agent from a template:

  1. Open Visual Studio 2019.
  2. Open the HelloWikipedia solution created in Lesson 3 - Create a RESTful API.

  3. Create a new project in the HelloWikipedia solution and select the Relativity Agent template.

    (Click to expand)

    Relativity Agent template in Visual Studio

  4. Click Next to display the Configure your new project dialog.

    (Click to expand)

    Configure your new project

  5. Enter the following information:
    • Project name - WikipediaAgent
    • Location - This field is automatically populated with the solution path when you add a new project to the HelloWikipedia solution.
  6. Click Create.
  7. Verify that you have a C# project named WikipediaAgent.

    Solution Explorer

  8. Rename the following items to match the code samples.
    • File - rename Relativity Agent to WikipediaAgent.
    • Class name - rename Relativity_Agent to WikipediaAgent.
    • Class name attribute - When you created the agent from the template, the GUID was automatically generated.
      Copy
      namespace WikipediaAgent
      {
          [kCura.Agent.CustomAttributes.Name("Wikipedia Agent")]
          [System.Runtime.InteropServices.Guid("44ae8827-1c7f-422c-849d-197c1c0f5b68")]
          public class WikipediaAgent : AgentBase
    • Name property
      Copy
      public override string Name
      {
          get
          {
              return "Wikipedia Agent-";
          }
      }
  9. Add the following code to update the Execute() method to display the message Hello World, and current date and time.
  10. In the Visual Studio menu, click Build > Build Solution.

Step 2 - Upload the agent to an application

Use the following steps to upload the agent to a Relativity application:

  1. Log in your Relativity instance.
  2. Navigate to the Resource File tab.
  3. Click New Resource File.
    The Resource File Information dialog appears.

    (Click to expand)

    Resource File Information dialog

  4. In the Resource File field, click Browse to select the .dll and .pdb files for the agent from the directory where you built the project. See Step 1 - Create a basic agent.

    Note: Upload the .pdb files to facilitate remote debugging the agent.

  5. In the Application field, click ellipsis button to select Hello Wikipedia, which is the application created in Lesson 2 - Build an application without any code.
    This action links your agent assembly to the Hello Wikipedia application.
  6. Click Save and Back.

Step 3 - Add the agent to a Relativity instance

After associating your agent with an application, you can add this agent to your Relativity instance.

Use the following steps to add your agent:

  1. Navigate to the Agents tab.

    (Click to expand)

    New Agent button

  2. Click New Agent.
    The Agent Information dialog appears.

    (Click to expand)

    Agent Information dialog

  3. In the Agent Type field, click Select and then search for your agent by name on the Select Item dialog.

    (Click to expand)

    Select Item - Agent Type dialog

  4. In the Agent Server field, click Select and then choose a server where you want your agent to run.

    Note: If you are using a DevVM, then select the RELATIVITYDEVVM with the Type as Agent.

    (Click to expand)

    Select Item - Agent Server dialog

  5. Use the default values for the Number of Agents and Run Interval fields.
  6. In the Logging level field, select Log all messages.
    With this setting, you can see the message added to the Execute() method.

    Note: We don't recommend setting Logging level field to Log all messages in a production environment.

    (Click to expand)

    Logging level option

  7. Click Save and Back.
  8. In the Agent list, search for your agent.
    After adding your agent, it may take several minutes for the Agent Manager to pick up the agent and start it.

    (Click to expand)

    Agent list view

  9. Verify that the Message column for the agent is populated with the message added to the Execute() method.

    Step 4 - Remotely debug an agent

    After deploying your agent in a Relativity instance, you can start remotely debugging it. The following steps are like those for debugging a Kepler service. See Lesson 3 - Create a RESTful API.

    Note: Make sure that you have the Visual Studio 2019 Remote Debugger service running on the Relativity instance where you want to debug.

    Use the following steps to remotely debug an agent:

    1. Open the HelloWikipedia solution in Visual Studio.
    2. Navigate to Debug > Attach to Process.
      The Attach to Process dialog appears.

      (Click to expand)

      Attach to Process option

    3. Click Find.
      Your Relativity instance with the debugging service running should be automatically detected. See the Auto Detected field in the following screen shot.

      (Click to expand)

      Remote Connection dialog

    4. Enter the administrator credentials for your Relativity instance when prompted.

      (Click to expand)

      Enter your credentials dialog

    5. Use the following steps to locate a process for attaching the debugger:
      1. Log in to the machine where your Relativity instance is running.
      2. Open the Task Manager.
      3. Click the Details tab.
      4. Right-click the Name column header to display the Select columns dialog.

        Task Manager - Details tab

      5. Select the Command line checkbox.

        Select columns dialog

      6. Click OK.
    6. Locate the kCuraAgentManager.exe service in the Details tab of the Task Manager.
      It displays two services with differing command line entries as follows:
      • C:\Program Files\kCura Corporation\Relativity\Agents\...
      • C:\Program Files\kCura Corporation\Relativity\WebProcessing\...

      (Click to expand)

      Agent processes

    7. Select the process for the server where your agent is running.

      For example, you would choose the kCuraAgentManager process at the command line entry, C:\Program Files\kCura Corporation\Relativity\Agents\, because it matches the server selected for the agent. See step 4 in Step 3 - Add the agent to a Relativity instance.

    8. In Visual Studio, use the process ID (PID) to search for the process and then select it. Click Attach.

      (Click to expand)

      Attach to Process dialog

    9. Add a break point in the agent code where you call the RaiseMessage() method.
      You should see the breakpoint being triggered immediately because your agent runs at 5 second intervals.

      Breakpoint in Visual Studio

Step 5 - Update the agent functionality

After creating the IWikipediaArticleManager and implementing all the methods on it, your agent can perform these tasks:

  • Find workspaces where the Hello Wikipedia application is installed.
  • Retrieve the Article Category objects in workspaces where the application is installed.
  • Retrieve the top 10 articles for each category in a workspace.
  • Create and update a Document and Reference Article object for each of the articles.
  • Link the Article Reference object to the appropriate Article Category object for each of the articles.

Use the following steps to update the functionality of your agent:

  1. Delete the file named WikipediaAgent.cs from the basic agent created in Step 1 - Create a basic agent. You will create a new agent in the following steps, which contains the code for the Hello Wikipedia application.
  2. Create a Constants.cs file in the agent project.
  3. Add the GUIDs for the application artifacts that you created to the Constants class.
    Use these steps to view the GUIDs:
    1. Navigate to the details views of the Hello Wikipedia application created in Lesson 2 - Build an application without any code.
    2. Click Show Component GUIDs in the Application console.
    3. Note the GUIDs for the Article Category and the Article Category – Name.

      (Click to expand)

      Application components view

  4. Install the Relativity.DataExchange.Client.SDK NuGet package in the agent project:
    1. Right-click on the References in the WikipediaAgent project.
    2. Click Manage NuGet Packages.

      (Click to expand)

      Manage NuGet Packages option

    3. Search for the Relativity.DataExchange.Client.SDK version 1.11.7 package, and click Install.

      (Click to expand)

      Nuget Manager dialog

  5. Add a reference to the WikipediaKepler.Interfaces project:

    1. Right click References in the agent project and click Add Reference.

      (Click to expand)

      Add Reference option

    2. Select the WikipediaKepler.Interfaces project and click OK.

      (Click to expand)

      Reference Manager dialog

  6. Create a new file named Article.cs in the agent project with the following code.
  7. Create a new file named ArticleCategory.cs in the gent project with the following code.
  8. Create a new file named IWikipediaArticleManager.cs in the agent project with the following code.

  9. Create a new file named WikipediaArticleManager.cs in the agent project with the following code.
    This class implements the IWikipediaArticleManager interface created in the step 8.
  10. Query for workspaces containing the Hello Wikipedia application by adding the following code for the GetHelloWikipediaWorkspaceIDs() method in the WikipediaArticleManager class.
  11. Create a new file for an agent named WikipediaArticleManagerJob.cs with the Relativity Agent template and add the following code.
  12. Set up the APIs used to retrieve Article Category objects by adding the following code to the Execute() method in the WikipediaArticleManagerJob class.
  13. Retrieve Article Category objects for the matching workspaces by adding the code for the GetArticleCategories() method in the WikipediaArticleManager class.
  14. Retrieve the top 10 articles for a category by adding code for the GetArticles() method.
  15. Create or update the web pages as Document objects after retrieving all the web pages for your list by using the Import API to add them to Relativity.
  16. Configure a job for uploading documents by adding the following code for the BuildArticleImportJob(), GetImportableArticles(), and InitializeImportJob() methods in the WikipediaArticleManagerJob class.
  17. Create an Article Reference object for each article by adding the following code for the AddOrUpdateArticleReferences() method in the WikipediaArticleManager class.
  18. Query for existing Article Reference objects and avoid duplicates by adding the following code for the FindExistingArticleReference() method in the WikipediaArticleManager class.
  19. Create or update an Article Reference object for a document by adding the following code for the CreateArticleReference() and UpdateArticleReference() methods in the WikipediaArticleManager class.
  20. Retrieve the Article Category object for an Article Reference object by adding the following code for the GetArticleCategory() method in the WikipediaArticleManagerJob class.
  21. Use the following steps to include additional assemblies from the Relativity.DataExchange.Client.SDK package required by the Import API as part of the RAP file:
    1. Build the solution in the bin folder for the WikipediaAgent.
    2. Upload the following assemblies as Resource files associated with the Hello Wikipedia RAP file:
      • Relativity.DataExchange.Client.SDK.dll
      • Relativity.Transfer.Client.Core.dll
      • Relativity.Transfer.Client.Aspera.dll
      • Relativity.Transfer.Client.dll
      • Relativity.Transfer.Client.FileShare.dll
      • Relativity.Transfer.Client.Http.dll
      • Renci.SshNet.dll
      • Polly.dll
      • FaspManager.dll

      In Step 7 - Verify that the agent runs, you will check that your agent retrieves the top 10 articles for article categories in a workspace. They should be retrieved as documents and article references in Relativity.

Step 6 - Write a unit test

In this section, you learn how to write a unit test for your new agent.

Review these guidelines for writing unit tests:

  • Test a single scenario per test. For example, when calling the GetHelloWikipediaWorkspaceIDs() method, the Application Install Manager is called and only workspaces that aren't administrator workspaces are returned.
  • Mock any dependencies to ensure that the test is limited to only the behavior that you want to test. For example, mock the dependencies of IApplicationInstallManager interface.
  • Follow testing best practices for naming conventions. The test should explain what is being tested. For example, when testing the GetHelloWikipedia() method, the test should indicate that the application is installed in a non-administrative workspace, and that any matching workspace IDs are returned.

Use the following steps to write a unit test:

  1. Open Visual Studio 2019.
  2. Create a unit test project for your solution.
  3. Select Unit Test Project (.NET Framework) template for your project and name it as WikipediaAgent.Tests.
  4. Add the project to the same root directory as your other projects.
  5. Use .NET Framework 4.6.2 as the project framework.
  6. Rename the UnitTest1.cs file and class name to WikipediaArticleManagerTests.cs and WikipediaArticleManagerTests.

  7. Install the following NuGet packages:
    • NUnit 3.12.0
    • NUnit3TestAdapter 3.16.1
    • Moq 4.5.30
    • Relativity.ObjectManager 11.2.172.14
    • Relativity.DataExchange.Client.SDK 1.11.7
    • Relativity.Api 10.3.226.8
  8. Add a reference to the following projects:
    1. Wikipedia Agent
    2. WikipediaKepler.Interfaces
  9. Update the WikipediaArticleManagerTests class to test the GetHelloWikipediaWorkspaceIDs() method.
  10. Run the test and verify that it passes.
    Use this test as a model for adding coverage for edge cases. For additional practice, implement unit tests for the other methods used by this agent.

Step 7 - Verify that the agent runs

After confirming that the agent passes the unit tests, you can add the updated agent to your Relativity instance.

Use the following steps to add the updated agent to Relativity:

  1. Log in to Relativity.
  2. Navigate to the Agents tab.
  3. Delete any instances of the Wikipedia Agent bycompleting the following steps:
    1. Select the checkbox for each the instance of the agent to delete.
    2. Select Delete in the drop-down menu at the bottom of the page.

      (Click to expand)

      Delete agent confirmation message

    3. Click Delete Agents.

      (Click to expand)

      Delete Agents button

  4. Navigate to the Resource Files tab.
  5. Delete the resource file for the previous version of the agent from the Hello Wikipedia application.
    You can use the delete mass operation to remove the file:

    (Click to expand)

    Delete Resource File Object dialog

  6. Repeat the steps in Step 2 - Upload the agent to an application and Step 3 - Add the agent to a Relativity instance to deploy your new WikipediaAgent.dll.

    The WikipediaAgent.dll consists of one agent as shown in the following screen shot:

    (Click to expand)

    Agents tab

    Note: When adding your new agent, make sure your set the Run Interval to a reasonable setting, such as a minimum of 60 seconds. In this tutorial, the code uses Wikipedia API calls. When deploying your agent, follow the usage guidelines at API:Etiquette on the MediaWiki website.

  7. Navigate to the details view of the application, and click Push to Library in the Application console.

    (Click to expand)

    Push to Library button

  8. Create a new workspace.
  9. Navigate to the Relativity Application tab of the new workspace and click New Relativity Application.
  10. In the Application Type field, choose Select from Application LIbrary and select Hello Wikipedia in the Choose from Application Library field.

    (Click to expand)

    Relativity Applications tab

  11. Click Import.
  12. Navigate to the Article Category tab in the new workspace.
  13. Create a new Article Category named Fish, and select the Automatic Updates Enabled field.

    (Click to expand)

    Article Category tab

  14. Verify that the document list displays the top 10 articles of the category created from Wikipedia, and corresponding article reference.