Remote Event Receivers – you’re all doing it wrong

Remote Event Receivers are a powerful way to integrate custom code into your SharePoint Online environment.  Essentially a Remote Event Receiver is a hook that allows you to execute your code in response to an event that occurs in SharePoint.  There are several techniques for responding to events in SharePoint Online, but the Remote Event Receiver is the most powerful. It offers dozens of different events to attach to and allows you to configure synchronously or asynchronously. It is also very easy to attach, develop, deploy, test, and maintain. Is also very misunderstood.

Remote Event Receivers were introduced along with SharePoint 2013 and the arrival of the App model. Microsoft provided tooling with Visual Studio to create Remote Event Receivers, but unfortunately the only way to expose this tooling was in the context of a Provider-Hosted App.

This is unfortunate because Remote Event Receivers have nothing to do with Provider-Hosted Apps. In order to develop a Remote Event Receiver using the Microsoft-provided tooling, a developer had to create a Provider-Hosted App project and deploy their RER along with it. This added a great deal of complexity to the development effort, and made packaging and deployment a painful and tedious experience.

To further complicate things, Microsoft decided to wire up a WCF service as the endpoint in its RER tooling. This is sheer lunacy, even back in 2013. A web API project would have been simpler and would be more in line with Microsoft development tooling efforts. The opacity and complexity of WCF made RER development even more cumbersome. Actually, I believe they decided to use the WCF service so the development experience would be similar to that of old-school Event Receivers, with the ability to use a deserialized Event Properties object.

Building a Remote Event Receiver is Easy

In truth, it is remarkably simple to configure, develop, deploy, and maintain a Remote Event Receiver, but in order to do so you must completely abandon the Microsoft tooling and just set up the pieces yourself. Luckily there are really only two components to a Remote Event Receiver:

  • The endpoint
  • The registration

The registration is where you tell SharePoint, “call this endpoint every time this event occurs”. The CSOM provides mechanisms for adding Remote Event Receivers, but the details depend somewhat on the type of event receiver being deployed. The  PnP PowerShell library provides the ability to register a Remote Event Receiver in a one-liner. For example, to set up an RER that is invoked every time an item is updated on a list, execute:

Add-PnPEventReceiver -List "Tasks" -Name "TasksRER" -Url https://my-rer.azurewebsites.net/Service1.svc -EventReceiverType ItemAdded -Synchronization Asynchronous

More about registering Remote Event Receivers

The endpoint is just a web service listening at a certain URL, and you have lots of options for this. A Web API project would work great for this. Azure Functions are also a very compelling option. You are also free to write services in Java, Node or whatever other technology you can think of. In the example below, we’ll use the canonical WCF Service you’d get with the Visual Studio item template, but we’re going to sidestep the template and wire things up ourselves. It’s actually easier this way.

 

Creating the Remote Event Receiver shell

In Visual Studio,

  1.  create an empty ASP.NET web application
  2. Add the Nuget Package ”AppForSharePointOnlineWebToolkit”.
  3. Add a new item of type WCF Service to the web app.
  4. Get rid of the IService reference and set your service to implement IRemoteEventService, which lives in the Microsoft.SharePoint.Client.EventReceivers namespace. This namespace came into the project with the Nuget packages we added earlier. Resolve the squiggly to implement the interface stubs.

Your service class should look something like this:

RER-stub

F5 your project and navigate to the service to make sure it’s accepting requests. Take note of the port number.  We’ll need that to set up our proxy for local debugging.

Locally debugging your remote event receiver

To test this event receiver locally, we’ll use ngrok. According to its documentation, “ngrok is a reverse proxy that creates a secure tunnel from a public endpoint to a locally running web service.”  We will use it to map an Internet endpoint to our local machine so we can intercept and debug requests coming from SharePoint Online.

Assuming you have installed Node.JS and ngrok, create your proxy by executing the following. 56754 is the port number hosting my local WCF service.

ngrok-1

Once it connects it’ll output some data, including the public URL of our proxy connection:

ngrok-2

