SharePoint 2013: workflows overview 2

Some more high level information about what to expect when building SharePoint 2013 workflows. Below are all the available actions:

The most interesting one for me personally is the 'Call HTTP web service' action. So when you want to write custom logic, instead of writing custom workflow actions just reuse or build a new workflow and call it with parameters if needed. The result given by the web service can then be captured by your workflow.

All conditions:

 All components:

To conclude: I think this might be a very good alternative for Nintex Workflow.

Windows Azure Workflow (WAW) troubleshooting

Right after I had installed WAS and tried to register my SharePoint 2013 test site collection with Windows Azure Workflow, the system told me it could not correctly communicate with the workflow service endpoint.

During WAW installation, databases and a new IIS website are created. This website has two end points running on port 12290 for HTTPS and 12291 for HTTP. If you use your browser to visit one of them you should see the correct endpoint scope info.

<?xml version="1.0"?>
<ScopeInfo xmlns="http://schemas.microsoft.com/workflow/2012/xaml/activities" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
   <DefaultWorkflowConfiguration/>
   <Description>Root Scope</Description>
   <LastModified>2012-08-07T11:09:34.42</LastModified>
   <LastRevised>2012-08-07T11:09:34.42</LastRevised>
   <Path>/</Path>
   <SecurityConfigurations>
      <ScopedSecurityConfiguration i:type="WindowsSecurityConfiguration">
         <Name>Microsoft.Workflow.Management.Security.WindowsSecurityConfiguration</Name>
         <WorkflowAdminGroupName>BUILTINAdministrators</WorkflowAdminGroupName>
      </ScopedSecurityConfiguration>
   </SecurityConfigurations>
   <Status>Active</Status>
</ScopeInfo>

However, in my case, I had a null pointer exception and I also could not start the 'Workflow service backend' service.

[NullReferenceException: Object reference not set to an instance of an object.] Microsoft.Workflow.Gateway.HttpMessageExtensions.AddServiceDiagnosticHeader(HttpResponseMessage response, ScopeOperationContext context) +165 Microsoft.Workflow.Gateway.HttpMessageExtensions.ConvertExceptionToResponse(HttpRequestMessage request, Exception exception, ScopeOperationContext context) +976 Microsoft.Workflow.Gateway.Global.CompleteRequestOnException(HttpContext context, Exception exception) +62 Microsoft.Workflow.Gateway.Global.Application_BeginRequest(Object sender, EventArgs e) +119 System.Web.SyncEventExecutionStep.System.Web.HttpApplication.IExecutionStep.Execute() +79 System.Web.HttpApplication.ExecuteStep(IExecutionStep step, Boolean& completedSynchronously) +164

First of all, if you have troubles with the workflow infrastructure and want to start digging in, use this Microsoft article to get you started. Basically it tells you to go to the correct category in the Event Viewer (Microsoft-Workflow) to check for clues there.

So that's what I did and there I found the following message:

Unhandled exception in AppDomain:  Microsoft.Workflow.Common.FatalException: An unrecoverable error occurred. For diagnostic purposes, this English message is associated with the failure: 'Workflow Service configuration 'WorkflowServiceMaxDispatcherFailureRate' is not formatted correctly. The configuration string should be parsable to a 'Single' type. Current config value is '0.1'.'. ---> System.IO.InvalidDataException: Workflow Service configuration 'WorkflowServiceMaxDispatcherFailureRate' is not formatted correctly. The configuration string should be parsable to a 'Single' type. Current config value is '0.1'.
   at Microsoft.Workflow.Common.AsyncResult.End[TAsyncResult](IAsyncResult result)
   at Microsoft.Workflow.Service.WorkflowServiceBackendHost.OnStartCompleted(IAsyncResult result)
   --- End of inner exception stack trace ---
   at Microsoft.Workflow.Common.Fx.<>c__DisplayClass2.<FailFast>b__0()
   at System.Threading.ExecutionContext.RunInternal(ExecutionContext executionContext, ContextCallback callback, Object state, Boolean preserveSyncCtx)
   at System.Threading.ExecutionContext.Run(ExecutionContext executionContext, ContextCallback callback, Object state, Boolean preserveSyncCtx)
   at System.Threading.ExecutionContext.Run(ExecutionContext executionContext, ContextCallback callback, Object state)
   at System.Threading.ThreadHelper.ThreadStart().

After spending a lot of time digging around in the web.config and related databases, I found that configuration value in the WFResourceManagementDB database. Then go into the WorkflowServiceConfig table and search for the configuration value. Change it from '0.1' to '0,1' and start the 'Workflow service backend' service. Now go back to your browser and refresh the page. You should see the correct endpoint scope info.

