In this fourth article in the series on Remote Event Receivers, we will look into some of the applicable business cases around the Remote Event Handlers.
You can reach the previous three articles in this series as follows:
- SharePoint 2013: Remote Event Receivers
- SharePoint 2013: How to develop Remote Event Receivers for App Events
- SharePoint 2013: How to develop Remote Event Receivers for List And List Item Events
We will investigate the working of the following scenarios which are quite obvious while working with SharePoint List & List Items.
Scenario 1 – How to restrict users to delete a certain item
In order to show case this scenario let’s consider an Item “Product-001-1” added to the List called “Products” as shown below:
Now let’s try to delete this item as highlighted below-
As soon as user try to delete the item SharePoint looks for any registered Event Receiver with the List and looking for its Receiver Definition to see what all event this Receiver is allowed to receive and executes it.
In our case we have registered the following Receiver Definition with the list-
Let’s investigate the code for register Remote Event Handler –
Since this a Before Event (as explained in one of the earlier post “SharePoint 2013: Remote Event Receivers”), we need to write the Code in “ProcessEvent” Method.
Step 1 is to check the type of Event that triggers this Event Receiver by making use of “SPRemoteEventType” Enum and “EventType” Property of the “SPRemoteEventProperties” object
Step 2 is to check the List Title by making use of “ItemEventProperties” collection of “SPRemoteEventProperties” object and ensure that we are handling Delete Events received only from a specific which in our case is “Products”
Step 3 is to check for the desired condition and if satisfied then set “ErrorMessage” and “Status” properties exposed by “SPRemoteEventResult” object.
In this case we have set a user friendly message and set status to “CancelWithError”. For all the valid status values we can look for “SPRemoteEventServiceStatus” Enum.
Step 4 is to return the SPRemoteEventResult object back to SharePoint
The setting we did in Step 3 will let SharePoint to terminate the event raised due user action and return the error message to SharePoint which would be rendered as Error Message for the user as highlighted below-
Scenario 2 – How to get Item Details after Item has been updated
In order to show case this scenario we can consider the same item as above and this time let’s let Edit the item as highlighted below
Now next thing is to investigate the code for registered Remote Event Handler –
Since this an After Event (as explained in one of the earlier post “SharePoint 2013: Remote Event Receivers”), we need to write the Code in “ProcessOneWayEvent” Method.
Step 1 & Step 2 are same as mentioned above
Step 3 is to fetch the Items Properties by making use of “ItemEventProperties” collection and preparing a variable to make it use later
It is worth noting that at this point, “ItemEventProperties” collection will contain the Properties of the List Item after the Update got succeed, which means that we can find all the updated values in the respective columns for the list item as highlighted and can consume as needed
Just to keep the story simple we are consuming these values in compiling a message to be written to Windows Event Log.
It is important to notice how we are accessing values of “Title” & “Price” Columns of that Item.
Step 4 is to write this message variable to Windows Event Log
Once execution is successful we can see the message logged in the Windows Event Log as shown below
Scenario 3 – How to validate User inputs using Remote Event Receivers
This scenario will talk on validating user inputs and terminate the execution as soon as the input value falls outside the valid value range.
For instance in this demo we are assuming a hypothetical business requirement demanding “Item Price should not exceed $300”
In order to showcase this validation scenario we can consider the same Item as mentioned above.
Let’s edit the item as shown below
Now specify the Item Price any greater than $300, here we are updating the Product Price as $350
As soon as we try to save the item, SharePoint handover the control to Remote Event Receiver which is registered with this list on Item Updating Event and Event Receiver validate the Item Price value against the specified business logic which on fail produces the error message “Price cannot exceed $300” as highlighted below-
If we look into the logic driving this business requirement we can see
Step 1 is to write the code in “ProcessEvent” handler as this action of updating the List Item is a Before Event [ItemUpdating]
Step 2 is to identify the Event Type and ensure that the business logic should be executed only in case of ItemUpdating event
Step 3 is to identify the Source of Event and ensure to handle the event only if the Source is “Product” List
Step 4 is to read the value of “Price” Field entered by the user
Step 5 is to validate the input Price value against the needed business logic
Step 6 is to set the “ErrorMessage” and “Status” Properties of the SPRemoteEventResult object. Set “Price cannot exceed $300” as Error Message and “CancelWithError” as Status. These properties let SharePoint to terminate the Event generated and no updates to the Item will get persisted.
Finally Step 7 is to capture information about the Item and Event and write it back to Windows Event Log.
These few simple scenarios might help you to understand the mechanics and objects exposed by Remote Event Receiver API that can be extended to achieve even more complex business scenarios at hand.
Hope you find it helpful…
by Prashant Bansal via Everyone's Blog Posts - SharePoint Community
No comments:
Post a Comment