Event Management System Specification

Introduction

This technical note contains functional and technical information for the EPiServer Events System. 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 seperate servers (load-balanced standard and enterprise).

Table of Contents

• Technical Platform
• Components
• Process Flow
• Configuration
• Testing
• Troubleshooting

Technical Platform

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.

Components

The system comprises of two main components.

• EPiServer CMS 5 Events Service.  This is hosted in the existing EPiServer Scheduler process. Its job is to receive and distribute event notifications both inter and intra machine. The inter machine protocol is UDP and the intra machine Named Pipes. However, the code is written to use the WCF bindings from the configuration file thus making the protocols “hot” swappable.
• EPiServer Site Events Classes.  A suite of classes have been written so that code within an EPiServer site can raise and receive events via the EPiServer Events Service.

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 the Scheduler process is started (via the service control manager on startup or via the services user interface) it will do the following:
1. Register a UDP listener to receive event notifications from other EPiServer CMS 5 machines.
2. Register a Named Pipe listener to receive registrations and events notifications from sites on the local machine
4. When an EPiServer 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. Register a Named Pipe listener to receive event notifications from the local Events Service.
3. Call the local Events Service via the Named Pipe channel to register its interest in receiving certain events types (e.g. cache changes). It also registers its site id and secret for use by the service to authenticate calls across the network from other servers (see point 8a) and its Named Pipe URL for the event notification callbacks.
5. Code in an EPiServer CMS 5 site raises an event with the Events Service using the events classes via the Named Pipe channel  (the Cache Manager could raise a cache changed event for example).
6. The Events Service calls all of the sites on the local machine that have registered the same site id as the sending site and if they have registered an interest in this event, via their respective Named Pipe callback channel.
7. The Events Service broadcasts the event to all the other machines in the network using the UDP channel. 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.
8. An Events Service on another machine receives the UDP broadcast and does the following:
1. Compares the site id in the message to those that have been registered by sites on the local machine. 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. Performs the same action as point 6 for 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 Enterprise Edition technote 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" eventSubscriberUrl="net.pipe://PublicTemplates/EventSubscriber">

2. The eventSubscriberUrl value above can be another value of your choosing but MUST start with "net.pipe://" as this determines the WCF protocol used by EPiServer. In the case of enterprise sites or where more than one standard site is installed on a server, this value must be unique for each site. 
3. In the <configuration> section ensure the <system.serviceModel> section is NOT commented out.
4. 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" />


5. The following points only apply to load balanced sites. Ensure that port 5000 is open in firewalls for UDP traffic between the two servers. If another port is to be used, the following should be adjusted in the EPiServer.SchedulerSvc.exe.config file (which should be found in Program Files\EPiServer.Scheduler):
6. In the <endpoint> section for the RemoteEventService change the address attribute value from "soap.udp://239.255.255.19:5000/RemoteEventService" to "soap.udp://239.255.255.19:XXXX/RemoteEventService" where XXXX is the new port number.
   
    

   <configuration>

     <system.serviceModel>

       <services>

         <service name="EPiServer.Events.Services.RemoteEventService">

           <endpoint name="RemoteEventServiceEndPoint" address="soap:udp://239.255.255.19:5000/RemoteEventService">
7. In the <endpoint> section for the RemoteEventServiceClientEndPoint change the address attribute from "soap.udp://239.255.255.19:5000/RemoteEventService" to "soap.udp://239.255.255.19:XXXX/RemoteEventService" where XXXX is the new port number (ensure the port number is the same as in the previous step).
   

   <configuration>

     <system.serviceModel>

       <client>

         <endpoint name="RemoteEventServiceClientEndPoint" address="soap:udp://239.255.255.19:5000/RemoteEventService">
8. On both servers, ensure the EPiServer CMS 5 Scheduler service is set to start automatically and ensure it is started.

Note: if enableEvents is set to true but enableRemoteEvents is set to false then any events raised will only be distributed to listeners 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 machine and other machines. 

Testing

Examples of the EPiServer CMS 5 functionality that uses 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 on #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 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 machine and by other machines on the same network. This can be useful to determine if firewalls or other software is blocking the EPiServer 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 are open that EPiServer Events uses. 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.