SharePoint 2013: Remote Event Receivers

In this first article on “Remote Event Receivers”, we will understand the concept of “Remote Events” & “Remote Event Handlers” which is a newly introduced concept in SharePoint 2013.

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:

  1. App Events
    • Handle App Installed
    • Handle App Uninstalling
    • Handle App Upgraded

1

  1. List Events : All list events are supported which are kept within SPRemoteEventType enumeration
    • ItemAdding
    • ItemUpdating
    • ItemDeleting
    • ItemCheckingIn
    • ItemCheckingOut
    • ItemUncheckingOut
    • ItemAttachmentAdding

2

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”:

3

  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”.

4

  1. 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.

5

How do Remote Event Receiver Works:

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

Step2: SharePoint then look for registered Web Service Endpoint designated to handle this event remotely

Step3: 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.

6

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

7

That is all for this post on Remote Even 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. 🙂

Advertisements

SharePoint 2013 : How to Start Workflow on a List Item using Workflow Instance Service

We are here in the Fourth and Final Post in the Series of Four articles on Workflow Services.

Last three posts in this series can be reached out at the below links:

  1. SharePoint 2013 : Introduction to Workflow Services API
  2. SharePoint 2013 : How to Copy Reusable Workflows from one site to another using Deployment Service
  3. SharePoint 2013 : How to Add Workflow Associations to a List using Workflow Subscription Service

This article will take you through to the automation steps of another more common requirement i.e. “Starting a Workflow on any List Item Programmatically”.

In order to automate this task we can leverage Work Instance Service.

Assuming that you are following me all along the previous three articles of this series, and you are already aware of that we have a List with the name “Workflow Testing” in the Child Site which we had created in one of the earlier posts of this series.

We also got a Workflow Definition “Workflow on Orders in Parent Site” Copied to this Child Site and published in context of “Workflow Testing” List.

Now let see how we can start the workflow on any desired list item programmatically using “Workflow Instance Services”.

For this demo lets consider a target item “Test Item 3” in “Workflow Testing” List on which we need to start the workflow, as shown below:

1

In order to trigger the Workflow Start process, we have got a super simple UI with one HTML button “Start Workflow” as shown below:

2

Now next thing is to get into the code line by line to understand the logic behind this implementation:

1.Specify the Workflow Definition ID which needs to be started on the list item

2.Specify the List ID to which this workflow is associated

3

3.Instantiate the List Object by calling “getById” method

4.Instantiate the List Item Object by calling “getItemById” method

5.Instantiate Service Manager Object as earlier

6.Query all the available Subscriptions for the Workflow Definition based on Definition ID specified in Step 1 using Workflow Subscription Service

4

7.For a specific Subscription call “startWorkflowOnListItem” function of Workflow Subscription Service by passing following parameters to it:

  1. Workflow Subscription Object
  2. List Item ID
  3. Initiation Parameters: This is applicable only when the Workflow is expecting any Initializing Parameters in the Workflow Definition, else we can pass an empty object to the function as shown below.

5

With this we are done with code development.

Now click on the HTML Button to test the code and if the code execution succeed you will get an Alert saying “Workflow Started” as shown below:

6

In order to test the implementation from UI, we need to browse the “Workflow Testing” list and look for the target item which is “Test Item 3” in our case.

Look for the Workflow Status column for this item to see if the Workflow status has been updated as shown below:

7

Click on the workflow status to see full history of workflow execution to ensure that all operations are executed as expected.

8

Hope you enjoy this series on Workflow Services.

Please share your feedback if you find it helpful.

SharePoint 2013 : How to Add Workflow Associations to a List using Workflow Subscription Service

Welcome to the third article of the series on JSOM Support for SharePoint 2013 Workflows.

Previous Articles in this Series can be reached at the following URLs:

  1. SharePoint 2013 : Introduction to Workflow Services API
  2. SharePoint 2013 : How to Copy Reusable Workflows from one site to another using Deployment Service

In this article we will look into a more obvious issue with SharePoint Designer Workflows, i.e. moving SPD workflows from one list to another within same or a different site.

This article will explain the steps on how to automate the Workflow movements from one location to another.

In order to showcase the scenario, we need to set up the prerequisites and in the next few steps we will work on the same.

We are having a list by the name “Orders” in the Parent Site as shown below:

1

We will create a workflow in Parent Site [that will be copied to the child site later on], let’s call it “Workflow on Orders in Parent Site” and get it associated with “Orders” List as shown in the steps below:

2

This is quite a simple Workflow with one step performing Logging Operation.

Once this Workflow Definition is Created and Published, we can get the Workflow ID as shown in the Article 1 of this series.

3

Here we are all done with configuration on Parent Site.

Now lets move on to the child site, where we have got another List by the name “Workflow Testing” as shown below:

4

Browse the child site in SharePoint Designer and look for the List ID for “Workflow Testing” List as shown below:

5

Now look for “Workflow History” and “Workflow Tasks” Lists and verify if they are present and if not we need to create them beforehand.

6

With this we are all done with setting up the prerequisites for this demo.

Now let take a deep dive in the code base to understand its composition-

1.Specify the Workflow ID which needs to be copied from Parent to Child Site

2.Specify the List ID to which this Workflow needs to be associated in the Child Site.

7

3.Instantiate Object of Workflow Service Manager Object using Context of Child Site

4.Instantiate Object of Workflow History List in Child Site

5.Instantiate Object of Workflow Tasks List in Child Site

8

6.Set Workflow Details before copying it to Child Site

  • Set Workflow Name
  • Specify if the workflow is enabled
  • Specify the Workflow Definition ID
  • Specify the Workflow Status Column Name
  • Specify the Target List ID
  • Specify supported Event Types

9

7.Setting Workflow Properties

  • Setting Workflow List IDs
    • Task List
    • History List
  • We need to Set “FormData” property to blank if we don’t want to set any specific value, but must set this property.

10

8.Finally call “publishSubscriptionForList” function of Workflow Subscription Service to get the workflow published on to the target list.

11

Once this code gets execute without error, sure enough we will get the workflow created in the child site and associated with the specified list.

Following are the steps that we can take to verify if the Workflow is copied and associated as expected on the Child Site:

1.Browse the Child Site and navigate to the Workflows section and see if we get “Workflow on Orders in Parent Site” workflow created

12

2.Browse the Child Site in Browser and navigate to the “Workflow Testing”, see if Workflow Status Column with the Name “Demo Subscription Added” is created.

13

3.Start the workflow on any Item in the list and see if it is working as expected.

14

15

16

Hope this article provides you a brief idea on how can we make use of Workflow Subscription Services to add the Workflow Association to a specific list.

See you in the next article of this series.