Pre Load event handlers

Note: For object types using Relativity Forms, Pre Load event handlers will implement only for view and edit layouts, and only if replaceRead is either not implemented, or is implemented using Object Manager API. Pre-population of field values for new object instances in Relativity Forms is accomplished by implementing replaceGetNewObjectInstance. Additionally, Relativity Forms only supports script execution via Page Interaction event handlers, so script contained in a Pre Load event handler's Response.Message property must be moved into a Relativity Forms Page Interaction event handler in order to be executed.

Pre Load event handlers execute before the new, edit, or view page layouts load. Pre Load event handlers can be used populate default values. You can use Pre Load event handlers for all fields on Dynamic Objects and documents. The event handlers have the following behavior:

  • Support both normal and read-only field modes.
  • Read-only fields that are updated by a Pre Load event handler aren't saved to the database on Edit pages.
  • Reflected fields are properly passed into Pre Load event handlers. However, changes made to reflected fields won't persist on the page.

This page contains the following information:

See these related pages:

Guidelines for Pre Load event handlers

Use these guidelines when developing Pre Load event handlers:

  • Create a new class in Visual Studio.

    Note: You can also use a template to create this event handler type. For more information, see Visual Studio templates.

  • Add NuGet packages - ensure your Visual Studio project has installed the relevant NuGet packages, including at a minimum the Relativity.EventHandler and Relativity.Api packages.
  • Add a GUID for the event handler - set the System.Runtime.InteropServices.Guid to the GUID identifying your event handler. Use the GUID generator in Visual Studio.
  • Set the CustomAttributes.Description attribute - provide a description that you want to appear in the Relativity UI for the event handler.
  • Inherit from the PreLoadEventHandler class – extend the PreLoadEventHandler base class.
  • Override the RequiredFields property – use to specify additional fields that the event handler can accesses. The layout doesn't need to include these fields . All Pre Load event handlers must override this property.
  • Optionally use event handlers to construct HTTP responses - event handlers can't access the request header, cookies, or session information using the HTTPContext object, although they can assisted in constructing an HTTP response.

Code sample for a Pre Load event handler

Review the following code sample for a Pre Load event handler.

Note: The following code sample uses the IsNew property to test whether an artifact is new before populating default Fields. You can only use this property to check for new RDOs. You can't use it to check for Document objects.

using System;
namespace ExampleEventHandlers
    /// <summary>
    /// This example presumes the existence of an object type with
    /// a fixed-length text field that serves as a unique identifier
    /// for each instance of that object type.  This event handler populates
    /// the identifier field each time a new instance (RDO) is created.
    /// </summary>
    [kCura.EventHandler.CustomAttributes.Description("Example pre-load event handler")]
    class ExamplePreLoadEventHandler : kCura.EventHandler.PreLoadEventHandler
        public static readonly Guid IDENTIFIER_FIELD_GUID = new Guid("24402D3C-4EAF-4C33-B244-A145EEB7C6C1");
        public override kCura.EventHandler.Response Execute()
            // Construct a response object with default values.
            kCura.EventHandler.Response retVal = new kCura.EventHandler.Response();
            retVal.Success = true;
            retVal.Message = String.Empty;
                // Check that this is a new artifact.
                if (this.ActiveArtifact.IsNew)
                    // Ensure the identifier field is uniquely populated.
                    this.ActiveArtifact.Fields[IDENTIFIER_FIELD_GUID.ToString()].Value.Value = Guid.NewGuid().ToString();
            catch (System.Exception ex)
                retVal.Success = false;
                retVal.Message = ex.ToString();
            return retVal;
        /// <summary>
        /// By overriding the RequireFields method you can specify fields needed in the Execute method.
        /// Fields that are on the object type but not specified here may not be populated on the
        /// ActiveArtifact.Fields property when the Execute method (above) is invoked.
        /// </summary>
        public override kCura.EventHandler.FieldCollection RequiredFields
                kCura.EventHandler.FieldCollection retVal = new kCura.EventHandler.FieldCollection();
                retVal.Add(new kCura.EventHandler.Field(IDENTIFIER_FIELD_GUID));
                return retVal;

Additional Resources

DevHelp Community GitHub Release Notes NuGet

Share knowledge with the Relativity developer community.

Access tools and resources to build an application.

Review the most recent product release notes.

Create .NET Apps faster with NuGet.