Build your first event handler

This tutorial illustrates how to create a simple event handler that updates the Name field on a Relativity Dynamic Object (RDO). It describes how to complete the following tasks:

  • Write the source code for this event handler.
  • Add references to your Visual Studio project.
  • Inherit from the event handler base class.
  • Override the Execute() method with your business logic.
  • Add the compiled .dlls for the event handler to Relativity.
  • Execute the event handler on an RDO.

For information about different types of event handlers, see Develop object type event handlers and Develop application event handlers.

This page contains the following information:

Before you begin

Complete the following tasks to before you implement an event handler:

Build an event handler

Use the following steps to build a simple event handler:

  1. Open Visual Studio.
  2. Create a new Class Library project called Relativity.BasicSamples.

    dialog for creating a class library

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

    dialog for creating a new class

  5. To add references to the project, right-click on References in the Solution Explorer. Click Add Reference. You need to add references to the .dlls that contain the Relativity classes and interfaces used to build your event handler.

    Add Reference menu option

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

    ...\Program Files\kCura Corporation\Relativity SDK\Event Handlers\Client

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

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

  8. 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 in this folder:

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

  9. In the BasicPreSaveEventHandler class, add the code to inherit from the kCura.EventHandler.PreSaveEventHandler class.

    code for Pre Save event handler

  10. Right-click on kCura.EventHandler.PreSaveEventHandler, and click Implement Abstract Class.

    Implement Abstract Class menu option

  11. Override the RequiredFields property and return a new FieldCollection, which includes the Name field. This step ensures that the Name field is always available in the ActiveArtifact.Fields collection even when it isn't on the layout.

    code to override RequiredFields property

  12. Add the following code to implement the Execute() method. You must override the Execute() method inherited from the base class. The Execute() method contains the code with your business logic. In this example, the Execute() method works as follows:
    • Instantiates a new Response object with the Success property set to true, and the Message property set to an empty string.
    • Retrieves the name of the current user who is logged in and the time.
    • Creates a string containing the user and time data.
    • Sets the Value property of the Name field in the ActiveArtifact.Fields collection equal to this string.

    code to override Execute() method

  13. Add a class attribute. This attribute determines the name of the event handler that appears in Relativity.

    code to override Description custom attribute

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

    Create GUID menu option

  15. Click the 5. [Guid("xxxxxxx-xxxx...xxxx")] > Copy.

    Create GUID dialog

  16. 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 then paste in the GUID.

    code for Guid custom attribute

    Your code for this simple event handler should be similar to the following sample. However, the GUID for the event handler 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.EventHandler.CustomAttributes.Description("Basic Pre Save")]
          [System.Runtime.InteropServices.Guid("6CAF19AA-A4C3-4871-91EB-DA7374C7250A")]
          class BasicPreSaveEventHandler : kCura.EventHandler.PreSaveEventHandler
          {
                public override kCura.EventHandler.Response Execute()
                {
                      kCura.EventHandler.Response retVal = new kCura.EventHandler.Response();
                      retVal.Success = true;
                      retVal.Message = String.Empty;
    
                      String yourName = this.Helper.GetAuthenticationManager().UserInfo.FullName;
                      String currentTimeString = DateTime.Now.ToLongTimeString();
                      String helloString = 
                            String.Format("Hello {0}! The time is: {1}", yourName, currentTimeString);
                      kCura.EventHandler.Field nameField = this.ActiveArtifact.Fields["Name"];
    
                      nameField.Value.Value = helloString;
    
                      return retVal;
                }
    
                public override kCura.EventHandler.FieldCollection RequiredFields
                {
                      get
                      {
                            kCura.EventHandler.FieldCollection retVal = 
                                  new kCura.EventHandler.FieldCollection();
                            retVal.Add(new kCura.EventHandler.Field("Name"));
                            return retVal;
                      }
                }
          }
    }
  17. To compile your event handler source code, click Build >Build Solution.

    Build Solution menu option

    After your event handler assembly builds successfully, you can upload it to Relativity.

  18. Open the Relativity instance used for development.

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

  19. Navigate to the Resource File tab, and click New Resource File.
  20. In the Resource File field, click Browse to select the Relativity.BasicSamples.dll from the directory where you built the project.
  21. In the Application field, click ellipsis button to select Default as the application. This action links your event handler assembly to the default application. In general, you link your assemblies to a custom application that you are developing.

    dialog to add new resource files

  22. Click Save. You now have a new event handler type available for use in Relativity. In this example, you attach your event handler to an RDO so that you can execute it.
  23. Create a new Object Type called Basic Samples RDO in a Relativity workspace.
  24. To attach the event handler to your new object type, click New on the Event Handlers associative list.
  25. Select the BasicPreSaveEventHandler in the dialog box. After you attach your event handler, you can execute it in Relativity.

    dialog for selecting an event handler

  26. To view your event handler execution, create a new instance of the Basic Samples RDO.
  27. In the New field, enter Test RDO Instance.

    dialog for adding an RDO instance

  28. Click Save to trigger your Pre Save event handler. Your event handler updates the Name field to display the text: Hello <your name>! The time is: <time>.

    field updated by Pre Save event handler