Next, open up a browser and navigate to the ngrok URL, append the service endpoint, and you should be able to see that the ngrok URL is returning your service.

ngrok-3

 

Next we’ll attach our event receiver to a SharePoint list. Using the PnP PowerShell cmdlet shown above, we’ll add a Remote Event Receiver to our site. Make sure to open a new PowerShell session for this and leave the ngrok session running in its window. The proxy will be released when the window is closed.

Now, set a breakpoint in your ProcessOneWayEvent method, add a task to the list and make an edit to it.  If all goes well your local web service will be called and the breakpoint will hit:

rer-2

Make sure you closely inspect the properties object in the debugger, and get a feel for all the data that’s in there. For this particular event we’ll want to check out ItemEventProperties and ItemEventProperties.AfterProperties for some useful metadata that gets passed into the service.

Deploying your Remote Event Receiver to Azure

When you are ready to deploy to the Internet you can deploy to Azure just like a normal web application. You’ll want to run Add-PnPEventReceiver using the Internet URL to register your event receiver for real, of course.

 

Advertisements

Microsoft Flow: First Impressions

Over the last several weeks I’ve had my first experiences using Microsoft Flow in a real-world application. The client has dozens of old 2010-style SharePoint Designer workflows touching a number of business functions: Sales, Procurement, Change Management, and Human Resources, and they were looking for a way to modernize their development process and eliminate some of the quirks and irksome bugs that have been plaguing their users.  Hearing that the client was looking down the road at moving from on-premises SharePoint Server 2013 to the cloud, I recommended re-writing a number of these processes in Flow instead of SPD.

flow

Flow is a part of Microsoft’s new cloud-based platform for process modeling, for lack of a better phrase. The idea is that non-developers can use Flow’s intuitive user interfaces to build robust integrations between their line of business applications with no code anywhere to be found.

At first glance, Flow seems to be a huge improvement over the experience of building workflows in SharePoint Designer. For starters, it’s web-based, so there’s nothing to install. Flow comes with an impressive array of standard integration points (“connectors”), a handful of entry points (“triggers”) and hundreds of pre-defined activities you can configure (“actions”).  By dragging and dropping widgets onto the control surface and setting up some basic properties, power users can create powerful applications without having to rely on developers or IT to set it up for them.

Here are a few quick takeaways from my experiences so far.

Low expectations

SharePoint Designer workflows come with so much baggage it’s difficult to imagine preferring it to any succeeding technology that comes along. So the bar here is low.

Wide range of capability

Flow’s range of out-of-the-box integration points is very impressive, and they keep adding new connectors and actions all the time. There’s even an extension model where you can create your own and submit them for inclusion in the platform.

More of a consumer focus

Many of the integration points, though, don’t seem to make a lot of sense in most enterprise scenarios. Twitter, Facebook, and Gmail are some such connectors. And many of the starter templates are more in the personal productivity realm. For example,

  • Text me when I get an email from my boss
  • Email me when a new item shows up in a SharePoint list
  • Start a simple approval process on a document when it’s posted
  • Save Tweets to an Excel file
  • Send me an email reminder every day

 

Easy to extend

It’s really simple to create extension points in Flow. Suppose you have a need to do something that isn’t supported by a Flow action. If you can code, you can write an API to do what you need, and call it via an HTTP action.  Azure Functions work really well for this. In fact, the HTTP action is the most powerful thing in Flow. You can even use it to trigger other Flows from within a Flow.

Approvals are not fully baked

If you’re building approval workflows and are expecting the way SharePoint Designer works, you’ll be disappointed. An Approval in Flow consists of an email and a two buttons, nothing more. There is no concept of setting a status on an item, no functionality for logging (unless you roll it yourself), and no notion of tasks. It changes the way you think about approvals in general, because the old model just doesn’t apply here.

The Designer does not scale

For a simple two- or three-step flow, the designer works great. Add a couple of nested if/else blocks (‘conditions’), or more than a half-dozen or so actions, and you’ll find that  the design surface is totally unsuited to the task. Scroll bars are in difficult-to-find places and it’s often next to impossible to maintain your context when trying to move around within a Flow.

