Handle form events

✖
Copy to clipboard

Xperience raises events when visitors submit form data and when administration users export form submissions. Handle these events to run custom logic, for example to integrate submissions with an external system or to keep an audit record of exports.

Handle form record events

You can run custom actions directly when form actions occur by implementing handlers for events of the BizFormItemEvents type. The system invokes the following events in response to form actions:

  • Update – invoked when a form record is updated.
  • Insert – invoked on each form submission.
  • Delete – invoked when a form record is deleted.

Use the appropriate event type to perform your custom actions or data modifications Before or After the given form event.

To access the data of the active form in the event handler, use the Item property (BizFormItem type) of the BizFormItemEventArgs parameter. The parameter is available for all form item event handlers.

C#
Example 


using System;

using CMS;
using CMS.DataEngine;
using CMS.OnlineForms;

// Registers the custom module into the system
[assembly: RegisterModule(typeof(FormHandlerModule))]

public class FormHandlerModule : Module
{
    // Module class constructor, the system registers the module under the name "CustomFormHandlers"
    public FormHandlerModule()
        : base("CustomFormHandlers")
    {
    }

    // Contains initialization code that is executed when the application starts
    protected override void OnInit()
    {
        base.OnInit();

        // Assigns a handler to the BizFormItemEvents.Insert.After event
        // This event occurs after the creation of every new form record
        BizFormItemEvents.Insert.After += FormItem_InsertAfterHandler;
    }

    // Handles the form data when users create new records for the 'ContactUs' form
    private void FormItem_InsertAfterHandler(object sender, BizFormItemEventArgs e)
    {
        // Gets the form data object from the event handler parameter
        BizFormItem formDataItem = e.Item;

        // Checks that the form record was successfully created
        // Ensures that the custom actions only occur for records of the 'ContactUs' form
        // The values of form class names must be in lower case
        if (formDataItem != null && formDataItem.BizFormClassName.Equals("bizform.contactus", StringComparison.OrdinalIgnoreCase))
        {
            string firstNameFieldValue = formDataItem.GetStringValue("FirstName", "");
            string lastNameFieldValue = formDataItem.GetStringValue("LastName", "");

            // Perform any required logic with the form field values

            // Variable representing a custom value that you want to save into the form data
            object customFieldValue = "customValue";

            // Sets and saves a value for the form record's 'CustomField' field
            formDataItem.SetValue("CustomField", customFieldValue);
            formDataItem.SubmitChanges(false);
        }
    }
}

Handle form data export events

The AfterExportListingEvent event (available in the Kentico.Xperience.Admin.Base namespace) occurs when a user exports form submissions. The event is intended for scenarios such as auditing or compliance logging, where you need a record of who exported which data and when.

Unlike BizFormItemEvents, this event uses the asynchronous event model described for content events. To handle the event, create a class implementing the IAsyncEventHandler<AfterExportListingEvent> interface (from the CMS.Base namespace) and define its HandleAsync method. Access the event object’s Data property to get an ExportListingEventData object with the following properties:

Property

Type

Description

ListingPageTypeName

string

The full type name of the listing page whose data was exported. For form submissions, the value is Kentico.Xperience.Admin.DigitalMarketing.UIPages.FormSubmissionsTab.

UserID

int

The ID of the user who performed the export. The value is 0 if the system cannot determine the user.

Timestamp

DateTime

The local time of the server at which the export was completed.

All properties of the event data are read-only and the event does not provide access to the exported file or its content. Handlers cannot modify or cancel the export.

C#
Log form submission exports 

using System.Threading;
using System.Threading.Tasks;

using Microsoft.Extensions.Logging;

using CMS.Base;

using Kentico.Xperience.Admin.Base;

// Handler triggered after a user exports form submissions
public class ExportAuditHandler : IAsyncEventHandler<AfterExportListingEvent>
{
    private readonly ILogger<ExportAuditHandler> logger;

    // Gets an ILogger instance using constructor DI
    public ExportAuditHandler(ILogger<ExportAuditHandler> logger)
    {
        this.logger = logger;
    }

    public Task HandleAsync(AfterExportListingEvent asyncEvent, CancellationToken cancellationToken)
    {
        // Accesses the strongly-typed event data
        ExportListingEventData data = asyncEvent.Data;

        // Logs the details of the export
        // The 'name' value of the EventId object sets the event code in the Xperience event log
        logger.LogInformation(
            new EventId(0, "EXPORT"),
            "User {UserID} exported '{ListingPageTypeName}' at {Timestamp}.",
            data.UserID,
            data.ListingPageTypeName,
            data.Timestamp);

        return Task.CompletedTask;
    }
}

The example uses the Information log level when logging events. Information level events are not written to the Xperience event log by default. To include them, set the log level for the event category in the XperienceEventLog logging provider. See Configure logging.

Register the handler by calling the AddEventHandler<TAsyncEvent, THandler>() extension method on IServiceCollection. Handlers are registered as singletons, so you can resolve any required services using constructor injection.

C#
Program.cs 


using CMS.Base;

using Kentico.Xperience.Admin.Base;

// ...

// Registers the handler for the AfterExportListingEvent event
builder.Services.AddEventHandler<AfterExportListingEvent, ExportAuditHandler>();