Building your first event handler

You can use this tutorial to learn about how to build a simple event handler with Event Handler Express. It describes how to create an event handler that checks whether the user has selected the Responsive choice on the Responsiveness field. If the user made this selection, then the event handler verifies that the user also selected at least one choice on the Issue Designation field. It displays an error message if the user hasn't made a selection for the Issue Designation field.

The tutorial also illustrates how to deploy your new event handler to the current workspace. This process makes it immediately available on its associated layout. For general information about building event handlers, see Using Event Handler Express.

This page contains the following information:

Before you begin

Complete the following tasks before building your event handler:

  • Obtain access to an instance of Relativity that has Event Handler Express installed. In Relativity, confirm that you have the correct permissions. For more information on event handler permissions, see Setting security permissions.
  • For testing purposes, identify a workspace where you can execute your new event handler. You can create a new workspace or use an existing one. Ensure that it contains some sample documents, and add the following objects to it. You reference these objects when you build your event handler.
    Object TypeNameComments
    FieldResponsivenessCreate a Single Choice field on the document object.
    FieldIssue DesignationCreate a Multiple Choice field on the document object.
    ChoiceResponsiveSelect Responsiveness in the Field option.
    ChoiceNot ResponsiveSelect Responsiveness in the Field option.
    Choice Not RelevantSelect Issue Designation in the Field option.
    ChoiceTechnical IssueSelect Issue Designation in the Field option.
    LayoutFirst Pass ReviewSelect Document as the Object Type. Add the Responsiveness and Issue Designation fields to the layout.

    The following screen shot illustrates how the First Pass Review layout appears after you add the Responsiveness and Issue Designation fields to it.

    (Click to expand)

    sample coding layout

Build an event handler

Use the following procedure to build an event handler with Event Handler Express:

  1. In Relativity, navigate to the workspace where Event Handler Express is installed.
  2. Click the Event Handler Express tab.
  3. Click New Event Handler Express.
  4. In the Basic Information section, enter the following information in these fields:
    • Event Handler Name - MyFirstEventHandler
    • Object Type - click Ellipsis button to display the Select Item dialog. Select the Document object, and then click Set.
    • Layouts - click Ellipsis button to display the Select Item dialog. Select the First Pass Review layout, and then click Add > Set.
    • Description - This event handler tests fields in the layout for a first pass review.

      (Click to expand)

      basic information for an event handler

  5. In Condition Group - 1, enter the following text in the Description box:

    These conditions check whether the Responsiveness field is set to Responsive. Next, they verify that the Issue Designation field is also set.

  6. To define Condition - 1, complete these steps:
    1. Click left parenthesis to select the left parenthesis.
    2. Select Field as the Validation Type.
    3. To set the Field/Group, click Ellipsis button to display the Select Item dialog. Filter on Responsiveness in the Name column, select this choice, and click Set.
    4. In the Condition drop-down menu, select Is as the operator.
    5. To set the Field/Group, click Ellipsis button to display the Select Item dialog. Select Responsive, and click Set.
    6. Click right parenthesis to select the right parenthesis.
  7. Click AND operator to link Condition - 1 with the AND operator to Condition - 2, which you add in the following steps.

    (Click to expand)

    a condition group for an event handler

  8. Click icon to create a condition to create a new condition. Repeat this process when you need to add another condition.
    1. Click left parenthesis to select the left parenthesis.
    2. Select Field as the Validation Type.
    3. To set the Field/Group, click Ellipsis button to display the Select Item dialog. Filter on Issue Designation in the Name column, select this field, and click Set.
    4. In the Condition drop-down menu, select Is Not Set as the operator.
    5. Click right parenthesis to select the right parenthesis.
  9. In the Message box, enter the following:

    When you choose Responsive, you must also select a choice for the Issue Designation field.

  10. Click Save.
  11. Click Deploy Event Handler in the Event Handler console. Your event handler now executes against the First Pass Review layout associated with it in your workspace.

    (Click to expand)

    Deploy Event Handler button

Executing your event handler in a layout

You can test your event handler by coding documents in the viewer in the workspace where you deployed the event handler.

  1. In the current workspace, open a document in the viewer.
  2. Select the First Pass Review layout and click Edit.

    (Click to expand)

    coding layout in viewer

  3. To test your event handler, select Responsive and click Save. Your error message should appear when you haven't selected a choice for the Issue Designation field.

    (Click to expand)

    error message in coding layout