Windows Azure Workflow: Could not successfully create management Service Bus entity 'WF_Management/WFTOPIC'

The problem has to do with the runas user you specified when creating a new Workflow Farm.  First of all make sure you read this article which specifies the required configurations for the account you use.

Also make sure you use the fully qualified name for the runas account: user@domain.com

SharePoint 2013: installing Windows Azure Workflow

Because I want to try and make use of all the new stuff that SharePoint 2013 offers in terms of workflows I had to install Windows Azure Workflow. I had some problems during the installation because a time-out seem to occur at the first step 'Creating a new service bus farm'.

Finally I found the following article that explained the system configuration prerequisites. For me the SQL Browser service was not running.

Also make sure that if your server is part of a domain, the runas user you specify is a domain account. It's important you use the fully qualified name of the user: user@domain.com

SharePoint 2013: using SharePoint Designer 2013 to create a workflow

Introduction
SharePoint Designer can be used to visually create workflows and keeps you away of using real code to create workflows. Therefore the complexity is far lower but as a result, your are limited in the actions you can use.

In SharePoint 2013, there is an improved visual designer. The Visio designer is included in SharePoint Designer if you have installed Visio. You can drag in the different shapes on the left representing the different actions to create your workflow.

New in SharePoint 2013 workflows are stages. Each stage can contain multiple actions. Each stage has an entry point and a gate. The gate determines what should be the next stage based on a certain condition if you want. You can go back to the same stage creating a loop, going to a next stage or end the workflow. If you want, you can still switch to the former text based view.

To make use of the visual workflow designer you must install Visio 2013. You also need to install Windows Azure Workflow. A guide for that installation can be found here.

SharePoint 2013: workflows overview

Introduction
Workflows is one of the most used functionalities in SharePoint and can be applied in almost any type of company. SharePoint 2010 didn't offer many different things compared to SharePoint 2007. Both were based on the Workflow foundation 3.5 framework.
SharePoint 2010 did introduce site based workflows running in the site context, you could create reusable workflows, import them in a Visual Studio 2010 coded workflow, create reusable workflows with SharePoint designer and some workflow events were introduced.

In SharePoint 2013, workflows from SharePoint 2010 are still going to run and you can still build workflows using the old methods. In the new version, a workflow is treated as a service and runs in an on-premise and a hosted model. Everything is now based on Windows Azure Workflow. These workflows run in the context of the Windows Azure Workflow and not in the SharePoint process.

High level architecture

When you publish a workflow to SharePoint 2013, it's going to store a copy (the master version) of the workflow and will then push it to Windows Azure Workflow where it will run.

When a workflow is started, SharePoint 2013 is going to tell Windows Azure Workflow (WAW) which workflow needs to run and will also provide it with information like on which list item the workflow was launched and in which site it needs to run. WAW will then queue the job and run it when possible. If extra information is needed, WAW will communicate to SharePoint using the CSOM via WCF to get the necessary details.

Workflows based on WFD 4.0 can only be built of your current farm is connected to a WAW environment.

Improvements

• Stages: provides support for repeating and skipping workflow steps. A stage is a combinations of workflow activities. After a stage is completed a new stage can start. This next stage is not necessarily the next stage in the schema. A stage has a 'goto' action. A stage can be connected to any other stage.
• Loops: SharePoint Designer 2013 now supports loops.
• We can call web services. The result of this call can be stored in workflow variables and used further on.
• Programmatic workflows are still possible but only in WAW. It's recommended to use web services when custom logic is needed.
• New tools: SharePoint Designer and Visual Studio.

SharePoint 2013: remote event receivers

Remote event receivers is another one of the very cool new things we can expect in the upcoming version of SharePoint. Remote event receivers are very similar to the regular event receivers we know from earlier versions of SharePoint: they are triggered when a certain event happens, we can specify which code has to run for which event and we can choose between synchronous and asynchronous events.

With remote event handlers this will all be the same. The only difference is that the code that will run when the event occurs will be served by a web service. This means that if we register a remote event receiver we will also tell SharePoint which web service needs to run.

How it works

1. The user does an action on SharePoint (e.g. edits a list item).
2. SharePoint talks to ACS  (Access Control Service) and requests a signed token contain information about the current user's context.
3. SharePoint then talks to the registered web service where we can do whatever we want. We could for example update a backend system as a result of the fired event.
4. The backend system sends succes or failure back to the web service.
5. The web service can now also talk to the ACS to request its own signed token to do a call back to SharePoint. So using this token we can do remote actions from within the web service as a result of our earlier operation in the backend system.

If you want to know which events are supported, open up Visual Studio, create a new SharePoint hosted app and add a remote event receiver. In the next screen, as today in Visual Studio 2010, you will see the supported events.

