Event Management

Table of Contents

• Introduction
• Process Flow
• Configuring the Event System
• Testing the Event System

Introduction

This document contains functional and technical information for the EPiServer Events System in EPiServer CMS. The system provides a mechanism for distributing events within an EPiServer CMS site, between EPiServer CMS sites on the same physical server (enterprise), and between EPiServer CMS sites on separate servers (load-balanced standard and enterprise).

The system is based on Microsoft Windows Communication Foundation technology as this provides for object-oriented interface definitions and configurable interprocess communication methods, without the need to change code.

Event Class

The EPiServer.Events.Clients.Event class is the public API of the EPiServer CMS Events System. It allows for the sending and receiving of site events in a de-coupled manner. The Events System does not have any predefined events when EPiServer CMS starts. It is up to the code that wants to send and receive events to register them using the Event.GetEvent static method. The GetEvent method accepts a GUID event Id and will create a new Event object instance if one has not already been created for the event ID, otherwise it will return the existing one. It is important to note that the GUID event ID is only important to users of the Events System in that it allows different pieces of code to identify the same event. The Events System has no knowledge of what these events are or who uses them.

The Event class has the following .NET events that user code can subscribe to:

• The Raised event is fired when some code has called the Raise method of the Event class.
• The Missed event is fired when the Event System detects that a remote event (an event received from another site or server) has gone missing. The algorithm for detecting a missing event is based upon tracking the sequence numbers allocated to remote events and detecting after a predetermind amount of time that one or more are missing.

Process Flow

This section describes the logical setup and execution of the events systems.

1. EPiServer CMS is installed on a computer.
2. Enable the EPiServer Events System in the web.config file, see the Configuration section in this document.
3. When an EPiServer CMS site starts, it will do the following if remote events are enabled:
   1. Create a site secretly if one does not already exist in the site database.
   2. Initialize the Remote Events Manager.
4. Code in a site obtains an Event object instance and subscribes to the Raised and optionally to the Missed event.
5. 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).
6. The Event object instance fires the Raised event to notify the local subscribers.
7. If remote events are enabled the Event object instance informs the Remote Events Manager about the event.
8. The Remote Events Manager broadcasts the event to all the other sites on the same server and other servers in the network using Windows Communication Foundation over UDP. In addition to the event information a cryptographic HMAC block is also sent in the message to allow the receiver to test the authenticity of the event.
9. A Remote Events Manager in another site on the local server (enterprise) or remote server receives the UDP broadcast and does the following:
   1. Compares the site ID in the message to that of the hosting site or to other sites in an enterprise. If no match is found, the action will be logged, the message dropped and no further action taken.
   2. Verifies the HMAC using the event data and the secret for the site.
   3. If the verification fails, the action will be logged, the message dropped and no further action taken.
   4. Obtains the Event object instance for the event and calls the Raise method to notify the local subscribers.

Configuring the Event System

The EPiServer event system is used to distribute events with an EPiServer CMS site and between sites in an enterprise and/or load balanced scenario. The EPiServer Events System configuration consists of two parts: Subscriber and publisher. An EPiserver Server can be both subscriber and publisher.

The Subscriber works as a WCF Server, therefore configure it as WCF Service. To configure the EPiServer Event System Subscriber make the following checks/adjustment to the EPiServer CMS web.config file:

1. In the <configuration> section ensure the following <system.serviceModel> section exists and insert the subscriber WCF Service element. The mandatory value are shown in the example (for example, Contract name and name of WCF service) and the * indicates the customer value. (Please See the microsoft documentation about WCF configuration for more info.)
   
   XML

   <system.serviceModel>
   ...
       <services>
          <service name="EPiServer.Events.Remote.EventReplication" 
                    behaviorConfiguration="*">
              <endpoint name="RemoteEventServiceEndPoint" 
                        contract="EPiServer.Events.ServiceModel.IEventReplication"
                        binding="*"RemoteEventsBinding" address="*&quot; />
          </service>
       </services>
   ...
   </system.serviceModel>

2. In the <configuration> section ensure the following <system.serviceModel> section exists and insert the subscriber WCF client element. The mandatory value are shown in the example (for example, Contract name) and the * indicates the customer value. (Please See the microsoft documentation about WCF configuration for more info.)
   
   XML

   <system.serviceModel> 
   ... 
       <client> 
           <endpoint name="*" address="*" binding="*" bindingConfiguration="*" 
                     contract="EPiServer.Events.ServiceModel.IEventReplication" /> 
       </client> 
   </system.serviceModel>

In the default web.config you will see an example of UDP configuration of the EPiServer Event System configuration.

Testing the Event System

Examples of EPiServer CMS functionality that use the Events System are:

• Page cache updates
• Permanent Link Map Store (a cache of resolved links on a page) updates
• Workflow updates

To test page cache events, edit a page on one EPiServer CMS site and ensure the change is reflected (with 2/3 seconds) on the 2nd load balanced EPiServer CMS site. See below for exact details:

1. On EPiServer CMS #1, navigate to a page in the example site.
2. On EPiServer CMS #2, enter Edit mode and navigate to the same page as in step 1.
3. On EPiServer CMS #2, add/edit/delete some text on the page and the click Save and Publish.
4. On EPiServer CMS #1, refresh the page and ensure it reflects the new information saved in step 3.

To test permanent link map store events, create or edit a link on a page on one EPiServer CMS site and ensure the change is reflected (with 2/3 seconds) on the 2nd load balanced EPiServer CMS site. See below for exact details:

1. On EPiServer CMS #1, navigate to a page in the example site.
2. On EPiServer CMS #2, enter Edit mode and navigate to the same page as on 1.
3. On EPiServer CMS #2, create or edit a link on the page and the click Save and Publish.
4. On EPiServer CMS #1, refresh the page and ensure the link reflects the new information saved in step 3.