Event Management System Specification

Introduction

This technical note contains functional and technical information for the EPiServer Events System in EPiServer CMS 5 Service Pack 2. For details of the EPiServer Events System in EPiServer CMS 5 R1, see this technical note.

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
• Process Flow
• Configuration
• Testing
• Troubleshooting

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.

To configure the EPiServer Events System, make the following checks/adjustments to the EPiServer CMS 5 web.config file on all affected servers:

1. 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.
2. 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" />
3. In the <configuration> section ensure the following <system.serviceModel> section exists and is NOT commented out. <system.serviceModel>
    <extensions>
      <bindingElementExtensions>
        <add name="udpTransport" type="Microsoft.ServiceModel.Samples.UdpTransportElement, EPiServer.Implementation" />
      </bindingElementExtensions>
    </extensions>
    <services>
      <!-- Before deployment, you should remove the returnFaults behavior configuration to avoid disclosing information in exception messages -->
      <service name="EPiServer.Events.Remote.EventReplication" behaviorConfiguration="DebugServiceBehaviour">
        <endpoint name="RemoteEventServiceEndPoint" contract="EPiServer.Events.ServiceModel.IEventReplication" binding="customBinding" bindingConfiguration="RemoteEventsBinding" address="soap.udp://239.255.255.19:5000/RemoteEventService" />
      </service>
    </services>
    <client>
      <endpoint name="RemoteEventServiceClientEndPoint" address="soap.udp://239.255.255.19:5000/RemoteEventService" binding="customBinding" bindingConfiguration="RemoteEventsBinding" contract="EPiServer.Events.ServiceModel.IEventReplication" />
    </client>
    <behaviors>
      <serviceBehaviors>
        <behavior name="DebugServiceBehaviour">
          <serviceDebug includeExceptionDetailInFaults="true" />
        </behavior>
      </serviceBehaviors>
    </behaviors>
    <bindings>
      <customBinding>
        <binding name="RemoteEventsBinding">
          <binaryMessageEncoding />
          <udpTransport multicast="True" />
        </binding>
      </customBinding>
    </bindings>
  </system.serviceModel>
4. The address attribute values in both the service and client endpoint sections specify a UDP multicast address and port. This may be changed as desired but the IP addess MUST be a UDP multicast address. Firewalls will need to allow communication on the port chosen if multiple servers are used and are seperated by firewalls.

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 

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. The EPiServerRemoteEventsListener 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.

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 UDP traffic on port 5000 or the port chosen if different.
• 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