The template code basically has two methods:

1. ProcessEvent: which allows to do the remote call but also provides code to get a context token to do a callback to SharePoint
2. ProcessOneWayEvent: used to do a one way call to the web service without a callback to SharePoint

Registering the remote event receiver

If you look in your app you will see that a new elements file has been added:

<?xml version="1.0" encoding="utf-8"?>

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

  <Receivers ListTemplateId="3100">

      <Receiver>

        <Name>RemoteEventReceiver1ItemAdding</Name>

        <Type>ItemAdding</Type>

        <SequenceNumber>10000</SequenceNumber>

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

      </Receiver>

  </Receivers>

</Elements>

Using this CAML, we can specify which events we want to support and via the 'Url' tag we can tell SharePoint which web service call needs to be made.

App events

You can also make use of events at the app level. Click on the app project and checkout the properties on the bottom right hand side of the screen. You have settings for 'Handle app installed/uninstalled/upgraded'. When you set these to through, new entries will be added to the app manifest to support these events.

Coding

If you check the generated code, the most important is the default paramater for both methods:

RemoteEventProperties properties

As with regular event handlers, this RemoteEventProperties will give you access to all kinds of details about the incoming event.

SharePoint 2013 URL tokens

Below a list of URL tokens that can be used at the beginning of the app URL specified in the app manifest file:

Token	Resolves to	Remarks
~appWebUrl	The URL of the app web of an app for SharePoint.	This token should be used only outside an app web. Within the app web itself, use ~site for the URL of the app web.
~controlTemplates	The URL of the ControlTemplates virtual folder for the current website.	This token cannot be used in the StartPage element of an app manifest, or in a custom action or app part on a host web.
~layouts	The URL of the Layouts virtual folder for the current website.	This token cannot be used in the StartPage element of an app manifest, or in a custom action or app part on a host web.
~remoteAppUrl	The URL of a remote web application in an app for SharePoint.	This token can be used in the app manifest only for autohosted apps. For provider-hosted apps, you must specify the URL. It can be used outside the app manifest for both provider-hosted and autohosted apps.
~site	The URL of the current website.	This token cannot be used in the StartPage element of an app manifest, or in a custom action or app part on a host web.
~sitecollection	The URL of the parent site collection of the current website.	This token cannot be used in the StartPage element of an app manifest, or in a custom action or app part on a host web.

URL tokens that can be used within URL's:

Token	Resolves to	Remarks
{AppWebUrl}	The URL of the app web in an app for SharePoint.	This token should be used only outside an app web. Within the app web itself, use {Site} for the URL of the app web.
{HostLogoUrl}	The logo for the host web of an app for SharePoint.
{HostTitle}	The title of the host web of an app for SharePoint.
{HostUrl}	The URL of the host web of an app for SharePoint.
{ItemId}	The ID of a item in a list or library (an integer).	This token cannot be used in the StartPageelement of an app manifest, or in a custom action or app part on a host web.
{ItemUrl}	The URL of the item being acted upon.	This token cannot be used in the StartPageelement of an app manifest, or in a custom action or app part on a host web.
{Language}	The current language/culture of the host web of an app for SharePoint.
{ListId}	The ID of the current list (a GUID).	This token cannot be used in the StartPageelement of an app manifest, or in a custom action or app part on a host web.
{RecurrenceId}	The recurrence index of a recurring event.	This token is not supported for use in the context menus of list items. This token cannot be used in the StartPageelement of an app manifest, or in a custom action or app part on a host web.
{Site}	The URL of the current website.	This token cannot be used in the StartPageelement of an app manifest, or in a custom action or app part on a host web.
{SiteCollection}	The URL of the parent site of the current website.	This token cannot be used in the StartPageelement of an app manifest, or in a custom action or app part on a host web.
{SiteUrl}	The URL of the current website.	This token cannot be used in the StartPageelement of an app manifest, or in a custom action or app part on a host web.
{StandardTokens}	This combines three other tokens. It initially resolves to SPHostUrl={HostUrl}&SPAppWebUrl={AppWebUrl}&SPLanguage={Language}. Then each of these tokens resolves. If there is no app web, the portion &SPAppWebUrl={AppWebUrl} is not present.

SharePoint 2013: app components

When using Visual Studio 2012 RC, by default the SharePoint 2013 developer tools are not installed. Use the link mentioned in one of my previous posts to download and install them.

To create a new SharePoint app, open Visual Studio -> file -> new -> project. Select the 'Office/SharePoint' node and then select 'App for SharePoint 2013'. Make sure you also select the 'SharePoint hosted' option.