Sometimes saving a Flow will trigger a phantom validation error, and you’ll have to expand every one of your actions until you find the offending statement, because the Flow team have not seen fit to provide any sort of feedback on where the failure occurred. In addition, sometimes, especially when working with variables, the validation will fail even though the variable is properly configured.

No Code view

As clunky as the designer gets, if you’re a developer you might be more comfortable just coding your Flow the old fashioned way – after all, it’s just JSON under the hood. But alas, code view is not available in Flow. The design view is all you have.

Another implication of this: If you have places in your Flows where there are large blocks of similar functionality, you have no option to copy blocks of code and modify to suit. You’re stuck having to re-create those similar blocks of functionality, manually, in the designer, every single time. Believe me, this gets old really fast.

No versioning

If you make a change to your Flow and somehow break it, well, that’s tough, you’d better figure it out because there’s no rolling back.

Clearly Flow is not the magic bullet in the Enterprise process modeling world. It has is quirks and its pitfalls. But remember, the bar is low due to the legacy application it replaces.  SharePoint Designer workflows share many of the same deficiencies as Flow: a clumsy design experience (check), an inability to edit code directly (for all practical purposes), and no rollback model (technically possible in SPD via version history but janky as hell).

Given that SPD has had its ten-plus years in the limelight, and Flow is a brand-new V1 product with an engaged product team, I’d say the future looks bright for Flow.

Setting multi-valued lookups in forms with jQuery

The solution presented here can be made to work in 2007, 2010 or 2013. I’ll explain later.

Setting SharePoint form fields using jQuery is a pretty standard practice nowadays, and not too hard either. We can fetch the current user, or a value in the query string, and use it to populate form fields, saving our users from having to do it themselves.

Multi-valued lookup columns, however, are not so easy to figure out, and understanding them requires some deep DOM inspection and trial and error.

Consider the form below. It could be an edit form or a new form, it doesn’t matter. They both work in the same way.

screenshot1

Here I have a multi-valued lookup column called “Project Document” with a number of documents in the parent library. The form shows two large text boxes (‘unselected values’ and ‘selected values’), along with an “add” and a “remove” button to shuttle the parent list items between the two text boxes.

Now you’d think that moving the choices from one text box to the other would be enough to “set” the value in the form, but you’d be wrong. Microsoft uses hidden elements to hold the “true” values present on the form, so in order to set that value we have to update both the visible and invisible elements in the form.

Digging into the DOM

The image below shows the DOM representation of the visible elements we are concerned about. This shows a 2013 environment, but the markup is the same in 2010, at least for this part of the form.

screenshot2

What we see here is the two text boxes (rendered as selects) along with options, about 20 or so in the “unselected” textbox, and one, titled “SET READ ONLY DATABASE” in the “selected” text box. Notice the title attributes on these selects, “Project Document possible values” and “Project Document selected values”. We will refer to these as we “move” an option from one select to the other using jQuery.

The second part, the part SharePoint uses under the hood to actually save the lookup values, is a hidden input element located just above the visible UI we have just seen.

screenshot3

There are actually three hidden input controls here, but we only care about the topmost one. It does not have a handy title attribute, but it has an ID of longstringofcrap_MultiLookup. This is the place where 2010 and 2013 are slightly different. The ID is a little different in 2010. We’ll fetch the input using jQuery by using the “ends with” selector, like so:

“[id$=’MultiLookup’]” for 2013 and “[id$=’MultiLookupPicker’]” for 2010.

The hidden input that stores the actual data for the selected items does so in a peculiar, pipe-delimited format. I’ll leave it to you to soak it in and try to make sense of it:

screenshot4

In our function we will need to create that crazy string using the option’s text and value along with that pipe-T thingy, and add or remove it from the input’s value attribute as needed.

Putting it all together

I wanted to write a function to add a selection by name, and another function to remove a selected option, also by name. I also wanted it to be as reusable as possible, so I made the column name and value as parameters to my functions. By including these functions in a globally-referenced JavaScript file, we can use this functionality everywhere on the site. Anyway here’s the code:

