Remote Event Receivers in SharePoint 2013

Event receivers in earlier versions of SharePoint primarily ran on the SharePoint Server to handle events that occurred on SharePoint objects such as list, libraries, site etc.

In SharePoint 2013, a new concept, Remote Event Receivers, has been introduced, where the event generated by a SharePoint app could be listened to and handled by the SharePoint Server.

In other words, we could create SharePoint Apps (that is a standalone module of code that is complete in itself and can be installed / uninstalled independently on a Client) that can act as event generators. The handlers can be written using web services. These are very similar to the event receivers in the earlier version - except that these work in remote clients. This provides substantially more scope for including useful functionality in our SharePoint Apps.

For example I can think of an app that can notify the user when a new category of tickets for a train are published (or even tickets become sold out or fall below a threshold value), so the user could expedite the process of decision making and book a ticket before it is all sold out. Of course, here the basic assumption is that there is a SharePoint based app that holds a list that contains the ticket availability for trains (and that is continuously updated when tickets are sold out).

Remote event receivers are done by means of Web services, that listen for events to occur. Instead of running code on the SP server, the app fires an event that is handled by this web service. By registering a remote end-point we can invoke either a one-way or two-way event receiver. Visual Studio 2012 provides templates to create a Remote Event Receiver, that creates the skeleton for this set up, that we can build on, to meet our requirements. By default, when we use Visual Studio 2012 to create the remote event receiver, there are 2 methods in the WCF service; they are:

1. ProcessEvent() that handles events that occur before an action occurs, such as when a user adds or deletes a list item. This is a synchronous event (2-way that can handle "-ing" (current) events) that can call-back to SharePoint, for example cancelling an addition to a list
2. ProcessOneWayEvent() that handles events that occur after an action occurs, such as after a user adds an item to a list or deletes an item from a list. This is an asynchronous event (1-way that can handle "-ed" (past) events, fire and forget type)

In our SharePoint app, we can add a reference to the above receiver. When we do this using Visual Studio, we can observe that a manifest file and elements XML are added to the SPApp solution with the following entry in the elements.xml:

<Receivers ListTemplateId="101">
    <Receiver>
        <Name>RemoteEventReceiver1ItemAdded</Name>
        <Type>ItemAdded</Type>
        <SequenceNumber>10000</SequenceNumber>
        <Url>~remoteAppUrl/RemoteEventReceiver1.svc<Url>
    </Receiver>
</Receivers>

If we are able to look at this elements.xml file of any one event receiver in SharePoint 2010 (that was server-side event receivers), we would see the following entries:

<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
    <Receivers ListTemplateId="101">
        <Receiver>
            <Name>EventReceiver1ItemAdded</Name>
            <Type>ItemAdded</Type>
            <SequenceNumber>10000</SequenceNumber>
            <Assembly>$SharePoint.Project.AssemblyFullName$</Assembly>
            <Class>_3_Training_EventReceiverProject.EventReceiver1.EventReceiver1</Class>
        </Receiver>
    </Receivers>
</Elements>

Comparing the above 2 elements.xml, we see that instead of a .Net assembly, here in 2013, we are providing a reference to the WCF service as the receiver.

In this article, we shall see how to create the event handler in such a scenario.

The following are the high-level steps to create a remote event handler:

1. Create a SharePoint 2013 App (we will use a SharePoint hosted app here). Ensure that the AppManifest.xml has "Internal" App Principal for a SharePoint-hosted app.
   
   
   
   
2. Add a SharePoint List to the app (called a "Tickets" List)
3. In the app, provide a mechanism to add entries into this Tickets list (in our case, when the user clicks on a button, a random train name and tickets are added to the list. This is done by means of jQuery as shown below)
   
   
   
   
4. Create the Remote Event Receiver (we shall be creating a WCF Service for this purpose) to receive the "List Item Added" event on the "Tickets List". In the app's elements.xml, ensure that the URL points to the webservice's URL. (Sometimes, the convention of representing the URL in the format "~remoteAppUrl/RemoteEventReceiver1.svc" does not work. In that case, try providing the complete URL.)
   
   
   
   
5. In the event receiver, take an action based on the list item changed event. (In this case, we create an announcement in a SharePoint List to indicate that a new item had been added to the Tickets List in the App.)
   
   
   
   
6. Publish the App and trust it.
   
   
   
   
7. Launch the App:
   
   
   
   
8. Click on the button in the app to generate a train and its ticket details:
   
   
   
   
9. We can observe that the event handler has fired and a new entry has been added in the SharePoint Announcement list (within a different SharePoint Site) with the details of the train ticket details generated in the previous step.