Using Event Handler Express

You create a new event handler entering or selecting basic information, such as a name, object type, description, and layouts that trigger it. To each event handler, you can add one or more condition groups, which contain individual conditions used for field validation. You can then deploy your new event handler for execution on layouts in the current workspace.

Note: Event handlers created by Event Handler Express cannot be added to custom applications since the resource files are tied to the "Default" application.

This page contains the following information:

Prerequisites for Event Handler Express

You must complete the following prerequisites before using Event Handler Express.

Defining basic information for an event handler

Use the following procedure to add basic information for an event handler:

  1. In Relativity, navigate to the workspace where Event Handler Express is installed.
  2. Click the Event Handler Express tab.

    Note: You can use the Delete mass operation to remove an event handler from the list view, and the Export to File operation to download a copy of it. The Copy or Edit mass operations aren't available on this view. You must manually create a new event handler rather than copying and modifying an existing one. For more information, see Editing or deleting an event handler.

  3. Click New Event Handler Express.
  4. Complete the fields in the Event Handler Express layout. See Fields for Event Handler Express.
  5. Perform one or more of the following tasks:
    • Add validation logic to your event handler. See Building condition groups and conditions.
    • To save your changes to the form, click Save. You can save your updates to the event handler and continue editing it later. However, your changes aren't deployed to the workspace.
    • To remove your updates to the form, click Clear. You can now start creating a new event handler. Event Handler Express deletes all the entries in the Basic Information and Condition Group sections, and displays a blank form. If you want to remove a specific condition group or condition, use icon to delete a condition group or condition to remove the appropriate item. See Building condition groups and conditions.

Fields for Event Handler Express

The Event Handler Express layout contains the following fields in the Basic Information section:

(Click to expand)

basic information for an event handler

  • Name - the name of the .dll file. Ensure that you enter a name, which is unique to your Relativity environment. On the Event Handler Express tab, the item list displays this name appended with additional text used to identify the .dll for your event handler. For example, if you entered MyEventHandler in the Name field then the item list displays your event handler as MyEventHandler.REHEPreSave.

    Note: Don't use special characters, wildcards, or spaces in the Name field. In addition, don't use a number as the first character in your event handler name.

  • Object Type - click to select a Relativity object, and then click Set. Event Handler Express supports attaching event handlers to document objects and RDOs. For example, you would select the document object if you want the event handler to execute when a reviewer selects choices on a layout during a review. We don't support attaching event handlers to system objects.
  • Layouts - click to select one or more layouts that you want to trigger this new event handler. These layouts must be associated with a document object or an RDO. When a user performs a task on one of these layouts, it raises an event that triggers your event handler to validate the user's responses. If you don't select an option, the event handler runs across all layouts associated with the object type. For more information, see Executing an event handler across all layouts.

    Note: Ensure that you select layouts that contain the fields used in the conditions defined for the event handler. Relativity displays an error message when an event handler attempts to execute on a layout that doesn’t contain the fields included in its conditions. Additionally, if you want to deploy all layouts, then each layout must include the fields used in the conditions.

  • Description - information about the event handler. This information appears in the Description column of the Event Handler Express tab. It also appears in the Event Handlers section of the object type details view. The source code for the event handler includes the description as a code comment. The maximum number of characters for this field is 100.For more information, see Creating and editing Relativity Objects.

Building condition groups and conditions

In Event Handler Express, you can build a series of validation rules by adding condition groups and conditions. A condition group contains one or more conditions. When you add multiple condition groups, Event Handler Express evaluates them as a series of expressions connected by the AND operator. You can choose to evaluate a series of conditions within a condition group with the AND or OR operators. Event Handler Express initially displays Condition Group - 1 and Condition - 1, so you can begin defining your validation rules. For more information, see Basic concepts.

After you add the required conditions, you can deploy the event handler in the current workspace. Event Handler Express performs the following operations:

  • It compiles a .dll.
  • It adds the .dll file to Relativity as a resource file.
  • It attaches it to an object in the workspace where you created the event handler.

If the .dll handler already exists in the workspace, Event Handler Express overrides the existing file, and attaches it to the object if necessary. If an event handler with the same name already exists, Event Handler Express displays an error message asking you to rename the new event handler.