//var selector = "[id$='MultiLookupPicker']"; //for 2010 or 2007
var selector = "[id$='MultiLookup']"; //for 2013

function addChoice(text, columnName) {
    $("[title='" + columnName + " possible values'] option").each(function () {
        if ($(this).text() == text) {
            $(this).appendTo($("[title='" + columnName + " selected values']"));
            var multilookupPickerVal = $(selector).val();
            if ($(selector).val() == undefined || $(selector).val().length == 0) {
                $(selector).val($(this).val() + "|t" + $(this).text());
            }
            else {
                $(selector).val(multilookupPickerVal + "|t" + $(this).val() + "|t" + $(this).text());
            }
        }
    });
}

function removeChoice(text, columnName) {
    $("[title='" + columnName + " selected values'] option").each(function () {
        if ($(this).text() == text) {
            $(this).appendTo($("[title='" + columnName + " possible values']"));
            var multilookupPickerVal = $(selector).val();
            var valToRemove = $(this).val() + "|t" + $(this).text();
            var newValue = multilookupPickerVal.replace(valToRemove, "");

            $(selector).val(newValue);
        }
    });
}


A couple of things to point out. I added two variable declarations called “selector”. Make sure only one of them is not commented out – the appropriate one for you environment. For updating the visible text boxes I am using the jQuery appendTo function, a really neat function which removes a DOM element from its current home and places it into the specified location.

Edit: Thanks to jameel’s comment below I fixed an earlier issue where I was hard coding the column name in the function. He also verified the 2010 code works for SharePoint 2007 as well.

Managing SharePoint Online with PowerShell

As a SharePoint developer and MSDN subscriber I was thrilled when Microsoft announced that it was offering a SharePoint Online subscription as part of the base benefits of an MSDN subscription.  Being able to automate administrative tasks in SharePoint Online is a big help to those of us who don’t want to click through an interface every time we need to do something.  To address this Microsoft has released the SharePoint Online Management Shell. 

Getting a SharePoint Online environment

 First, you need a SharePoint online environment.  If you are an MSDN subscriber, you already have one included in your subscription.  If not, the Developer Subscription costs $99 per year. There are also a number of Office 365 plans that include SharePoint online site. These come with a per-user monthly charge.  There are also 30-day trials available.

Installing the SharePoint Online Management Shell

Setting up the PowerShell tools for SharePoint Online is easy and only takes a couple of minutes.  You’ll need to be on PowerShell 3.0 first though.  If you’re running Windows 8 or Server 2012 you’re in luck, it’s already there.  If not it’s available for Windows 7 and Server 2008 and 2008R2 here.

Next, download the appropriate executable here, and execute it.  That’s all there is to it.

Connecting to your environment

Once the install is complete, you’ll now have a new program installed called “SharePoint Online Management Shell”.  You’ll need to launch this. Before interacting with your SharePoint environment you’ll need to connect to it, and that is done through the cmdlet connect-sposervice. This cmdlet takes a url and administrator credentials as parameters.  There are two ways you can run this.  Omitting the password will prompt you with a log in screen. To include the password, you’ll need to create a PSCredential object and pass that into the command:

$username = "admin@contoso.sharepoint.com"
$password = "password"
$cred = New-Object -TypeName System.Management.Automation.PSCredential -argumentlist $userName, $(convertto-securestring $Password -asplaintext -force)
Connect-SPOService -Url http://contoso-admin.sharepoint.com -Credential $cred

(this snippet was taken straight from the Technet documentation)

It’s important to note that the url you pass in must be the  url of the administrative site, the one that looks like this:

admin

When running Connect-SPOService, the “no news is good news” rule applies, and if it succeeds you will just see a new command prompt on the next line.

Let’s do something!

All of the available commands in SharePoint Online Management Shell have to do with creating, deleting, or maintaining site collections. To create a new site collection run the following command:

New-SPOSite -Url https://contoso.sharepoint.com/sites/accounting -Owner admin@contoso.com -StorageQuota 100 -NoWait -ResourceQuota 50 -Template STS#0

