SharePoint Dragons

Nikander & Margriet on SharePoint

Tag Archives: sharepoint 2013

SharePoint 2013 on demand loading pattern

Leave a comment Posted by Nikander & Margriet Bruggeman on September 3, 2016

SharePoint has a JavaScript on-demand loading library, the SP.SOD library (more info on https://msdn.microsoft.com/en-us/library/office/ff410742(v=office.14).aspx). We find the following pattern useful to ensure that a custom JavaScript library called MyCustomLib.js is only loaded once and on demand. So in the pattern below, MyCustomLib.js is only loaded when SP.SOD.executeFunc() is executed.

RegisterSod(MyCustomLib.js’, ‘/sites/ OurTestSite/Style%20Library/Javascript/MyCustomLib.js’);

RegisterSod(AnotherCustomLib.js’, ‘/sites/OurTestSite/Style%20Library/Javascript/AnotherCustomLib.js’);

RegisterSodDep(“MyCustomLib.js”, “SP.js”);

RegisterSodDep(“MyCustomLib.js”, ” AnotherCustomLib.js”);

SP.SOD.executeFunc(MyCustomLib.js’, null, function () { LoisAndClark.CustomApplication.MyCustomLib.init(); });

Uncategorized Margriet, Margriet Bruggeman, Nikander, Nikander Bruggeman, sharepoint 2013

Bug in January 2016 CU for SharePoint 2013: adjusting external links in site pages

Leave a comment Posted by Nikander & Margriet Bruggeman on April 9, 2016

There’s a bug in the January 2016 CU where the CU erroneously updates external links. On a site page, we have a link to an external JavaScript library placed on a CDN like this:

· //cdn.ourcompany.com/js/jquery/jquery.js

After the CU is done “fixing” it, this link has become an internal one:

· /js/jquery/jquery.js

Because of that, the page no longer is able to find the javascript file and the page fails. Links explicitly including the protocol are not molested in this way, so http//cdn.ourcompany.com/js/jquery/jquery.js remains http//cdn.ourcompany.com/js/jquery/jquery.js after CU installation. Let’s hope this bug is fixed in future updates, since we really want to leave out explicit protocols (like so: //cdn.ourcompany.com/js/jquery/jquery.js). We also would like the CU not to try to be too smart and stay away of the contents of our site pages. Btw, it also seems that the CU doesn’t touch similar references in page layouts.

Uncategorized January 2016 cu, Margriet, Margriet Bruggeman, Nikander, Nikander Bruggeman, sharepoint, sharepoint 2013

Quick link title strangeness in SharePoint 2013: wrong Title value

Leave a comment Posted by Nikander & Margriet Bruggeman on August 5, 2015

There is some strangeness surrounding the retrieval of quick launch links in SharePoint 2013 which may very well be a bug in SharePoint. Although we’re the first ones to admit we haven’t been let in on the exact reasoning behind SharePoint’s implementation of the quick launch title, and there may be very good reasoning behind it, we’re inclined to believe that this is another area where multi-language scenarios have been implemented sloppily in SharePoint 2013. In this article we discuss what the problem is and, better yet, how to solve it.

In principle, retrieving the link title of a quick link is easy. The next C# code uses the server-side OM to retrieve the title of every first link of every web site in a site collection.

string siteUrl = “[site collection URL]”;
using (var site = new SPSite(siteUrl))
{
    foreach (SPWeb web in site.AllWebs)
    {
        string title = web.Navigation.QuickLaunch[0].Title;
    }
}

There are situations when the Title does not contain the value you’d expect. There are 2 preconditions that need to be met to experience this strangeness (there may be more scenarios causing it, but we’re describing the one we’ve encountered):

We’re editing the default first link of a new team site.
The locale of the thread running the code is different from the default language of the SharePoint web site.

To clarify, let’s present an example that runs as expected, then followed by the example that does not behave as we expect.

Example 1: Expected Title

Create a new team site and choose language “English”.
Go to the Navigation link (so the Publishing features need to be enabled in order to do this) and edit the first link and change it’s title to “Test”. Do not change the URL!
Run the code and verify that web.Navigation.QuickLaunch[0].Title indeed returns the value of “Test”, the same value as seen via the UI in the quick launch bar.

Example 2: Unexpected Title

Create a new team site and choose language “Dutch” (or some other language as long as its not English).
Go to the Navigation link (so the Publishing features need to be enabled in order to do this) and edit the first link and change it’s title to “Test”. Do not change the URL as this will ensure the Title functionality to function correctly!
Run the code and verify that web.Navigation.QuickLaunch[0].Title does not return the value of “Test”, but instead returns “Home”, even when the quick launch bar itself displays the link title “Test” correctly.

Inspecting the implementation of the Title property in the Microsoft.SharePoint.Navigation.SPNavigationNode class sheds some light on this issue:

public string Title
{
    get
    {
        if (System.Globalization.CultureInfo.CurrentUICulture.LCID == this.Navigation.Web.UICulture.LCID)
        {
            return this.m_strTitle;
        }
        return this.TitleResource.Value;
    }
}

In our case our code was running under a thread with the LCID of 1033 (English – United States). As long as the default language of the SharePoint web site is set to English, this works fine and the member variable m_strTitle is returned containing the correct quick link title value of “Title”.

But, when the LCID of our thread is 1033 and the default language of the SharePoint web site is set to Dutch, we get this.TitleResource.Value which is “Home” and that is incorrect.

As a remedy, we can use reflection to retrieve the value of private member m_strTitle. In C#, this goes like this:

SPNavigationNode firstLink = web.Navigation.QuickLaunch[0];
FieldInfo fieldInfo = firstLink.GetType().GetField(“m_strTitle”, System.Reflection.BindingFlags.NonPublic | System.Reflection.BindingFlags.Instance);
string realLinkTitle = fieldInfo.GetValue(firstLink).ToString();

In PowerShell, the same feat goes like this:

$site = Get-SPSite $siteUrl
foreach ($web in $site.AllWebs)
{
    $firstLink = $web.Navigation.QuickLaunch[0]
    $fieldInfo = $firstLink.GetType().GetField(“m_strTitle”,
        [Reflection.BindingFlags]::NonPublic
        -bor [Reflection.BindingFlags]::Instance)
    $actualLinkTitle = [string]$fieldInfo.GetValue($firstLink)

    $web.Dispose()
}
$site.Dispose()

Now, regardless of the thread your code is running in, you get the actual link title instead of the resource value.

Uncategorized Margriet, Margriet Bruggeman, Nikander, Nikander Bruggeman, Quick Launch, sharepoint, sharepoint 2013

Uploading and activating sandbox solutions via CSOM/JSOM

Leave a comment Posted by Nikander & Margriet Bruggeman on June 20, 2015

In this post we’re discussing how to upload and activate a sandbox solution via CSOM/JSOM. First, we’ll do it using C#. That’s a little bit easier and we’ve seen several examples discussing that (such as this one: http://blogs.msdn.com/b/frank_marasco/archive/2014/08/10/upload-and-activate-sandbox-solutions-using-csom.aspx , probably the first one written about this topic and without it, we couldn’t have written this post). Then, we’ll do it using JSOM which has some additional challenges. We didn’t find any resources discussing that, so there should be value in that.

First off, create a new sub site using the template team site. Then, save that sub site via Site Settings > Save site as template and go to the Solution Gallery and download it somewhere on your local file system. That way, you’ve created a site template that can be used to upload and activate later on. When finished, remove that solution from the Solution Gallery (otherwise, there’s not much point in uploading it again programmatically, now is there?).

In the C# version, we’re basically doing this:

Establish the correct client context
Upload the solution directly to the Solution gallery.
Read the site template (*.wsp) from the local file system.
Create a new FileCreationInformation object representing the site template that will be uploaded.
Upload the solution somewhere. Please note: somewhere can be the solution gallery, but it can also be any other document library. This is because the DesignPackageInfo class accepts a relative URL of an asset located in SharePoint, takes it, and installs it in the Solution Gallery.
Use the DesignPackageInfo class to install and activate the sandbox solution.

The code to do that looks like this:

using Microsoft.SharePoint.Client;

using Microsoft.SharePoint.Client.Publishing;

using System;

using System.Collections.Generic;

using System.IO;

using System.Linq;

using System.Text;

using System.Threading.Tasks;

using System.Web;

namespace SolutionUploader

{

class Program

{

static void Main(string[] args)

{

try

{

ClientContext context = new ClientContext(“http://%5Burl of site collection] “);

Web web = context.Web;

context.Load(web);

var lib = web.Lists.GetByTitle(“[destination lib]”);

context.Load(lib);

var filePath = @”D:\TestTemplateFolder\TestTemplate.wsp”;

var file = new FileStream(filePath, FileMode.Open);

var fileCI = new FileCreationInformation()

{

ContentStream = file,

Url = “TestSiteTemplate-v1.2.wsp”,

Overwrite = true

};

var uploadedFile = lib.RootFolder.Files.Add(fileCI);

context.Load(uploadedFile);

context.ExecuteQuery();

var wsp = new DesignPackageInfo()

{

// Guid can be empty and is autofilled,

// but specifying it explicitly makes it easier if you want to remove it

// later.

PackageGuid = new Guid(“[GUID]”),

//PackageGuid = Guid.Empty,

MajorVersion = 1,

MinorVersion = 0,

PackageName = “[package name]”

};

string filerelativeurl = “[site relative path of *.wsp] “;

DesignPackage.Install(context, context.Site, wsp, filerelativeurl);

context.ExecuteQuery();

}

catch (Exception ex)

{

Console.WriteLine(ex.Message);

}

}

}

}

You may notice that after installation, the solution is always named like so:

[package name]v[major version].[minor version].wsp

Let’s move on to the JSOM example. In other to write it, there where bits and pieces we’ve copied related to the binary encoding and uploading of files and we’ve tried to give credit where possible, but we’re pretty sure we’re missing an acknowledgement. Rest assured, this wasn’t because of any bad intentions.

We found doing the same thing in JSOM is harder, especially when you’re trying to do it before creating a POC in C#. Part of the reason for this is that the JSOM DesignPackageInfo documentation isn’t really helpful at the time of writing, but it’s here: https://msdn.microsoft.com/en-us/library/office/jj954421.aspx in case you want to take a look.

This example involves an HTML page that uploads the site template and activates it in the Solution Gallery. It goes something like this:

You need a reference to the sp.publishing.js library, because it contains the DesignPackageInfo class.
Include a file control to allow end users to upload the site template.
Use a client-side FileReader object to read the binaries.
Upload the file to a SharePoint library and give it a title. Failing to give the file a title may result in situations where the eventual package name is [a guid consisting of 0’s]v.[major].[minor]. We’ve seen this happen on several occasions and it seems to be a problem that doesn’t happen in C#/CSOM.
Use the DesignPackageInfo class to install and activate the solution.

<!DOCTYPE html>

<html lang=”en” xmlns=”http://www.w3.org/1999/xhtml”>

<head>

<meta charset=”utf-8″ />

<title></title>

<script type=”text/javascript” src=”/_layouts/15/sp.publishing.js”></script>

<script type=”text/javascript” src=”[reference to jquery library]”></script>

</head>

<body>

<h1>Upload en Activeer Solution</h1>

<input id=”inputFile” type=”file” />

<input id=”uploadDocumentButton” type=”Button” value=”Upload Document”/> <p/>

<script>

$(“#uploadDocumentButton”).click(function () {

if (document.getElementById(“inputFile”).files.length === 0) {

alert(“Select a file!”);

return;

}

CreateFile();

});

var file;

var fileCreateInfo;

function CreateFile() {

// Ensure the HTML5 FileReader API is supported

if (window.FileReader) {

input = document.getElementById(“inputFile”);

if (input) {

file = input.files[0];

fr = new FileReader();

fr.onload = receivedBinary;

fr.readAsDataURL(file);

}

}

else {

alert(“The HTML5 FileSystem APIs are not fully supported in this browser.”);

}

}

// Callback function for onload event of FileReader

function receivedBinary() {

var clientContext = SP.ClientContext.get_current();

this.oWebsite = clientContext.get_web();

clientContext.load(this.oWebsite);

var listTitle = “[title of destination library for *.wsp”;

var list = this.oWebsite.get_lists().getByTitle(listTitle);

fileCreateInfo = new SP.FileCreationInformation();

fileCreateInfo.set_url(file.name);

fileCreateInfo.set_overwrite(true);

fileCreateInfo.set_content(new SP.Base64EncodedByteArray());

// Read the binary contents of the base 64 data URL into a Uint8Array

// Append the contents of this array to the SP.FileCreationInformation

var arr = convertDataURIToBinary(this.result);

for (var i = 0; i < arr.length; ++i) {

fileCreateInfo.get_content().append(arr[i]);

}

// Upload the file to the root folder of the document library

this.newFile = list.get_rootFolder().get_files().add(fileCreateInfo);

clientContext.load(this.newFile);

var item = this.newFile.get_listItemAllFields();

item.set_item(“Title”, “[title value]”);

item.update();

clientContext.executeQueryAsync(onUploadSuccess, onUploadFailure);

}

function onUploadSuccess() {

// File successfully uploaded

var clientContext = SP.ClientContext.get_current();

var wsp = new SP.Publishing.DesignPackageInfo();

wsp.set_packageName(“[package name]”);

//wsp.set_packageGuid(“{GUID makes deleting easier}”);

wsp.set_majorVersion(3);

wsp.set_minorVersion(0);

var filerelativeurl = “/[site relative url to *.wsp] “;

SP.Publishing.DesignPackage.install(clientContext,

clientContext.get_site(),

wsp,

filerelativeurl);

clientContext.executeQueryAsync(onActivateSuccess, onActivateFailure);

}

function onUploadFailure() {

// Error occurred

console.log(“Request failed: ” + arguments[1].get_message());

}

function onActivateSuccess() {

alert(“Solution successfully activated!”);

}

function onActivateFailure() {

alert(“Solution activation failed: ” + arguments[1].get_message());

}

// Utility function to remove base64 URL prefix and store base64-encoded string in a

// Uint8Array

// Courtesy: https://gist.github.com/borismus/1032746

function convertDataURIToBinary(dataURI) {

var BASE64_MARKER = ‘;base64,’;

var base64Index = dataURI.indexOf(BASE64_MARKER) + BASE64_MARKER.length;

var base64 = dataURI.substring(base64Index);

var raw = window.atob(base64);

var rawLength = raw.length;

var array = new Uint8Array(new ArrayBuffer(rawLength));

for (i = 0; i < rawLength; i++) {

array[i] = raw.charCodeAt(i);

}

return array;

}

</script>

</body>

</html>

And that’s all folks!

Uncategorized csom, jsom, Margriet Bruggeman, Nikander Bruggeman; DesignPackageInfo, sharepoint 2013, site template

Are Draft versions of items and documents indexed in SharePoint 2013?

1 Comment Posted by Nikander & Margriet Bruggeman on December 16, 2014

This can be tested for both lists and document libraries, and the answer depends on various list settings (a term we use in a generic way that also includes document library settings). Possible list settings are:
– Content approval setting: With or without content approval
– Draft item security: Any user who can read items, Only users who can approve items, or Any user who can approve items (and the author of the item).

Searching using the credentials of the author results in items in lists as well as document libraries that only require Read permissions (option “Any user who can read items”). All other Draft versions in lists and libraries with different settings are not included in search results. For instance, a document in Draft version in a library that has the following condition: [go to document library > Library > Library Settings > Versioning settings > Draft Item Security > Only users who can edit items] is NOT returned.

Searching under the context of a user that only has READ permissions yields the exact same search results.

Investigating the crawl log shows that the items that are not returned aren’t even indexed.

Uncategorized Margriet, Margriet Bruggeman, Nikander, Nikander Bruggeman, sharepoint 2013

Microsoft Fakes: building a shim for the SharePoint 2013 SSOM

1 Comment Posted by Nikander & Margriet Bruggeman on October 30, 2014

We were building a mail class used by SharePoint solutions that leverages the SmtpClient class because SPUtility.SendEmail() is too limited in some ways:

It doesn’t send attachments.
It contains a max of 2048 chars per line, although this can be circumvented by adding line breaks (‘\n’).

More about those limitations over here: https://sharepointdragons.com/2012/05/21/sputility-sendemail-limit/

However, we did want to use the SSOM to determine the SMTP server that should send the e-mail messages for us. We could do it like so:

System.Net.Mail.SmtpClient smtpClient = new System.Net.Mail.SmtpClient(objWeb.Site.WebApplication.OutboundMailServiceInstance.Server.Address);

But in this case, we went for this solution:

SPAdministrationWebApplication.Local.OutboundMailServiceInstance.Server.Address;

This resulted in the following method implementation in our custom SharePoint library is a class called Manager:

public string GetSmtpServer()
{
return Microsoft.SharePoint.Administration.SPAdministrationWebApplication.Local.OutboundMailServiceInstance.Server.Address;
}

Very simple. Then, we decided we needed to add some unit testing. If you have VS.NET Ultimate, you can consider using Microsoft.SharePoint.Emulators. We gave it a spin and weren’t that happy with it. At some point, we had to uninstall the package, switch the project to x86, install the emulator again, and switch back to x64, and more stuff like that. But apparently it can be done, according to: http://writeabout.net/2014/06/21/spemulators-available-on-nuget/ , so don’t let us stop you from checking it out!

Then, we were considering other Mocking frameworks (Typemock Isolator, JustMock, Microsoft Fakes) and decided to go with Fakes because of monetary reasons. We then added a unit test project ( VS.NET 2012 > Add > New Project > Unit Test Project), added a reference to our custom SharePoint libary, right-clicked it and chose Add Fakes Assembly.

If you want to know more about Fakes, check out http://msdn.microsoft.com/en-us/library/hh549176.aspx . Basically, it allows you to replace methods and properties during run time with your own implementation.

Because our custom SharePoint library uses the SPS 2013 SSOM it’s built for 64 bit, which required us to change the unit test project to 64 bit too (right-click unit test project > Properties > Build > Platform target: x64). That is not all, you also need to set the Test processor architecture to 64 bit, like so: VS.NET 2012 > TEST > Test Settings > Default Processor Architecture > X64.

When that is done, the unit test project is able to call the SharePoint custom library and we were able to create a shim for our GetSMTPServer() method., which goes something like this:

[TestMethod]
public void GetSmtpServerReturnsFakeName()
{
using (ShimsContext.Create())
{
MyLib.Fakes.ShimManager.AllInstances.GetSmtpServer = (@this) => { return ”mySMTPServer”; };
Manager man = new Manager();

// returns mySMTPServer
string smtpServer = man.GetSmtpServer();
}
}

Uncategorized fakes, Margriet, Margriet Bruggeman, Nikander, Nikander Bruggeman, sharepoint 2013, shim

Application Management Center

Leave a comment Posted by Nikander & Margriet Bruggeman on February 11, 2014

It is hard not to be aware of the existence of Apps. Made hugely popular by the smart phone and iPad markets, these little programs can be downloaded from different types of App stores against a fee, or sometimes completely free of charge. After that, those Apps run on some type of client device, fulfilling the personal needs of the owner of that client device. SharePoint 2013 innovates that game by introducing Apps targeted towards the enterprise instead of the consumer.

Note App stores are becoming increasingly important in the Microsoft world. You will not only find an App store for SharePoint, App stores are also integrated within Windows 8 and Office 2013.

The introduction of Apps to the SharePoint platform is likely the one new feature that is the biggest eye catcher of all. Or, as Brian Jones (Group Program Manager on the Office Solutions Framework team) stated it with some sense of drama: “It’s the most significant thing we’ve done with the (Office) platform in 15 years since the introduction of Visual Basic for Applications (VBA)”.

At first, Apps may sound like nothing more than a change in brand name. In SharePoint 2013, lists are Apps, document libraries are Apps, site pages are Apps, event handlers are Apps, and so on. “Everything is now considered an app”, is a quote from Richard Riley, Director of Product Management for SharePoint. You will likely hear this quote, or something similar, a lot when talking about SharePoint 2013. You may also think about Apps as a logical evolution in the way SharePoint solutions are built and made available to the platform, and you wouldn’t be wrong. But you will see that Apps are more. Firstly, this blog post will teach you that Apps are in fact a paradigm shift in the way the SharePoint platform can be customized by 3^rd parties. Secondly, you will learn how to deal with this new paradigm.

Apps, the SharePoint Store, and the Corporate Marketplace

With SharePoint 2013, the platform has in-built support for Apps, which provide functionality that allows you to customize SharePoint. Or, to put it in other words, Apps are ready-to-use solutions. The term App doesn’t just apply to third-party efforts, basically everything that is there in SharePoint out of the box is now also designated as an App. For example, now lists, libraries, tasks, and calendars all are Apps.

Note Apps are reusable pieces of functionality. Sounds familiar? This does sound a lot like the definition of a web part. The big difference being that web parts are hosted and executed on the SharePoint servers themselves. As you will see later on, SharePoint Apps don’t have to be.

The main reason for introducing Apps to the enterprise market is to make it real easy, but also safe, to extend your existing SharePoint platform with third-party Apps. To facilitate this and make life easier for Microsoft Independent Software Vendors (ISV) partners, Microsoft has introduced an online App store called the SharePoint Store, which is itself hosted in the cloud. SharePoint Store is directly integrated with SharePoint 2013 (in the on-premises variant as well as the Office 365 cloud variant) so that it’s real easy to acquire, buy and manage these Apps. The SharePoint Store shares the same back-end as the Office Store and is hosted on Office.com. Alternatively, you can get Apps from on-premises Corporate Catalogs. It is to be expected that Apps will provide various services, like:

· Site templates, Apps can provide ready-to-use site templates targeted towards specific branches.

· Site add-ons, Apps can enhance existing functionality by, for instance, adding new ribbon buttons that provide some type of new feature.

· Web parts, Apps can provide pieces of reusable functionality in the form of web parts that make sense in the enterprise sphere.

· Branding, Apps can provide custom branding themes by providing CSS files and JavaScript.

· Application Integration, Apps can integrate with external services, such as the ones offered in the Azure Marketplace (https://datamarket.azure.com/ ).

· Independent Line of Business (LOB) applications that integrate with SharePoint, Apps can provide an immersive full page solution that is still tied in to SharePoint.

The SharePoint Store has its own integrated payment system and it’s possible to allow end users to install Apps without requiring server administrators to be involved with the deployment and activation of Apps. Apps, after undergoing a rigorous validation process conducted by Microsoft, can be admitted to the SharePoint Store.

At the time of writing, the SharePoint Store is still in preview and the offering is still limited. The possibilities are endless though. To mention a few, there are Apps that offer Facebook integration, offer Digital Asset Management capabilities for working with paper documents, extend the SharePoint ribbon with the possibility to create compound documents, and offer an HTML 5 workflow creation tool. As may be clear, the range of possibilities is endless end the surface has barely been scratched.

Understanding the SharePoint App Model

If you take a look at the history of the SharePoint platform, you can tell there has been an evolution in the way the platform could be customized by 3^rd parties. Always, there was a need for balance between the security/stability of the platform versus the power required by 3^rd party customizations to offer useful solutions.

In the 2001 version, you could run web part code directly within page execution, in the same process, in the same thread, using either the JavaScript Eval or VBScript Execute functions. The power was limited to running either VBScript or JavaScript, and the potential disruptive force in the area of stability of the custom scripts during the normal page execution life cycle was huge.

The 2003 version was the first step towards maturity. Customizations were deployed to the server and ran under a strict set of privileges defined by various Code Access Security (CAS) policies, or full trust. This allowed IT Pros, if they chose to do so, to limit the potentially dangerous actions that could be executed by custom assemblies. At the same time, SharePoint web applications could be separated between multiple IIS Application Pools running in separate processes, thereby limiting the impact a single SharePoint web app could have on another. But still, custom code was executed on one or more servers of the SharePoint farm and could definitely have their impact on the performance and stability of such servers.

The development model didn’t really change in the 2007 version, although one major issue was addressed: a fool-proof way was added that allowed solutions to impersonate user accounts and run code in an elevated context. Other than that, as far as the available development models went, not much changed.

The development model did change in version 2010. Sandboxed solutions were introduced. They could be uploaded by site collection users and ran in a special and safe sandbox (in its separate process); under the control of a very strict Code Access Security policy to ensure sandboxed solutions couldn’t do any real harm. For instance, sandboxed solutions were allowed to execute a subset of the SharePoint server-side object model, but didn’t have read/write access to the file system, registry, or database. Another new feature was that sandboxed solutions could not only be run in on premises SharePoint farms, but also in SharePoint Online. To top it all, there was a sandbox resource limitation mechanism that allowed IT Pros to specify resource throttling settings to prevent sandbox solutions from over expanding server resources.

SharePoint Server 2013 brings a new addition to the available development models: the App model. To put it in black-and-white, the App model allows you to customize your SharePoint farm by running code outside your farm. For the first time, it is possible to develop custom solutions that are unable to affect your SharePoint farm in a direct way, since they are no longer a part of that farm. In the next sections, you will see how Apps are able to do that.

SharePoint App Architecture

As established earlier, SharePoint Apps provide custom pieces of functionality and have the capability to run isolated from your SharePoint farm. What an App can do exactly is determined by three factors (and you will learn about each of these factors later on in this section):

· App scope

· App permissions

· App authorization policy

In order for these factors to have an effect on Apps, every App needs to have its own App identity that can be used to recognize the App and associate the App to a security principal, which is also known as the App principal. The App principal needs to contain 5 pieces of information:

· App ID (also known as the client ID), a GUID that uniquely identifies the App.

· App Secret, a signing key that consists of a Base64 encoded string that is used by various parties to encrypt and decrypt messages and send it across the network.

· App Title, the friendly SharePoint App name.

· App URI, typically the base DNS name required to get to the App, such as https://myappserver.mydomain.com.

· Redirect URL (optional), in some cases the SharePoint App wants to increase the permissions it has been given programmatically. In such cases, SharePoint will respond by calling the Redirect URL that has been specified as part of the App Principal and send its answers along with this response.

Important The App Identity is great for tracking App activities via the SharePoint Audit Trail mechanism.

App Principals can be retrieved via the following page (be warned: it’s not a very user friendly UI):

http://%5Bserver name] /_layouts/15/appprincipals.aspx

Apps have two different ways to retrieve their App identity:

· From Azure Access Control Service (ACS) over the OAuth protocol, see section “OAuth” for more information.

· From a High Trust Relationship (via S2S trust and certificates), see section “High-Trust Apps” for more information.

NOTE The notion of applications having their own identity recognized apart from user identities sets OAuth and S2S apart from other authorization protocols.

Every App is shipped with an App manifest file (an XML file called appmanifest.xml), which contains essential information about the App and its configuration. The following is considered to be the essential information about Apps:

· The App Client ID

· The App display name

· The App domain

· The App version number

Then, there is information in the App manifest pertaining to its configuration, such as:

· The URL of the App start page, the page that opens when the App is started. This can be any page located anywhere, the sole requirement is that the file type of the start page must be able to support HTTP POST requests (so, for example, images as start pages are out of the question, but ASP.NET or PHP pages are perfectly acceptable).

· A list of App prerequisites (for example, certain features or services that just have to be there in order for the App to be able to run correctly).

· App scope, authorization policies, and permission requests for that scope.

· Other properties such as supported locales (i.e., en-US, nl-NL).

The following fragment shows some example content of an App manifest file:

<?xml version=”1.0″ encoding=”utf-8″ ?>

<App xmlns=”http://schemas.microsoft.com/sharepoint/2012/app/manifest”

ProductID=”{ff01dda0-712e-62c4-c224-d4d522d2286d}”

Version=”1.0.0.0″

SharePointMinVersion=”15.0.0.0″

Name=”TheCustomApp”

>

<Properties>

<Title>The Custom App</Title>

<StartPage>~remoteAppUrl /default.aspx/?SPHostUrl={HostUrl}</StartPage>

<SupportedLocales>

<SupportedLocale CultureName=”en-US” />

<SupportedLocale CultureName=”nl-NL” />

</SupportedLocales>

</Properties>

<AppPermissionRequests AllowAppOnlyPolicy=”true”>

<AppPermissionRequest Scope=”http://sharepoint/content/sitecollection/web/list” Right=”Write”/>

</AppPermissionRequests>

<AppPrincipal>

<RemoteWebApplication ClientId=”2ab64d52-6b4d-688f-e44f-bb453baad652″ />

</AppPrincipal>

</App>

Note You may have noticed that there is some magic surrounding the URLs of the start page and permission request. The format of the start page looked like this: ~remoteAppUrl/default.aspx/?SPHostUrl={HostUrl}, and as you can see it contains some tokens that can be used within the URLs. ~remoteAppUrl stands for the URL of the remote web application in an App for SharePoint, {HostUrl} is replaced by the URL of the host web of an App for SharePoint. See http://msdn.microsoft.com/en-us/library/jj163816(v=office.15).aspx for an overview of the available tokens. The format of the URI of the permission request in the <AppPermissionRequest> element was in this form: http:// sharepoint/content/sitecollection/web/list. This is because permission requests are made without intimate knowledge of the topology of the SharePoint site collection where the App gets installed. So, instead of specifying a specific SharePoint URL, you need to specify a generic URI. To complete the discussion about tokens and URL formatting, see http://msdn.microsoft.com/en-us/library/ms431831(v=office.15).aspx for an overview of generic SharePoint URL tokens.

When an App is installed within a SharePoint environment, this environment is called the Host. Once an App gets installed in a SharePoint site, this site is called the Host Web. It’s possible that the App needs a place to store specific App resources or declarative items, such as lists, site pages, CSS files, and JavaScript files. These resources won’t be added to the Host Web, they’re added to a dedicated child site called the App Web. If an App doesn’t contain any resources, no App Web will be created.

The end user who is installing the App is shown which permissions the App wants, based on the permissions requested in the App manifest file, and then it’s up to the end user to decide if the App is granted those permissions. This is an all or nothing thing: Apps can choose from one of the predefined permission sets and can’t create custom ones, and end users either grant the App all of the permissions requested or none at all.

Note There are multiple events that lead to a change in permissions assigned to Apps: the App is installed by the site administrator, the App is explicitly granted permission by a tenant administrator or site administrator, the end user gives consent, or the App is removed.

After granting permissions to Apps, you can’t modify them, so that the App won’t be broken because of it. Of course, it is possible to revoke App permissions, see section “Uninstalling Apps” for more information. End users can only grant permissions they actually have, or the installation fails.

Important At this point, the App has made clear which permissions it needs, but also to which scope those permissions apply and which authorization policy will be used. Under water, it’s the App principal that gets associated to specific SharePoint permissions and rights.

The scopes to which App permissions can apply are these:

· SharePoint Site collection, permissions apply to the entire site collection (including all children, such as sites, lists, and list items) where the App is installed. In the App manifest file, this scope is represented using the following URI: http://sharepoint/content/sitecollection/.

· SharePoint site, permissions apply to the entire SharePoint site (including all children, such as lists, and list items) where the App is installed. In the App manifest file, this scope is represented using the following URI: http://sharepoint/content/sitecollection/web. If you want to use a site-scoped App, you need to install it for each and every SharePoint site where you want to use the App.

· SharePoint list, permissions apply to the entire list (including all children, such as list items) where the App is installed. In the App manifest file, this scope is represented using the following URI: http://sharepoint/content/sitecollection/web/list.

· Tenancy, permissions apply to the tenancy where the App is installed. In the App manifest file, this scope is represented using the following URI: http://sharepoint/content/tenant. Tenancy-scoped Apps are installed in a single App Catalog site and are available for use in multiple host webs (as opposed to site-scoped Apps). This means that every host web accesses one single App instance, which centralizes App management.

· Feature, scopes can apply to specific SharePoint features, such as Search, Business Connectivity Services (BCS), and Project Server 2013. All other URIs referred to content stored in the SharePoint content database only. The way feature URIs look depends upon the specific feature.

Important All App permissions that were mentioned apply to resources in the SharePoint host environment. By default, Apps get Full Control rights over their corresponding App web.

The site collection, site, list, and feature scopes are probably familiar to you. The Tenancy scope may require a little further explanation. A SharePoint 2013 tenancy is a set of site collections in either a SharePoint farm or SharePoint Online. Usually, a tenancy relates to a single customer in a SharePoint environment used by multiple customers. A tenancy can be an entire site collection, or a subset of them, and the format of a tenancy URL looks like this (the content part reflects the fact that you’re accessing content stored in the SharePoint content database): http://sharepoint/content/tenant.

More Info For more information about tenancies, please refer to http://msdn.microsoft.com/en-us/library/fp179896(v=office.15).aspx .

Next to App permissions and scope, App authorization policies are a key factor in determining what Apps can do. The following App authorization policies are available:

· User and App policy, both the App as well as the current SharePoint end user have to have sufficient permissions in SharePoint to execute an operation. This policy is mandatory for SharePoint Store Apps that call back to SharePoint resources.

· App Only, only the App needs to have sufficient permissions to execute an operation. This is a good policy when the App is not impersonating end user actions in any way. The end user installing the App must have site collection administrator rights in order to grant the App the use of this policy. All operations executed by Apps under this policy run under the special SHAREPOINT\APP account.

Note Apps that do not make OAuth authenticated calls can’t use this policy. In addition, some APIs, such as the Search API, require the presence of a user context and therefore won’t run under the App Only policy.

· User Only, the current SharePoint end user needs to have sufficient permissions in order for the App to complete an operation successfully. This is a good policy when end user resources are accessed.

Each App can choose between four different, predefined permission sets to access SharePoint content:

· Read-Only, these rights correspond to the end user Reader default permission level. This allows an App to view pages, list items, and download documents.

· Write, these rights correspond to the end user Contributor default permission level. This allows an App to view, add, update, and delete list and library items.

· Manage, these rights correspond to the end user Designer default permission level. This allows an App to view, add, update, delete, approve, and customize items or pages within a SharePoint site.

· FullControl, these rights correspond to the end user Full Control default permission level. This allows an App to have full control within the specified scope.

Important See http://technet.microsoft.com/en-us/library/jj219576(office.15).aspx[ for a detailed overview of the exact permissions that are included in each set. It’s important to note that separate SharePoint features can have separate scopes and available permission sets. For example, the scope for Business Connectivity Services (BCS) applies to BCS connections, and you can only assign Apps Read permissions. For Search, there’s a permission set that won’t be found in the standard collection of permission sets: the QueryAsUserIgnoreAppPrincipal permission set. See http://msdn.microsoft.com/en-us/library/fp142383(v=office.15).aspx for more details.

When Apps are stored in the cloud, their App Manifest data is stored in ACS. To make it possible to install such Apps, SharePoint 2013 introduces a new service application called the Apps Service Application. The main responsibility of the Apps Service Application is to store basic information about Apps, their related App licenses (when Apps are downloaded from the SharePoint Store) and related App permissions.

Note The place where this information is stored is also known as the Storefront. First of all, you can use the Storefront to view all Apps in the SharePoint Store (so that SharePoint users don’t have to go to Office.com themselves). All Apps that are downloaded from the SharePoint Store, or from other places that will be discussed shortly, are persisted in this Storefront. Access to the Storefront is not just restricted to site collection administrators; in principle every site user can be granted access to it.

The Apps Service Application is consulted each time an App is accessed to ensure that the end user has sufficient permissions to make such a request. At this point, you have already learned that you can get Apps from the SharePoint Store, but there are several other options as well. Here’s the overview of the available options when it comes to hosting (and/or retrieving) SharePoint Apps:

· Submit your App to the SharePoint Store, also located in the cloud.

· Place the App in an isolated SharePoint site, but within your SharePoint farm.

· Place the App outside your SharePoint farm, on a dedicated self-hosted application server.

· Place the App outside your SharePoint farm, in the cloud (Azure).

· No hosting, of traditional SharePoint artifacts

Another common way of dividing SharePoint Apps models is this:

· SharePoint hosted

· Cloud (or remote) hosted

You will also find the hosting models divided in a different way: no hosting, SharePoint hosted (where the Apps run inside SharePoint), and provider hosted (cloud or dedicated application server).

App – SharePoint Communication

Before we dive into the different hosting models, it’s interesting to take a look at how exactly Apps communicate with SharePoint, since Apps will typically run outside of the SharePoint environment that are using the Apps. First thing you need to know is that Apps won’t be able to use the SharePoint server object model at all – even when the App runs in its own isolated SharePoint site (and therefore, runs on a SharePoint server). This is a good thing where it concerns the stability of your SharePoint farm.

In 2013, the only means by which Apps can interact with SharePoint have to come from the several client APIs offered by SharePoint. Apps will be more reliant on client-side technology such as JavaScript, jQuery (a very popular JavaScript library), and Ajax techniques to communicate with SharePoint leveraging either SharePoint’s client-side object model (or CSOM, pronounced ceesom) or REST API (also known as OData). The SharePoint client object model comes in different flavors:

1. Managed client object model, which can leveraged by .NET applications (such as a console application or WPF client) or PowerShell script to communicate with SharePoint.

2. Mobile client object model, which can be leveraged by Windows Phone devices.

3. JavaScript client object model, which can be leveraged by JavaScript code to communicate with SharePoint.

4. Silverlight client object model, which can be leveraged by Silverlight applications to communicate with SharePoint.

Since Apps are so reliant on CSOM, the coverage of SharePoint functionality has been extended a great deal. Starting in SharePoint 2013, new APIs are also available within CSOM, such as User Profiles, Search, Taxonomy, Publishing, Workflow, Analytics, E-Discovery, IRM and BCS.

In all forms of the client object model, client-side calls will be made to the CSOM end point, a Windows Communication Foundation (WCF) service called client.svc. In SharePoint 2013, client.svc is extended with REST capabilities (implemented in accordance with the OData protocol) so that it, as opposed to SharePoint 2010, now not only supports the fixed amount of entry points reserved for the different kind of CSOM flavors, but also has direct support of REST clients. In addition, all the CSOM calls can also be made via REST. REST calls will be made via URLs of the following format: [sharepoint url]/_api. Under the cover, these requests will be redirected to client.svc.

Note The new CSOM capabilities overlap with the previous REST endpoint ListData.svc. While new applications should be created using the new CSOM/REST capabilities, old client applications leveraging ListData.svc will still work in SharePoint 2013. In 2013, the new REST API always uses _api in the URL that accesses a REST end point. The following is an example of the format of a REST API call that requests the title of a SharePoint root web: http://ASharePointSiteColl/_api/ASharePointSite/title.

All this results in a major shift for App developers. Where in the previous versions of SharePoint most code was written in C#, or at least server-side code, now App developers will have to shift and write a lot more of their business logic using JavaScript. Microsoft did take care to make these client-side APIs a lot more powerful than they were in the previous version.

As an alternative, applications hosted on a dedicated application server or in the cloud won’t be able to leverage the SharePoint server-side object model, but will be able to leverage the managed client object model to let the App server-side code communicate with SharePoint.

Best Practices It would be a fair assessment if one would state that the App model is best suited for solutions that are mainly oriented towards HTML and JavaScript. From the administrator’s perspective, you can’t overlook the fact that Apps will bring along a lot of additional web traffic, much of it consisting of large blocks of JSON and XML data.

As you have seen, there are a lot of different options when it comes to communicating with SharePoint. Let’s finish this section with some closing advice about when to which option, as this will help you validate design choices made by App developers:

· Apps that offer Create/Read/Update/Delete (CRUD) actions against SharePoint or BCS external data, and are hosted on an application server separated by a firewall benefit most from using the JavaScript client object model.

· Server-side code in Apps that offer Create/Read/Update/Delete (CRUD) actions against SharePoint or BCS external data, and are hosted on an application server but not separated by a firewall mainly benefit from using the managed client object model, but the Silverlight client object model, JavaScript client object model or REST are also options.

· Apps hosted on non-Microsoft technology (more on this later) will need to use REST.

· Windows phone Apps need to use the mobile client object model.

· If an App contains a Silverlight application, it should use the Silverlight client object model.

· Office Apps that also work with SharePoint need to use the JavaScript client object model.

Note Keep track of further insights into best practices concerning the question when it makes sense to use a client API, please visit the following TechNet Wiki page: http://social.technet.microsoft.com/wiki/contents/articles/13637.sharepoint-2013-best-practices-what-client-api-should-you-choose-when-building-apps.aspx.

More Info The following MSDN article contains more information about important aspects of the App for SharePoint architecture and development landscape: http://msdn.microsoft.com/en-us/library/fp179922(v=office.15).aspx.

App Hosting Options

In the next sections, you will learn about the various App Hosting options, such as Cloud hosted, Provider hosted, and SharePoint hosted. At this point, it’s important to understand that the various App Hosting options are not mutually exclusive: it’s perfectly possible that Apps include various components that are hosted differently. For example, think of an App that contains SharePoint hosted components as well as Cloud hosted components.

Apps in the SharePoint Store

Only ISVs will go through the trouble of going to the SharePoint Store submission process, which requires adding Apps to the Office AppHub and undergoing an approval process. Once Apps are approved, they can be found in the SharePoint Store via the SharePoint Storefront in your SharePoint farm and used. The life cycle of a SharePoint Store App looks like this:

1. The ISV or individual software developer creates an App.

2. The App is entered in the official submission process and sent to the Office AppHub.

3. Microsoft validates each and every Apps and checks for potential issues about security, performance, any threats the App might pose to the SharePoint farm, and such.

4. If Microsoft approves and certifies the App, it becomes available in the SharePoint Store (at Office.com).

5. Both your own on premises SharePoint farm and SharePoint Online (your farm in the cloud) have a Storefront. The Storefront is responsible for integrating the SharePoint Store with your own SharePoint environment in a way that is completely transparent for your end users. Storefront uses a set of web services to communicate with the SharePoint Store.

6. End users will leverage the SharePoint UI and use Storefront to retrieve information about Apps that are actually hosted in the SharePoint Store. Please note that both administrators and end users can be allowed to have access to Storefront.

7. At that point, end users can actually buy or get (if the App is free) the App of their choice. By doing this, the App becomes available within SharePoint by hosting it either in the cloud, on a dedicate application server, or as an AppWeb within the SharePoint farm. After that, the App can be executed.

8. Every time an App gets executed, the Apps Management Service will check that the end user has the sufficient amount of permissions to do so. The Apps Management Service will also check if license requirements for that particular App have been fulfilled.

9. If the App is shipped under a licensing model, the App will contact the SharePoint Store at Office.com to validate if the end user is allowed to use the App.

10. The App UI will be generated and rendered by the App host (cloud, application server, or AppWeb).

The life cycle for a custom App that isn’t submitted to the SharePoint Store (a situation you’ll typically find for in-house development scenarios) is a little bit different. Instead of submitting the App to the SharePoint Store, it will be packaged and the SharePoint administrator will manually add that package to a Corporate Catalog. After adding the App to the Corporate Catalog, it too will become available via Storefront, where it can be selected by the end user. Figure 1 clarifies the App lifecycle as discussed so far:

Figure 1 The SharePoint App lifecycle: from App submission to usage.

Now let’s look at more detail at the architecture of what happens once the App is installed and ready for use.

1. The end user wants to use a specific App.

2. This request is received by the Web Front-End (WFE).

3. The WFE, via its service application proxy, calls the Apps Management Service.

4. The Apps Management Service decides what information regarding permissions and licenses needs to be retrieved from the database, but doesn’t retrieve this information itself. Instead, it returns control to the WFE. For performance reasons, the WFE caches the location of the Apps Management database. Therefore, it is more efficient if the WFE, and not the Apps Management Service, retrieves the required information.

5. The WFE retrieves information surrounding App permissions and licensing from the Apps Management database.

This is the normal workflow of a normal App request, which is displayed in Figure 2. If you manage Apps (for example, by using the administration UI or PowerShell commands) things work a little differently. Such administrative requests are directed directly against the Apps Management Service, instead of to the WFE, as was the case during a normal App request. Again, to optimize performance, the Apps Management Service won’t interact with its service application database, but will leave that to the WFE.

Figure 2 A depiction of the general SharePoint App communication flow.

Apps in an isolated SharePoint site

In this hosting option, Apps are still hosted on-premises within SharePoint, although they run completely isolated. This type of App is generally called a SharePoint Hosted App and comes in two flavors:

· AppWebs

· App Parts

Let’s start with a discussion of AppWebs. During this hosting mode, whenever an App is installed, a new SharePoint site is created that will house the App. This SharePoint site is called the AppWeb. AppWebs can’t be modified using either SharePoint Designer or the browser UI, to make sure end users are unable to interfere with the correct running of the App.

AppWebs need to be created as sub sites of the SharePoint site collection, but AppWebs don’t have to be immediate children of the root site. AppWebs provide their own chrome and contextual elements, but the permissions are provided by the parent web and the parent context is also passed to the AppWeb so that the client object model (CSOM) can make calls to resources located in the parent site, thus making it easy for the App to interact with SharePoint. However, despite their ability to communicate with their parent web sites, AppWebs can’t communicate with other AppWebs. AppWebs are made visible in the UI via an IFrame in the parent site.

The other flavor of SharePoint-hosted apps is the App part, also known as a Client Web Part. The App part is nothing more than an IFrame which can be added to any page and provides access to some remote resource.

Apps on an Application Server

Microsoft Support has found that the most common reason for issues in farms is caused by custom code. The greatest thing about hosting Apps on dedicated application servers is that it’s guaranteed that your SharePoint farm won’t be harmed anymore by custom code, while still leaving you in full control of the environment. Such Apps are the first example of Provider-hosted Apps. The Apps are stand-alone applications that run completely outside of your SharePoint farm, and SharePoint is completely technology-agnostic as far as these Apps go. This means, Apps can be hosted on any technology, such as application servers running on components of the LAMP stack (Linux, Apache, MySQL, and PHP).

Best Practices This particular feature was hailed enthusiastically by developers. I don’t share the sentiment. Although in itself it’s great to have the flexibility to use any flavor of application server you like, in reality I’ve found that this type of platform independence is almost never an issue. If you’re an avid Java or PHP developer planning to build Apps, you’ll find that you still have to have intimate knowledge of SharePoint technology and development models, as well as access to SharePoint-friendly tools. I’m convinced that the share of skilled Java and SharePoint developers is pretty limited. In addition, some people have even predicted the end of the era of SharePoint developers, since now every ASP.NET developer will be able to create Apps as well. I think this is a wrong conclusion, for exactly the same reasons. If you want to develop SharePoint solutions, you need the knowledge about the platform. You simply can’t do that, while avoiding becoming a “SharePoint” developer.

Apps on a dedicated application server are the first example of provider-hosted Apps. The interesting thing about provider-hosted Apps is that as soon as end user clicks on the App icon in the UI, the end user gets redirected to a destination web site located on the application server. The App can then leverage a set of available JavaScript libraries that enable the retrieval and display of basic chrome elements from the referring SharePoint site (including the basic stylesheet of that referring site). Apps can interact with the referring SharePoint site and execute callbacks to the referring SharePoint site collection and web resources. Apps will rely heavily on JavaScript to execute asynchronous JavaScript client object model calls and/or REST calls that allow the App to communicate with the SharePoint referral context.

In addition to running Apps on a dedicated application server, on-premises, it’s also possible to host Apps on dedicated remote application servers, under the control of a 3^rd party vendor. The biggest advantage of running Apps on dedicated application servers is twofold: not only is it guaranteed that executing custom Apps won’t affect your SharePoint farm directly, if custom Apps don’t perform well enough you don’t have to scale SharePoint anymore: it’s sufficient to just scale the App causing trouble. From a management perspective, this is truly a great thing.

Apps in the Cloud

In essence, this option is identical to hosting Apps on a dedicated application server, with the big difference that in this scenario Apps are hosted in the cloud (Azure), within the Azure Web role. Therefore, this type of Apps is called Azure Hosted Apps. Azure Hosted Apps won’t be hosted in a dedicated cloud space provided by the App developer and shared by all customers. During installation, every App is installed in the cloud space of the customer: it will create Web, worker, and database roles as required. The App developer/vendor can ensure that the infrastructure that is external to SharePoint but required for the App is created in Azure during the App deployment process, but the customer is responsible for paying the costs associated to such an infrastructure. Because of this, these types of Apps are also known as Azure auto-provisioned Apps.

No Hosting

It may come as a bit of a surprise, but SharePoint Apps also come in a flavor where they don’t have to be hosted at all. In this case, it concerns Apps that contain classic SharePoint artifacts, such as content types, fields based on existing field types (but not custom field types or CFTs) such as the Calculated and Computed field types, remote site pages that can also include built-in SharePoint web parts, remote event receivers, list templates, and web templates. Such Apps can be deployed directly into the target SharePoint site.

What Apps can’t do

SharePoint Apps are quite powerful, but you need to be aware that there are certain things you can’t do. This section provides an overview of App limitations.

Best Practices Now we have arrived at what I think are two of the biggest drawbacks of the current App model: although Apps can use a basic stylesheet of the referring site, so far it doesn’t look as though Apps provide a seamless UI experience, but customers will expect nothing less. A second thing is that Apps, as opposed to previous versions that were dominated by server-side, object-oriented code, will now for a large part be written in JavaScript. It’s easily possible that this will lead to spaghetti code. It remains to be seen how App developers will respond to these challenges.

Within Apps, you can’t:

· Create custom web parts, although Apps can provide similar functionality in the form of site pages containing SharePoint web parts or App parts that run on a SharePoint site page.

· Use SharePoint server-side object model event receivers. Instead, Apps can handle remote events and App events (see section “Handling events in Apps for SharePoint” for more information).

· Deploy Custom Field Types. However, it is possible to deploy new fields based on existing field types.

· Deploy application pages.

· Call the SharePoint server-side object model.

· Access SharePoint components located on another SharePoint site.

· Deploy master pages, custom site definitions and themes.

· Deploy custom action groups and custom action hiding.

· Deploy custom user controls (.ascx files).

· Deploy delegate controls.

· Communicate with other Apps (but can share access to a list located in a parent SharePoint site).

Best Practices I expect that the first question companies will ask themselves when deciding to build Apps (or not) is this: will we able to build this App using CSOM? If the answer is yes, building a feature as an App becomes a lot more attractive.

Handling events in Apps for SharePoint

Apps know how to communicate with the referring SharePoint site and site collection via the JavaScript client object model or the REST API, but you may be surprised to find out that Apps are also able to subscribe and respond to several SharePoint events. App developers can create remote events receivers and App event receivers (both via WCF) to handle events:

· Remote event receivers handle events that occur within the life cycle of a SharePoint artifact, such as a SharePoint list item, SharePoint list, or SharePoint site. They function in a way very similar to their SharePoint server object model event counter parts, except for the fact that they work remotely. Events that occur before the actual action occurs can even prevent certain events from happening, such as the deletion of important list items. One way events always happen after the action has occurred, and can only be used to observe what has happened to the SharePoint environment.

· App event receivers deal with events within the App life cycle itself, most notably App installing, upgrading and App uninstalling events. Such event receivers are very useful for cleaning up App changes that affect the SharePoint environment, sending notifications, and logging purposes.

As part of the deployment deliverables, you should demand that App developers provide sufficient error handling within App event receivers. Failing to do so may lead to Apps that can’t be installed, upgraded, or uninstalled due to unhandled exceptions within App event receivers. The next code fragment shows a part of an installation file of a SharePoint App that registers an event receiver that responds when new items are added to a SharePoint announcements list:

<?xml version=”1.0″ encoding=”utf-8″?>

<Elements xmlns=”http://schemas.microsoft.com/sharepoint/”>

<Receivers ListTemplateId=”104″>

<Receiver>

<Name>RemoteEventReceiver1ItemAdding</Name>

<Type>ItemAdding</Type>

<SequenceNumber>10000</SequenceNumber>

<Url>~remoteAppUrl/RemoteEventReceiver.svc</Url>

</Receiver>

</Receivers>

</Elements>

Understanding SharePoint Customization Models

Now that you have learned more about the Apps customization model that makes it possible that SharePoint is extended with customizations, it’s a good idea to contrast that model against the other available development models for customizing SharePoint. Let’s start out by recapping what models are there:

· Farm solutions

· Sandboxed solutions

· SharePoint Apps

Farm Solutions

Farm solutions (.wsp files, a specific flavor of .cab files) are deployed to the Global Assembly Cache or web application Bin folder of every SharePoint Web Front-End (WFE) in the farm. These solutions typically have a wide range of possibilities as far as executing server-side code goes, and can be very powerful. Because of that, they also have the potential to destabilize the SharePoint farm in a direct way.

Security Alert In a lot of the resources I’ve seen about SharePoint 2013 Apps, the terms Farm solution and Full Trust solution are used interchangeably (even in MSDN documentation), implying that the code in Farm Solutions always runs under full trust. Don’t make this mistake. The capabilities of farm solutions can be limited to a very fine-grained level, but do require IT Pros to have a working knowledge of Code Access Security (CAS). In real life, there are plenty of companies that have taken the shortcut by letting farm solutions run under full trust. This goes against best practices and is not a trait of farm solutions per se.
However, be aware of a breaking change in SharePoint 2013: the default CAS policy that is used in this version is Full Trust (instead of the safe wss_minimal policy that allowed solutions to perform a very limited set of operations, like it used to be). In the web.config file it’s defined like this:

<trust level=”Full” originUrl=”” legacyCasModel=”true” />

This means that by default, a SharePoint 2013 farm solution will run under full trust, and allows a solution to do pretty much everything it wants. In effect, by default this also makes every farm solution a full trust solution. At the time of writing, it wasn’t completely clear what the reasoning behind this break in security best practices is and if it’s possible to run SharePoint 2013 under a different trust model without breaking. One thing that is quite clear at this point is that lots of companies found it hard to deal with security policies and opted for the easy way out by running their SharePoint farms under Full Trust anyway.

Sandboxed Solutions

Sandboxed solutions (.wsp files, a specific flavor of .cab files) run in isolation in a separate process called the User Code Service, running under a very strict CAS policy that does allow you to make service calls via full trust proxy services, as well as client-side web service calls (such as WCF services). What’s more, Sandboxed solutions run under a resource throttling mechanism that allows IT Pros to assign points of server resources that a solution is allowed to spend. This system allows for the automatic shutdown of solutions that spend too many server resources. All in all, although Sandboxed solutions run within your SharePoint farm, they are designed for safety, are intentionally limited in their capabilities, and have a minimal impact on their environment. Because of that, in SharePoint 2010, it was a recommended best practice to build Sandboxed solutions whenever you could. However, in the real world, most people found Sandboxed solutions to limited to be very useful. Therefore, Sandboxed solutions haven’t become as popular as was anticipated.

Important Although Sandboxed solutions are still supported; they are deprecated in SharePoint 2013. This means this type of solution probably isn’t supported in SharePoint vNext anymore, and best practices dictate that it’s better to avoid building new sandboxed solutions in SharePoint 2013. The development community won’t mind this decision as much.

App Solutions

We have talked about Apps, but let’s recap for a moment. Apps can run outside of your SharePoint farm, outside of any SharePoint technology, even outside of Microsoft technology, and if you want, in the cloud (Azure). Apps can do this in a safe way by leveraging the OAuth and S2S security protocols and still provide the functionality by leveraging the extended and improved client object model and/or REST (OData) API.

Note App solutions are deployed in the form of .spapp files. Each App package file itself contains a .wsp file (a cab file of the SharePoint brand) full of App resources.

What Apps typically can’t do is execute server-side code. The Apps model is by far the model that has the littlest impact on your SharePoint farm as it can’t affect it directly. However, as of yet, it is more difficult to integrate it with your SharePoint farm and also requires an understanding of the architectural ramifications of the App model.

Best Practices It’s an interesting question what to do when you’re still doing SharePoint 2010 development, and expect that one day in the undefined future you’ll be migrating to SharePoint 2013. Since SharePoint 2010 Best Practices dictate to buld Sandboxed solutions whenever you can, there’s a clear conflict because SharePoint 2013 Best Practices advise to build Apps wherever possible. What’s more, SharePoint 2013 deprecates Sandboxed solutions. One way to approach this problem is to go ahead and build Sandboxed solutions in a way that makes them easy to port to the App model. This would mean that they should be designed in such a way, that they leverage either the client object model or SharePoint REST interface a lot, and refrain from using the server-side object model. I would advise differently. You have to realize that both the client object model and the SharePoint REST interface have become a lot more powerful in SharePoint 2013. Therefore, you can create lots of headaches by trying to create the same solutions for SharePoint 2010 and will most likely end up with higher initial development costs. Instead, build Sandboxed solutions like you’re used to do and remember that they will continue to run effortlessly in SharePoint 2013 environments. If your solution survives until SharePoint vNext, invest in an upgrade at that point in time.

Comparing SharePoint Customization Models

You have learned about the various models available for customizing SharePoint, but now the question remains: when should you prefer which model? Let’s start with this: in SharePoint 2013 it’s a best practice to create SharePoint Apps whenever possible, in lieu of the other development models: Farm solutions and Sandbox solutions, since Apps can’t hurt your SharePoint farm directly. The things you could do with Sandboxed solutions can also be achieved via Apps, in a better way, so it should always be avoidable to build Sandbox solutions. The use of Farm solutions however, can’t be avoided completely. The following table provides detailed guidance on how to make the decision of which model to choose.

table 1 Comparison of SharePoint Customization Models

When to use/Customization model	Sandboxed solutions	SharePoint Apps	Farm solutions
Is it a best practice?	Sandboxed solutions are still supported but deprecated. Therefore, it’s unadvisable to build new sandboxed solutions.	For SharePoint 2013, creating SharePoint Apps is the best practice. You should choose Apps as a way of customizing your SharePoint environment if at all possible.	Create farm solutions when you need to do something that can’t be done using SharePoint Apps. See section “What Apps can’t do” for more information.
Does it have the ability to run server-side code?	Runs under a strict CAS policy and is limited in what it can do.	When Apps are hosted in an isolated SharePoint site, no server-side code whatsoever is allowed. The use of the SharePoint server-side object model code is never allowed within Apps.	Can run full trust code or under a fine grained custom CAS policy. Provides all the flexibility and power you could wish for.
How much impact does it have on server resources?	Run under an advanced resource management system that allows resource point allocation and automatic shutdown for troublesome solutions. In this regard, sandboxed solutions provide the most advanced capabilities, although they still run inside your SharePoint farm.	Apps run isolated from a SharePoint farm, but can have an indirect impact by leveraging the client object model.	Can impact SharePoint server-farm stability directly.
Is it able to runs cross-domain?	No, and there’s no need to since code runs within the SharePoint farm.	Yes, this provides a very interesting way to distribute server loads.	No, and there’s no need to since code runs within the SharePoint farm.
How about the efficiency and performance of the solution?	Runs on the server farm, but in a dedicated isolated process. The sandbox architecture provides overhead.	Apps hosted on separate app servers (even cross-domain) or in the cloud may cause considerable communication overhead. Apps can leverage the CSOM which has built-in task batching capabilities, which relieves this problem to a certain degree.	Very efficient.
How safe is it?	Very safe.	Apps rely on OAuth 2.0. OAuth is a protocol designed for safety, but App architecture offers a bigger attack surface compared to the other models. The Apps Updating mechanism has received criticism, since full control Apps that get updated are not subject to an extensive approval process (as long as the App manifest doesn’t change). In theory, this allows Full Control Apps to start misbehaving after receiving an update. In reality, App vendors can be traced easily via the SharePoint Store, which makes them easily reachable in case of losses caused by malicious Apps.	Can be very safe, but this requires administrators to put thought and effort in the CAS policies they allow to run.
Manageability	Easy to manage within the SharePoint farm. The technical infrastructure of sandboxed solutions is more complicated compared to farm solutions.	Can even be managed on a dedicated environment without SharePoint. Dedicated app admins can take care of this. The technical infrastructure of SharePoint Apps is without a doubt the most difficult to understand of all three customization models.	Easy to manage within the SharePoint farm. The technical infrastructure of farm solutions is the easiest to understand.
Cloud Support	Yes, sandboxed solutions are supported in Office 365.	Yes, Apps are supported in Office 365. What’s more, they have inherent support for the cloud (Azure).	No, on-premises only.
Maturity	There has been only one version of sandboxed solutions. After that, this technology has been deprecated. Therefore, the maturity and success of this technology is very limited.	The Apps model is completely new and therefore needs to mature.	Farm solutions have been around for a long and provide the most mature of all customization models. However, farm solutions have been known, because of their power and the fact that they run inside your SharePoint farm, to destabilize SharePoint farm deployments.
Audience	Available within Office 365 and on-premises SharePoint farm.	An immense audience can be reached easily by adding Apps to the SharePoint Store. Apps can be used in Office 365 as well as on-premises SharePoint farms.	Only available within your on-premises SharePoint farm.

Best Practices As a general rule of thumb, solutions targeted towards administrators don’t lend themselves well to be implemented as Apps. It seems fair to state that Apps are end-user focused almost exclusively.

The overview provided by this table is subject to change, since further insights can impact the comparison. Track the following TechNet Wiki page for a recent comparison of SharePoint customization models: http://social.technet.microsoft.com/wiki/contents/articles/13373.sharepoint-2013-what-to-do-farm-solution-vs-sandbox-vs-app.aspx. The following MSDN article compares Apps with SharePoint solutions: http://msdn.microsoft.com/en-us/library/office/apps/jj163114(v=office.15).

Understanding Security Protocols: OAuth and S2S

As a way of obtaining an App identity that can be used for authentication and authorization purposes, SharePoint Apps are able to leverage two different security protocols: OAuth and S2S. OAuth is the only security protocol supported in Office 365, which means that SharePoint Online will only be able to use Apps leveraging OAuth. By default, on-premises installations don’t contain an OAuth provider which makes S2S the de facto standard for on-premises App deployments.

High-Trust Apps

High-Trust Apps are hosted on on-premises Application servers, as opposed to the Office 365 model where Apps use the ACS to be able to support OAuth and obtain their App identities that way. ACS acts as an authorization service that needs to be trusted by both content server (SharePoint) and client application (SharePoint App). High-Trust Apps are a good solution for on-premises scenarios, because they make the use of ACS obsolete. Instead, High-Trust Apps leverage the S2S protocol to obtain App identities. High-Trust Apps are called this way because they are trusted to assert any user identity that they want by creating the user part of the access token. The term High-Trust App doesn’t mean that such Apps have Full Trust. App permissions have to be requested and granted separately, like Apps leveraging OAuth. In fact, S2S is also called application to application OAuth, but is not an official part of the OAuth specification, as you will learn later.

Best Practices Theoretically, it is possible for on-premise environments to use ACS. In order to do so, you will have to configure this explicitly, although you have to realize you won’t be able to use ACS directly. Instead, you need to acquire an Office 365 tenancy to manage security principal accounts, set up a trust from the on-premises SharePoint farm to the Office 365 tenancy, and go through the tenancy to communicate with ACS. All in all, this route means more work, additional costs, and it is unlikely that organizations will have it set up for use. More than that, doing so doesn’t provide tangible benefits above using the High-Trust App model which makes it hard to argue with the local Enterprise Architect if you do want to enable ACS. In Office 365 environments, OAuth and ACS are already configured reducing the effort of using the ACS/OAuth model to the minimum, which makes a lot more attractive option. All in all, I don’t expect that ACS will be used in on-premises environments that much.

The SharePoint S2S STS, running within the SharePoint farm, provides the tokens necessary for server-to-server authentication. This enables SharePoint 2013 to access application services such as SharePoint Apps hosted on Application servers using temporary access tokens, if a 2-way trust relationship (also known as the S2S Trust or trusted connection) between SharePoint 2013 and the application service exists.

Note At the moment, the other Microsoft application services (also known as App principles) that support S2S are Exchange Server 2013, Multi-tenant workflows running in Azure Workflow Server, and Lync Server 2013. This means it’s possible to configure S2S authentication between a SharePoint 2013 farm and other SharePoint 2013 farms, and/or these other server products. Refer to http://technet.microsoft.com/en-us/library/jj219532(v=office.15).aspx for an explanation how to configure this.

S2S Security Tokens are like OAuth tokens (to be discussed later), but are not a part of the OAuth specification. Microsoft has submitted S2S Security Tokens to the OAuth specification, so they may end up becoming a part of OAuth eventually. Each S2S Security Token must contain the following information:

· It must contain the App identity

· It can optionally contain the identity of the end user

· It must be encrypted with an SSL certificate

S2S Trusts are configured using one or more SSL certificates. The App running on a dedicated application server needs to have access to both the public and the private key pair of the SSL certificate.

Note Private key files end with the extension .pvk, or .pfx when it’s encrypted using a password. For security reasons, Apps should work with .pfx files. Password encrypted .pfx files can be created using the pvk2pfx.exe tool located by default in c:\Program Files (x86)\Windows Kits\8.0\bin\x64. SSL certificates are X509 certificates that end with .cer. These .cer files contain the public key of the certificate.

The App authenticates the end user (using Windows authentication, Forms authentication, and such), then uses the private key to sign a security token, including information about the end user identity, and sends it to SharePoint. SharePoint then uses the public key of the SSL certificate to validate that the security token was indeed signed by a party having access to the private key, which it trusts.

In addition to sending a valid S2S Security Token, Apps are also responsible for exposing a web service end point for metadata discovery which must be available using anonymous access. This end point returns a JavaScript Object Notation (JSON) security token with service metadata (type of certificate, public key of SSL certificate, and App ID) and allows SharePoint 2013 to discover the App ID and public key value.

Once the App metadata end point is in place, the S2S STS can be created on the SharePoint farm using the New-SPTrustedSecurityTokenService PowerShell cmdlet by passing it a friendly name and the URL of the App metadata end point. By doing so, the S2S STS retrieves and stores the App ID and SSL public key. The S2S STS needs the latter to be able to decrypt the security tokens sent by the App that were encrypted using the SSL private key.

Now that the S2S STS is up and running, you usually need to register one App principal. If you’re working with multiple tenancies (refer to section “SharePoint App Architecture” if you’re not sure what a tenancy is), you’ll need to register multiple App principles: one for each tenancy. This can be done via the PowerShell Register-SPAppPrincipal cmdlet. Once you’ve done that, you’ll need to assign permissions (such as Full Control) to the App principal using the Set-SPAppPrincipalPermission PowerShell cmdlet.

The resulting communication flow that happens once the end user starts making requests to a SharePoint Apps looks like this:

1. The End User makes a request to a SharePoint site page via the browser.

2. Because the browser finds the site page contains a reference to a SharePoint App hosted on a dedicated application server, now the browser makes a request to this App as well.

3. The App interacts with a SharePoint Web Front-End (WFE) by sending requests via CSOM or the REST API, and includes a special S2S security token.

4. The WFE sends a response message.

5. The App renders the UI that is displayed in the end user’s browser.

This communication flow is shown in Figure 3.

Figure 3 High-Trust App communication using the S2S protocol.

In the remaining part of this section, you will see how to set up an S2S trust to a High-Trust App. We won’t discuss how to create a High-Trust App, as this is a developer topic. However, if you want to create one for testing purposes, the following MSDN article http://msdn.microsoft.com/en-us/library/fp179901(v=office.15).aspx explains how to create one. For the purposes of this section, we have already created this App and for clarity purposes use the same name and client ID as the MSDN article. The App name is HighTrustSampleApp, the client ID is 6569a7e8-3670-4669-91ae-ec6819ab461. You will see them again in the procedures of the rest of this section.

If you want to set up an S2S Trust to a High-Trust App, you’ll need to follow the next steps:

1. In the registry of the SharePoint server, make a change to indicate that you’re supporting High-Trust Apps.

2. Check that required SharePoint services are running.

3. Check that at least one profile exists (or create the first one).

4. Create an S2S STS on the SharePoint server via PowerShell.

5. Turn off the HTTPS requirement for the S2S protocol (only a good idea for testing purposes).

6. Open the High-Trust App in your SharePoint site.

First, you need to configure your server so that it supports High-Trust Apps. You can do this by adding a new registry key called AppDeploymentCheckAppPrincipalAccessToken. The next procedure explains how to do this:

1. Press Windows+R to Open the Run dialog window.

2. Type regedit. This opens the Registry Editor.

3. Go to [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Shared Tools\Web Server Extensions\15.0\WSS].

4. Right-click the WSS node and choose New > DWORD (32 bit) Value.

5. Choose the following name: AppDeploymentCheckAppPrincipalAccessToken.

6. Accept the default value.

7. Close the Registry Editor.

8. Restart your computer.

This registry setting disables the App Principal Access Token Check, a check that is required for Cloud-Hosted Apps, but not necessary for High-Trust Apps.

Next, we will check if the SharePoint services required for S2S Apps are running: the User Profile Service and App Management Service. In addition, at least one profile needs to be present. If this isn’t the case, you will need to add a new profile. S2S depends on the mapping to a user account via the User Profile application, in case you were wondering about the User Profile related prerequisites. SharePoint uses it to create a user context in the form of a user token that contains the following end user information taken from the User Profile Application (UPA): the UPN, SMTP, and SIP attributes.

The next procedure checks the state of the SharePoint services as well as the number of profiles present in the User Profile Service:

1. Start SharePoint 2013 Central Administration.

2. On the Home – Central Administration page, click Application Management > Manage service applications. This opens the Manage Service Applications page.

3. Locate the name App Management Service and check that its status is Started.

4. Locate the name User Profile Service Application and check that its status is Started.

5. Click the User Profile Service Application link (of type User Profile Service Application). This opens the Manage Profile Service: User Profile Service Application page.

6. Click People > Manage User Profiles. This opens the Manage User Profiles page.

7. Check the Total number of profiles. Usually, this already contains at least 1 profile. If that’s not the case, create one by clicking the New Profile link.

The S2S STS is responsible for handling App security tokens. To set it up, you need to have access to the public key of the SSL certificate (.cer file), which will be provided by the App vendor/developer.

Next, you will learn how to set one up for our test High Trust App. Add the following code to a PowerShell cmdlet file and call that file ConfigS2S.ps1. Then, start the SharePoint 2013 Management Shell and execute the ConfigS2S.ps1 PowerShell cmdlet. Take note of the following things:

· We’re using a .cer file called HighTrustSampleCert.cer, located in the c:\Projects folder.

· The app ID is the App client ID mentioned earlier in this section.

· Replace the URL of http://%5Bsharepoint site collection url] with the URL of the SharePoint site collection where you want to add the App.

· The cmdlet needs to be executed on the SharePoint server.

Add this code to the ConfigS2S.ps1 file:

$publicCertPath = “C:\Projects\HighTrustSampleCert.cer”

$appId = “6569a7e8-3670-4669-91ae-ec6819ab461”

$spurl =”http://%5Bsharepoint site collection url]”

$spweb = Get-SPWeb $spurl

$realm = Get-SPAuthenticationRealm -ServiceContext $spweb.Site

$certificate = Get-PfxCertificate $publicCertPath

$fullAppIdentifier = “$appId@$realm”

New-SPTrustedSecurityTokenIssuer -Name “High Trust Sample App” -Certificate $certificate -RegisteredIssuerName $fullAppIdentifier

$appPrincipal = Register-SPAppPrincipal -NameIdentifier $fullAppIdentifier -Site $spweb -DisplayName “High Trust Sample App”

For testing purposes, you can optionally turn off the HTTPS requirement for the S2S protocol. Add the following code to a file called ConfigNoHttps.ps1 and execute it in the SharePoint 2013 Management Shell:

$serviceConfig = Get-SPSecurityTokenServiceConfig

$serviceConfig.AllowOAuthOverHttp = $true

$serviceConfig.Update()

In principle, this completes the section. At this point, you have successfully set up an S2S High Trust. To be complete, we will show what happens if you have created the High Trust App as described in the MSDN article http://msdn.microsoft.com/en-us/library/fp179901(v=office.15).aspx and add it to your SharePoint site.

First, the App will ask for the permissions it needs. In this case, this is limited to Read permissions, as is shown in Figure 4.

Figure 4 SharePoint Apps have to be trusted explicitly before they are added to a site.

After installing the App, it’s shown in the SharePoint Site Contents, shown in Figure 5.

Figure 5 All installed SharePoint Apps can be found in the Site Contents list.

After this, you can click on the App to execute it. If the App uses a Self-Signed test certificate, the browser will issue a warning that the security certificate is not issued by a trusted certificate authority. In this case, just click Continue to this website (not recommended). The App itself does very little: it just displays the title of the SharePoint site that hosts the App.

OAuth

The SharePoint 2013 App model relies heavily upon the OAuth protocol for authentication and authorization. Every Office 365 App uses it and, as of yet, OAuth is only supported in Office 365. OAuth integration for SharePoint as well as Office Apps is made possible via the Azure Control Service, which is configured automatically. The required trusts from ACS to SharePoint, and ACS to SharePoint Apps are configured automatically as well and is ready for use. All Apps leveraging OAuth obtain their App identity from ACS. When Apps are deployed to the SharePoint Store, they have to be registered with ACS as well.

Note Apps used in on-premises scenarios leverage the S2S protocol instead of OAuth. OAuth is designed for use with HTTP and HTTPS only.

OAuth is a protocol that allows end users to grant third-party applications access to the end user resources without sharing their passwords. It also provides a more fine-grained access method compared to a traditional security mechanism such as Windows authentication, as OAuth also makes it easy to grant limited access (such as: limited in the scope of accessible resources, or duration of access) or revoke access.

Note Because OAuth doesn’t require the sending of password information, it’s an attractive candidate in scenarios where HTTP is used and SSL encryption is not an option. Originally, OAuth was designed with insecure communication methods in mind.

Let’s contrast OAuth to the traditional client/server security model in which the client uses its credentials (typically, a user name/password combination) to access its resources on the server. Such resources are also known as protected resources, because they require that authentication takes place in order to access them. In a client/server scenario, the client and server share a secret (normally a password) that belongs to the client. Each request that uses these credentials is authenticated, which is depicted in Figure 6.

Note Clients in client/server scenarios are usually end users, but clients can be any entity controlling server resources.

Figure 6 A classic client-server authentication request.

As far as the server is concerned, the requester is the client; it knows no other roles. As a result, in SSO scenarios, every application acting on behalf of the client needs to be aware of the client’s credentials, and every application pretends to be the resource owner. This scenario is depicted in Figure 7.

Figure 7 A client-server impersonation scenario.

The traditional client/server model doesn’t work that well in typical web scenarios, where it’s the web front-end (WFE) accessing databases using its own identity instead of the end user context (it just wouldn’t scale well). This makes the web model one step more complicated, especially in situations where the WFE does need to make calls to back-end systems on behalf of the user. In this scenario, the WFE impersonates the end user and makes requests in the context of that end user. Such scenarios may be supported by some type of SSO service, such as the Secure Store Service (SSS) that you might know from the SharePoint world. This scenario is depicted in Figure 8.

Figure 8 Single Sign-On in Web scenarios.

In traditional client/server scenarios, when it comes to providing third-party server applications access to resources owned by the end user, several problems and limitations exist:

· Client applications are required to store the end user credentials in a safe way for future use, which requires the type of some type of Single Sign-On solution. At best, this complicates the architecture of the solution and decreases its manageability. At worst, the SSO implementation is unsafe.

· The scope of access client applications get is too coarse grained and too broad: they get the same access as the end user himself, which is almost never really necessary.

· Server applications are required to support password authentication, which, compared to other solutions such as the use of certificates, is a security weakness.

· Once end users hand out their credentials, they can’t revoke access given to client applications without changing their password. Since most end users tend to reuse a limited set of passwords over a large set of applications, this may not be a very attractive course of action.

Best Practices There are secure password management tools (or digital wallets) available that can help manage a multitude of passwords.

· If any client application used by the end user is compromised, the end user password and all the resources protected by it are compromised.

In OAuth, a new abstraction layer in the form of a third role is introduced: the resource owner. In OAuth, there’s a client application who acts on behalf of the end user who is the actual resource owner and knows the credentials to access those resources. The term client application doesn’t imply that it runs on the desktop of the end user, it can run anywhere (a mobile device, a server, in the cloud, and so on) and still be called a client.

Important In OAuth terminology, the term resource owner is preferred above the term end user. This is because the resource owner doesn’t have to be a person, but can be an application as well. In this blog post, the term end user is preferred. This is a SharePoint blog after all, and ultimately, when we’re talking about OAuth, we have scenarios in mind where end users allow SharePoint Apps to access SharePoint resources.

The client application sends requests to the server (or resource server) which hosts the resources that are controlled by the end user (or resource owner) and is capable of accepting and responding to protected resource requests using access tokens . The three roles in OAuth, consisting of client, server, and resource owner, are also fondly known as the OAuth Love Triangle.

In addition, the OAuth infrastructure requires the presence of an authorization server, a trusted server authenticating client applications and issuing access tokens to client applications authorizing them to access end user resources. The application server may act as the authorization server, but the authorization server existing as a separate entity is equally possible. A single authorization server may serve multiple application servers. The OAuth specification doesn’t address the interaction between server and authorization server, so that implementation is completely left to the discretion of the vendor implementing OAuth.

In the OAuth model, the first thing the client application needs to do is obtain sufficient permissions from the end user to be able to access the end user’s resources later. Such permissions are expressed in the form of a security token (or access token) and a matching shared secret. Security tokens contain a scope, lifetime, and optionally other attributes and are issued to client applications by an authorization server with the approval of the end user. Security tokens make it unnecessary for the end user to actually share his credentials with a client application, which is the biggest advantage offered by OAuth and makes it an ideal candidate for implementing Single Sign-On (SSO) solutions. OAuth also differs from other protocols and services in the sense that it’s good at other services not just web sites; it also has built-in support for desktop applications, mobile devices, and set-top boxes. Having said that, at the moment OAuth is only defined for HTTP(S) resources.

Note Another concept mentioned frequently when talking about OAuth is the number of legs used to describe an OAuth request. This typically refers to the number of parties involved in the request. In a simple request the end user makes a request to the server. This is a 2-Legged request. If it’s a little more complicated, let’s say that the client application makes a request to the server on behalf of the end user, three parties are involved. This is a 3-Legged request. This goes up to n-Legged for scenarios where access is shared with yet more client applications (also known as re-delegation) and is limited by your imagination only.

In OAuth, there are three kinds of credentials:

· Client credentials, which are used to authenticate the client application. In potential, servers can do interesting things with this information, such as providing throttling-free access for important client applications. Most of the time, these credentials will only be used for informational purposes and logging.

· Token credentials, which are used instead of sharing the actual end user credentials. Servers will typically treat these token credentials differently from a scenario where an end user uses his credentials to log in to the server and issue a special class of credentials to the client application representing the permission grant given by the end user. Key here is the fact that the client application doesn’t have to know about the end user credentials. Token credentials are usually encrypted using some type of certificate and are limited in scope and duration.

· Temporary credentials, which are used to identify the authorization request itself. This can be used to differentiate between various clients such as web-based, mobile, desktop and such, and thus offer more flexibility.

OAuth operates on two different channels. The communication between end user (resource owner) and client application (client) is called the front-channel. The communication between client application and server application is called the back-channel. OAuth access tokens are only used in the back-channel, so that the end user and his browser will never have to know about it. OAuth access tokens are usually larger than front-channel temporary credentials that the end user sees when the client application asks for authorization. To protected OAuth requests from replay attacks, OAuth uses a nonce and timestamp. Nonce stands for number used once and is a unique and random string that uniquely identifies each OAuth request. In addition to nonces, timestamps are added to each OAuth request so that server applications don’t have to store nonce values forever. Requests that were sent after the allowed time limit are considered to be replay attacks.

Security Alert It’s up to the server application to keep track of nonces and implement an anti-replay attack mechanism. The OAuth specification makes it easy to devise a mechanism that prevents replay attacks, but ultimately it’s up to the server application.

Important At this point, it’s important to understand that OAuth allows client applications to access end user resources using access tokens. It is not a sign-in protocol that issues sign-in tokens that can be used by end users to log in to SharePoint. That is a huge difference to SharePoint claims authentication that focuses on providing a powerful and flexible way to allow end users to sign-in to SharePoint as well as other applications.

OAuth Protocol Communication Flow

The communication flow of the OAuth protocol generically looks like this:

1. The client application registers itself once with the authorization server and doesn’t have to do this each time anew when it wants to use OAuth. This registration can take place in many forms, such as involving end-user interaction with an HTML registration form, or the opposite, and administrator executing a PowerShell cmdlet on the application server to establish a trust relationship with the client application (this is the variant that is used in SharePoint 2013).

Note App registration information can be retrieved via the following URL: http://%5Bserver name]/_layouts/appinv.aspx. This page allows you to do a lookup based on the App ID used to register the App. It returns App title, App domain, the redirect URI, but not the App Secret.

2. The client application requests authorization from the end user to access end user resources. This request can be made directly, but preferably indirectly via the authorization server.

3. If the end user accepts, the client application receives an authorization grant that represents the permission set granted by the end user.

4. Using this authorization grant, the client application requests an access token from the authorization server.

5. The client application requests end user resources from the server application, and includes the access token in the Authorization HTTP header of each request. The access token is used by the server application to authenticate this request and, if all is well, responds by presenting the protected resource.

When translated to the SharePoint 2013 world, the OAuth model looks like this: end users are the resource owners. They have to grant SharePoint Apps (the client application) the permissions to access end user resources hosted on SharePoint 2013 (the server application). SharePoint Apps use ACS as the authorization server to obtain their App identity from ACS in the form of the access/security token which is also known as the OAuth token, which gets included in any request made by the SharePoint App. This makes it possible for the SharePoint App to interact with a particular SharePoint site using the permissions that were granted by the end user for a specified duration. Access tokens will expire (based on the nonce and timestamp information discussed earlier). When that happens, the SharePoint App will send a refresh token to the authorization server to obtain an updated OAuth access token.

Security Alert The App is itself responsible for storing OAuth tokens, the SharePoint infrastructure doesn’t provide facilities for this. Potentially, this can be a risk. The App vendor has to deal with this adequately. As an administrator: always ask developers and third parties how they handle token storage.

SharePoint App Communication Flow

The SharePoint App communication flow in SharePoint 2013 looks like this:

1. The end user (the resource owner) uses a browser on a device (such as a desktop computer, smart phone, or tablet) to go to a page in a SharePoint site (part of the resource server). If the end user isn’t logged on automatically and isn’t logged on yet, the end user will be prompted to log on. As a result, SharePoint will create a claims based identity in the form of a SAML token.

Important The OAuth protocol flow requires the use of claims authentication.

2. The SharePoint page contains a SharePoint App (the client). As a result, SharePoint asks ACS (the authorization server, or, in SharePoint terminology, the Security Token Service (STS)) to create a context token that contains information about current end user, current App, and current SharePoint context (such as the URL of the SharePoint site). The context token is signed using the App Secret that only the ACS and the SharePoint App know about. The SharePoint App already knows about this client secret, because it received it from ACS during the App registration process in the cloud. The SharePoint App will use the context token later to request an Access token from ACS.

3. ACS returns the context token to SharePoint.

4. SharePoint renders the page including the App. When it gets to the rendering of the SharePoint App, either as a separate full page or in an IFrame, it will do so by creating a so-called App Launcher which runs in the end user browser and uses JavaScript to provide its functionality. SharePoint will pass the context token to the App Launcher which posts this information to the App URL via the browser via a HTTP POST.

5. The application server hosting the SharePoint App validates the context token and, if the App needs to communicate with SharePoint, extracts a refresh token (which remains valid for almost a year) from the context token which gets then signed using the App Secret. After that signing it, the application server uses the refresh token to get an OAuth Access token (which remains valid for a couple of hours to prevent replay attacks) specific for the current end user from ACS, which can be used by the SharePoint App to request end user resources hosted in SharePoint. Based on the Access token, SharePoint is able to validate that the Access token indeed originated from ACS.

6. It is up to the application server hosting the SharePoint App to decide what to do when it retrieves an Access token from ACS. Typically, it should cache it in order to prevent it from having to ask ACS for it time and time again.

7. The SharePoint App uses the Access token for any SharePoint resource requests it makes, using CSOM or REST.

8. SharePoint returns site content to the SharePoint App, which is rendered to HTML and displayed in the browser.

Important SharePoint Apps written in .NET can leverage the TokenHelper class that is available for making the responsibilities for SharePoint Apps (such as calling ACS, or obtaining token information) a lot easier to do, although the TokenHelper class is not supported officially. For non .NET Apps, such tasks have to be coded by hand and are therefore a lot more error prone. As an administrator, this is something to look out for. Non .NET Apps have to be screened more carefully in order to check if they’re able to handle to OAuth communication flow correctly. The source code for this TokenHelper is available, and should be used as either a starting point or a reference for manual implementations. For .NET Apps, you should also check with the developers or vendor whether they’re using the TokenHelper class or some custom application.

The OAuth communication flow in SharePoint 2013 is shown in Figure 9.

Figure 9 A detailed overview of the OAuth Protocol flow in SharePoint 2013.

More Info The following MSDN article contains more information about OAuth and remote Apps for SharePoint 2013: http://msdn.microsoft.com/en-us/library/fp179932(v=office.15).aspx.

Managing Apps

One of the biggest advantages of the new SharePoint App model is that it makes for a much cleaner and simpler installing, updating and uninstalling process. This doesn’t mean to say that you can just sit by idly while end users are interacting with Apps all over your SharePoint farm, so in this section you will learn how to manage SharePoint Apps.

Configuring the App environment

Before end users are allowed to install online SharePoint Apps in your environment, you must perform some configuration involving domain names, service applications, and App URLs. If you install a SharePoint App from the SharePoint Store, each App get its own unique URL, separate from the URLs of the SharePoint sites and other Apps. This is made possible by the use of Host headers. The format of App URLs looks like this: http://[App prefix][App hash].[App domain]/[relative site URL]/[App name]. The next example is a valid App URL: http://myappprefix-f7e14f7b0643e5.contosoapps.com/TheAppName/Pages/Home.aspx. The feature is implemented this way, because unique URLs prevent cross-domain JavaScript attacks. This makes sure SharePoint Apps won’t steal information from each other.

Warning If you get the following error message: “Sorry, apps are turned off. If you know who runs the server, tell them to turn on the App Management Shared Service.”, you probably didn’t follow this procedure or have not yet created a Corporate Catalog.

In the next procedure, you will learn how to create a subdomain that’s going to be used for hosting SharePoint Apps.

Create a Subdomain

1. Select Start > Administrative Tools > DNS. This opens DNS Manager.

2. Select [server name] > Forward Lookup Zones > [domain name].

3. Right-click the domain name node, and choose New Alias (CNAME)…. This opens the New Resource Record dialog window.

4. In the Alias name text box, enter *.app. This will be the sub domain name for all the SharePoint Apps that get installed in your environment.

5. Click Browse…. This opens the Browse dialog window.

6. Select [server name] > Forward Lookup Zones > [domain name] > (same as parent folder) node, and click OK twice. The DNS Manager Details pane should display the *.app entry.

Now that you have configured the required DNS settings, you need to configure SharePoint as well. First, add the following code to a file called Config.ps1 (the code can be obtained from http://msdn.microsoft.com/en-us/library/fp179923(v=office.15)

$account = Get-SPManagedAccount “[administrator account]”

$appPoolSubSvc = New-SPServiceApplicationPool -Name SettingsServiceAppPool -Account $account

$appPoolAppSvc = New-SPServiceApplicationPool -Name AppServiceAppPool -Account $account

$appSubSvc = New-SPSubscriptionSettingsServiceApplication –ApplicationPool $appPoolSubSvc –Name SettingsServiceApp –DatabaseName SettingsServiceDB

$proxySubSvc = New-SPSubscriptionSettingsServiceApplicationProxy –ServiceApplication $appSubSvc

$appAppSvc = New-SPAppManagementServiceApplication -ApplicationPool $appPoolAppSvc -Name AppServiceApp -DatabaseName AppServiceDB

$proxyAppSvc = New-SPAppManagementServiceApplicationProxy -ServiceApplication $appAppSvc

Open the SharePoint 2013 Management Shell and execute the Config.ps1 file. This creates two service applications called AppServiceApp (of the type App Management Service Application) and SettingsServiceApp (of the type Microsoft SharePoint Foundation Subscription Settings Service Application).

In the next procedure, you will verify that these service applications are ready for use and configure the App URLs so that Apps can be downloaded from the SharePoint Store.

1. Start SharePoint 2013 Central Administration.

2. Go to Application Management > Manage service applications to verify these service applications are present and started.

3. Select Apps. This opens the Apps page.

4. Click Configure App URLs. This opens the Configure App URLs page as shown in Figure 10.

Figure 10 Configuring App URLs is essential for running Apps as each App gets its own unique URL.

5. In the App Management section, click Configure App URLS. This opens the Configure App URLs page.

6. In the App Domain textbox, enter the URL of the APP domain: app.[domain name], e.g. app.contoso.com.

7. In the App prefix textbox, choose a prefix that will be prefixed to the subdomain of App URLs. Normally, a prefix such as app will do. In this case, myappprefix is used for educational purposes.

8. Click OK.

At this point, online Apps can be deployed to your SharePoint environment. If you’re getting an error stating the following: “Everything is fine, but we had a small problem getting your license. Please go back to the SharePoint Store to get this app again and you won’t be charged for it.”, it probably means you’re trying to add Apps using the SharePoint System Account. You can’t install Apps using this account by design, as importing App licenses under this account could lead to performance problems (http://technet.microsoft.com/en-us/library/fp161231(v=office.15).aspx). Use a regular end user instead.

It’s not as easy to sign in as a different user account as it used to be. In SharePoint 2013, the quick shortcut Sign in as Different User is missing, so one thing you can do is go to Start > click Shift + Internet Explorer and choose Run as Different User to run the browser in a different user context. If you’re working on a virtual machine and the SharePoint Store has trouble detecting your language settings, you’ll have to actually log out and log in again as that end user to test it out, or access the SharePoint site from your host computer using that user account. After that, go on to the next section and create a Corporate Catalog. Then, adding Apps from the SharePoint Store should work fine.

More Info See TechNet article “Configure an environment for apps for SharePoint 2013” at http://technet.microsoft.com/en-us/library/fp161236(v=office.15) for more details.

Managing the Corporate Catalog

App Catalogs are special SharePoint document libraries that contain SharePoint Apps. There are special site collections containing App Catalogs, called App Catalog sites. Each SharePoint web application is associated to a single App Catalog site, and each SharePoint farm can have multiple App Catalog sites. Every App Catalog site has two App Catalogs: one document library that is intended for SharePoint Apps, the other one is intended for Office Apps. App Catalog Sites are a great thing, because they allow you to set up a Corporate Catalog for Apps that you want to make available throughout your entire organization, or throughout certain parts in your organization. So, whereas the SharePoint Store provides a public marketplace, a Corporate Catalog provides an internal App catalog for Apps that are approved for use within the organization.

In the next procedure, you will learn how to create an App Catalog site (you do need to be a member of the Farm administrators group).

1. Start SharePoint 2013 Central Administration.

2. Click Apps > Manage App Catalog. This opens the Manage App Catalog page, seen in Figure 11.

Figure 11 App Catalogs give administrators control over the set of Apps they want to make available within the enterprise.

3. In the upper right corner, select the Web Application for which you want to create an App Catalog site. Make sure the web application is not yet associated to an App Catalog site, otherwise you won’t get the option to create a new one. If necessary, create a new site collection for this.

4. You’ll see a message stating that the selected web application does not have an app catalog site associated to it. Select Create a new app catalog site and click OK. This opens the Create App Catalog page.

5. Enter the required information. For this example, we are creating an App Catalog called TestAppCatalog. Note that you can select a predefined quota template.

6. Also note that in the End Users section you need to specify which users or groups are allowed to see Apps from the App Catalog. For testing purposes, add Everyone.

7. When you’re done, click OK.

Note Alternatively, you could have reused an existing App Catalog by entering its URL on the Manage App Catalog page.

Now, you have successfully created a new App Catalog site and associated it to a SharePoint web application. By default, the App Catalog site contains document libraries for App Requests, Apps for Office, and Apps for SharePoint, as shown in Figure 12. You can delete App Catalogs by deleting the App Catalog site collection, this is not different from deleting normal site collection. Unfortunately, it’s not possible to update the association between a web application and its App Catalog site: once associated, it stays associated.

Figure 12 Every App Catalog has document libraries for App requests, Office Apps, and SharePoint Apps.

Adding Apps to the Corporate Catalog Site is simple. You can do this by going to the Apps for SharePoint list (if it’s a SharePoint App) and click new item or drag the files to the list. Now, you can browse and upload the SharePoint App to the Corporate Catalog.

Note For testing purposes, it is allowed to upload any kind of file, so you’re free to create a .txt file to play around with the Apps for SharePoint user interface.

Edit App Settings by clicking the Edit button, and remove the App by selecting it, clicking the File ribbon and selecting Delete Document. After deletion, the App is moved to the site Recycle Bin.

Buying Apps from the SharePoint Store

For each web application scope, it’s possible to determine whether end users are allowed to purchase Apps from the SharePoint Store and whether they can make requests for Apps. Farm administrators and the App Catalog site owner review such App requests. In the next procedure, you will learn how to configure End User App Purchasing.

1. Start SharePoint 2013 Central Administration.

2. Click Apps. This opens the Apps page.

3. In section SharePoint and Office Store, click Configure Store Settings. This opens the SharePoint Store Settings page, shown in Figure 13.

Figure 13 The SharePoint Store settings define centrally how end users interact with Apps and allow administrators an easy way to keep track of current end user App requests.

4. In the App Purchases section, you need to decide whether end users are allowed to buy Apps in the SharePoint Store.

5. The App Requests section contains a link to the AppRequests document library of the App Catalog Site associated to the web application you have selected (you can change the selected web application in the upper right corner). This will help you to decide how much interest in SharePoint Apps currently exists.

6. In the Apps for Office from the Store section, you need to decide whether Office Apps are allowed to start.

7. Click OK.

Note The last setting doesn’t affect Office Apps located in App Catalog Sites, it only pertains to Office Apps purchased online.

Now you have successfully adjusted the SharePoint Store configuration settings. SharePoint Central Administration also provides direct access for administrators to the SharePoint Store, which makes the purchase of SharePoint Apps quite easy, as is demonstrated in the next procedure.

1. Open SharePoint 2013 Central Administration.

2. Click Apps. This opens the Apps page.

3. In the SharePoint and Office Store section, click Purchase Apps.

This opens the SharePoint Store where you can choose from a wide range of available SharePoint Apps.

Requesting Apps

The number of SharePoint Apps that are available in the public market place, the SharePoint Store, will continue to grow rapidly. It will be undoable for administrators to keep track of each and every new SharePoint App and evaluate it. Yet, it’s quite possible that there are Apps that are quite beneficial for end users. Therefore, SharePoint contains a mechanism that can be enabled that allows end users to request SharePoint Apps from the SharePoint Store. App requests (a mechanism which is a nice example of a governance feature) can be tracked by administrators, and after some internal validation process, can be made available in a controlled way.

In the next procedure, you’ll see how to check App requests via the SharePoint Store Settings (note that the User Account needs to be a member of the Farm Administrators group and member of the Site Owners or Designers group for the App Catalog site collection).

1. Open SharePoint 2013 Central Administration.

2. Click on the Apps link. This opens the App page.

3. In the SharePoint and Office Store section, click Configure Store Settings. This opens the SharePoint Store Settings page for the selected web application (change this in the upper right corner).

4. In the App Requests section, click Click here to view app requests. This opens the App requests page of the App Requests list of the App Catalog site.

Alternatively, you can manage requests directly by going to the App Catalog site collection and opening the App Requests list. On the App Requests page, each end user is required to fill in information why the App is needed, as shown in Figure 14.

Figure 14 End users can make requests for Apps that are useful but unavailable within their company.

Every App request goes through a workflow process that allows the administrator to communicate what happens with each request. The next procedure shows how to handle App requests.

1. Open the App Requests list, as shown in Figure 15.

Figure 15 End user App Requests can be tracked and managed via the App Requests list.

2. Click on the Edit button of a request (if there are no requests available just go ahead and create a new request yourself).

3. Fill in Approval details, as shown in Figure 16, and click Save.

Figure 16 Interaction with the end user is an important part of the App Request approval workflow.

As you can see, the App Request page now contains a section that allows you to change the status of the App (to New, Pending, Approved, Declined, Withdrawn, Closed as Approved, Closed as declined), explain your decision making, or find out more details about the App requested. Once the App status is approved, end users are allowed to purchase the App.

End users can make new App Requests and track the status of current App requests using the following procedure:

1. Go to Site Settings > Add an app. This opens the Your Apps page.

2. Click Your Requests. This opens the Your Requests page.

On this page, you can request the purchase of new App requests and track the status of your current requests. In Figure 17, you see how an end user has placed a pending request for the purchase of a SharePoint App.

Note The SharePoint App that was used was picked randomly from the available amount of SharePoint Apps in the Preview.

Figure 17 On the Your Requests page, end users can check the status of the App requests they’ve made.

Installing Apps

End users can install Apps coming from various places, if they have the Manage Web site and Create Subsites permissions that are by default part of the Full Control permission level or available to all members of the Site Owners group. Also, you need to enable Apps, as described in section “Configuring the App environment”. Only real end users can install Apps, you can’t install them while you’re logged in using the System account.

Apps are installed to SharePoint site collections. As a result, if you want to reuse Apps, you’ll need to reinstall them for each site collection. Another gotcha is that you need to be aware of the various sources where Apps are coming from. There is a set of default Apps, such as the standard SharePoint lists and libraries or Apps you’ve already purchased, there are Apps from a Corporate Catalog, and then there are Apps from the SharePoint Store.

In the next procedure, you will learn how to add Apps coming from the default set to a SharePoint site.

1. Open your SharePoint site.

2. Click Settings > Add an App. This opens the Site Contents > Your Apps page. Here, you see the Apps that are available by default, as shown in the Figure 18.

Figure 18 The Site Contents – Your Apps page contains an overview of all the Apps that are available by default.

3. Click the App you want to add and specify a name for SharePoint Apps, or follow the instructions for custom Apps.

Once the App is added, it appears in the Site Contents list (Settings > View Site Contents). This page is not opened automatically after App installation, so this may be confusing the very first time.

Note Once the App is added, it is added for all end users within the same site collection at the same time.

The next procedure discusses how to add Corporate Catalog Apps to a SharePoint site.

1. Open your SharePoint site.

2. Click Settings > Add an App. This opens the Site Contents > Your Apps page.

3. Click the From [App Catalog name] link.

4. Choose an App, this opens the Grant Permission to an App dialog box.

5. Click Allow Access.

Again, the App appears in the Site Contents list.

In the next procedure of the section, you will see how to add SharePoint Store Apps to a SharePoint site.

1. Open your SharePoint site.

2. Click Settings > Add an App. This opens the Site Contents > Your Apps page.

3. Click the SharePoint Store link.

4. Choose one of the Apps and click Buy It.

5. Then, follow the instructions and Allow Access to the App.

Again, the App appears in the Site Contents list. If you have saved the App package on a file system, you can also use PowerShell to install the App to the SharePoint site collection. Before you do so, check that you’re a member of the securityadmin fixed server role on the SQL Server instance, db_owner fixed database role on all databases that are to be updated, server Administrators group, and SharePoint Site Owners group of the site collection where the App is installed.

In the final procedure of the section, you will see how to install an App package from the file system to a SharePoint site collection and add the App to a SharePoint site.

1. Start the SharePoint 2013 Management Shell.

2. Import the App package using the following command (replace [Path] with the file system path pointing to your App, replace [URL] with the site collection URL, and replace source with one of the following options Marketplace, CorporateCatalog, DeveloperSite, ObjectModel, RemoteObjectModel, or InvalidSource.:

Copy $spapp = Import-SPAppPackage -Path [Path] to app -Site [URL] -Source [Source]

3. Type Y to import the app.

4. Add the App to a site by entering the following command (Replace [URL] with the SharePoint site URL):

Copy Install-SPApp -Web [URL] -Identity $spapp

The App is successfully added to the SharePoint site.

Note If you want to learn more about using PowerShell and SharePoint 2013, and in particular PowerShell and SharePoint 2013 Apps, there are TechNet resources available for you. http://technet.microsoft.com/en-us/library/jj219772(v=office.15).aspx provides an overview of all App Management Service cmdlets in SharePoint 2013, and http://technet.microsoft.com/en-us/library/ee890108(v=office.15).aspx contains the Windows PowerShell for SharePoint 2013 reference.

Uninstalling Apps

To remove Apps, end users need to have Manage Web Site permissions which by default are handed out to Site Owners or end users with Full Control permissions. One of the biggest advantages of the SharePoint App model is that it guarantees a clean uninstall, since all App specific resources such as lists, site pages, and JavaScript files are created in a separate AppWeb. In this section, you will learn how to uninstall Apps.

The next procedure explains how to uninstall Apps via the user interface.

1. Open the SharePoint Site where the App is added.

2. Click Settings > View Site Contents. This opens the Site Contents page.

3. Select an App > … > Remove. This opens the Message from webpage dialog window asking if you’re really sure about removing the App.

4. Click OK.

The App is removed from the SharePoint site.

If you want to remove Apps via PowerShell, you need to have the same permissions that are required to install Apps via PowerShell. Please refer to section “Installing Apps” for more information. The next procedure explains how to uninstall Apps via PowerShell.

1. Open the SharePoint 2013 Management Shell.

2. Get all installed Apps of a specific SharePoint site using the following command (replace [URL] with the SharePoint site URL):

$instances = Get-SPAppInstance -Web [URL]

3. Get the App you’re looking for using the following command:

$instance = $instances | where {$_.Title -eq ‘[App_Title]’}

4. Uninstall the App using the following command:

Uninstall-SPAppInstance -Identity $instance

5. Type Y to indicate that you really want to uninstall the App.

Now, the App is uninstalled.

Updating Apps

Eventually, Apps will get updated. Either because new functionality is added or because of some bug fix. SharePoint 2013 has its own Upgrade framework for handling these situations. Under water, an App upgrade means a new App package is created that contains an App manifest file that contains an increased version number. Once this new App version is deployed to either the SharePoint Store or Corporate Catalog, the Site Contents page of every SharePoint site where the App is installed shows a link that can be clicked by end users or administrators to update the App. If the App requires a different set of permissions, the end user will be asked to approve these changes.

Important This also means that as an administrator, if there’s a new version of an App available, you need to upgrade it for every SharePoint Site separately.

Updating an App is an all or nothing approach. Once a new App version is installed, let’s say v1.1, an entire new AppWeb is created for the new version. Once that has been completed, the AppWeb v.10 becomes read-only, and any content from the v1.0 AppWeb is copied to the v1.1. AppWeb. Once that is completed, the AppWeb v1.0 gets deleted. All these actions happen in the background and are seamless for end users and administrators. It’s the responsibility of each App itself to make sure a new version is compatible with older App versions.

More Info The following resource contains more information about the updating SharePoint Apps: http://msdn.microsoft.com/en-us/library/fp179904(v=office.15).aspx.

Managing Licenses

Apps that are purchased via the SharePoint Store require licenses, which can be managed via SharePoint Central Administration. The next procedure explains how to do this.

1. Open SharePoint 2013 Central Administration.

2. Click Apps.This opens the Apps page.

3. In the SharePoint and Office Store, click Manage App Licenses. This opens the App Licenses page. Here you will seean overview of all the Apps you’ve obtained from the SharePoint Store.

4. Select an App > Manage License. This opens the Manage App License page.

5. In the Actions drop down box, you can choose to view the App in the SharePoint Store, Recover the App license, or Remove the App license.

6. In the License Managers section, you can add and remove people who are responsible for handling the Licensing for the given App.

Mote Info The following TechNet article contains more information about this topic: http://technet.microsoft.com/en-us/library/fp161235(v=office.15).aspx.

Monitoring Apps

It’s possible to monitor Apps within SharePoint Central Administration, or in the SharePoint site hosting the App. The data about monitored Apps is collected by the ECM analytics timer job and can be delayed for up to 29 hours. When this timer job is run, it collects all App events about the previous day. In this section, you will see how to set up App monitoring.

Important The Monitor Apps page only works correctly if the following timer jobs are active: the Usage Analytics timer job for Search Service, and the Microsoft SharePoint Foundation Usage Data Import timer job.

The next procedure explains how to set up App monitoring in SharePoint Central Administration.

Note The user account must be a member of the Farm Administrators SharePoint group.

1. Open SharePoint 2013 Central Administration.

2. Click Apps. This opens the App page.

3. In the App Management section, click Monitor Apps.

4. Click Add App and select the checkbox for the App that you want to monitor, or search for an App using the Search for App name textbox, and then select the App that you want to monitor.

Note Only Apps that have not been added to the Monitored App list will be displayed in the search results.

This allows you to be build a centralized list of Apps that you want to monitor via SharePoint Central Administration. For each App, the following information is tracked: Name, Status, Source, Licenses in Use, Licenses Purchased, Install Locations, and Runtime Errors. Apps can be removed again by checking a specific App and clicking Remove App in the ribbon.

The next procedure explains how to monitor Apps in a SharePoint site (you need to have site owner permissions in order to complete the steps).

1. Go to Settings > View Site Contents. This opens the Site Contents page and all Apps that are installed on this site are displayed. This page allows you to start monitoring Apps, as shown in the Figure 19.

Figure 19 You can start monitoring Apps via the Site Contents page to get insight in its health.

2. Click the icon next to the App you are interested in and select MONITOR. This opens the App Details page for the selected App, shown in Figure 20.

Figure 20 The App Details page displays interesting information about App’s everyday life.

The App details page, contains information about its version, installer, install data, possibly licensing information, any install, runtime or upgrade errors about the last four days, and shows usage data about the last days, months, or years. Some of this information allows you to see more details by clicking on it (the various error metrics are good examples of this). For Apps that leverage Business Connectivity Services (BCS), there’s even a graph showing the number of calls made to external data sources.

Note After Apps are provisioned, each App gets its own permissions and App Identity. The App Identity can be used to find out about the activity of Apps in the audit trail.

The final procedure of the section discusses how to check App permissions.

1. Open SharePoint 2013 Central Administration.

2. Click Apps. This opens the Apps page.

3. In the App Management section, click App Permissions. This opens the App Permissions page.

Now, you can lookup App permissions by entering the App ID that was used to register the SharePoint App.

Uncategorized sharepoint 2013

Creating and Managing Workflows

1 Comment Posted by Nikander & Margriet Bruggeman on January 7, 2014

Since the very first version of SharePoint, workflows have always been an important feature for the platform as a whole. This is due to the fact that for a long time, companies have found workflows indispensable for automating business processes. Over the years, in the various versions of SharePoint, workflows have become more powerful, flexible, customizable, and easier to create. However, some criticism remained regarding the performance and scalability of SharePoint workflow services. As an administrator, you will be happy to learn that these issues have been addressed in SharePoint 2013.

The architecture of the workflow platform for SharePoint 2013 has been changed quite dramatically compared to what it is in SharePoint 2010. First off, the old SharePoint 2010 workflow platform is still available in SharePoint 2013, but there’s also a new workflow platform available that is based on .NET 4.5.

Note Workflows hosted in SharePoint 2013 and built using the old SharePoint 2010 workflow platform are typically called SharePoint 2010 workflows, while workflows created using the new workflow platform introduced in SharePoint 2013 are called SharePoint 2013 workflows. Both terms are a bit misleading: SharePoint 2010 workflows can actually run in SharePoint 2013, not just in SharePoint 2010. And it can be argued that, as you’ll soon find out, SharePoint 2013 workflows don’t run in SharePoint at all. Never mind its shortcomings, make sure you’re familiar with this terminology.

The new workflow platform allows you to take SharePoint workflows and actually run them outside of your SharePoint farm. Taking SharePoint features and run them outside of the SharePoint farm is a general trend in SharePoint 2013, you will see the same in other SharePoint 2013 technologies such as Office Web Apps and the new SharePoint App model. This is a good thing, since this reduces the surface of custom programs that negatively impact the stability and performance of your SharePoint farm. Architecturally, this is a huge break from previous SharePoint platforms.

Other than the biggest eye catcher, meaning the architectural changes mentioned, the SharePoint workflow platform offers more new improvements, which will all be discussed in the rest of this blog post.

Best Practices The old SharePoint 2010 workflow platform is still available in SharePoint 2013 for compatibility reasons and is based on the Windows Workflow Foundation (WF), included with the .NET 3.5 framework. However, it is recommended to base new custom workflow efforts on the new model.

Workflow Architecture

In this section, we will give you an overview of the new workflow architecture platform and discuss which things are changed regarding workflows in SharePoint 2013. With the arrival of SharePoint 2013 the architecture of the workflow platform has completely changed. In SharePoint 2010 the workflow platform was an integrated part of SharePoint itself, running within the SharePoint farm. The .NET 3.5 Workflow Foundation Runtime was hosted by SharePoint 2010, which acted as the so-called custom workflow service host. In SharePoint 2013, this is absolutely not the case, as the workflow host provider is taken out of the SharePoint farm altogether.

Before delving into this new architectural change, it might be comforting to know that SharePoint 2013 keeps hosting the 2010 workflow platform, so every SharePoint 2010 workflow will still work in SharePoint 2013.However, the new 2013 workflow platform will not be hosted by SharePoint at all. Instead, the new workflow execution host (or workflow server) is Windows Azure Workflow (WAW). We have to be real careful here, as the name WAW implies that such workflow execution hosts run in the cloud which doesn’t have to be the case, and most of the times are not. On premises SharePoint farms use workflow servers that are real machines running on premises as well. As a matter of fact, on premises SharePoint deployments only work with on premises workflow servers running WAW. As of yet, they are not able to leverage Azure based WAW servers. Opposed to that, Office 365 does leverage Azure based WAW servers.

Note This is another trend you will see frequently in SharePoint 2013: whenever possible, SharePoint 2013 will offer built-in cloud support.

This new SharePoint 2013 workflow model is based on Windows Workflow Foundation 4.5 (WF), part of the .NET framework 4.5, and is substantially redesigned compared to earlier versions. Not only are SharePoint 2013 workflows powered by Windows Azure Workflow, a powerful new workflow service part of the .NET 4.5 framework, Windows Azure Workflow itself is built on Windows Workflow Foundation 4.5. In its turn, Windows Workflow Foundation makes extensive use of the messaging functionality provided by Windows Communication Foundation (WCF).

Note Windows Workflow Foundation is a technology that makes creating workflows within .NET easy. It provides a workflow API, an in-process workflow engine, as well as a rehostable workflow designer. Windows Communication Foundation is a set of application programming interfaces (APIs) that can be used for building connected, service-oriented applications (SOAs). Essentially, SOAs are applications that deal with exchanging messages. As is the case with WF, WCF is also a part of the .NET framework.

You can use workflow models to give structure to business processes. To put it in other words, a workflow is a representation of a business process. In Windows Workflow Foundation 4.5, each workflow consists of a structured collection of workflow activities. Each activity represents a functional component of a business process, such as sending an e-mail message, checking out a document located in SharePoint, or logging information to a SharePoint history list.

The Windows Workflow Foundation 4.5 activity model is adopted by SharePoint 2013 to represent SharePoint-based business processes. Another concept you will find in SharePoint workflows is the concept of conditions, which are indispensable decision makers that will allow workflows to behave intelligently and decide which activities need to be executed. Examples of conditions are: if x happens do something, wait until time to perform an operation, as long as is true do nothing. Most often, conditions in SharePoint workflows rely on some type of information about a document in a SharePoint document library or a SharePoint list item.

As a new addition to activities and conditions, SharePoint 2013 provides a new stage model. Stages provide a convenient way to group conditions and activities together and now are the building blocks for the new recommended best practice surrounding the construction of workflows that don’t have fixed execution paths, replacing the old and deprecated state workflow model.

Note Workflows can be sequential where the order of the execution path is fixed. State workflows are event driven and their execution paths are determined by external factors.

A final concept you will need to know about is workflow actions. So far, we have only talked about workflow activities, but it is also important to know the difference between workflow activities and workflow actions. Workflow activities are a lower level concept and represent the underlying managed objects whose methods drive workflow behaviors. Workflow developers will interact with workflow activities via code or using a specific development environment. Workflow actions, on the other hand, are wrappers that encapsulate the underlying activities and present them in a user-friendly form in SharePoint Designer 2013 or Visual Studio 2012 (more about these tools later). When you create a workflow you will work directly with workflow actions. At the level of the workflow execution engine, the engine acts directly on the corresponding activities.

Workflow activities, which are implementations of activity classes, are implemented declaratively by using XAML. Workflow activities are invoked using loosely coupled web services that use messaging APIs to communicate with SharePoint. These APIs are built on the messaging functionality that is provided by Windows Communication Foundation (WCF). The messaging framework is very flexible and supports virtually any messaging pattern that you need. Within your SharePoint 2013 farm, Windows Workflow Foundation and WCF are hosted in a component called the Windows Azure Workflow Manager Client server (located on premises, or, for Office 365, in the cloud), so that is also the place where the workflow activities actually run.

Note XAML is a declarative XML-based language for describing structures such as Windows Presentation Foundation (WPF) user interfaces, or, in this case, workflows.

Figure 1 depicts a high-level view of the SharePoint 2013 workflow framework. Notice, first, how the new workflow infrastructure introduces the Windows Azure Workflow Manager Client as the new workflow execution host (denoted in the Figure as Azure Workflow). Whereas in previous versions workflow execution was hosted in SharePoint itself, this has changed in SharePoint 2013. Workflow Manager Client is external to SharePoint and communicates using common protocols (REST API calls over HTTP or HTTPS) over the Windows Azure service bus, mediated by OAuth 2.0.

Note OAuth is a security protocol that allows applications to communicate with other applications, if need be across domains, without actually sharing user credentials. As a best practice, communication between such applications will be over HTTPS, to ensure all OAuth tokens are sent safely across the network.

Other than that, the architectural overview contains no big surprises; the SharePoint “box” contains the features that you would expect to see: content items, events, apps, and so on. As promised before, notice that there is also an implementation of the SharePoint 2010 workflow host (that is, the Windows Workflow Foundation 3.5 engine). It’s there for backward compatibility reasons.

Let’s take a further moment to define the major workflow related components found on Figure 1:

Windows Azure Workflow Manager Client server (or, as it is called in the Figure, just Azure Workflow) takes care of managing the workflow definitions and is responsible for hosting the execution processes for workflow instances.
SharePoint 2013 provides the framework for SharePoint workflows, which model SharePoint-based business processes that involve SharePoint documents, lists, users, and tasks. Additionally, SharePoint workflows, associations (where SharePoint workflows are tied to SharePoint entities such as lists, libraries, sites or content types), activities, and other workflow metadata are stored and managed in your SharePoint 2013 farm.
SharePoint Designer 2013 is a tool for creating, designing, and publishing workflows. Because of its ease of use, the main target audience for this tool consists of power users.

Figure 1 SharePoint 2013 workflow architecture.

The Workflow Manager Client needs to be present on every SharePoint machine running workflow services and sits on top of the Workflow Manager Client Service Application Proxy (also shown in Figure 1). The Workflow Manager Client allows SharePoint 2013 to communicate and interact with the Workflow Manager Client server. Server-to-server authentication is provided using OAuth 2.0 (hence the Azure Access Control component). The various SharePoint events to which a SharePoint workflow can be listening, like itemCreated, itemUpdated, and so on, are routed to Workflow Manager Client using the Windows Azure service bus. For the return trip, the platform uses the SharePoint Representational State Transfer (REST) API to call back into SharePoint.

Note A service bus is a software architecture model used in SOA architectures to describe a piece of software that facilitates interaction and communication between various distributed applications. As such, it is a more advanced form of client/server architecture models, which are typically used in heterogeneous and complex infrastructures. REST can be seen as a light version of SOAP. The REST protocol leverages the HTTP protocol and allows clients to interact with server resources in various ways, supporting HTTP verbs such as GET, POST, PUT, and DELETE.

There are additions to the SharePoint workflow object model that allow you to manage and control workflows and their execution by interacting with the Workflow Services Manager. These additions are also known as the Workflow Services Manager object model and are part of the bigger all-encompassing SharePoint 2013 object model (as can be seen in Figure 1).

Note Typical reasons to leverage the Workflow Services Manager object model are related to workflow deployment, messaging, instance control, and interoperability with SharePoint 2010 workflows. A new and interesting feature of the Workflow Services
Manager is that it allows 3^rd party vendors to create separate workflow designers that leverage it and build a new UI to create workflows, and offer such separate workflow designers to the audience in the form of SharePoint Apps.

Workflow authoring can be done in various ways. SharePoint Designer, in its 2013 version, can now be used to create and deploy both SharePoint 2010 and SharePoint 2013 workflows, and Visual Studio 2012 not only provides a designer surface for creating declarative workflows, but can also create apps for SharePoint and solutions that fully integrate Workflow Manager Client functionality.

Workflows in SharePoint 2013

Let’s start with some good news: the workflows that you have built for SharePoint 2010 will continue to work in SharePoint 2013. When you install SharePoint 2013, the SharePoint 2010 Workflow platform is installed automatically. But to make use of the new SharePoint 2013 Workflow platform you have to install and configure Windows Azure Workflow (WAW)separately from SharePoint 2013. Probably the easiest way to get it is using the Microsoft Web Platform Installer (Web PI at http://www.microsoft.com/web/downloads/platform.aspx) and searching in it for windows azure workflow. When the search results display, make sure you see the Workflow 1.0 and Workflow Client 1.0 versions. The Web PI then allows you to install both pieces of software, and starts a configuration wizard that you need to follow.

Note If you’re installing a development environment where SharePoint 2013 runs on a domain controller, you need to enter the Fully Qualified Domain Name of any end user names you’re using during the installation of WAW. So, instead of entering contoso\username, you need to enter contoso.com\username.

So, in a typical SharePoint 2013 farm, you will have two different Workflow platforms installed that you could use to create workflows. Other than SharePoint 2010 Workflows, and SharePoint 2013 Workflows, there is a 3^rd workflow platform option of the type SharePoint 2013 Workflow – Project Server. This type requires the presence of Project Server 2013 and falls outside the scope of this blog post.

You can choose to install the Windows Azure Workflow component on a separate server or farm of servers and connect it to your SharePoint farm. This allows you to scale the Workflow component according to your needs, and manage it separately. There are two different topology models for handling scale out scenarios: collocated and federated.

In a collocated topology model, every SharePoint web front-end (WFE) is connected to its own dedicated Workflow Manager server, which is responsible for storing persistent data in a database that can be accessed by every Workflow Manager server. If there are multiple nodes in the SharePoint farm, traffic between SharePoint WFEs and Workflow Manager nodes takes place via HTTP and goes through SharePoint’s Network Load Balancer (NLB) or hardware NLB, if you’re using it.
In a federated topology model, you can create a Workflow Manager farm, also known as a Workflow cluster, consisting of multiple Workflow Manager servers. A Workflow cluster can be reused by multiple SharePoint farms and can be managed completely independent of SharePoint. According to current best practices, workflow clusters should contain up to 3 Workflow Manager servers to ensure high availability. Based on Microsoft findings, this is more than enough to handle all kinds of high demanding workflow solutions.

Important Both topology models require the presence of the Workflow Manager client on every SharePoint node in the farm. See http://technet.microsoft.com/en-us/library/jj658588(v=office.15) for more information on how to do that. Workflow clusters can be created by specifying a farm scope in the Register-SPWorkflowService PowerShell cmdlet that will be discussed shortly hereafter.

Note This is a perfect example of the trend where pieces of custom software are encouraged to run outside of your SharePoint 2013 farm. This includes pieces of custom software such as workflows, InfoPath forms, SSRS reports, SharePoint Apps and so on. For administrators, this is great news as this is a huge step towards securing your SharePoint farm health.

After installing and configuring Windows Azure Workflow, you need to run the Register-SPWorkflowService PowerShell cmdlet to configure the communication between Windows Azure Workflow and SharePoint 2013. The easiest way to do this is to run this cmdlet within the SharePoint 2013 Management Shell and pass it at least the URL of the SharePoint site collection, the URI of the Windows Azure workflow host, and some optional arguments. For example:

Register-SPWorkflowService –SPSite “http://myserver/mysitecollection” –WorkflowHostUri “http://workflow.example.com:12291” –AllowOAuthHttp

Security Alert For production environments, OAuth expects the use of SSL so that all OAuth tokens are sent securely. Allowing OAuth over HTTP is a setting intended for use in development and test scenarios.

Port 12290 is used by default by the Windows Azure workflow host for HTTPS, while port 12291 is used by default for HTTP. If you’re not sure about the port number, you can always take a look at IIS Manager to find out which port you are using. The –AllowOAuthHttp flag must be added when you’re using HTTP instead of HTTPS, which ensures secure communication between your SharePoint 2013 site collection and the Windows Azure Workflow host.

Important You cannot connect Windows Azure Workflow to SharePoint Foundation. Installation of the features required for Windows Azure Workflow rely on files only found in SharePoint Server 2013 installations, specifically in the OSFSERVER install files. These files are not available in SharePoint Foundation, and therefore it is only possible to connect Windows Azure Workflow to SharePoint Server 2013.

See Also More information about connecting Workflow Managers on servers that are not a part of your SharePoint 2013 farm can be found at http://technet.microsoft.com/en-us/library/jj658588(v=office.15).

Workflow subscriptions and associations

As you have learned, the most significant change to SharePoint 2013 workflows is the moving of workflow processing onto an external workflow hosts (Windows Azure Workflow). Because of this, it was essential for SharePoint messages and events to connect to the workflow infrastructure in Windows Azure. In addition, it was necessary for Windows Azure to connect the infrastructure to customer data. Workflow associations (which are built on the WF concept of subscriptions) are the SharePoint infrastructure pieces that support these requirements.

Before we can discuss workflow associations and subscriptions, we must take a look at the Windows Azure publication/subscribe service, which is sometimes referred to as pub/sub, or simply PubSub. PubSub is an asynchronous messaging framework. Message senders (publishers) do not send messages directly to message receivers (subscribers). Instead, messages are rendered by publishers as classes which have no knowledge of the message subscribers. Subscribers, then, consume published messages by identifying messages of interest, regardless of the publisher, based on subscriptions that they have created.

This decoupling of message creation from message consumption allows for scalability and flexibility. It enables multicast messaging on the publisher side (where one message sent by a single publisher is received by multiple subscribers), and for promiscuous message consumption on the subscriber side (a subscriber receives messages by multiple publishers).

Note The PubSub feature is a part of the Windows Azure Service Bus, which provides connectivity options for WCF and other service endpoints. These include REST endpoints, which can be located behind network address translation (NAT) boundaries, or bound to frequently changing, dynamically assigned IP addresses, or both. For more information about the Windows Azure Service Bus, see http://msdn.microsoft.com/en-us/library/windowsazure/ee732537.aspx .

Workflow associations bind workflow definitions to a specific SharePoint scope, with specific default values. The associations themselves represent a set of subscription rules that are stored in the Windows Azure publication/subscription service that process incoming messages to ensure that they are consumed by appropriate (that is, subscribed) workflow instances. By default, the messaging infrastructure supports workflows at the following scopes:

SPList (for list workflows)
SPWeb (for site workflows)

Unlike previous versions, SharePoint 2013 does not support workflows that are scoped to a content type (SPContentType). However, the messaging infrastructure is extensible, so it can support any arbitrary scope.

Note Although outside of the scope of this blog post, it may be of interest to know that developers of custom workflows can set the EventSourceId property on a given WorkflowSubscription instance to any Global Unique Identifier (GUID). Workflow developers can then use that EventSourceId value to call the PublishEvent(Guid, String, IDictionary<(Of <<‘(String, Object>)>>)) method, which triggers a new workflow instance of the specified WorkflowSubscription. In other and simpler words, this allows custom solutions to notify SharePoint workflows of their own custom events.

Workflow Modeling and Development Tools

Typically, administrators won’t be responsible for creating custom workflows. Having said that, there are exceptions to this rule, and it’s certainly to be expected of SharePoint administrators that they have a working knowledge of existing workflow modeling and development tooling.

Important If you want to be able to understand the complete workflow architecture in SharePoint and its surrounding workflow tooling, it’s unavoidable to learn about the workflow modeling and development tools. A basic working knowledge of these tools will make you more effective in your job as a SharePoint administrator.

The following tools are available for creating custom workflows:

Visio 2013 can be used to create a graphical design of a workflow. It is not possible to create a fully active workflow that can be published to SharePoint directly. What you can do is use Visio 2013 to transform business processes into SharePoint workflow artifacts and import such workflows into SharePoint Designer 2013, where it can be processed further and published to SharePoint. Business analysts are the primary audience for this tool.
SharePoint Designer 2013 can be used to model new workflows or edit existing workflows in a graphical, non-programming, way. You can create fully active workflows using this tool. SharePoint power users are the primary audience for this tool.
Visual Studio 2012 is used to create workflows that can be associated with any list or library. This is the most powerful tool for creating custom workflows, as it provides its users full access to the programmatic capabilities concerning SharePoint workflows. It must come as no surprise that Visual Studio 2012 is primarily aimed at developers.

Using Visio 2013, a business analyst or information worker can design a workflow. The building blocks of the workflow can be put into place but the values of those building blocks not. This effectively allows business analysts to design the logical structure of a business process and capture that workflow artifact in a form that can be taken for further processing. The actual configuration of SharePoint workflow artifacts can be further handled in SharePoint Designer 2013.

Visual Studio 2012 and SharePoint Designer 2013 both provide a fully declarative, no-code authoring environment for creating custom workflows. A declarative workflow is a workflow that is fully described in the XML language XAML without using any code, which, from a security standpoint, is a huge advantage. XAML is interpreted at run time by the workflow engine and is derived from the stages, steps, actions, and conditions, etc. that you have used to create a custom workflow in either SharePoint Designer 2013 or Visual Studio 2012. The building blocks that are available for creating XAML documents differ depending which tool you use.

Note All workflow modeling and development tools mentioned in this section are examples of Domain Specific Language (DSL) tools. A DSL is a programming language dedicated to a particular problem domain, using its own particular problem domain visualization techniques. The various SharePoint 2013 workflow tools offer a graphical language that allows you to create workflows without having to write a single line of XAML.

You have learned that Visio 2013 cannot be used to actually create workflows that can be published directly to SharePoint, and that you would actually need to use either SharePoint Designer 2013 or Visual Studio 2012 to do this. So, when should you use which tool? That is always the question and we will take a moment to delve a little deeper into the answer.

Since SharePoint Designer 2013 and Visual Studio 2012 are both suitable to create declarative workflows, we will take a look at the different kinds of persons that would be interested in creating workflows. SharePoint Designer 2013 is easy to use and allows for Rapid Application Development (RAD). Therefore, in that respect, SharePoint Designer 2013 is suitable for use by all interest groups: information workers, business analysts and SharePoint developers. On the other hand, SharePoint Designer 2013 is quite powerful and to be able to create a workflow using SharePoint Designer 2013 you have to be familiar with the core workflow components, like stages, actions, conditions and loops. Because of this: the general audience for SharePoint Designer 2013 is described as consisting of power users: users that have a considerable working knowledge of SharePoint. Generally, this means that business analysts will stick to using Visio 2013: they will have extensive knowledge about the specific problem domain, but typically won’t have much SharePoint knowledge (or the need to learn about SharePoint at the power user level).

The target audience of Visual Studio 2012 is quite limited: it consists of intermediate or advanced software developers as the tool allows you to do actual programming. These developers have to be familiar with both Visual Studio itself as well as SharePoint.

Having described the general audiences for both tools, let’s take a look at their specific advantages and disadvantages. The overview below discusses the most important workflow features, and then explains which of the available tools is most suitable for handling those features.

Rapid workflow development Using either SharePoint Designer 2013 or Visual Studio 2012, you can create workflows very quickly. This is because the workflows are created in a declarative fashion and both tools contain building blocks to create such workflows in an easy and visual way. Having said that, SharePoint Designer 2013 has a definite edge when it comes to rapid workflow development.
Enable reuse of workflows A workflow created with SharePoint Designer 2013 can only be used on the list or library for which it was developed. SharePoint Designer 2013 does provide reusable workflows which can be used more than once in the same site. However, using Visual Studio 2012 you can create a workflow that can be associated with any list or library on any site and also be reused. That is a big advantage, so here the advantage lies with Visual Studio 2012.
Create a SharePoint workflow solution or workflow App for SharePoint Using SharePoint Designer 2013 it is absolutely not possible to create these. However, Visual Studio 2012 is created for these types of artifacts. Therefore, this tool has an absolute advantage over SharePoint Designer 2013.
Create custom actions Using SharePoint Designer 2013, you cannot create custom actions, you can however use custom actions created and deployed with Visual Studio 2012. Visual Studio 2012 does allow you to create custom actions.
Create custom code This is not possible using either SharePoint Designer 2013 or Visual Studio 2012. Even in Visual Studio 2012, you now only have a visual design surface to create workflows.

Note As stated repeatedly, Visual Studio 2012 does allow developers to create custom code in a form. They will have to do so in the form of creating custom actions or calls to separate WCF services, since it’s not possible anymore to add custom code to workflows directly.

Make use of workflows created by Visio 2013 In SharePoint Designer you can import workflows made using Visio 2013, this is not possible with Visual Studio 2012.
Deployment In SharePoint Designer 2013, deployment is done automatically once you’ve clicked the Publish button. Using Visual Studio 2012, you can create a SharePoint solution package and deploy your workflow to a site. With both tools you can package the workflows and deploy them to a remote server, although Visual Studio 2012 allows you more control over this process, whereas SharePoint Designer 2013 makes deployment just a little bit easier.
Debugging It is not possible to debug custom workflows in SharePoint Designer 2013; with Visual Studio 2012 you can debug workflows. This is an essential capability for workflows that are more complex in nature.

Concluding, you have seen why Visio 2013 is the premier tool of choice for business analysts (it is great for capturing business processes but can’t be used to publish workflows to SharePoint), why SharePoint Designer 2013 is the premier tool of choice for power users (in general, it’s easier to use then Visual Studio 2012, and does allow you to publish workflows to SharePoint), and why Visual Studio 2012 is the premier tool of choice for developers (it’s the most powerful of all tools). In the next sections, you will take a closer look at each of the different SharePoint workflow development tools.

Visio 2013

In this section, you will take a closer look at the Visio 2013 tool. Visio 2013 makes it easy to create workflows if you’re used to working with Visio. As a result, this tool is specifically interesting for business analysts and process consultants who know exactly about the logical steps of a workflow/business process, but aren’t experienced (or SharePoint savvy) enough to implement it themselves using SharePoint Designer 2013 or Visual Studio 2012. These users will typically use Visio 2013 to create a mock-up workflow, and hand this workflow artifact over to either developers or power users that will use it as a starting point for the further implementation and configuration of the workflow.

After creating a workflow using Visio 2013, it can be exported to SharePoint Designer 2013. In SharePoint Designer 2013, after importing the Visio 2013 workflow, power users can add logic to the workflow steps by using the workflow text editor or/and the new Visual Workflow Designer. When they’re done, the power users can publish the workflow to SharePoint 2013.

Note SharePoint Designer 2013 contains a new Visual Workflow Designer which shows a visual representation of the workflow in the way the workflow is shown in Visio 2013. This is done via a Visio 2013 add-in in SharePoint designer 2013. This requires Visio 2013 to be installed on the same machine as SharePoint Designer 2013. Check for available licenses as Visio 2013 is a part of Office 2013 and is not free, as opposed to SharePoint Designer 2013.

Visio 2013 contains a new template called the SharePoint 2013 Workflow template. This template contains three stencils: Actions, Conditions, and Components, as shown in Figure 2.

Figure 2 Visio 2013 workflow stencils.

Using the shapes in these stencils you can build a workflow. That is very easy because the only thing to do is to drag the workflow shape onto the drawing canvas. It is only the visual that you’re dragging onto the canvas, since using Visio 2013 you cannot add the logic behind the visual. This can be added later using SharePoint Designer 2013. Figure 3 shows a sample Visio 2013 workflow diagram.

Figure 3 Example of a Visio 2013 workflow diagram.

Best Practices After modeling the workflow in Visio 2013, you can check if the workflow contains any errors by clicking the Check Diagram button in the ribbon. You should do this every time before exporting the Visio 2013 workflow diagram.

SharePoint Designer 2013

If you are knowledgeable about SharePoint and want to take it to new limits, or even want to develop SharePoint applications, there comes a time when you need to take a look at SharePoint Designer 2013, a tool that enables rapid SharePoint development. SharePoint Designer 2013 allows advanced users and developers to create no-code solutions for a variety of problems. This is especially true when it comes to creating custom workflows; traditionally this has been made quite easy via SharePoint Designer 2013.

New functionality in SharePoint Designer 2013

SharePoint Designer 2013 contains support for the new workflow platform specifically designed for Windows Azure Workflow. This platform is called the SharePoint 2013 Workflow Platform. The new functionality that can be found in SharePoint Designer 2013 to support this new platform includes:

A new visual designer that makes use of a Visio 2013 add-in.
A new action called Call HTTP Web Service with which you can make no-code web service calls from within a SharePoint Designer 2013 workflow.
New actions for assigning a task and starting a task process. With both actions you can edit the Task Creation Email and the Task Overdue Email.

Real World These features are very popular and have been requested for a long time. Expect that these actions will be used a lot. I’m especially excited about the ease with which custom tasks can be made, and the amazing new opportunities to access external lists. Think, for example, of a customer list. Now think that just by entering customer names, a workflow kicks off and fills in the rest of the customer details in the list, such as phone numbers, addresses, and such. By the way, all web services responses are handled asynchronously by the Workflow Services Manager and managed using a throttling mechanism, so you don’t have to worry about blocking your workflow or workflow timer jobs. You can even poll a web service repeatedly by creating a stage that calls a web service, followed by another stage that pauses for, let’s say 1 hour, and then goes back to the first stage that calls the web service. That way, the information retrieved from a web service always stays up to date.

New actions for starting a List workflow or a Site workflow that are built on the SharePoint 2010 platform.
A new Dictionary type that can be used to store variables. When creating a workflow, most of the time the workflow creator will save a value in some variable (i.e. x = 10, or currentDate = 10/8/12) so you can use this value in other parts of the workflow. The Dictionary variable type is a container that is designed to hold a collection of different variables. So suppose you want to store the name and the birthday of an employee, you could use the Dictionary variable type to create an Employee Dictionary instead of creating two separate variables EmployeeName and EmployeeBirthday. In other words, dictionaries allow you to create logical groups that make it convenient to store related information together. The following new actions are designed specifically for working with the Dictionary variable type:
- Build Dictionary With this action you can create a Dictionary variable type, create the various variables that are part of this dictionary, and give the Dictionary variable itself a unique and descriptive name.

Note You can nest Dictionary variables, in other words, you can put Dictionary variables into another Dictionary variable. This can be very beneficial, and helps to make your custom workflows clean, structured, and easy to understand. For example, you could have an Employees dictionary containing multiple Employee dictionaries. In other words, the Employees dictionary acts as a collection of Employee entities. Each employee dictionary could, in its turn, contain the name of the employee, address and job title. This way, SharePoint workflow development introduces some techniques commonly found in traditional object oriented (OO) programming.

Count Items in a Dictionary Using this action, you can count the number of variables that a Dictionary contains and store that number in an Integer variable. This can be handy in case you would want to loop through all the items in a Dictionary, a very common task.
Get an Item from a Dictionary This action can be used to retrieve the value of a specific variable from a Dictionary and store it in another variable.

There are new workflow building blocks:
- Stage Using the building block Stage you can group conditions and actions together. Before moving on to the next stage, all conditions and actions are processed in the order as listed within the stage. Again, this is an improvement that makes it easier to create workflows in a clean and structured way. Improvements such as these go a long way towards making complex workflows easier to build and manage.
- Loop A loop contains a series of actions that is executed repeatedly for just as long as the specified conditions are true (i.e. while a task isn’t completed, send reminder e-mails).

Note Loops have been a much requested feature for SharePoint Designer. Probably the most anticipated one. In SharePoint 2010, workflow Loops where only available in Visual Studio 2010 as it was considered too dangerous to hand the power of Loops and its possible disastrous side-effects to power users. One misconstrued infinite loop in a custom workflow could have a definite impact on SharePoint farm performance. Now, since SharePoint 2013 workflows run outside the SharePoint farm, such risks are considered to be acceptable.

App-Only Step The contents of this step will run as the workflow application.

You can choose on which workflow platform you want to build a workflow, 2010 or 2013.
Windows Azure Workflow capabilities

Figure 4 The Visio 2013 add-in available in SharePoint Designer 2013.

Because workflows are built using Windows Azure Workflow these workflows automatically gain several new capabilities like:

High Density and Multi-Tenancy The multi-tenant hosting capabilities provide for safe, high efficiency and high performance execution of workflow instances.
Elastic Scale Elastic scale refers to the fact that the workflow service is able to manage scaling up and down of the required system capacity whenever it is necessary. This is a typical trait of cloud solutions. This advantage applies to Office 365 only.
Activity / Workflow Artifact Management There are also new capabilities for managing activities and workflows in the system. You can upload your activity via a REST API or client library, and the activities are stored in a scaled out, reliable repository. The relations between the activities, workflow definitions and the versions of the workflow definitions are also managed.
Tracking and Monitoring There are several ways to monitor your workflow including:
- Performance Counters Performance counters are grouped by counter sets. There are two counters sets available: Workflow Management and Workflow Dispatcher. Figure 5 shows the Performance Monitor. The available performance counters for workflows are:
  - Management requests per second
  - Workflow events per second
  - Management request failures per second
  - Authorization errors per second
  - Publish workflow event duration
  - Episodes outstanding
  - Episodes failed per second
  - Events processed per second

Figure 5 Relevant SharePoint 2013 workflow performance counters available via the PerfMon tool.

Event Tracing Event Tracing for Windows (ETW) is used for tracing since this has the least overhead in terms of performance. The Event Tracing for Windows provider is called Microsoft-Workflow and the following channels are used: Operational, Debug, and Analytic. You can find a complete list of events generated by Windows Azure Workflow (version 1.0) at the following location: [InstallDrive]\Program Files\ Windows Azure Workflow\1.0\Workflow.
PowerShell Using PowerShell you can easily administrate your workflow server. There are a couple of PowerShell cmdlets provided by Windows Azure Workflow that you can use to check the state of the workflow server and the health status. You must pay specific attention to two cmdlets: Get-WFFarm and Get-WFFarmStatus. The Get-WFFarm cmdlet provides a quick overview of details about your workflow farm, the hosts in your farm, and the endpoints on those hosts. The Get-WFFarmStatus cmdlet provides an overview of the basic status of the farm and the various nodes within the farm.
System Center Operations Manager Management Pack This specific SCOM pack for Windows Azure Workflow allows you to leverage SCOM as an alerting mechanism that activates whenever a workflow failure is detected.

Instance Management The hosting and management part of the workflow service and its instances are more advanced compared to SharePoint 2010.
Fully Declarative Authoring This includes fully declarative authoring of workflows via an expanded activity library, expression translation and a new declarative data modeling feature.
REST and Service Bus Messaging For REST and Service Bus Messaging, there are integrated messaging capabilities available. These messaging capabilities are integrated with the hosting runtime to ensure that inbound and outbound messages are coordinated with workflow persistence to guarantee the reliability and integrity of your processes.
Managed Service Reliability All capabilities are provided as part of a managed service offering, which delivers the reliability and service availability that your business demands. This includes service health monitoring and management, performance and scale management, 24×365 operations support, fault tolerant design, cross-data center disaster recovery, service and platform upgrades and management, and standards compliance. This advantage applies to Office 365 only.
Windows PowerShell cmdlets that manage workflow With the Get-SPDesignerSettings PowerShell cmdlet you can retrieve the SharePoint Designer 2013 settings that are enabled on a specific web application:

Get-SPDesignerSettings [-WebApplication] <SPWebApplicationPipeBind> [-AssignmentCollection <SPAssignmentCollection>]

You can also set the SharePoint Designer 2013 features of a specific web application by using the Set-SPDesignerSettings cmdlet:

Set-SPDesignerSettings [-WebApplication] <SPWebApplicationPipeBind> [-AllowDesigner <$true | $false>] [-AllowMasterPageEditing <$true | $false>] [-AllowRevertFromTemplate <$true | $false>] [-AssignmentCollection <SPAssignmentCollection>] [-Confirm [<SwitchParameter>]] [-ShowURLStructure <$true | $false>] [-WhatIf [<SwitchParameter>]]

Creating and Deploying Workflows in SharePoint Designer 2013

We will take a quick tour on how to create workflows in SharePoint Designer 2013 and show you how to deploy the workflows to SharePoint 2013. In this tour, you will also learn how to import a workflow created using Visio 2013 into SharePoint Designer 2013 and how to export a workflow created in SharePoint Designer 2013 to Visio 2013.

1. Open SharePoint Designer 2013 and open a SharePoint site.

2. You can either create a new workflow or edit an existing workflow. If you’re going to edit an out of the box existing workflow we advise you to make a copy of the original workflow. You can use one of the following options to create a new workflow or edit an existing one:

· On the New group of the Site tab of the Ribbon, you can create a new List Workflow, Reusable Workflow, or Site Workflow.

· By selecting the File tab of the Ribbon you will also have the choice to create a new List Workflow, Reusable Workflow, or Site Workflow.

· Select Workflows under Site Objects in the Navigation Pane. By selecting the New group of the Workflow tab of the Ribbon, you can create a new List Workflow, Reusable Workflow, or Site Workflow. Here you can also select an existing workflow and edit the workflow by selecting Edit Workflow on the Edit group of the Workflow tab. Or you just right click the workflow you want to edit and select Edit Workflow.

3. Open SharePoint Designer 2013 and open a SharePoint site.

4. Regardless which type of workflow you want to create, you always have to specify the Name and Description (optional) for the new workflow. For a new reusable workflow, you also have to select the content type you want to limit the workflow to. Other than that, you also have to make sure that you select the SharePoint 2013 Workflow platform type.

5. The next step is to create the workflow. SharePoint Designer 2013 contains a various set of Conditions and Actions you can add. You can also add Steps, Loops, and Parallel Blocks.

6. You can edit the settings for the workflow via the Manage group of the Workflow tab of the Ribbon. Here you can edit, for example, the workflow information, the settings of the workflow as well as other options.

For each task that you add to the workflow via a Task action, it is possible to set the task properties such as the description of the task, specify if you want to wait for task completion, and define various email options. Regarding these email options, you should know that you can specify the frequency of the email: daily, weekly, or monthly, how many times you want an overdue email to be sent and, last but not least, you can customize the Task Creation Email and the Task Overdue Email. See Figure 6 for a sample Task Creation Email edit window.

Note Customizing the tasks Task Creation Email and Task Overdue Email are certainly not the least interesting option. The ability to specify custom email messages is a popular request for almost every customer. In previous versions, this used to be more work, but in SharePoint 2013 this has become really easy.

7. After creating the workflow you can check if there are any errors. You can do this by selecting the Check for Errors menu item on the Save group of the Workflow tab.

8. If there are no errors in your workflow you can publish the workflow via the Save menu item on the Save group of the Workflow tab.

Figure 6 Creating a custom email message has become really easy.

Importing workflows from Visio 2013

It is possible to model a workflow using Visio 2013 by making use of visual building blocks, save the workflow and import this workflow into SharePoint Designer 2013. The following procedure shows you how to import a Visio 2013 workflow in SharePoint Designer 2013.

See Also See section “Visio 2013” for more information about creating Visio 2013 workflows.

1. Open SharePoint Designer 2013 and open a SharePoint site.

2. Select Workflows under Site Objects in the Navigation Pane.

3. Select Import from Visio from the Manage group of the Workflow tab of the Ribbon. This opens the Import Workflow From Visio dialog box.

4. Click Browse and select your Visio SharePoint workflow diagram and click Open.

5. Select the kind of workflow that you want to import and depending on what type of workflow you have selected you have to choose a list or a content type to associate the workflow to.

6. Click Finish.

At this point you have imported a Visio 2013 workflow in SharePoint Designer 2013 and you can edit this workflow. Then, you can start defining values for the actions and conditions that you’ve created with Visio 2013. Once you’re finished, you can publish this workflow to SharePoint 2013.

Note As a quick reminder: further configuration and workflow publication is something that can’t be done in Visio 2013 itself. This is a design choice by Microsoft: business analysts are supposed to be knowledgeable about business processes, not about SharePoint. Microsoft doesn’t want to force this audience to become SharePoint specialists before you are able to leverage their knowledge.

Exporting workflows to Visio 2013

Because SharePoint Designer 2013 contains a Visual Designer that is based upon Visio 2013, it is possible to export your workflow made in SharePoint Designer 2013 to Visio 2013 format. This is a great way to validate a workflow design and gather input from business analysts. The next procedure shows you how to export a SharePoint Designer 2013 workflow to Visio 2013 format.

1. Open SharePoint Designer 2013 and open a SharePoint site.

2. Select Workflows under Site Objects in the Navigation Pane.

3. Select Export to Visio from the Manage group of the Workflow tab of the Ribbon.

4. The Export Workflow to Visio Drawing dialog box opens, select a location where you want to save your Visio drawing, enter a name and click Save.

At this point, you’ve saved your SharePoint Designer 2013 workflow as a Visio drawing. You can now open Visio 2013 and select the workflow. You can edit the workflow and change the shapes, save the workflow or export it to work on it again in SharePoint Designer 2013.

Visual Studio 2012

Using Visual Studio 2012, you can create declarative workflows. Visual Studio 2012 contains a visual workflow designer surface to create workflows in a designer environment. For Visual Studio developers, the most significant change is that workflows are no longer compiled and deployed as .NET framework assemblies. Instead, Visual Studio 2010 creates XAML documents that are interpreted directly by the workflow engine.

Workflows are designed to run on WAW and work with Apps for SharePoint. For on-premises farms, the WAW servers also run on premises. For Office 365, WAW runs in the cloud (Azure). Running workflows on WAW enables you to remotely run and host workflows outside SharePoint Server. The workflows no longer make use of InfoPath forms, only ASP.NET forms are used. There is no distinction between state or sequential workflows anymore, as stages (discussed previously) can be used to create state workflows if needed.

Workflows now have their own identity, the App identity or App principal, which it gets as a result from the new SharePoint App model where workflows are now considered to be Apps, just like lists, libraries, events, and such. The reverse is also true: custom Apps can include custom logic as well as contain SharePoint workflows and leverage that as part of its custom logic. So, SharePoint 2013 workflows are Apps, not all Apps are SharePoint 2013 workflows, and some Apps contain SharePoint 2013 workflows. If workflows are part of another App, they run under the App identity of that App instead of having their own App identity.

The default access scope of a workflow is read/write permissions to the host site (which can be checked via Site Settings > Site App Permissions, then look at the Workflow App Display Name). If workflows run as part of another App, they run under the permissions granted to that App.

By default, when workflows access SharePoint resources, both the Workflow App identity and the end user have to have access in order for the action to succeed. Alternatively, workflows can be created that use so-called App Step actions (also available within SharePoint Designer), that are placed within Stages. Any action placed within an App Step succeeds if the Workflow App identity has sufficient permissions to complete the action, regardless of whether the end user has access or not. This is the SharePoint 2013 way of elevating end user privileges. App Steps are only available if the Workflows can use app permissions site feature is activated.

Note It’s a remarkable move that InfoPath forms are no longer used in workflows. InfoPath in combination with Forms Services is a great platform that makes it quite easy to create robust and nice looking web forms. I’ve found that one of the places where InfoPath really shines was within SharePoint workflows. InfoPath forms are rendered to HTML by Forms Services, running as a service within your SharePoint farm. To me, this is just another example of the clear trend where Microsoft tries to move custom code outside of your SharePoint environment.

If you want to create a workflow using Visual Studio 2012 you first have to create a SharePoint 2013 project, as shown in Figure 7.

Figure 7 Start developing a SharePoint workflow by creating a SharePoint 2013 solution within Visual Studio 2012.

After the creation of a SharePoint 2013 project you have to add a new workflow item to the project. When you have done this, the designer surface will open, as shown in Figure 8.

Figure 8 The workflow designer surface in Visual Studio 2012.

As stated earlier you can only write no-code workflows using Visual Studio 2012. If you want to write custom code for your 2013 workflow you’re supposed to create a custom WCF service and call that service from the new HTTP activities that are available, such as:

· HttpDelete An activity for sending an HTTP Delete request (a request to delete a server resource) and receiving an HTTP response.

· HttpGet An activity for sending an HTTP get request (a request for retrieving a server resource) and receiving an HTTP response.

· HttpMerge An activity for sending an HTTP merge request (a request for updating a server resource) and receiving an HTTP response.

· HttpPost An activity for sending an HTTP post request (a request for submitting information to the server) and receiving an HTTP response.

· HttpPut An activity for sending an HTTP put request (a request for creating a server resource if it doesn’t already exist, or update an existing server resource) and receiving an HTTP response.

Visual Studio 2012 also contains a workflow custom action-item type to create a custom activity. This custom activity can also be imported in SharePoint Designer 2013 (see Figure 9).

Figure 9 Creating a custom workflow activity.

Setting up and configuring SharePoint 2013 workflows

You can enable workflows in SharePoint 2013 without thinking about security and configurations, but that should be contrary to all of your administrator instincts. In the next sections, you will learn how to set up SharePoint workflow configuration.

Enable or disable user-defined workflows

As an administrator you’re able to decide if you want to allow users to deploy declarative workflows on a specific web application. By default, users can deploy declarative workflow to a SharePoint 2013 site. These are workflows that are created using SharePoint Designer 2013 or Visual Studio 2012. There are some scenarios where you don’t want users to deploy workflows without you, the administrator, knowing about it. The following procedure shows you how to enable or disable the deployment of declarative workflows.

1. Go to SharePoint 2013 Central Administration.

2. In the section Application Management, click Manage web applications.

3. Select the web application for which you want to change the user defined workflow settings.

4. Go to the Web Applications tab in the Manage section, click General Settings and select Workflow.

5. The Workflow Settings dialog box opens and contains the following settings (see Figure 10):

· Yes – enable user-defined workflows for all sites on this web application.

· No – disable user-defined workflows for all sites on this web application.

6. Click OK to close the Workflow Settings dialog box.

Figure 10 Inspect available workflow settings.

Configuring task notifications

SharePoint wouldn’t be as effective if end users would have to go and actively find out if there are any tasks waiting for them. Typically, end users will be notified when tasks are awaiting them. An interesting case and security issue arises when internal end users get task assignments within sites where they don’t actually have sufficient permissions, or when external end users get task assignments. As an administrator, there are several generic task notification settings surrounding these issues you can set per web application. The following procedure demonstrates how to specify these settings:

1. Open SharePoint 2013 Central Administration.

2. In the section Application Management, click Manage web applications.

3. Select the web application for which you want to configure the task notification settings.

4. Go to the Web Applications tab in the Manage section, click General Settings and select Workflow.

5. The Workflow Settings dialog box opens and contains the following settings:

· Yes – alert internal users who do not have site access when they are assigned a workflow task.

· No – do not alert internal users who do not have site access when they are assigned a workflow task

· Yes – allow external users to participate in workflow by sending them a copy of the document.

· No – do not allow external users to participate in workflow by sending them a copy of the document.

6. Click OK to close the Workflow Settings dialog box.

Configuring Workflow timer jobs

Timer jobs run by themselves according to a specific predefined schedule, or are started manually. When timer jobs are executed, they run in a specific Windows service, the SharePoint 2013 Timer service (SPTimerV4), on (depending on the timer job configuration) one or more SharePoint servers within your farm. A timer job contains a definition of the service to run and specifies how frequently the service is started. The following timer jobs are related to workflows: Workflow Auto Cleanup, Workflow, and Workflow Failover. Timer job schedules can also be specified via Windows PowerShell.

The following PowerShell cmdlets are available for timer jobs:

Disable-SPTimerJob The name speaks for itself, this cmdlet disables a timer job. The syntax is as follows (where Identity specifies the timer job to disable, this can be the GUID of the timer job, the name of the timer job, or an instance of a valid time job object):

Disable-SPTimerJob [-Identity] <SPTimerJobPipeBind> [-AssignmentCollection <SPAssignmentCollection>] [-Confirm [<SwitchParameter>]] [-WhatIf [<SwitchParameter>]]

· Enable-SPTimerJob This cmdlet enables a timer job. Before you can start a timer job you must enable it. The syntax is as follows:

Enable-SPTimerJob [-Identity] <SPTimerJobPipeBind> [-AssignmentCollection <SPAssignmentCollection>] [-Confirm [<SwitchParameter>]] [-WhatIf [<SwitchParameter>]]

· Get-SPTimerJob If you call this this cmdlet without specifying any parameters; it retrieves information about all timer job definitions within the SharePoint farm. By specifying the parameters, you can retrieve a specific timer job, timer jobs of a specific type, or timer jobs defined for a specified scope, for example SPWeb (SharePoint site scope). The syntax of this cmdlet is as follows:

Get-SPTimerJob [[-Identity] <SPTimerJobPipeBind>] [-AssignmentCollection <SPAssignmentCollection>] [-Type <String>] [-WebApplication <SPWebApplicationPipeBind>]

· Set-SPTimerJob This cmdlet can be used to set the schedule of a timer job. The syntax is as follows:

Set-SPTimerJob [-Identity] <SPTimerJobPipeBind> [-AssignmentCollection <SPAssignmentCollection>] [-Confirm [<SwitchParameter>]] [-Schedule <String>] [-WhatIf [<SwitchParameter>]]

· Start-SPTimerJob This cmdlet runs a timer job once on each front-end Web server where the parent service is provisioned. The syntax is as follows:

Start-SPTimerJob [-Identity] <SPTimerJobPipeBind> [-AssignmentCollection <SPAssignmentCollection>] [-Confirm [<SwitchParameter>]] [-WhatIf [<SwitchParameter>]]

Configuring Workflow Auto Cleanup timer jobs

When you associate a workflow to a SharePoint entity (such as a list), you have to choose or create a task list and a history list. Workflows that are completed and their related task entries are removed automatically after a default period of 60 days. This may be something you want to change, and you can do this by configuring the Workflow Auto Cleanup job, which is the timer job that is responsible for cleaning up the completed workflows and their task entries. Follow the next procedure to configure the Workflow Auto Cleanup job:

1. Open SharePoint 2013 Central Administration.

2. Select the Monitoring section on the left navigation bar.

3. In the Timer Jobs section, select Review job definitions.

4. On the Job Definitions page, select the Workflow Auto Cleanup job definition.

5. The Edit Timer Job shows the following options:

· The Job Title, in our case we’re looking for the Workflow Auto Cleanup timer job.

· The Job Description.

· The Job Properties, which contain the name of the web application as well as the last time the timer job ran.

· The Recurring Schedule section can be used to modify the schedule of the timer job. You can schedule the timer job to run every x minutes, or hourly where you can specify how many minutes past the hour the timer job can run, or daily where you can specify between which hours the timer job is allowed to run, or weekly where you can specify which day of the week the timer job can run, or monthly to be specified by the day of the month or the day of the month, for example the second Sunday of the month.

6. Finally, after configuring the schedule of the timer job, you have the following choices:

· Run Now, if you want the timer job to run immediately. This choice is great for testing purposes and administrators typically use it to run the timer job for the first time after initial installation.

· Disable, if you want to disable the timer job and don’t run it at all.

· Ok, if you’re satisfied with your new schedule and you want to timer job to run according to this schedule.

· Cancel, if you’re not satisfied and just want to keep your old or the default preferences.

Figure 11 Configuring Workflow timer job settings.

Configuring Workflow timer jobs

The timer job for cleaning up workflows and tasks, the Workflow Auto Cleanup timer job, is useful, but it’s not the only one you need to know. Next, we’re discussing the Workflow job. This timer job is responsible for processing queued workflow events that could not immediately be handled, and does this within the actual context of the web application. By default this timer job is scheduled to run every 5 minutes but this is adjustable, just follow the procedure as described in section “Configuring Workflow Auto Cleanup Timer Jobs”, only this time, look for the Workflow timer job.

Configuring Workflow Failover timer jobs

The last timer job to discuss is the Workflow Failover timer job. This timer job is responsible for processing workflow events that have failed and are marked to be retried. By default this timer job is scheduled to run every 15 minutes but this is adjustable, just follow the procedure as described in section “Configuring Workflow Auto Cleanup Timer Jobs”, only this time, look for the Workflow Failover timer job.

Deploying workflows

The following section shows you how to deploy a workflow in SharePoint 2013, arguably one of the top two tasks that fall under the responsibility of SharePoint administrators (the other one being workflow monitoring). The deployment method depends on the way the workflow was created, using either SharePoint Designer 2013 or Visual Studio 2012.

Although creating custom workflows is reasonably easy to do, don’t forget that there is a set of the out of the box workflows that is ready for use. No new workflows have been added in SharePoint 2013, so you can only choose from the list of workflows that was already available in SharePoint 2010. The following predefined workflows are available for use out of the box:

· Collect Feedback routes a document or item to a group of people for feedback.

· Approval routes a document or item to a group of people for approval.

· Disposition Approval, this workflow manages document expiration.

· Collect Signatures collects digital signatures from a group of people for a specific document created within an Office application.

· Three-State tracks the status of a list item through three different phases (such as Active, Resolved, and Closed).

· Translation Management manages manual workflow translation by creating and routing copies of source documents to designated translators for translation.

Note All of these out of the box workflows can be copied and customized to your specific needs. Although possible, it’s a best practice to refrain from adjusting the original workflows directly.

Deploying an out of the box SharePoint workflow

Out of the box workflows are workflows that are present by default on your SharePoint 2013 server. The out of the box workflow available in SharePoint 2013 are in fact the old SharePoint 2010 workflows, not 2013! We will nevertheless discuss how to deploy and use these workflows because they are also part of SharePoint 2013.

Important This is not a case where old SharePoint 2010 workflows are deprecated and are only there for backward compatibility reasons. On the contrary, the set of SharePoint 2010 workflows have been tested and used thoroughly over the years and there was no urgent reason to recreate them using the SharePoint 2013 workflow platform. Expect that this set of SharePoint 2010 workflows remains popular and useful and don’t hesitate to use them.

Before you can deploy and use the workflow you have to activate the corresponding features, otherwise these workflows won’t be visible. The following procedure shows you how to deploy a default workflow (later on, in section “Activating Workflows” we will discuss specifics for the most important default workflows):

1. Activate the workflow feature that corresponds to the workflow you want to deploy.

2. Associate the workflow you want to deploy to a list, library, content type, or site.

3. Start the workflow and check if it works!

Deploying a SharePoint Designer 2013 workflow

Deploying a workflow created with SharePoint Designer 2013 is very easy to do. The following procedure shows a high level overview of the steps you need to take to deploy a workflow that is associated with a list, library, content type, or site.

1. Create a workflow using SharePoint Designer 2013.

2. Check if the workflow contains any errors.

3. Deploy the workflow via the Publish button.

Deploying a Visual Studio 2012 workflow

Visual Studio 2012 workflows are packaged and deployed as features. The deployment of a feature includes installing a solution, activating a feature and associating the workflow to a SharePoint entity such as a list. The following procedure shows how to deploy a workflow created in Visual Studio 2012.

1. Create a workflow using Visual Studio 2012.

2. Package the workflow as a feature. This feature will be packaged as a solution file.

3. Install the solution on the SharePoint server.

4. Deploy the solution on the SharePoint server.

5. Go to the site collection and activate the workflow feature.

6. Go to the list, library, content type, or site and associate the workflow.

Activating workflows

Before using any type of workflow, whether it is an out of the box workflow or it is a workflow created with SharePoint Designer 2013 or Visual Studio 2012, you must activate the workflow before you can start associating the workflow. Table 1 shows which feature to activate for the most important out of the box SharePoint 2010 workflows that are available to you.

Table 1 Features and workflows

Feature	SharePoint 2010 out of the box Workflow
Disposition Approval Workflow site collection feature	Disposition Approval Workflow
Publishing Approval Workflow site collection feature	Publishing Approval Workflow
Three-state Workflow site collection feature	Three-state Workflow

Activating a feature

The following procedure shows you how to activate a feature:

1. On the top level of the site collection, click the Settings icon, and select Site Settings. This icon is located on the top right of the page.

2. In the Site Collection Administration section, click Site collection features.

3. On the site collection features page, activate the features that you need. Figure 12 shows a part of the site collection features page.

Figure 12 Activating features required for out of the box workflows.

Associating a workflow

After creating and deploying a workflow you have to associate the workflow. You have to do this for the out of the box, SharePoint Designer 2013, and Visual Studio 2012 workflows. Associating a workflow is more than adding the workflow to a list, library, content type, or site; it is also assigning a task list and history list to the workflow. You can select an existing task list or history list to use or you can create a new list. For a small site you could use just one task list or history list. But we recommend using a different task list and history list for each workflow, this way you avoid potential performance problems and it’s clear for the administrators and users. In the next sections we’re going to discuss how to associate a workflow to a list, library, content type, or site.

Associating to a content type

The following procedure shows you how to associate a workflow to a content type:

1. Go to the site where you want to associate a workflow to a content type.

2. Click the Settings icon which is located on the top right of the page, and select Site Settings.

3. On the Site Settings page in the Web Designer Galleries section, click Site content types.

4. On the Site Content Types page, select the content type that you want to associate with a workflow.

5. On the Site Content Type page of the content type you’ve selected in the Settings section, click Workflow settings.

6. On the Workflow Settings page, click Add a workflow. You can also use this page to view and change the workflow settings and to add or remove workflows.

7. On the Add a workflow page, select a workflow you want to associate to the content type.

8. In the Name section, type a unique name for the workflow that is recognizable and descriptive.

9. In the Task List section, enter the name of the task list you want to use or create. If you enter a name of an existing task list then that task list will be used. If you enter a task list name that doesn’t exists yet, then a new task list will be created.

10. In the History List section, enter the name of the history list you want to use or create. For the history list name the same things apply that apply to the task list name: if a history list with the same name already exists, that list will be used. Otherwise, a new history list will be created.

11. In the Start Options section, you can specify how the workflow can be started (see Figure 13). The following options are available to choose from:

· Allow this workflow to be manually started by an authenticated user with Edit Item permissions. Select this option to allow users to start the workflow manually. You also have an extra option called Require Manage List Permissions to start the workflow. This way you can make sure that only administrators can start the workflow.

· Start this workflow when a new item is created. Select this option when you want the workflow to start when a new item or document is created.

· Start this workflow when an item is changed. Select this option when you want the workflow to start when an existing item or document is updated.

12. In the Update List and Site Content Types section, you can choose if you want the workflow to be applied to all child content types.

13. Click Next to go to the next page. This second page contains additional configuration information specific for each workflow. When you’re done configuring the second page, click Save.

14. Now you can use the associated workflow with any item or document that inherits from the content type you’ve associated the workflow with.

Figure 13 Associate a workflow to a SharePoint entity.

Associating to a list or library

Use the following procedure to associate a workflow to a list or library:

1. Go to the site where you want to associate a workflow to a list or library.

2. If you want to associate a workflow to a list follow these steps:

a. Go to the list you want to use.

b. Select the List tab.

c. In the Settings section, select Workflow Settings and click Add a Workflow.

3. If you want to associate a workflow to a library follow these steps:

a. Go to the library you want to use.

b. Select the Library tab.

c. In the Settings section, select Workflow Settings and click Add a Workflow.

4. On the Add a workflow page select the workflow you want to add.

5. In the Name section, type a descriptive name for the workflow.

6. In the Task List section, provide a name for the task list you want to use. This can be an existing task list or a new one. If the task list doesn’t exist yet, a new one will be created automatically.

7. In the History List section, type a name for the history list. If the history list doesn’t exist yet, a new history list will be created automatically.

8. In the Start Options section you can specify how the workflow can be started. The following options are available to choose from:

· Start this workflow to approve publishing a major version of an item. This option is only available in document libraries when you have enabled content approval and are using major/minor versioning. This option is also only available for the Approval and Publishing Approval workflow.

· Start this workflow when a new item is created. Select this option when you want the workflow to start when a new item or document is created.

· Start this workflow when an item is changed. Select this option when you want the workflow to start when an existing item or document is updated.

9. Click Next to go to the next page. In this procedure, we have chosen the Disposition Approval workflow, in which case you just have to click the OK button.

10. This second page contains additional configuration information specific for each type of workflow. For example, when you choose to create an instance of the Collect Feedback workflow, you have to specify the names of the reviewers, and the content of a task request.

11. When you’re done configuring the second page, click Save.

Associating to a site

The following procedure shows you how to associate a workflow to a site:

1. Go to the site that you want to use to associate a workflow to.

2. Click the Settings icon and select Site Settings.

3. On the Site Settings page in the Site Administration Settings section, click Workflow settings.

4. On the Workflow Settings page, select the workflow you want to associate.

5. In the Name section, type a descriptive name for the workflow.

6. In the Task List section, select a task list you want to use or select the option New task list from the dropdown list.

7. In the History List section, from the dropdown list select a history list you want to use or select the option New history list.

8. In the Start Options section you can specify if you want the workflow to be manually started by an authenticated user with Edit Item permissions. In effect, this means users that are administrators. With site workflows, there are not many options available for starting workflows: you can only start a workflow manually.

9. After finishing the configuring options you can click the OK button.

Monitoring workflows

It is essential to monitor a workflow during the life cycle of the workflow. Arguably, this is the most important task you are responsible for when it comes to administrating workflows. You can do this via the associated list or library of a workflow scoped at that level. Alternatively, you can check the workflow status for site workflows. You can also check the workflow reports and troubleshoot errors that happen during the execution of the workflow. In the next sections, we will show you the various aspects concerning workflow monitoring.

Checking Workflow Status

First, you will learn how to check the status of a list or library workflow. This is done via the workflow status column. A new workflow feature in SharePoint 2013 is that workflow status columns are now treated as normal list columns, which means you can have access to all list column features and you can do all sort of things to these columns, such as ordering and filtering. The following procedure shows how to check the status of a workflow:

1. Go to the list where you’ve associated and started the workflow.

2. Every item in the list or library that contains a workflow has a workflow status column. This column contains the status of a workflow, for example In Progress. Click on the status of the workflow.

3. On the Workflow Status page, you will find a lot of workflow information as can be seen in Figure 14 which shows a part of this page.

4. On the Workflow Status page you will find the following workflow information:

· The name of the initiator of the workflow.

· The start date of the workflow.

· The date when the workflow last run.

· The name of the document or list item.

· The status of the workflow.

· A workflow visualization displayed in a Visio 2013 diagram (this is a new feature in SharePoint 2013 and is a great way to get an idea of what a workflow does). If you don’t want to interact with this visualization within a web interface, you can open the workflow visualization directly in Visio 2013, by clicking on the available Open in Visio link. This last option also allows you to make changes to the workflow. You can also find information about the shapes that are used in the workflow by clicking on the Shape Info link.

· Links to tasks associated with the workflow, for example approval workflows will display a link that cancels all approval tasks.

· A link to terminate the workflow immediately. This can sometimes be useful if a workflow contains errors or stops responding. The workflow status will be set to Canceled and all workflow tasks will be deleted.

· An overview of all the tasks that are assigned together with their status. You can also click on the task and have a look at the contents.

· An overview of the workflow history. The events logged into the history list contain the Date Occurred, the Event Type, for example an error, User ID, and Description

Figure 14 Monitoring running workflows.

The following procedure shows you how to check the workflow status of a site workflow:

1. Go to the site that you want to check.

2. Click the Settings icon, and select Site Settings.

3. On the Site Settings page in the Site Administration section, select Workflow Settings.

4. To view the status of a workflow, just click on the name of the workflow.

5. The Workflow Settings page shows the following information:

· The name of the initiator of the workflow.

· The start date of the workflow.

· The date when the workflow has run for the last time.

· The status of the workflow.

· An overview of all the tasks that are assigned together with their status. You can also click on the task and have a look at the contents.

· An overview of the workflow history. The events logged into the history list contain the Date Occurred, the Event Type, for example an error, User ID, and Description

Troubleshooting workflow issues

Because SharePoint 2013 uses a new workflow platform, namely Windows Azure Workflow, and because Visual Studio now creates declarative workflows, developers cannot put code directly into custom workflows anymore. The only way to add custom code to workflows is to either create a custom activity that can be used within a custom workflow, or put the custom code into a web service and call the web service from one of the new workflow HTTP activities. This makes debugging a lot harder.

Troubleshooting Out of the box workflows

Let’s start the discussion of troubleshooting workflows by taking a look at the out of the box workflows. The first hint that an out of the box workflow contains an error is that the SharePoint item workflow status in the UI displays the Error workflow status. The best thing to do when this happens is to take a look at the history list of that workflow and figure out where the workflow went wrong. The most common errors are connectivity problems, incorrect email settings, or user permissions that are not correct, probably insufficient permissions.

Note A nifty way of making out of the box workflows easier to debug is to use SharePoint Designer to create a copy of one of the existing workflows and start adding logging capabilities to it. While this will definitely make it easier to debug out of the box workflows, this is usually overkill since the existing workflows have been tested thoroughly and have been around for a long time. So, not many, if any, inherent problems in the workflows exist. Plus, there’s a lot of support out there when it comes to using the default SharePoint workflows, for example in the form of the online SharePoint forums. Nevertheless, it’s good to know the option exists.

Troubleshooting SharePoint Designer 2013 workflows

There are no debugging options available in SharePoint Designer 2013. You cannot put breaks and step into the workflow while it’s running and take a look at the stack trace (which displays the code execution path so that it’s easier to determine where the workflow went wrong).

Note This style of troubleshooting is only suitable for development, and optionally test and staging environments. Debugging production environments using breaks etc. is extremely harmful for server performance and availability.

The only thing you can and should do is put comments at strategic places and take a good look at where the workflow fails. Such comments ultimately show up in the History lists associated to workflow instances and they form an essential aid when it comes to debugging workflows.

Important As an administrator, you should demand that as a part of the deliverables for a custom workflow, documentation is included detailing what kind of diagnostics instrumentation is included in the workflow, what kind of messages you should look for, and finally, you should ask about the meaning of those messages.

In addition, if you want to debug SharePoint Designer workflows at a lower level, you could take a look at the section “Debugging Workflows” to learn how to use Fiddler to closely watch all HTTP traffic that the workflow generates.

Troubleshooting Visual Studio 2012 workflows

Developers can easily debug Visual Studio 2012 workflows (again: not in a production environment); they can set breakpoints and run the workflow to watch where exactly and at which activity things go wrong. Administrators however, cannot do that, and shouldn’t want to do that. They have to look at either the log files or history list. So the best thing to do is to ask the developers to include detailed diagnostics instrumentation in their custom workflows, and make them provide clear documentation about it.

On a lower level, asking developers to include diagnostics is usually equivalent to asking them to use the WriteToHistory workflow activity in each workflow they create to make history log entries to track the status of the workflow and track where it failed. Make it a protocol that whenever a workflow is created, all important information and status of the workflow is logged using the WriteToHistory activity.

Important Logging guidelines should be a part of the deployment guidelines of your company. You should not allow the deployment of custom workflows without having such guidelines in place, and without making sure the custom workflows adhere to these workflows. Best practices concerning SharePoint 2013 have yet to emerge, but the TechNet Wiki SharePoint 2013 Best Practices page at http://social.technet.microsoft.com/wiki/contents/articles/12438.sharepoint-2013-best-practices.aspx is a good place to keep track of such emerging best practices.

Debugging workflows

The introduction of Windows Azure Workflow in SharePoint means that workflows are hosted and executed within an environment external to SharePoint. This also means that behind the scenes, a lot of communication at the HTTP level is going on between SharePoint and Windows Azure Workflow. As a result, a lot of information can be obtained by monitoring HTTP traffic between your SharePoint farm and Windows Azure Workflow. And that’s not all, as you have learned; WCF services have become increasingly important as a means to add custom code to custom workflows. This means yet more HTTP traffic.

In this section, you will learn how to debug SharePoint 2013 workflows using an HTTP traffic monitoring tool such as Fiddler. Or, to take a quote from the Fiddler web site: Fiddler is a free web debugging proxy that can be used to log all traffic the computer and internet, you can download Fiddler here: http://www.fiddler2.com/fiddler2/. Fiddler is created by a Microsoft employee and has involved to the de facto standard when it comes to free HTTP traffic monitoring tools used in troubleshooting SharePoint deployments.

Important As opposed to the other techniques described in the “Troubleshooting workflow issues” section, this technique can be used in black box troubleshooting scenarios. In other words, if you can’t modify a workflow (or have it modified by somebody else) to add diagnostic info, and the current diagnostic capabilities of a workflow are not sufficient, you can still use this technique to find out more about the workings of a workflow and the problems it encounters. Although this technique can potentially be used in production environments, this should be done with extreme caution and off hours, as it will affect SharePoint server performance.

To use Fiddler to debug SharePoint 2013 workflows, just follow the next procedure:

1. Open Windows Explorer and go to the following location: %systemdrive%\Windows\Microsoft.NET\Framework\v4.0.30319\Config. Find the machine.config, make a copy of the file and open the original machine.config. The copy is just for backup in case something goes wrong. Add the following code to the end of the machine.config, just before the last closing tag.

<system.net>
<defaultProxy enabled=”true”>
<proxy bypassonlocal=”false” usesystemdefault=”true” />
</defaultProxy>
</system.net>

2. Save the file and close it.

3. Go to the next location using the Windows Explorer: %systemdrive%\Windows\Microsoft.NET\Framework64\v4.0.30319\Config. Find the machine.config, make a copy of the file and open the original file. The copy is just for backup in case something goes wrong. Add the following code to the end of the machine.config, just before the last closing tag.

<system.net>
<defaultProxy enabled=”true”>
<proxy bypassonlocal=”false” usesystemdefault=”true” />
</defaultProxy>
</system.net>

4. Save the file and close it.

5. Start Fiddler.

6. Intercept the HTTP traffic that is coming from SharePoint and Windows Azure Workflow by selecting Tools in the tool bar of the Fiddler product and clicking Fiddler Options. The Fiddler Options dialog box opens.

7. Click the Connections tab, as shown in Figure 15.

8. Select the following options:

· Reuse client connections

· Reuse connections to servers

· Act as system proxy on startup

· Monitor all connections

9. Click OK.

Figure 15 Monitoring HTTP traffic using the free Fiddler tool.

Now you must install the Fiddler certificate as a trusted root on the SharePoint server. This certificate is used to re-encrypt the traffic after debugging it.

1. Select Tools in the tool bar of the Fiddler product, and click Fiddler Options. The Fiddler Options dialog box opens.

2. Click the HTTPS tab.

3. Select the following options (which is necessary as SharePoint 2013 and Windows Azure Workflow communicate over SSL):

· Capture HTTPS CONNECTs

· Decrypt HTTPS Traffic

4. A windows box opens with the message that Fiddler generates a unique root certificate. Click Yes if you don’t mind reconfiguring a Windows Trusted CA list.

5. The next security warning pops up, now stating that you’re about to install a certificate with an unconfirmed thumbprint asking if you really, really want to do that. Click Yes.

6. Check the Ignore server certificate errors check box, as shown in Figure 16.

7. Click the Export Root Certificate to Desktop button.

8. You will see a popup window that says that the file FiddlerRoot.cer has been exported to your desktop. Click OK.

9. Click OK in the Fiddler Options dialog box.

Figure 16 Specifying advanced Fiddler options to inspect SharePoint-WAW traffic.

Now you must install the Fiddler certificate that is located on our desktop. You can do this using PowerShell.

1. Open the SharePoint 2013 Management Shell.

2. Copy or type the following in the SharePoint 2013 Management Shell:

certUtil.exe -addstore -enterprise -f -v root [path]\FiddlerRoot.cer
$trustCert = Get-PfxCertificate [path]\FiddlerRoot.cer
New-SPTrustedRootAuthority -Name “Fiddler” -Certificate $trustCert
IISRESET

Now that everything is configured, you’ve ended up editing two machine.config files, configured the interceptions of the traffic coming from SharePoint and Windows Azure Workflow, and finally you’ve installed the Fiddler certificate as a trusted root. In the final procedure, you will see what happens when everything is working:

1. Log in as the service account user for SharePoint and Windows Azure Workflow.

2. Open Fiddler.

3. Run iisreset to restart SharePoint. This way Fiddler is able to catch the traffic between SharePoint and Windows Azure Workflow.

4. Restart the Windows Azure Workflow by clicking Start, selecting Administrative Tool, and clicking Services. Go to the Workflow Service Backend service.

5. Right-click the Workflow Service Backend service and select Restart. This way Fiddler can monitor HTTP(S) traffic between SharePoint and Windows Azure Workflow.

Now that Fiddler is running, and SharePoint and Windows Azure are restarted, you will be able to inspect the communication between SharePoint and Windows Azure Workflow.

See Also To give credit where credit is due, as far as I know Andrew Connell was the first one to use and document this type of advanced workflow debugging. More information about this technique can be found at http://www.andrewconnell.com/blog/archive/2012/07/18/sharepoint-2013-workflow-advanced-workflow-debugging-with-fiddler.aspx.

Uncategorized sharepoint 2013

PowerShell Maxer for SharePoint 2013

Leave a comment Posted by Nikander & Margriet Bruggeman on October 8, 2013

Checking Capacity boundaries was made simpler using our Maxer tool (http://gallery.technet.microsoft.com/office/Maxer-for-SharePoint-2013-52208636). We decided that it would be way easier to port the code to PowerShell (and then add some). This makes it easier for everybody to add or adjust sections according to personal or company liking.

PowerShell Maxer for SharePoint 2013 is a script that checks for capacity planning limits as described per the Planning section of the TechNet Wiki SharePoint 2010 Best Practices overview page at http://social.technet.microsoft.com/wiki/contents/articles/12438.sharepoint-2013-best-practices.aspx

PowerShell Maxer for SharePoint 2013 can do the following things:

· Checks user limit in groups.

· Checks list item limits.

· Checks site user limits.

· Displays group membership.

· Displays group owners.

· Analyzes all web applications, site collections, and sites in a farm.

· Displays which features have been activated at the farm, web application, site collection, and site level.

· Checks sub site limits.

· Checks site collection limits per content db.

· Displays site collection owner and creation date.

· Lists relevant application pool names.

· Checks user limit in site collections.

To get the idea, we’ve included some code snippets.

Here’s code for counting the number of list items:

Copy code

PowerShell

Edit|Remove

function CountLists($currentWeb)

{

foreach ($currentList in $currentWeb.Lists)

{

$sw.WriteLine(“There are {0} items in list {1}. A max of 30,000,0000 is allowed.”, $currentList.ItemCount, $currentList.Title)

}

Code for counting members in a group:

Copy code

PowerShell

Edit|Remove

function CountGroups($currentSc)

{

foreach($currentGroup in $currentSc.OpenWeb().SiteGroups)

{

$sw.WriteLine(“Group {0} has {1} users. A max of 5,000 is allowed.”, $currentGroup.Name, $currentGroup.Users.Count)

}

Code for counting all users in a site collection:

Copy code

PowerShell

Edit|Remove

function CountUsers($currentSc)

{

foreach ($currentUser in $currentSc.OpenWeb().SiteUsers)

{

$sw.WriteLine(“User {0} is a member of {1} groups. A max of 5,000 is allowed.”, $currentUser.get_Name(), $currentUser.Groups.Count)

}

Code for finding group owners:

Copy code

Edit|Remove

function CountOwners($ownersWeb)

{

foreach($ownersGroup in $ownersWeb.Groups)

{

if($ownersGroup.Name -like “*Owners*”)

{

$sw.WriteLine(“”)

$sw.WriteLine(“The following users are a member of the {0} group:”, $ownersGroup.Name)

foreach($ownerUser in $ownersGroup.Users)

{

$sw.WriteLine(“User: {0}”, $ownerUser.Name)

}

Code for counting sub sites and displaying activated site features:

Copy code

PowerShell

Edit|Remove

function Countwebs($currentSc)

{

foreach ($currentWeb in $currentSc.AllWebs)

{

$sw.WriteLine(“”)

$sw.WriteLine(“Analyzing Web site {0}”, $currentWeb.Title)

CountOwners $currentWeb

$sw.WriteLine(“”)

$sw.WriteLine(“The following features are active at Web scope:”)

$contentWebAppServices = (Get-SPFarm).services

$webFeatures = Get-SPFeature | Where-Object {$_.Scope -eq “Web” }

if ($webFeatures -ne $null)

{

foreach ($feature in $webFeatures)

{

if ((Get-SPFeature -Web $sc.Url | Where-Object {$_.Id -eq $feature.id}) -ne $null)

{

$sw.WriteLine(“Feature: {0}, Typename {1} with GUID {2} is hidden {3}”, $feature.DisplayName, $feature.TypeName, $feature.Id, $feature.Hidden)

}

$sw.WriteLine(“”)

$sw.WriteLine(“Web site {0} has {1} sub sites. A max of 2,000 is allowed.”, $currentWeb.Title, $currentWeb.Webs.Count)

CountLists $currentWeb

$sw.WriteLine(“”)

}

Code for counting site collections in content db’s:

function CountContentDatabases($currentWebApp)
{
foreach($currentCd in $currentWebApp.ContentDatabases)
{
$sw.WriteLine(“Content database {0} has {1} site collections. The maximum supported is 10,000. Recommended is a maximum of 5,000.”, $currentCd.name, $currentCd.Sites.Count)
}
}

And so on… Get the full PS script via the download link at http://gallery.technet.microsoft.com/office/PowerShell-Maxer-for-cd9e13d6

Uncategorized sharepoint 2013, Tools

SharePoint 2013 Workspaces

Leave a comment Posted by Nikander & Margriet Bruggeman on August 8, 2013

For all people missing workspaces in sps 2103:

Document Workspace site template:
– No longer available to simplify the list of site templates. Collaborating on a document is now provided by the Team Site site template.
– Workspaces created in SPS 2010 and upgraded to 2013 continue to function, but are deprecated and will not work in vNext.

Meeting Workspace site templates
– All meeting workspace templates are no longer available (such as Blank Meeting Workspace) as functionality overlaps to much with other Office and/or SharePoint functionality (such as Lync live meetings, OneNote note taking during meetings, normal SharePoint team sites).
– Workspaces created in SPS 2010 and upgraded to 2013 continue to function, but are deprecated and will not work in vNext.

Changes from SPS 2010 to 2013 overview: http://technet.microsoft.com/en-us/library/ff607742.aspx

Uncategorized sharepoint 2013

← Older posts

Tag Archives: sharepoint 2013

Apps, the SharePoint Store, and the Corporate Marketplace

Understanding the SharePoint App Model

SharePoint App Architecture

App – SharePoint Communication

App Hosting Options

Apps in the SharePoint Store

Apps in an isolated SharePoint site

Apps on an Application Server

Apps in the Cloud

No Hosting

What Apps can’t do

Handling events in Apps for SharePoint

Understanding SharePoint Customization Models

Farm Solutions

Sandboxed Solutions

App Solutions

Comparing SharePoint Customization Models

Understanding Security Protocols: OAuth and S2S

High-Trust Apps

OAuth

OAuth Protocol Communication Flow

SharePoint App Communication Flow

Managing Apps

Configuring the App environment

Managing the Corporate Catalog

Buying Apps from the SharePoint Store

Requesting Apps

Installing Apps

Uninstalling Apps

Updating Apps

Managing Licenses

Monitoring Apps

Workflow Architecture

Workflows in SharePoint 2013

Workflow subscriptions and associations

Workflow Modeling and Development Tools

Visio 2013

SharePoint Designer 2013

New functionality in SharePoint Designer 2013

Creating and Deploying Workflows in SharePoint Designer 2013

Importing workflows from Visio 2013

Exporting workflows to Visio 2013

Visual Studio 2012

Setting up and configuring SharePoint 2013 workflows

Enable or disable user-defined workflows

Configuring task notifications

Configuring Workflow timer jobs

Configuring Workflow Auto Cleanup timer jobs

Configuring Workflow timer jobs

Configuring Workflow Failover timer jobs

Deploying workflows

Deploying an out of the box SharePoint workflow

Deploying a SharePoint Designer 2013 workflow

Deploying a Visual Studio 2012 workflow

Activating workflows

Activating a feature

Associating a workflow

Associating to a content type

Associating to a list or library

Associating to a site

Monitoring workflows

Checking Workflow Status

Troubleshooting workflow issues

Troubleshooting Out of the box workflows

Troubleshooting SharePoint Designer 2013 workflows

Troubleshooting Visual Studio 2012 workflows

Debugging workflows

Archives

Follow Blog via Email