Use the following procedure to build condition groups and add conditions:

  1. Click Add Condition Group at the top of the page. A condition group appears below the Basic Information section.
  2. Complete the fields for a condition group. See Fields for condition groups and conditions.
  3. Click icon to create a condition to create a condition.
  4. Complete the fields for a condition. See Fields for condition groups and conditions.
  5. To add multiple conditions to a condition group, click icon to create a condition for each new condition that you need.
  6. Repeat steps 1 through 5 until you have added all the condition groups and conditions required for the event handler.

    Note: To copy an existing condition group or condition, click icon to copy a condition group or condition. You also click on a condition's name to hide or show its details.

  1. Perform one or more of the following tasks:
    • To associate your event handler with one or more layouts, click Deploy Event Handler in the Event Handler console. Your event handler now executes against layouts associated with it in your workspace.

      (Click to expand)

      Deploy Event Handler button

    • To save your changes to the form, click Save. You can save your updates to the event handler and continue editing it later, but your changes aren't deployed to the workspace.
    • To remove your updates to the form, click Clear. Event Handler Express deletes all the entries in the Basic Information and Condition Group sections, and displays a blank form. If you want to remove a specific condition group or condition, use icon to delete a condition group or condition to remove the appropriate item. See Building condition groups and conditions.

Fields for condition groups and conditions

A condition group contains the following fields:

(Click to expand)