(again, code sample lifted from technet)

The full list of SharePoint Online cmdlets can be found here.

 How does it work?

Whenever you are working with tools that access remote environments, it is always illuminating to figure out the underlying technologies that make it work.  In this case I launched Fiddler and ran a few commands.  Here’s what I saw the first time:
 

fiddler

That call to client.svc is the calling card of the SharePoint Client Side Object Model. It looks like the call to lists.asmx was simply to fetch a Form Digest so the CSOM call could use that to authenticate.  Subsequent commands run from the shell do not make this call, so I am guessing the Form Digest is still valid in this case.

It’s interesting to note that the ability to manage site collections is a new feature in the CSOM for 2013.  This functionality would not have been possible in 2010.

Limitations

On-Premise SharePoint PowerShell tools are quite powerful and can be used as a text-based SharePoint Manager to discover all sorts of things about your SharePoint environment.  I routinely use PowerShell to look at things like list and view schemas, field definitions, web properties, and the like.  Developers who are comfortable with using PowerShell in this fashion will find the array of commands available in SharePoint Online a little limiting.  There is no way in this tool to manage objects below the site collection level.  It appears this is strictly an administration tool.

Become a great SharePoint developer in 10 easy steps

The job market for SharePoint developers is really hot lately, and right now it’s a really nice place to be from a career perspective. There just doesn’t seem to be enough of us around, and those who are can expect to be courted quite aggressively by recruiters (at least that has been my experience). With that in mind I thought I’d put together a list of steps to becoming a great SharePoint developer and getting in on the action:

1. Be (or become) really good at solving problems. When developing SharePoint solutions, you will quite often find yourself doing things that no one has ever done before. While this is true for any type of software development(I mean, if someone else has already done it they’d just use that), it seems especially true for SharePoint development, for a number of reasons:

a. There are just not that many SharePoint developers, and the more advanced your problem the fewer people there are doing something similar;
b. The sheer size and scope of the SharePoint platform means there is lots of unexplored and undocumented territory, and every now and then you’ll search on some aspect of SharePoint and find zero hits online.
c. SharePoint rarely exists in a vacuum. There are always integration points and little quirks that are unique to the organization deploying the product. These often center around network irregularities, legacy systems, business processes, or cultural issues within the organization. Any of these points, and more, can throw wrenches into your solution.

So all these things add up to one thing: you’d better be really good at solving these issues, because there is often nowhere to turn if you can’t figure them out.

2. Have access to a SharePoint environment. And when I say “access”, I really mean a complete development farm over which you have full control. Having your own environment opens up the following opportunities:
a. The freedom to make mistakes. Software development is about “poking the box”, as Seth Godin would say. That is, you learn by trying new things, making mistakes, and drawing lessons and understanding from them. Having your own environment means you can make all the mistakes you need to, roll back and keep going.
b. Your own security sandbox. Security is an important aspect of SharePoint solutions, and you’ll need the ability to create accounts and alter the privileges of those accounts. Suppose you are building a workflow that routes to different users. Without the ability to create and use different accounts, how on earth are you going to test that workflow?

If your employer is trying to get you to learn SharePoint and they have not provided you a full SharePoint server to use, they are setting you up for an uphill and frustrating experience.

3. Get some real-world problems to solve. Real-life solutions in SharePoint are rarely as straightforward as training or demo scenarios would make it seem. It is managing those quirky idiosyncrasies peculiar to the customers’ way of doing business that separates the competent devs from the pretenders. Workflows, especially, tend to get very tricky when you try to automate real-world business processes. Hands-on labs are a great way to get introduced to a topic, but once you’ve done them, try to apply them to the way things would actually work in your environment.

4. Get to know SharePoint’s user interface really well. Smart SharePoint developers know to leverage the out-of-the-box capabilities of the platform as much as possible. This means having a firm grasp on how to use SharePoint’s various UI components properly. The Ribbon, the ECB, Site Actions, List Views, Forms, layouts pages, web parts – each of these components, and more, lend a unique aspect to the SharePoint ecosystem, and knowing when and where to deploy these items will pay off in a number of ways. For example, leveraging OOB components will simplify your development efforts and result in a more consistent experience for your users. Knowing this will also come in handy when practicing skill number 5….

