November Happy Hour will be moved to Thursday December 5th.

AI OnAI Off

Event Management System Specification

Product version:

EPiServer CMS 5 R2 SP2

Document version:

1.0

Document last saved:

Introduction

This technical note contains functional and technical information for the EPiServer Events System in EPiServer CMS 5 R2.

The system provides a mechanism for distributing events within an EPiServer CMS 5 site, between EPiServer CMS 5 sites on the same physical server (enterprise), and between EPiServer CMS 5 sites on separate servers (load-balanced standard and enterprise).

Table of Contents

Technical Overview

The system is based on Microsoft Windows Communication Foundation (“Indigo”) 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 5 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 hasn't 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 two .NET events that user code can subscribe to; the Raised event and the Missed event. 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

The following text describes the logical setup and execution of the events systems.

  1. EPiServer CMS 5 is installed on a computer.
  2. The EPiServer Events System should be enabled in the web.config file. See the Configuration section in this document for details of how to do this.
  3. When an EPiServer CMS site starts, it will do the following if remote events are enabled:
    1. Create a site secret if one doen’t 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.

Configuration

The EPiServer Events System is used to distribute events with an EPiServer CMS 5 site and between sites in an enterprise and/or load balanced scenario. See the Configuring EPiServer CMS 5 Enterprise technical note for information about installing and configuring load balanced and enterprise sites. 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 and it should be configuerd as WCF Service.

To configure the EPiServer Event System Subscriber make the following checks/adjustment to the EPiServer CMS 5 web.config file.

Note the configuration examples below are for IIS6 for IIS7 examples, see the tech note Changes between IIS6 and IIS7.

  1. In the <httpModules> section ensure the <add> element for the EventSubscriberHostModule is not commented out:
    <configuration>
      <system.web>
        <httpModules>
            ...
            <add name="EventSubscriberHostModule" type="EPiServer.EventSubscriberHostModule, EPiServer" />
  2. 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 (e.g. Contract name and name of WCF service) and the * indicates the customer value. (Please See the microsoft documentation about WCF configuration for more info)

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


    To configure the EPiServer Events System Publisher make the following checks/adjustments to the EPiServer CMS 5 web.config file.

  3. In the <siteSettings> section ensure the following values are set as shown:

    <configuration>
      <episerver>
        <sites>
          <site>
            <siteSettings enableEvents="true" enableRemoteEvents="true">

    If enableEvents is set to true but enableRemoteEvents is set to false then any events raised will only be distributed to subscribers within the same site. For load balanced or enterprise sites then enableRemoteEvents must also be set to true so that the events can be distributed to other sites both on the same server and other servers.

  4. 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 (e.g. Contract name) and the * indicates the customer value. (Please See the microsoft documentation about WCF configuration for more info)

    <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

Examples of EPiServer CMS 5 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 5 site and ensure the change is reflected (with 2/3 seconds) on the 2nd load balanced EPiServer CMS 5 site. See below for exact details:

  1. On EPiServer CMS 5 #1, navigate to a page in the example site.
  2. On EPiServer CMS 5 #2, enter Edit mode and navigate to the same page as in step #1.
  3. On EPiServer CMS 5 #2, add/edit/delete some text on the page and the click “Save and Publish”.
  4. On EPiServer CMS 5 #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 5 #1, navigate to a page in the example site.
  2. On EPiServer CMS 5 #2, enter Edit mode and navigate to the same page as on #1.
  3. On EPiServer CMS 5 #2, create or edit a link  on the page and the click “Save and Publish”.
  4. On EPiServer CMS 5 #1, refresh the page and ensure the link reflects the new information saved in Step 3. 

Troubleshooting 

Admin Plug-in

An EPiServer CMS Admin Plug-In is available here. The plug-in helps to diagnose problems and configuration errors in the events system. More information can be found here.

EPiServerRemoteEventsListener

EPiServerRemoteEventsListener is a diagnostics application for the EPiServer CMS 5 Events System.

EPiServer CMS 5 uses Windows Communication Foundation technology to send events between load balanced sites. By default the RemoteEventsListener application listens on the same UDP channel as EPiServer CMS in order to display the events that are being transmitted by EPiServer CMS both on the local server and by other servers on the same network. This can be useful to determine if firewalls or other software is blocking the EPiServer CMS events. You have to change the EPiServerRemoteEventListener.config file in the case you have configuerd the publisher and subscriber on different binding or address. (See the Microsoft WCF configuration documentation).

The application can also be used to send events. It can be useful to run an instance in send mode on one server and one in receive (normal) mode on another server to test if the necessary ports EPiServer Events use are open. To launch in send mode, start the application with a command line parameter of 'send'.

The application requires .NET 2.0 and can be installed using a simple XCopy of the contents of the zip file.

If the Events System doesn't appear to be working properly, check the following items:

  • Ensure that enableEvents and enableRemoteEvents are set to true in the web.config for the relevant sites on all servers.
  • Ensure the <system.serviceModel> section is NOT commented out in the web.config for the relevant sites on all servers.
  • Ensure the <add> entry for the EventSubscriberHostModule in <httpModules> section is NOT commented out in the web.config for the relevant sites on all servers.
  • Ensure any firewall that is active between servers allows the port chosen.
  • Restart IIS on the offending server. There is a window when a new site is created in an enterprise where other existing sites in the same enterprise are not aware of the new site's existence

Problems with Mulitcasting UDP  - configuring to one specific server

See the FAQ which contains an example of how to configure to one specific server using the tcp protocol.

Problems during application startup and installation

See the FAQ which contains information regarding the error operation on a socket.