a condition group for an event handler

  • Description - information about the validation that this condition group performs. If you enter double quotation marks (") in this field, Event Handler Express removes them from the text.
  • left parentheses - click the option with the appropriate number of parentheses to group your conditions.
  • Validation Type - select the Field or User as the type that you want to validate. Supported field types include Current User, Fixed-length Text, Single Choice, Multiple Choice, and Yes/No fields. For the Current User field, Event Handler Express only validates conditions for the user currently logged in to Relativity.
  • Field/Group - the name of the field that you want to validate. If you set the Validation Type to Group, then you don't need to select an option for this field.
  • Condition - select an operator that you want to use for validation. The field type that you selected in the Validation Type drop-down box must support the operator. See Supported conditions by field type.
  • Choice/Value - select a choice that you want to use for validating your condition.
  • right parentheses - click the option with the appropriate number of parentheses to group your conditions.
  • AND or OR operators - click the AND or OR operator to determine if both or only one condition needs to be met respectively. The operator that you selected appears in a red font.
  • Message - an error message that users see when they have met all conditions in the condition group. You can add your message after you have added conditions. The maximum number of characters for this field is 255.

Supported conditions by field type

When building a condition, you must use only the operators supported by the field type selected in the Validation Type drop-down box. The following table displays ü for each operator supported by a specific field type.

Operator Current User Fixed Length Text Multiple Choice Single Choice Yes/No
Is       ü ü
Is Not       ü  
Is Set   ü ü ü  
Is Not Set   ü ü ü ü
Contains     ü    
Has Changed Do Not Include Initially Set   ü ü ü  
Has Changed Include Initially Set   ü ü ü  
Is In Groups ü        
Is Not In Groups ü        

Additional information about operators

Event Handler Express provides operators that you can use to control whether an event handler fires on a layout that doesn’t contain any initial values. In general, you create a new layout in a workspace and then deploy the event handler that you want associated with it. The fields on the layout won’t contain any values when a user first begins to code with it. You may not want your event handler to fire when initial updates are made. You could use the operator called Has Changed Do Not Include Initially Set to add a condition on the event handler. When you set this condition, the event handler executes as follows:

  • When the user sets the initial values on a layout, the event handler doesn’t fire.
  • When the user sets or updates any subsequent values, the event handler fires.

For example, the layout contains a required Responsiveness field that isn’t set when the user initially accesses the layout. You wouldn’t want the event handler to fire and display an error message the first time that a user updates the field, but only on subsequent changes.

In addition, you may want to add a condition that ensures the event handler fires when the user changes an existing value on a layout. You could use the Has Changed Include Initially Set operator to add this condition. When you set this condition, the event handler executes as follows:

  • When the user sets the initial values on a layout, the event handler fires.
  • When the user sets or updates any subsequent values, the event handler fires.

For example, you may want the event handler to fire only after the Responsiveness field on a layout has been updated to a new value. When a user changes the value from Not Responsive to Responsive, or from unset to Responsive, you may want to execute the event handler to ensure that the Issue Designation field is also set.

Editing or deleting an event handler

You can edit and delete the event handlers that you create through Event Handler Express. This section explains how editing or deleting an event handler affects your Relativity environment.

Editing event handlers

You can update an event handler by clicking the Edit link appearing next to its name on the Event Handler Express tab. When you click this link, Event Handler Express displays the basic information and condition groups used to create the event handler. You can update these sections as necessary.

Deploying your updates affects all workspaces in your environment where you have added the event handler. Event Handler Express recompiles the .dll file and overwrites the existing version. All copies of the event handler in your environment now reference the updated file. Consequently, any changes made to this file immediately modify the behavior of the event handler throughout your Relativity environment.

Deleting event handlers

When you deploy an event handler, Event Handler Express creates a resource file of type .dll that contains your source code. It attaches this .dll file to the object that you selected when you created the event handler. You need to remove the event handler from the Event Handler Express and the object associated with it. Additionally, you need to remove its resource file.

To delete an event handler, complete the following steps:

  1. Remove the event handler from Event Handler Express. You can use the Delete mass operation on the Event Handler Express tab to remove the event handler from this list view. You can't edit the source code for the event handler after you delete it from this list.
  2. Remove the event handler from the object that the event handler was created on. For example, you may have created the event handler on the Document object, so you now need to remove it from this object. For more information, see Creating and editing Relativity Objects.
  3. Remove the resource file created for the event handler. You can completely remove the event handler from your Relativity environment by deleting its resource file. For more information, see Resource files.

Note: Deleting the resource file affects all workspaces in your environment, where you may have added the event handler. The functionality provided by the deleted event handler isn't available in any workspace after this action.

Uploading an event handler to another Relativity instance

You can reuse your custom event handlers built with Event Handler Express by uploading them to other Relativity instances. When you associate the event handler with an object type, ensure that the workspace contains layouts, objects, fields, and choices with the same names as those used to create the event handler.

Use the following procedure to upload an event handler to another environment:

  1. From Home, click the Applications & Scripts > Resource Files tabs.
  2. On the Resource Files tab, locate your event handler and double-click on its name.
  3. On the details view, double-click on your event handler's name in the Resource Files field. After your browser downloads the .dll file, save it to a location of your choice.

    (Click to expand)

    details view of a resource file

  4. Log in to another Relativity instance.
  5. On the Resource Files tab, upload the .dll for your event handler. For more information, see Resource files.
  6. Navigate to a workspace where you want to add the event handler.
  7. Click the Workspace Admin > Object Type tabs.
  8. On the Object Type tab, locate the object type that you want to associate with the event handler. Event Handler Express supports attaching event handlers to document objects and RDOs.
  9. Click on the name of object type to display its detail view.
  10. In the Event Handlers section, click New to display the Select Event Handler dialog.

  11. Select your event handler .dll, and click OK to add it to the Event Handlers section of the object type. The event handler now executes when a user performs a task on the layouts selected when you initially built the event handler.

    event handler displayed on details view

Special considerations for building event handlers

Review these guidelines to ensure that your event handlers function properly after you deploy them to a workspace.

Executing an event handler across all layouts

Your event handler executes across all layouts if you don't select one or more items in the Layouts option when building the event handler. If you want your event handler to run across all layouts in a workspace, ensure that they contain the fields required for the event handle to execute properly. Relativity displays an error message when an event handler attempts to execute on a layout that doesn’t contain a required field. Any field that you add to a condition is a required field. See Defining basic information for an event handler.

Backslashes in field and choice names

When adding conditions, ensure that the names of choices and fields don’t contain a character string containing a backslash preceded and followed by a space. For example, you don’t want to use a multiple choice field in a condition that contains a choice with the following name:

Choice B \ 1

However, you can use choices and fields that contain a backslash preceded and followed by text. See the following choice name:

Choice B\1

Wildcards in field and choice names

When adding single or multiple choice fields to a condition group, you may select fields or the choices with names that contain wildcards. Ensure that fields or choices have unique names if you omitted the wildcard characters.

Event Handler Express ignores the wildcards in the field and choice names when it compiles the .dll. The generation of the .dll fails when multiple choices have the same name. For example, you could have a multiple choice field called Choice B with the following sub-choices:

  • Choice A
  • Choice B
    • Choice B\1
    • Choice B \ 1
    • Choice B \\ 1

Because Event Handler Express ignores the wildcard characters, it sees the same name for three sub-choices, causing the compiling event to fail.

Troubleshooting your event handler

You can use the following list to troubleshoot your event handlers and resolve common errors that prevent them from executing:

  • Verify that you have associated the event handler with the correct object type.
  • Ensure that the workspace where you want to use the event handler contains all the objects that it requires. These objects include layouts, fields, or choices.
  • If you experience errors after adding your event handler to different workspace, compare the names of layouts, fields, and choices added to Event Handler Express with those used in the workspace where you created the event handler.
  • Ensure that the conjunction operators are properly set on your event handler.