Presentation deck: Modern SharePoint development – techniques for off-box code

I recently gave a couple of talks at the SharePoint Evolution 2014 conference (a roadshow no less! Check out the tour bus to the left!) I spoke in London and Cambridge - I had a great time as a speaker, and had some great conversations with attendees.

I created some new materials for these talks (slide decks/demos etc.) and will publish links to these over the next couple of posts, starting here. For the first time, I’ve recorded my demos and published the videos to YouTube (links in the slide deck) – so hopefully much of the information conveyed in the demos is available too.

"Modern SharePoint development - techniques for moving code off SharePoint servers"

Background

Almost 2 years after many of us first began to get exposure, it’s fair to say that “SharePoint apps” are not going away. Although Microsoft certainly have changed tack on some things in the SharePoint dev world, it does seem that the apps/remote code model is something that Microsoft are committed to and will continue to invest in. Whilst they’re not right for every scenario, I generally do also buy into the message that building solutions in this way can help even for on-premises deployments. Some specific points here include:

• Greater isolation – an app running “off-box” cannot bring down SharePoint for the entire organization
• Ease of upgrade – less customizations made in SharePoint, the easier upgrade (e.g. to SharePoint 2015) becomes
• Possibility of transitioning to cloud – if the organization is even half-considering a move to Office 365 (e.g. in the next few years), building solutions the “cloud-friendly” way means no/minimal re-work is required to move. Certainly we have more than one client who has asked us to build this way – because they want to leave the door open for Office 365 (or hybrid) as they move forward

Speaking to attendees I realise that for many folks, Microsoft’s push to this “Cloud Application Model” hasn’t really resonated yet. They ask “why change, especially when new skills are required and many common SharePoint things become more difficult to implement?”. Well, I do agree that it doesn’t always make sense. No-one is saying you have to do things using these techniques. If, for example, the organization is sure that the cloud isn’t the right solution for them in the next few years, and they are happy with the deal they get in managing SharePoint (including any upgrade projects they might undertake), then fine – you might be able to deliver more business value using farm solutions and full-trust code.

In general, however, I think at least an awareness of this emerging trend (towards cloud-friendly SharePoint development) is beneficial. Hopefully this slide deck is of some use here, but there are many other good resources too – I list some at the end of this article

Presentation

There are 3 main areas – each with an accompanying demo/YouTube video:

• Running code in Azure (Remote Event Receivers used as example)
• Using "PowerShell + CSOM" scripts
• Analysis of Microsoft's "AMS Samples"

Chris O'Brien - Modern SharePoint development: techniques for moving code off SharePoint servers from Chris O'Brien

Original abstract

Those implementing Office 365 know that custom code cannot run on the SharePoint servers, and remote code alternatives must be used. However, it can be valuable to adopt the same "cloud-friendly" development techniques even for on-premises implementations. In addition to increasing platform stability, this enables you to build in flexibility to your deployment - leaving the door open to a potential move to Office 365 in the future without major re-engineering. With several code-focused demos, this session examines approaches for switching to "off-box" code - including Remote Event Receivers, PowerShell and CSOM scripts, and a nod to JavaScript-based approaches. We’ll also take an in-depth look at Microsoft’s Office App Model Samples (AMS) and why you should care about them.

Resources/further reading

• Office App Model Samples
• Vesa Juvonen’s blog
• Reimagine SharePoint development

Office 365 hybrid and search – presenting results from both on-premises and SharePoint Online sites

In my previous post about Office 365 and on-premises SharePoint hybrid deployments, we discussed the idea that, whilst it can be the right solution in many cases, a hybrid deployment is NOT simple and really only encompasses search, BCS, and Duet (for SAP) integration. Other aspects around document management, sites/navigation, metadata, customizations, and perhaps any other thing you care to mention are not synchronized or joined-up in any way. As a reminder, these articles are structured like this:

1. Office 365 SharePoint hybrid – what you DO and DON’T get
2. Office 365 hybrid and search – presenting results from both sides [this article]

Even in search, one of the cornerstones of hybrid, what you get might not be what you’re hoping for – results from the “remote” environment are displayed in a separate Result Block or Promoted Result. Here’s a reminder of the (more powerful) Result Block approach:

Clearly this isn’t the best user experience. And the alternative, Promoted Results, are more about defining an individual result to appear at the top for a given search (i.e. a Best Bet) – so that’s great for individual results but not entire sets.

Last time, I discussed some of the questions and issues that can be raised by the current experience:

• How many results should be shown (from each source) on page 1?
  • HINT – you’re only allowed a maximum of 10 for a Result Block anyway :)
• What about paging? What happens when I go to page 2?
• How can I easily see more results from both sources?
• How do I determine which results are more relevant, from the local or remote environment?
• Are there any options for seeing the results in a more integrated way?

Important news on this topic (April 2014)

At the recent SharePoint Conference 2014, Microsoft stated that they were looking at this problem (of disjointed search results in hybrid deployments), and hope to have a solution later this year. So, hopefully this whole problem will go away at some point. In any case, I think it’s still worthwhile discussing the current situation and possible interim techniques to work around it.

 

Investigation – can results be merged using code?

So, given the limitations of of the current out-of-the-box user experience, I was keen to see if there are other options. Indeed, for some things we are putting together for my current client, the requirement is very much “just search across everything and show me the most relevant things!” I think there’s nothing wrong with wanting that as the user experience. So as a developer, I wondered if going direct to the search API would provide any other options – perhaps the standard search page is built in a certain way, but the API has more flexibility. I’d also previously noticed a very interesting property in the API, so I started there:

Investigation 1 - using the EnableInterleaving property on the Query class

The SharePoint search API has an interesting option which can be used when writing custom code for SharePoint search. The name of the property in the API is “EnableInterleaving” on the KeywordQuery object – this sounded promising in terms of potentially being a native way of merging the result sets. The Microsoft documentation is (currently) not hugely clear on what the setting does, at least not to me anyway:

