Manage events and event providers

6 min

The events system provides a mechanism for distributing events between IIS applications and Optimizely Content Management System (CMS) websites in a load-balanced environment. The CMS event system is provider-based, and you can use the built-in event provider or develop your own customized one.

Event providers

Built-in event provider

The built-in event provider is based on Microsoft Windows Communication Foundation (WCF) and requires some manual WCF configuration steps to enable. It uses UDP broadcasting or TCP, which requires detailed knowledge about ports, firewalls, and endpoints. To use elastic scaling (adding and removing servers on demand) with the WCF provider, you must use UPD broadcasting because TCP requires you to configure endpoints manually.

Elastic scaling in cloud environments does not work well using the built-in WCF provider because you may not have detailed control over networks and servers. An event provider optimized for Azure Web Apps is available on NuGet. The event provider for Azure uses a Service Bus for distributing events and requires no configuration of servers or network details. An event provider for Amazon Web Servers is also available on NuGet.

Customized event provider

Another alternative is to develop a custom event provider adapted to your hosting environment.

Configure an event provider

For the built-in WCF-based event provider, it is enough to define WCF endpoints (as described in Configure events over WCFConfigure events over WCF because it is the default provider.

To use another custom event provider, add the provider configuration to the event element in the <episerver.framework> section of the web.config. For example:

<episerver.framework>
  <event defaultProvider="msmq">
    <providers>
      <add name="msmq" type="MSMQEventProvider.MSMQEventProvider, MSMQEventProvider" />
    </providers>
  </event>
</episerver.framework>

See Use the Event APIUse the Event API.

Event system process flow

The following procedure describes the logical setup and execution of event system actions.

When an Episerver CMS website starts, it does the following: a. Creates a secret if one does not already exist in the site database. b. Initializes the Event Broker, which is responsible for remotely sending and receiving event messages. c. Initializes each configured Event Provider. d. Enables the Event system when the initialization process has completed (for example when CMS or Optimizely Customized Commerce has completed initialization).

Code in a site obtains an Event object instance and subscribes to the Raised and optionally to the Missed event.

Code in a site obtains an Event object instance and calls the Raise method (the Cache Manager could raise a cache changed event, for example).

The Event object instance fires the Raised event to notify the local subscribers.

The Event object instance informs the Event Broker about the event.

The Event Broker sends the event to the other sites on the same server and other servers in the network using the configured Event Provider. In addition to the event information, a cryptographic HMAC block is also sent in the message to let the receiver test the event's authenticity (the provider can turn off this functionality if a secure channel is already present).

The Event Broker on another instance (an IIS site on the local server or remote server) receives the sent message and does the following: a. Sends a message from another instance sharing the same database. If the message does not match, it logs the action, drops it, and takes no further action. b. Verifies the HMAC using the event data and the secret stored in the database (unless the provider disabled validation)c. If the verification fails, it logs the action, drops the message, and takes no further action. d. Obtains the Event object instance for the event and calls the Raise method to notify the local subscribers.

Test the event system

An example of CMS functionality that uses the events system is cache updates. To test cache events, edit a page on one CMS site and ensure it reflects the change on the second load-balanced CMS website:

On CMS #1, go to a page in the example website.

On CMS #2, enter edit view and go to the same page as in step 1.

On CMS #2, add, edit, or delete some text on the page and click Publish.

On CMS #1, refresh the page and ensure it reflects the new information saved in step 3.