SharePoint 2013: Remote Event Receivers

The last three posts in this series can be reached at the below links:

• SharePoint 2013: How to Start Workflow on a List Item Using Workflow Instance Service
• SharePoint 2013: How to Copy Reusable Workflows from one site to another using Deployment Service
• SharePoint 2013: How to Add Workflow Associations to a List using Workflow Subscription Service

What are Remote Events & Remote Event Receivers

Remote Events are meant to be considered in context of SharePoint Apps only, since the newly introduced SharePoint Apps Model has got restrictions on how the code should be executed in SharePoint Environment.

SharePoint Apps Model restricts the Apps to execute any server side code within SharePoint execution boundaries. But there are scenarios where it becomes really necessary to handle certain Events during the App Life Cycle.

For instance this is an obvious scenario to perform any desired operation like “creating a Global Settings List in Host Web” during App Installation, similarly it is also a valid scenarios where an Email notification needs to send to the App Users with some of the relevant information regarding the app or taking backup of the App Data or Settings on to the Host Web before actually removing the App during App Uninstallation.

Due to such valid business cases, it is necessary to have a mechanism to handle such events from within the Apps and that’s where Remote Event Handler comes into play.

There are broadly two types of Remote Events most likely to be triggered out of an App:

App Events

1. Handle App Installed
2. Handle App Uninstalling
3. Handle App Upgraded
   
   

List Events: All list events are supported which are kept within SPRemoteEventType enumeration,

1. ItemAdding
2. ItemUpdating
3. ItemDeleting
4. ItemCheckingIn
5. ItemCheckingOut
6. ItemUncheckingOut
7. ItemAttachmentAdding
   
   

The listed events are just a few out of the complete list of Events that are exposed as Remote Events.
For the complete list of Remote Events you can visit SPRemoteEventType Enumeration.

In order to handle all of the above listed Events SharePoint provides following two Handler functions via an Interface “IRemoteEventService”:

1. ProcessEvent: This is “Before or Synchronous” Handler, which executes before any action (like List Item Added/Updated/Deleted) takes place. This is a Two-Way Event Receivers which means it takes instructions from SharePoint based on User Actions (List Items Added/Deleted), Process it and returns back the result to SharePoint. This function has a return type of type “SPRemoteEventResult”.
   
   
   
   
2. ProcessOneWayEvent: This is “After or Asynchronous” Handler, which executes after any action (like List Item Added/Updated/Deleted) completed. This is not a Two-Way Handler so it will just accept the instructions from SharePoint based on User Actions (List Items Added/Deleted) and does not returns back any result or notification to SharePoint. This function should be mainly employed for operations like Logging, Sending Notifications to App Users and so on.
   
   

How do Remote Event Receiver Works

Step 1: User Performs Operations that generates an event in SharePoint [Be it App or List Events].

Step 2: SharePoint then look for registered Web Service Endpoint designated to handle this event remotely.

Step 3: Web Service Endpoint process the instructions based on the Event generated from within SharePoint and returns the result back to SharePoint.

In order to perform any action directly from within the Web Service, Web Service Endpoint needs to call Access Control Service to obtain its own signed token.



SharePoint provides the TokenHelper.cs Class file which can be used to make request for necessary tokens.



That is all for this post on Remote Event Receivers.

Hope you will find it helpful.

In the upcoming articles on Remote Event Receivers we will explore the implementation details and see each of the types of Events Receivers in action.

So sit tight and stay tuned.