“A Boolean value that specifies whether the ResultTable objects in the ResultTableCollection produced by running this query should be interleaved.” (from http://msdn.microsoft.com/en-us/library/office/microsoft.sharepoint.client.search.query.query.enableinterleaving.aspx).

To start testing, I configured hybrid search in my dev environment – I used the outbound hybrid model, where the search center site exists on-premises but reaches out to Office 365/SharePoint Online to bring in results from there. (TechNet documentation is at Configure hybrid search for SharePoint Server 2013, or numerous sessions at the SharePoint Conference on this next week for those attending). At this point, the out-of-the-box search results page gave me the experience shown in the image at the start of the article, with the separate results blocks (highlighted in red/blue boxes).

I then wrote some custom code which allowed me to test this config option – effectively I have a custom web part with some CSOM (JSOM) code which runs a search query using the API. I have some URL parameters which enable me to specify the query text and whether EnableInterleaving is enabled or not. Unfortunately, EnableInterleaving does NOT interleave results between Office 365 and on-premises SharePoint. The main finding is that multiple result sets are still returned (i.e. for Office 365 and on-premises), and results are not combined together in any way. One difference I did observe, is that is an additional set of results is returned (a ResultTable) for personalized results (“PersonalFavoriteResults”), but it’s empty for me (most likely because this is a non-production environment where analytics aren’t in use. I’m sure SharePoint does natively populate/maintain this under real usage – it stores results previously clicked on by the user for this search).

Conclusion: - the EnableInterleaving property does NOT help us combine search results across Office 365 and on-premises SharePoint.

Investigation 2 – manually merging results in custom code

Anyone very familiar with SharePoint search will know that for any given query (e.g. a search for the query text “SharePoint”), the search engine can return different “tables” of results – perhaps think of these as “flavors” of results. They are:

• Relevant results (“RelevantResults”)
• Best Bet results (“SpecialTermResults”)
• Personal favorite results (“PersonalFavoriteResults”)

Usually it’s the “relevant results” that we care most about – this table has the core set of results for the query. If our goal is to combine results from Office 365 and on-premises SharePoint, really what we want is a single “relevant results” table containing items from both locations. However, when we’re in hybrid mode, what we actually get by default is two separate “relevant results” tables – the image below shows my custom code rendering these tables, and you can see the similarities between this and the out-of-the-box search results page (which displays a separate Result Block for the Office 365 results):

So, if we want to display combined results (rather than separated), we *could* write some code to merge the result tables together (e.g. in memory). But what logic would we use? How should the results be sorted? Well, one of the columns returned in the result tables is “Rank” – this is the “relevancy score” of the result compared to the query which was used (all search engines have such a calculation – like Google’s PageRank). So the question is – can we use Rank to compare results from different search indexes? Is it valid to merge the two result sets together, and then sort the full list by rank? After all, this can definitely be achieved with custom code – here’s my custom web part which goes direct to the search API to do this:

I had a feeling it wasn’t valid to do this. So I asked some folks including Microsoft, other MVPs etc. for input and my suspicions were confirmed – Wictor summed it up best with this response:

“Interleaving results from two different indexes would produce very strange results. Since the ranking is based on the analytics you basically need to "normalize" the rank and analytics data between the two (or more) different indexes. Assume the user behaves differently in the different environments (which is not uncommon - one environment might be collaboration and the other some other workload such as BI).”

So in effect, you can mash up the results, but not in a way which gives you the most relevant results first (across both environments) – the sorting by rank is artificial, and shouldn’t be trusted. However, it is worth considering that if you *don’t* care about relevance/rank, then this custom approach works fine. For example, if the requirement is to display results sorted by last modified date (or by something else, such as author, site URL or whatever) then happy days! You could use this custom code approach to merge results from your Office 365 and on-premises sites just fine in those cases.

The code

If you’re interested in this approach, here’s the code to do it. I used JSOM code to execute the search, but REST should be another option. When I have the two result tables, I iterate the results in each and add to a combined collection. Finally I sort the results, with a little help from Underscore.js. All this JavaScript is referenced by a custom web part, that I deploy to my on-premises site and add to a page there. So long as hybrid is properly configured, my code can reach across to the associated Office 365 environment and obtain search results from there too.

This is the initial code to execute the search – the main thing to note here is that there is NOTHING different needed in the code to “use hybrid mode” or “enable hybrid” or anything. The results automatically come back from both sources if the infrastructure is configured. You might notice I pick up some URL parameters for the query text and EnableInterleaving properties – you would need to integrate this with your UI as appropriate:

In the success handler, some different code *is* required here. Since 2 result tables are returned, here we do some processing to combine the results into a new JavaScript array, and implement any sorting. The code below provides different options for sorting – by rank (even though we’re saying it’s not valid under hybrid), and last modified date:

..and here’s the full JavaScript code with all my helper functions etc. (NOTE: I’m still leaving it as an exercise for the reader to implement this somewhere – I used two custom web parts which referenced this JavaScript, so providing the exact implementation you need is up to you):

Summary

At the current time the user experience for search in hybrid mode isn’t necessarily as optimal as we would like it to be, because results are displayed separately for Office 365 sites and on-premises SharePoint sites. In some cases, users will just want to “search across everything” and not care where the results live.

However, under some circumstances you might be able to use custom code to “join-up” the results. Specifically, this should work well if you are happy to display results sorted by something *other* than rank – perhaps last modified date, the author name or some other piece of metadata. Sorting by rank across two SharePoint environments is not valid, since for one reason, rank uses SharePoint’s analytics framework, which operates within the scope of an individual environment only (i.e. it doesn’t do anything magical for hybrid deployments).

In the future, Microsoft will hopefully provide capability which will address this problem “natively”, without the need for custom code. Then, it will be possible to show results across Office 365 sites and on-premises SharePoint sites together. Until then, the solution presented here might be an option for you.

Using the Azure instance behind your Office 365 tenant

Something that perhaps isn’t common knowledge in the SharePoint world, is that every Office 365 tenant has an Azure instance behind it – and that if you’re doing some types of Azure stuff, sometimes you *must* use this instance. I’ve spent the last few months doing Office 365 development with some use of Azure, and this only became clear to me fairly recently. When I’ve mentioned it to other people, most have been completely unaware, and I’m not surprised when you consider that:

• There is no link from Office 365 to the Azure instance (e.g. in the Office 365 tenant admin screens)
• If you try to log-in to Azure as an Office 365 user, you initially get presented with a screen that makes you think you’ve done something wrong (as at spring 2014 time anyway)

Scenarios where you NEED to use this Azure instance

For many Azure usages (e.g. “externalizing” assets such as CSS/JS files like my team do, Azure Service Bus, Azure CDN etc.) it doesn’t matter which Azure instance you use. The most natural thing is to go the Azure Portal (https://manage.windowsazure.com) and sign-up if you don’t have a subscription already. Of course, this creates you a brand new Azure instance – and that works great for these types of scenarios. However, you’d need to use the “integrated” Azure instance for anything which needs to work with the directory of Azure AD/Office 365 users for your tenant. This could be things like:

• Implementing Azure AD authentication on an external application (e.g. a provider-hosted app, or other website), where you are aiming for some kind of Single Sign-On
• Working with some aspects of Office 365 users (e.g. the Azure AD profile which is “behind” the SharePoint Online user profile) via the Azure Graph API
• Integrating a 3rd party application which is able to use Azure AD authentication/have SSO (e.g. salesforce.com, Dynamics CRM, Dropbox for Business etc.)
• ..and many other scenarios involving identity

Accessing the Azure instance behind your Office 365 tenant

So let’s say one day you think, “I wonder how I’d get to this magical Azure instance?” Well, if you go to the Azure Portal, you’ll either see a sign-in screen asking you to enter a username to continue, or you might be auto-logged in if you have previously signed-in to the Microsoft gateway – for example, you’re already logged-in to Office 365. If you did that (even as an Office 365 tenant administrator) you’ll see this:

I don’t know about you, but my immediate reaction to that is “Whoah, obviously I shouldn’t be here logged-in as this user!” However, now is the time be brave and not flinch! Sometimes in life, it takes a valiant act of courage to push through the terrifying situations that can befall a modern-day I.T. warrior! The thing to do now is actually to click:

“Sign up for Windows Azure”

Yes, it’s counter-intuitive. As I mentioned earlier, the Azure instance already exists so why do we need to “sign-up”? Well, you just do - for now at least. I did hear a Microsoft speaker at SPC mention this experience as a side-note, and that they will probably improve things soon. The main thing to understand is that you have to supply payment details before this Azure instance can be accessed – because then it becomes a true pay-as-you-go instance.

Viewing the Azure AD directory behind your Office 365 tenant

Once you’ve gone though the sign-up process, you should be able to go into the Azure Portal (https://manage.windowsazure.com, or the new preview version https://portal.azure.com). Here, out of the all the things you can use in Azure, you’ll probably have just one thing – a Directory:

..and if you go into the Directory, you should see all your Office 365 users (including those synchronized by DirSync, if configured):

Apps which integrate with Azure AD

As I mentioned earlier, you mind yourself creating some kind of app which needs to work with Azure AD (e.g. for authentication/SSO, or some usage of the Azure AD Graph API for user records perhaps). The first step in many of  these cases is to register the app in your Azure AD directory – this is done in the “Applications” area of the directory:

Other scenarios around Azure subscriptions and identities

It turns out there are quite a few permutations of starting an Azure subscription, or joining up to an existing one. One reason for this is that in the new world of Microsoft identities, it’s possible to use a Microsoft account (formerly Live ID) OR an “Organizational Account”. If you’re an Office 365 user, your Azure AD record is an Organizational Account. Personally I’m still getting my head around some of the nuances here, but Microsoft recently released this video which talks through various Azure sign-up scenarios – if you want further information, I think it’s helpful:

Using a existing Windows Azure AD Tenant with Windows Azure

 

First Release and NDA Preview for Office 365 – early access to Microsoft’s changes for testing

One of the most interesting sessions I attended at SPC 2014 was around change management in Office 365. For those of us who have worked on Office 365 (i.e. SharePoint Online) or hybrid projects, it’s been a challenging time recently – Microsoft have made various updates and patches to Office 365, which have subsequently caused lots of customizations to break and ultimately made it hard to support organizations on Office 365. And I think it’s normal to have *some* level of customization in an Office 365 project – for some it might just be branding, but since the SharePoint user experience is still not ideal in places, our clients are often requesting enhancements around search, user profiles, sites, OneDrive for Business (the new name for My Sites) and so on. Some examples of unannounced Microsoft changes which have caused valid customizations to break are:

• The HTML change to the “title” attribute of form elements, as described by Marc Anderson at Office 365 Update Changes ‘Display Name’ on Required Fields
• Several issues reported by Andrew Connell at Office 365 Needs to Treat the UX as an API if Our Customizations are to Stay Off the Server
• API changes – changing the “throttling” on CSOM batches, so that code which previously worked now failed

Of course, a big part of this is that Microsoft have taken a leaf from the Facebook/Yammer book, and have shifted their “release cadence” – updates are deployed to Office 365 in small batches very frequently(every month), which is very different to the on-premises world with a big release every 3 years and service packs and cumulative updates within that.

Taking a step back – lack of Office 365 test environments

Clearly, Microsoft are always going to need to update Office 365/SharePoint Online. And in many cases, all we need is a way of testing the change (and any impact on our customizations) before it’s in production. I recently had a meeting with some Microsoft UK folks about this, and I summarized this aspect as:

• Lack of test environments in Office 365
  • Whilst we can (and do) create and pay for multiple O365 tenancies/environments to simulate non-production environments, we have no control of the *sequence* that tenants are patched in – in other words, a Microsoft update can hit our “production” tenant before our dev/test tenants
• No notice/awareness of the date that an update will occur on (for our tenants)

Announced at SPC 2014 - “First Release” and “NDA Preview” options

The good news is that Microsoft are taking big steps to improve this situation – it’s a topic close to my heart, so I wanted to provide my interpretation here (as well as publicize the initiative), but will also link to official TechNet pages when they arrive. In a slightly “under the radar” session on the schedule, a few changes were announced by Jake Zborowski (Group Product Manager, Office 365) at the conference:

1. Improved communication about updates
2. A more structured approach to releasing updates
3. “First Release” for Office 365
4. “Office 365 NDA Preview”

The next sections go into some more detail on each one.

Improved communication about updates

This includes:

• A published *public* roadmap – used to communicate some types of upcoming updates
  • This is targeted for April 2014
• Use of the Office 365 updates blog to communicate changes
• Use of the Office 365 System Requirements page to communicate changes
• Changes to the Message Center
  • Ability to display messages/warnings specific to the tenant (currently cannot)
  • Will show near-term warnings, recommended actions etc.
  • New API, so that developers can write notification apps
  • Enhancements to the existing Office 365 Admin mobile app

A more structured approach to releasing updates

Changes will be classified into different types, and each given a different communication and release plan. The slide below summarizes the communication aspect - but note that at a lower level, communications will actually appear at different times in the different communication vehicles (e.g. an upcoming change will be announced on the public roadmap before it shows up in Message Center etc.):

“First Release” for Office 365 

This is the ability to switch mode for a certain Office 365 tenant – effectively you are signing-up to be “first in the queue” for many types of changes/updates, before they get made generally available in Office 365. The scope of this is for changes to SharePoint Online and Exchange Online. This is AWESOME news, and should go a long way to solving some of the issues for us. Some more details:

• Opt-in switch (off by default):
  • The switch will appear in the Office 365 admin center around early April 2014, and then changes will start to be rolled through it around 4 weeks after that
  • Changes to the switch will be respected within 24 hours – you can switch First Release on/off for your tenancy as you like
  • If you opt-out, any changes already deployed will not be pulled back but future updates will no longer be applied early to your tenant
• Types of updates:
  • Updates which do get pushed through will be supported/vetted/documented and end-user facing
  • Not all updates will be pushed through First Release – I wasn’t 100% clear on what is/isn’t, but I believe something like storage increases (e.g. for OneDrive, or general site collections) would not be
• Timing:
  • You’ll get a warning of at least 7 days alerting you that a change is going be rolled out to First Release
  • An update will be in First Release for a minimum of 2 weeks before standard rollout – however, for most tenants it could work out to be around 1 month until the update lands
  • N.B. at the time of writing, the Product Group are currently working on the ability to know for sure when an update will hit a specific tenant (and consider that for some updates this could actually be different for individual site collections and/or users!). Obviously this is crucial to implementers (like us), because sometimes we may need to deploy a code change to "match up" with a change in Office 365 (otherwise there will be a period where something is not working properly

Here’s a mock-up of how the First Release switch might appear (apologies for the low-quality image):

A note on how I expect WE will use First Release

As I discuss in my Office 365 developer decisions, tips and tricks presentation, we long ago decided to use multiple tenants for each client we work with (representing dev, test and production at least). With the introduction of First Release, I expect we will enable First Release on dev and/or test but leave it off for our “production” tenants. I have some thoughts on whether *both* dev/test should be enabled

“NDA Preview” for Office 365

NDA preview is another useful option for early access to changes – here, Microsoft’s changes are rolled out to a subset of users in your tenant. So whereas First Release affects an entire tenancy, NDA Preview affects only nominated users. There is more involved than just flicking a switch here – I don’t yet know for sure whether it will be open to everyone, but it is a TAP-like program where the organization needs to be able to dedicate time to providing good information to MSFT engineering and working together on issues. Just like a TAP, contracts have to be signed etc. 

Some more details:

• Up to 100 users (TBC) can be nominated
• All changes going through  First Release will also go through NDA Preview
  • BUT, some new changes will go through NDA Preview only, and NOT First Release – an example could be the storage increase change I mentioned earlier
• Sign up at http://prereleaseprograms-public.sharepoint.com
  • Microsoft will then be in touch at a later date – as I say, contracts need to be signed (possibly because of the different nature of some changes pushed through NDA Preview)

A note on how I expect WE will use NDA Preview:

Even with First Release, I think the NDA Preview option will be very valuable. and I expect we WILL enable it for each of our production tenants and nominate some users from at least the implementation team. The production tenant is sometimes the only environment which truly “has everything” – directory synchronization, federated authentication, Yammer SSO/integration to the Yammer Enterprise network, two-way hybrid config (for hybrid deployments) are all examples of things which may not be in place elsewhere if you run multiple tenants. As such, the option of testing Microsoft’s updates in production before full rollout is a very good thing.

Timelines and NDA Preview/First Release

The following diagram gives a sense of how the two programs will work in terms of the timeline for updates:

Summary

I’m really happy to see Microsoft start addressing the issue of Office 365 change management. My fear had been that the platform had not been engineered to release updates to tenants in different ways (and you get a sense of that when the Product Manager mentions that big back-end changes are required for Microsoft to predict when a patch will hit a certain tenant). However, it seems Microsoft *do* appreciate that there is a huge need for a better process around Office 365 patches and updates – and indeed Microsoft’s message these days is “we do expect you to build customizations on Office 365” (but no doubt the usual caveats about what is sensible apply). This is positive for organizations using Office 365 and partners who support them.

 

Office 365 SharePoint hybrid – what you DO and DO NOT get

As far as I can see, more and more clients are interested in “hybrid” these days – the idea of running some of their SharePoint sites in Office 365 (SharePoint Online), and some on-premises. For any organization where the I.T. group is thinking is “we like cloud, but not for everything”, the hybrid idea can be quite appealing. There can many reasons for hybrid – companies wanting to supplement their on-premises capability (perhaps for the “quick spin-up” that Office 365 offers, or to leverage particular features/functionality such as Power BI), companies doing phased migrations to the cloud, or companies with regulatory or data sovereignty constraints – hybrid can work well for these scenarios and more.

TechNet has some great coverage of hybrid configuration process (start with Hybrid for SharePoint Server 2013), but folks who are new to the landscape (especially less technical types) are often surprised by what you actually “get”, and what you don’t, in hybrid mode. Search is a particular area where you get a certain deal – and this may or may not match up with what users are expecting. This post started out as an exploration of that, but I realised that some folks might appreciate some background on hybrid before that, so I’ve split the content up into:

1. Office 365 SharePoint hybrid – what you DO and DON’T get [this article]
2. Office 365 hybrid and search – presenting results from both on-premises and SharePoint Online sites

In many ways, hybrid looks SO SIMPLE! I mean, as TechNet shows, you have some sites in Office 365 and some on-premises – frankly, my mother could probably architect this stuff, right?

In reality of course, there’s a HUGE amount to consider for a hybrid deployment! In a straight comparison of “100% on-premises”, “100% SharePoint Online” and hybrid, I think most would agree that hybrid is the most complex option. After all, you have to do all the on-premises planning (e.g. planning the SQL layer, planning for service applications etc. etc.), in addition to understanding how you will configure and use Office 365. Also, hybrid typically requires extra on-premises configuration (DirSync, maybe ADFS, and maybe reverse proxy infrastructure). And if you’re doing any kind of customisation, there is complexity there around how you build for on-premises vs. SharePoint Online (or perhaps your customisations need to always work in both) – the list goes on.

Hybrid – what you DO get

So, hybrid isn’t necessarily the magical solution it sounds like it could be. That’s not to say it’s not the right solution for you/your client – as an aside, it is for my current client. But it’s not a turn-key solution where you set “Mode = hybrid” and Office 365/SharePoint magically sets things up and all aspects of your deployment are covered. Instead, SharePoint hybrid really covers three areas:

• Search
  • Being able to search across both environments (with caveats – see later)
• BCS
  • Being able to access data in on-premises applications/systems from Office 365
• Duet integration (SAP)
  • Being able to access data in on-premises SAP from Office 365

And that’s really it.

It’s true to say that some aspects of SharePoint can easily be made to work in a way which suits hybrid – My Sites, for example, can be made to exist only in SharePoint Online (if that’s the preferred option) by redirecting the My Site host to the URL in the cloud.

But otherwise, that’s basically what hybrid looks like.

Hybrid – what you DON’T get

So now let’s think about what you don’t get through “native support” – in other words, things you will need to plan for and spend time implementing yourself.

You don’t get:

• Any kind of global navigation
  • A key issue here is the “Sites” page (where a user can find to links to”bookmarked” sites/documents i.e. things they have followed) – if a user follows a site/library/document in on-premises, that will NOT show up in the Office 365 sites page!
• Any kind of global site directory
  • Indeed, SharePoint 2013 no longer has an out-of-the-box site directory of course, it was removed from the product
• A joined-up social/newsfeed experience (if you are using SharePoint social rather than Yammer) across Office 365/on-premises – there are numerous issues here, but essentially any activity such as likes, comments, follows etc. in on on-premises environment will not appear in the newsfeed in SharePoint Online
• A great search experience
  • Instead, search results are displayed in separate blocks from Office 365/on-premises – more on this later
• Any kind of auto-deployment/synchronization of:
  • Branding
  • Master pages
  • Any other customisations packaged as (sandbox) WSPs
  • Taxonomy/Managed Metadata
    • There are numerous considerations here – all related to having two Managed Metadata Service Applications (one in Office 365 and one on-premises)
  • Content types
    • (And if you’re wondering if you can leverage the Content Type Hub, by “chaining” together an on-premise CT Hub with one in SharePoint Online – no you cannot)
  • Document templates (e.g. MyCompanyProposalTemplate.docx)
  • Many aspects of configuration:
    • e.g. Search settings (best bets, search suggestions, search schema such as managed properties etc.)
    • e.g. List and library settings (workflow, versioning settings, policies etc.)
  • Many aspects related to apps
    • Apps available in the App Catalog (because you cannot share an App Catalog between SPO and on-premises)
    • App settings (e.g. whether apps can be installed from the Store)
    • Apps which are being monitored
    • Authentication of provider-hosted apps across SPO and on-premises usually requires some planning
  • Some aspects of user profiles
    • Custom properties
    • Sync across Office 365 and on-premises profiles (i.e. you need to separately configure sync from AD to both locations)
  • [… and no doubt there are lots of other things to add to this list too]

Hopefully you get the idea - in summary, there really is only a minimal link between your Office 365 tenant and your on-premises SharePoint environment (covering search, BCS, etc.). If you need something in both places - and you often do – you’ll need to take care of that yourself.

The hybrid search experience

Search is high on that list of things which get “interesting” for hybrid. After all, your SharePoint sites are split across (at least) two environments, but you’ll usually want users to be able to search across all content easily – without having to go to two different search engines. Providing a global search can certainly be done, and if you’re new to this area there are several options (all of which require some configuration to be done in the on-premises environment at least):

• Outbound hybrid – search center in on-premises environment brings in results from Office 365
• Inbound hybrid – search center in Office 365 brings in results from on-premises environment (requires a supported reverse proxy device)
• Two-way hybrid – both search centers can display results from the other environment

Configure hybrid Search for SharePoint Server 2013 is the best place to start on TechNet.

In all cases, there are limitations - most folks don’t realise that there is no way to “merge” the search results together. There are two possible options:

1. Add a Promoted Result (i.e. a “best bet”)
2. Add a Result Block
3. [OK, so you can also transform the query and therefore change the results – but this doesn’t help in merging the search results.]

The Result Block approach will probably be the most common. But both this and Promoted Results are poor for the client who is expecting to “just search across everything and show me the most relevant things!” This is what the Result Block approach looks like (Office 365 Result Block in red, results from on-premises content in blue):

In other words, it’s very much like a “federated” search experience – the search is executed in two stages:

• The local SharePoint environment is searched and results returned
• The query is also “sent” to the remote SharePoint environment, and results returned

The page then loads and shows both sets of results (assuming some items match in both places). But this experience can raise some questions:

• How many results should be shown (from each source) on page 1?
  • HINT – you’re only allowed a maximum of 10 for a Result Block anyway :)
• What about paging? What happens when I go to page 2?
• How can I easily see more results from both sources?
• How do I determine which results are more relevant, from the local or remote environment?
• Are there any options for seeing the results in a more integrated way?

In my next post, I’ll talk about some options for merging the results – including how you might do it, caveats around this, and so on. But hopefully this post provides some background information on hybrid before then. If it sounds like I’ve painted a negative view of hybrid, that’s not my intention. It can work great, but I think it's worth noting these considerations - I do find many folks have expectations that don’t necessarily match how the bigger picture works in practice.

Add/delete and list Remote Event Receivers with PowerShell/CSOM

Recently I’ve been looking at Remote Event Receivers more and more, as I think they are important (and somewhat unavoidable) if you are trying to build “cloud-friendly” SharePoint solutions – either because you’re on Office 365, or simply want to leave the door open for such a move. You might need to use a RER for something in the host web or app web. I’ll most likely write more on RERs in the future, but if you need a basic step-by-step guide to Remote Event Receivers, my previous post Deploying SP2013 provider-hosted apps/Remote Event Receivers to Azure Websites (for Office 365 apps) may be useful. In this post I want to share some potentially useful PowerShell (and background info), for those who work with RERs.

As I note in the article at the previous link, when you create an RER you actually need to create an app for SharePoint, even if it is an RER to be used in the host web. The app must be either provider-hosted or auto-hosted. For production use I like the provider-hosted option, even if the code is deployed to a cloud service such as Azure. This offers much more flexibility than auto-hosted, which doesn’t have the same options for configuration/monitoring/scaling-up etc. An app is needed because you are creating remote code which most likely needs to use OAuth to communicate back to SharePoint, and the trust model means that (in the standard case at least) an administrator such as the site owner needs to agree to the permissions requested by the app. This could be “Web – Read” or “Site Collection – FullControl” and so on.

Registering Remote Event Receivers

There are several ways to register RERs:

• Declaratively
• With CSOM code e.g. in the AppInstalled event
• With a PowerShell/CSOM script

One big downside to the declarative approach is that it can only be used for lists in an app web (i.e. a SharePoint list deployed by the app). It cannot be used for lists in the host web (e.g. to add a RER to a list in a team site). For completeness, the declarative XML is shown below – it’s just like the XML you might have used for any other event receiver, the only difference is the new “Url” element in the XML:

** N.B. There is a code sample here but it will not show in RSS Readers - click here for full article **

I’ve found more and more that as I’m doing development, the PowerShell approach is highly useful. Sometimes you just need to directly interact with the list - perhaps to see if your RER really is registered properly, or change the URL to a different WCF service for testing. Since there is no user interface for setting RERs, some quick PowerShell is ideal – this post is to share my functions in case they’re useful. I’ll list the different ones for adding/deleting/listing RERs, then provide a full/combined script at the end.

By the way, if you’re new to the idea of PowerShell scripts which have CSOM code embedded in them, see Using CSOM in PowerShell scripts with Office 365.

Adding a new Remote Event Receiver

The function below adds a remote event receiver to a named SharePoint list.

(N.B. Note that all the functions below require a valid ClientContext object to be passed in – see the Prerequisites section towards the end of this post for more details.)

** N.B. There is a code sample here but it will not show in RSS Readers - click here for full article **

Delete a Remote Event Receiver

The function below removes a remote event receiver from a named SharePoint list.

** N.B. There is a code sample here but it will not show in RSS Readers - click here for full article **

List Remote Event Receivers on a SharePoint list

In fact, RER declarations are just like regular event receivers – the SPList class just has one “EventReceivers” property, rather than separate collections for remote event receivers and regular event receivers:

** N.B. There is a code sample here but it will not show in RSS Readers - click here for full article **

Combined/all-up script

So having walked through the functions individually, here's a combined script for download/copy and paste:

** N.B. There is a code sample here but it will not show in RSS Readers - click here for full article **

Prerequisites

To get started with these scripts you should follow the “Getting Started” section of Using CSOM in PowerShell scripts with Office 365, including the “The top of your script – referencing DLLs and authentication” section.

All of the samples above need you to pass a valid ClientContext object – which you have once you have provided the credentials and URL, and have authenticated to SharePoint/Office 365. As in my previous posts, I obtain this in a separate file which I call something like TopOfScript_PSCSOM.ps1. For clarity, here’s an idea of what you need:

** N.B. There is a code sample here but it will not show in RSS Readers - click here for full article **

Summary

Hopefully this script is useful to those working with RERs. Using PowerShell/CSOM isn’t the only way to declare a Remote Event Receiver – in production you might use CSOM code in the AppInstalled event (which is itself declared declaratively in AppManifest.xml – the only way for that event), but the PowerShell/CSOM approach is definitely useful in dev. Happy coding!

Extending the SP2013/Office 365 search hover panel (e.g. adding “post to my feed” functionality)

The enhanced search experience is one of the great things about SharePoint 2013, and the “hover panel”, which shows more information about the result when you hover over it, is a key part of that. Being able to peek inside a document or presentation, or see a preview of a web page without clicking on the result makes for way more efficient searching. Just like search results themselves, the appearance and functionality of the hover panel can be easily extended with HTML, CSS and JavaScript – in this post I am providing some sample code I’ve used in conference talks, which I think highlights things in this area quite well. My sample could be used as-is or modified to provide some other customization to the hover panel.

For context, here’s a reminder of what the hover panel looks like:

 
Actually that image shows a document preview *without* Office Web Apps being available – just a simple summary of the document is shown. Arguably the more normal experience is to have OWA (for example it is standard in Office 365), and in this case you can page through the document/presentation to see if it’s what you’re looking for:

Great. So now let’s look at tweaking the hover panel to add some custom behavior.

Customizing the hover panel – adding an “action”

[Minor diversion/story]: In September 2013, Microsoft added some new functionality to Office 365 which allows a user to “post to Yammer” from the search hover panel. The entry point is a new “action” in the bottom part of the hover panel:

As a coincidence, a few months earlier in April 2013 I had demo’d a very similar customization at the SharePoint Evolutions Conference in London, but in my case my code was posting to the SharePoint 2013 social feed (i.e. not Yammer). Spookily enough, I had even chosen the same word, “POST”:

Seeing the Office 365 change reminded me that I should post this code somewhere – maybe it could be useful to you if your organization uses the SharePoint newsfeed rather than Yammer, or you’re just generally looking for technical info on the hover panel.

[End of minor diversion/story]

My customization

My code modifies the hover panel for all item types (e.g. web page, Word doc, Excel doc etc.). As described above, the “POST” action is added to the actions bar. When clicked, a textbox appears *in the hover panel* to allow the user to type a message to post (to the accompany link):

[I’m sure the UX team at my place of work would have something (very bad!) to say about this, but really I’m just trying to show that you can do all sorts of things with the hover panel :)]

I display a new button to do the actual “Post” at this point. Once a message is typed and this button is clicked, an AJAX request is fired to the SharePoint social API, and a success or failure confirmation is displayed in the hover panel:

And as you’d expect, the message has now been broadcast to my followers (with a link to the original document) and is now listed in the activities section of my profile:

Search hover panel – key info

The hover panel is broken down into three areas:

 
All this stuff comes from HTML/JavaScript files in the Master Page Gallery of your SharePoint search site – so to be clear, let’s say you have a Search Center site at a URL of “/search” (as in Office 365), then these files can be found in that site’s Master Page Gallery. You’ll find the files under the “Display Templates/Search” folder path:

Firstly you’ll notice above that there is a HTML file for every JavaScript file – this is the case for any site which has the publishing feature enabled and therefore Design Manager support for display templates. Past that, there are three broad types of file:

• “Item” display templates - for each item type, such as Item_PDF.js, Item_Word.js, Item_Person.js and so on. Customize these if you wish to tweak how that particular Result Type looks in search results
• “Hover panel” templates – again for each item type, such as Item_PDF_HoverPanel.js and so on. Customize these to tweak the hover panel (which is what we’ll be doing in this post)
• Files for “misc” things - like best bets, the search box control etc.

Importantly, as well as the “per item type” files there are some “common” files – these are hooks which can be used to implement customizations across all Result Types, without having to edit the files for each one. Effectively there is some pseudo-inheritance implemented in JavaScript by Microsoft, where both the “common” and “specific” templates are used provide the UI for a specific item (nice work Product Group). For the hover panel, this works in the following way:

• Each “specific” file provides some outer HTML which may be specific to that item type, but also calls functions called:
  • ctx.RenderHeader()
  • ctx.RenderBody()
  • ctx.RenderFooter()
• These functions are implemented in the “common” files

Effectively you could throw away the idea of calling the common functions for a specific item type if you wanted, and provide an entirely custom hover panel - usually you’ll want to keep the consistency though. The common files are:

It’s these files we’ll be modifying.

Code for my customization

So my sample adds some HTML/CSS, but also has some custom JavaScript code – effectively the moving parts are:

• Some new CSS and JavaScript files, which need to be referenced on the page
• Some changes to the HTML/JS files in the Master Page Gallery which are used for the hover panel

Here’s a run-down of the changes I make to which file:

File	Change description
Item_CommonHoverPanel_Actions.html	Adds the “POST” action link which sits in the “actions” bar
Item_CommonHoverPanel_Body.html	Adds the core customization – the textbox which appears for the comment to be typed into, and the button which does the actual “Post”. Also has the JavaScript call to my custom JavaScript function which does the processing work.
COB-js-demos.js	Custom JavaScript file holding my custom functions such as: “ShowHoverPanelTextBox” “PostToCurrentUserFeed” etc. I added this to the page using a CustomAction.

As you can see, I’m modifying the HTML file and allowing the JS file to be generated. In production you may want to package the JS files as a WSP and overwrite the OOTB ones (keeping a copy of the original of course). I’ll provide a link to a zip file with all files at the end, but here is the new code in each:

Item_CommonHoverPanel_Actions.html

** N.B. There is a code sample here but it will not show in RSS Readers - click here for full article **

Item_CommonHoverPanel_Body.html

** N.B. There is a code sample here but it will not show in RSS Readers - click here for full article **

COB-js-demos.js

** N.B. There is a code sample here but it will not show in RSS Readers - click here for full article **

So in summary we reference the custom JS file on the page (e.g. in a ScriptLink, CustomAction or script tag in the master page) and make the changes to the hover panel files. I’m supplying all the files which make up my solution in the zip linked below, but just as a set of files - you’ll need to package  them into a WSP if that’s what you need (and choose where you want CSS/JS files to deploy to). 

Summary

The search hover panel is a key part of the SharePoint 2013/Office 365 search experience, and is designed to be customized to meet different needs. A new behavior can be implemented across all item types or just for a specific one, such as a Word document or “person” result. In this sample I have shown not only how to tweak the HTML/CSS, but also provide some custom AJAX-based functionality in the hover panel. I chose to use the SharePoint social feed, but the mechanics could be adapted to any behaviour which SharePoint exposes through REST/CSOM/other client APIs.

Download

COB.SharePoint.SearchHoverPanel-Files.zip

Slides from my “Office 365 – developer decisions, tips and tricks” talk published

Recently I gave a talk at SharePoint Saturday UK, following some work my team and I have done on a large Office 365 project. The project involves a reasonable amount of customisation, and we found that many of the techniques we were used to using on classic SharePoint projects cannot simply be applied. Personally I feel like I’ve learnt a lot over the last few months – at my current employer (Content and Code) we are on our 3rd or 4th “Office 365 project with SharePoint customisations”, and we were lucky to also have some time to prepare techniques/scripts etc. before the first one started.

I can’t share all this work, but if you’re starting a similar project you might find some useful info in the ground we have covered and decisions we made. I also point to some useful resources which might be helpful.

Office 365 – developer decisions, tips and tricks

The presentation is embedded below (along with a link to it on SlideShare if you don’t see it).

Contents:

• Decision – how we deal with test environments in the cloud (e.g. do you need a separate Office 365 tenancy for test?)
• Decision – do developers still need powerful desktops/laptops to run virtual machines?
• Decision – should you use (server-side) code in the sandbox?
  • And should you worry about the “sandbox is deprecated” message?
  • What are the alternatives to server-side code?
• Using the magic “PowerShell + CSOM” combination to write PowerShell scripts for Office 365
• Dealing with Managed Metadata fields
  • Provisioning taxonomy (Term Sets) with CSOM, to ensure consistent IDs
  • Our approach - 100% declarative provisioning of Managed Metadata fields
• The new way of working with Managed Properties – search schema XML
  • Using the SearchConfigurationPortability object in CSOM
• Automated deployments to Office 365 – using PS/CSOM to:
  • Recreate site collections
  • Import taxonomy term sets and terms
  • Import search schema
  • Upload sandbox WSPs to the site’s Solution Gallery
  • Activate Features, apply custom WebTemplate to site
• Wrapping the above in TFS build for Continuous Integration (nightly builds of latest packages to Office 365)

I’ll expand on some of these topics in future articles. Similarly I’m expecting to further develop this talk and incorporate new content.

View/download  link - https://www.slideshare.net/chrisobrien/chris-o-brien-office-365-decisions-tips-and-tricks-with-screenshots

Office 365 - developer decisions tips and tricks (Chris O'Brien) from Chris O'Brien

View/download  link - https://www.slideshare.net/chrisobrien/chris-o-brien-office-365-decisions-tips-and-tricks-with-screenshots

Waiting for a search crawl in Office 365 – plan search-driven sites carefully

Here in autumn/fall 2013, if you’re working with Office 365 you might notice that content changes (such as new pages and documents) take some time to appear in search results. I spent a little time thinking about this recently, as my team and I finished building a search-driven news site. On this project, we are mainly developing against Office 365 – we use local virtual machines also, but since O365 is the target we are deploying our customisations there frequently as we develop.

We noticed that “index latency” – the time taken for new content to appear in the search index – was poorer than we expected on Office 365. We run several tenancies on different subscription levels (e.g. SharePoint P2, Office 365 E3 etc.), and we experience the problem across all of them. Some days are good, some days are bad. One memorable (read, stressful) time, we had a “end of sprint demo” - our solution was provisioned 2 days before the demo, giving us lots of time to create test content in order to make the demo to the business users go well. We completed adding our pages, documents, pictures and videos a full 24 hours before the demo, and waited for our home page to “light up” as content was crawled in Office 365.

Unfortunately, only some of the content was indexed in time. The demo itself went well, but perhaps only because a bit of narrative helped the business users imagine the ‘full’ picture. Overall, it’s difficult not to feel that 24 hours is a long time to wait for content to be indexed in SharePoint! Business users these days have higher expectations, and most on-premise environments I’ve worked with have used incremental crawls with a frequency of 15 or 30 minutes.

How long is normal in Office 365?

The poor performance surprised us somewhat. My colleagues and I thought that we had originally read that a delay of up to 15 minutes was expected in Office 365, perhaps suggesting that SharePoint 2013’s “Continuous Crawl” is used. The Office 365 Service Descriptions – Search page now suggests that isn’t the case, but however it is managed in the back-end, we certainly weren’t expecting such long delays. Some further digging will lead you to this KB article:

Search doesn't return all results in SharePoint Online – KB2008449

“Search crawls occur continuously to make sure that content changes are available through search results as soon as possible. Recently uploaded documents may not immediately be displayed in search results because of the time that's required to process them. SharePoint Online targets between 15 minutes and an hour for the time between upload and availability in search results (also known as index freshness). In cases of heavy environment use, this time can increase to six hours.”

OK, so at least that’s something official, even if it’s not necessarily what we wanted to hear. But why are we sometimes seeing longer delays than 6 hours even? I raised a Service Request with Microsoft to find out..

The support line

In short, I didn’t get a 100% satisfactory answer from Office 365 support. Ultimately it sounds like this kind of thing is fairly normal in Office 365 right now. I asked if other customers were reporting this issue, and the answer was “yes, but we just ask them to wait another day”. Hmm, OK then! Of course, if your site deals with time-sensitive content (or you are just looking for fresh content to be shown in search in a reasonable timeframe) this isn’t a great situation.

Working around the issue

So if you need to consider other alternatives:

• If you are dealing with search-driven functionality, could the same thing be provided with query rather than search (e.g. if you do not need to aggregate across site collections)?
• If you are in a hybrid situation, could the functionality be delivered by an on-premises environment?
• Do you need a solution right now, or can you afford to wait for improvements? (I personally am hopeful that upgrades to Office 365 will improve the situation in the future.)

For us, in fact all three are options we could use. In our situation the 2nd option could be the simplest if we need an immediate solution - everything we are building for this client can work be deployed to Office 365 or on-premises SharePoint. This requires quite a lot of careful engineering (not only in terms of the solution, but also deployment scripts/processes etc.), but results in a nice position to be in for a hybrid deployment.

In general though, let’s hope that Microsoft work on this in Office 365. I’ll keep you posted if we see improvements - and if anyone has any useful information in this area, feel free to share in the comments below.