5. Learn to do things the SharePoint way. SharePoint is a funny platform. In many ways it gives you a lot of freedom, but it will punish those who take too much of that freedom. I see this a lot with user interfaces. Sure, in theory you can build lots of custom web parts and user controls and layouts pages to build out your screens exactly how you want them. Just know that if you do this as a default approach you are exposing yourself to some risks:
a. You are building an unnecessarily complex solution, which will lead to bugs, maintenance overhead and place more burden on your administrators.
b. You are likely missing out on a great deal of out-of-the-box SharePoint functionality. For example, if you are building a custom solution to show a grid of data, you are losing the ECB, the Ribbon, and some nifty sorting and filtering functionality, not to mention the security trimming, which you’ll now have to manage yourself. A common List View provides all this and more, and can be quite flexible through customization.

Also included with this skill is knowing how to push back when requirements are out of line with SharePoint’s expectations. You’ll need to seize these opportunities to educate your customers on “the SharePoint Way”.

6. Find a mentor. Trying to learn SharePoint on your own is an uphill struggle, and when you hit a wall you need somewhere to turn for help. Blogs and MSDN will only get you so far, and much of the content you’ll find on the web is either not useful or downright wrong – until you figure out where to look and whom to trust. Having a mentor or a network of colleagues will be a major asset, and if you are lacking this you’ll want to look for a user group or at the very least an online community like stack exchange to bounce ideas and ask for help.

7. Learn the internals of SharePoint. While the first six traits I outlined were mostly non-technical in nature, the remaining skills will cover the technical aspects of the things a SharePoint developer needs to know. Foremost on that list is an understanding of the underpinnings of SharePoint. There is a lot to learn here, but most of it is found in the “hive”, or the file system location where SharePoint’s files live(this is known as the ’14 hive’ in SharePoint 2010). The 14 hive is a treasure trove of useful information, and by looking through it(on a development machine of course), one can learn a whole lot about how Microsoft builds things. Among the useful things you can browse in the hive include:
○ Features
○ Layout pages
○ JavaScript files
○ Site Definitions and Web Templates
○ XSLT files
○ Images
○ Configuration files
○ User controls
○ Resource files
○ Much, much more

An understanding of how SharePoint is put together will help you understand how to extend it, and will offer clues as to the right way to do things when you are stuck(which will be often).

8. Learn .NET. SharePoint heavily leverages .NET, and any non-trivial solution you build will likely involve some amount of .NET integration. Knowing how to code in .NET is crucial, of course, but of equal concern is knowing the internals of .NET. Deploying an assembly to a SharePoint farm is a complex process, and you must master the various ways to deploy and register assemblies, modify and troubleshoot configuration entries, and advanced debugging techniques.

9. Get to know the Windows Infrastructure ecosystem. I’ve said it before, SharePoint doesn’t exist all alone by itself. It is tightly integrated with several Windows products, and getting comfortable with SharePoint means getting cozy with these systems as well, including Windows Server, SQL Server, and IIS. You may optionally find yourself dealing with other players as well, including Exchange, SQL BI, and the Office client. A knowledge of WCF and Workflow Foundation will likely come into play at some point as well.

10. Build solutions, not customizations. Many people who call themselves SharePoint developers never launch Visual Studio. While it’s true you can build great solutions in a very short time without ever using Visual Studio, the benefits of that approach will diminish in the long run. These “customizations” are one-off solutions and cannot be repeated unless the work is re-done. Since there is no source code associated with these efforts, maintenance becomes a dicey affair, and when a solution is broken, there’s often no way to resurrect it.

A professional SharePoint developer will use Visual Studio to build a repeatable, deployable solution package which can be deployed and activated on a site. He will follow the same processes as a custom-code solution, with source control, testing, deployment, and support.