As you can see in the Solution Explorer, the solution contains one project containing the app manifest and all the other resources that will make up the final SharePoint app.

The app manifest
The app manifest is a CAML file which tells SharePoint something more about the app we want to install. It contain the name, a unique product ID, an icon, ... . Notice that when you double click on the manifest file, Visual Studio 2012 now provides you with a new and far more easier configuration screen which in the background will correctly adapt the CAML itself. Also notice that when you right click on the manifest file you can still do 'View code' to see the actual CAML and do your own modifications if needed.

<?xml version="1.0" encoding="utf-8" ?>

<App xmlns="http://schemas.microsoft.com/sharepoint/2012/app/manifest"
     Name="SharePointApp1"
     ProductID="{98baa31c-06be-4144-bb39-f9b26595416c}"
     Version="1.0.0.0"
     SharePointMinVersion="15.0.0.0">
  <Properties>
    <Title>SharePointApp1</Title>
    <StartPage>~appWebUrl/Pages/Default.aspx?{StandardTokens}</StartPage>
  </Properties>

  <AppPrincipal>
    <Internal />
  </AppPrincipal>

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

</App>

• The first node, the 'App' node contains the name, product ID, version and minimal version of SharePoint required.
• The default 'properties' tag holds the title and the startpage. Notice the new token '~appWebUrl': The URL of the app web of an app for SharePoint.
• What I have added myself is the 'AppPermissionRequests' tag. Remember that app permissions are not the same as user permissions. There is not real hierarchy and the application will ask for certain permissions during installation. What is asked for exactly is specified in the manifest file. The permission request is in the form of a URL pointing to what permissions are needed. If you use the visual configuration in Visual Studio, in the 'Permissions request' section, you can try out different stuff. The available options will be listed for you.

Resource files

What else is in the package ? Basically a collection of standard SharePoint modules which will take care of the deployment if the resource files. These are mainly javascript, CSS and ASPX pages. Remember that to create the logic of your app, you cannot use server side code on a SharePoint server. You will have to use a combination of javascript, REST and CSOM to do all your stuff. Microsoft has already included the JQuery javascript library and has also provided you with an app.js file where you can start coding some Javascript. All files are loaded in the default.aspx page.

SharePoint 2013: SharePoint apps overview

In SharePoint 2013, one of the biggest new things is SharePoint apps. An app is the new way to add new functionality to your SharePoint environment. In fact, to avoid confusion, even lists are called apps from now on.

You have two main types of apps:
1. SharePoint hosted: all the resources and logic are hosted within SharePoint
2. Cloud based apps: developer hosted app (resources and logic are hosted outside of SharePoint, for example on an IIS website on a none SharePoint server) or resources and logic are hosted in Azure (Azure website + Azure SQL)

Very important to know is that apps cannot run server side code on a SharePoint server. You will have to use client side code (REST, CSOM (Client Side Object Model), oAuth) to do all your stuff. I will talk about REST and CSOM in future posts.

Apps can be distributed via Microsoft's Marketplace where you can download free and payable apps or you can setup your own corporate catalog running within your enterprise.

There are separate permissions for apps and it's not the same as user permissions in SharePoint. The difference is that apps will request certain permissions to the user during installation. This is done in the application manifest file. The user will then have to approve or reject this request. When rejected, the app is simply not installed.

When an app is installed on a specific web, SharePoint will for us create a new sub web, the application web. This web will host the resources of the installed app and will have a unique URL to provide app isolation. Isolation is a very important factor when talking about apps. It's important that apps cannot talk to each other and can access each-other's resources. The unique URL's avoid cross site scripting.
The app web is invisible when clicking the 'More' (former 'View all site contents') so this page is not overcrowded with websites. You can however list them using PowerShell.

The URL of such an app web looks something like this:

http://tenant-APP1UID.domain.com/GUIDAPP1

APP1UID: unique ID given to the app during installation. Will make each app domain unique.
GUIDAPP1: name of the SPWeb under which the app will be installed. By default, visual studio will propose a GUID when creating a new app. As a developer you can change  this value.

From a user perspective, you will have three types of experiences:
1. immersive app: the application takes over the entire UI, takes over the complete screen.
2. part app: a web part serving the app as a part of the screen.
3. extension app: more related to custom actions. Extension of the ribbon or ECB.

In future posts, I will talk in more detail about some of the aspects touched above.

Microsoft Office Developer Tools for Visual Studio 2012

If you are like me trying some stuff out with the new upcoming version of SharePoint 2013 and want to make use of the new templates for Visual Studio 2012 RC, you can download them here under the 'Tools' section.

In the coming days I will be adding a lot of new articles about SharePoint 2013 and all the new cool features you can expect. Get ready for some really cool stuff.