A good way to understand the new architecture of workflow in SharePoint 2013 is to compare it to the existing WF 3.x architecture in SharePoint 2010 (Figure 16-1). This legacy workflow engine is still available in SharePoint 2013, mainly for backward compatibility, and a good understanding of its limits allows a better understanding of the architectural choices made in SharePoint 2013.

Figure 16-1. A simplified schema of the architecture of WF 3.x in SharePoint 2010 and 2013.

From a functional perspective, every workflow instance running on WF 3.x is hosted in SharePoint 2010/2013 and runs on a SharePoint server. When a running workflow instance interacts with an end user through custom pages or tasks, the workflow instance is executed within the process of a web front-end server. When a workflow instance executes some background tasks, it runs in the background timer service of SharePoint, through a dedicated timer job that will run every n minutes (by default, every 5 minutes) onto one dedicated application server. While a workflow instance is not running—for example, because it is waiting for an external event such as an approval from an end user—the instance gets persisted in the content database of the target site collection and is unloaded to keep the environment light and safe.

Such an architecture works great for simple and low-traffic scenarios. For a huge workflow infrastructure with thousands of running workflow instances, however, you cannot rely on executing instances within the same process that is providing web content to end users, nor can you rely on a single dedicated application server. Thus, in SharePoint 2013 you should take advantage of the new WF 4.5 engine (shown in Figure 16-2) and relegate WF 3.x to backward compatibility uses only.

Figure 16-2. A simplified schema of the new architecture of WF 4.5 in SharePoint 2013.

As shown in Figure 16-2, the workflow engine now runs on a dedicated server farm, based on a new service called Workflow Manager 1.0. The Workflow Manager 1.0 engine has a highly scalable architecture, which allows executing a huge number of workflow instances in near–real time and using an external multiserver and multitenant infrastructure. In Microsoft Office 365, Workflow Manager is hosted on Microsoft Windows Azure to improve scalability. On-premises, you have to deploy a server farm, which can be hosted on the same SharePoint servers or on a dedicated set of servers, in case you need to serve a high number of workflow instances and users in a dedicated environment.

The Workflow Manager farm and the SharePoint 2013 farm communicate across the network, empowering the new Windows Azure Service Bus when communicating between SharePoint and Workflow Manager. In Office 365, the Windows Azure Service Bus will be provided by Windows Azure. On-premises, however, you will have to install the stand-alone version of the Service Bus, which can be installed together with Workflow Manager 1.0. Later in this chapter, you will learn how to deploy on-premises both Workflow Manager 1.0 and the Service Bus engine. On the other side, when Workflow Manager communicates with SharePoint 2013, it uses the new Representational State Transfer (REST) APIs, like any external SharePoint 2013 app.

The security infrastructure is enforced using OAuth 2.0 and Windows Azure Access Control Services (ACS) in Office 365, or, if you are on-premises, a local security (server-to-server, or S2S) trust between SharePoint 2013 and the local Workflow Manager.

On the SharePoint side of the architecture, there is also a service application proxy, which connects the SharePoint 2013 farm with the remote Workflow Manager 1.0 farm. To communicate with the remote Workflow Manager 1.0 farm, the service application proxy uses a Workflow Client 1.0 library, which provides the basic and primitive commands for interacting with the remote Workflow Manager 1.0 farm. Internally, the Workflow Services Manager component, which sits on top of the workflow service application proxy, provides capabilities to support workflow instance management, deployment, messaging, and interoperability with legacy SharePoint 2010 workflows.

SharePoint, on its own side, manages lists, libraries, items, documents, and all the events that can be of any interest for the workflow engine. Moreover, SharePoint saves and manages workflow associations, activities, and metadata configuration. Whenever an event of interest occurs for Workflow Manager, such as itemAdded or itemUpdated, the workflow service application proxy will inform Workflow Manager using a WCF-based communication channel, using the Service Bus and an event publish/subscribe model. This publish/subscribe model can also be accessed by apps and custom workflows, which can send activation messages through the Service Bus to the external Workflow Manager engine. One interesting thing to notice is that, thanks to the publish/subscribe event model offered by the Service Bus, if an event of interest for multiple target workflow instances occurs on the SharePoint side, the communication channel between SharePoint and Workflow Manager will deliver only one event notification. On the Workflow Manager side, the Service Bus will raise the event in every target workflow instance, via a multicast event-based system, reducing the traffic across the wire and allowing multiple subscribers for the same published event.

In this new architecture, you can associate a workflow definition either with an SPWeb object or an SPList instance. Starting with SharePoint 2013 and the new workflow architecture, a workflow association cannot be defined targeting an SPContentType object, however. Thus, SharePoint 2013 supports list workflows and site workflows only. Moreover, as it was in the previous version of the workflow engine, in 2013, a workflow instance can be started manually by an end user, or automatically upon specific events, such as an item creation or change. Furthermore, with the new engine, as with the old, you can start a workflow definition as many subsequent times against a specific item as you want, but you cannot start two concurrent instances of the same workflow definition against a unique target item.

As soon as a workflow association is started against a target item, the client side of the workflow service will inform the remote Workflow Manager using an event, which is defined accordingly to the publish/subscribe infrastructure defined. If there will be any workflow definition on the Workflow Manager side subscribed for that specific event happening, then a new workflow instance will be created. Moreover, as it was with SharePoint 2010 workflows, every workflow association relies on a workflow tasks list, as well as a workflow history list. The workflow tasks list holds the tasks related to the workflow processes, while the workflow history list stores history messages.

From a development perspective, an advanced user can create workflow definitions using either SharePoint Designer 2013 or Microsoft Visual Studio 2012. You can create workflows for both versions of the workflow engine using either tool.

The following are the main goals achieved with this new architecture:

To start playing with the new Workflow Manager 1.0 engine, you can use Office 365, which is already configured and ready to use, or you can deploy the workflow engine on-premises. The new workflow engine is not configured by default, however; you need to download, install, and configure it before you can use it. If you plan to play with the new workflow engine simply on Office 365, skip ahead to the “Your first workflow with SharePoint Designer 2013” section. If you plan to deploy the workflow on-premises, read on here.

You can download the Workflow Manager 1.0 engine, as well as Workflow Client 1.0, from Microsoft through Web Platform Installer 4.5 (or later), which is available at http://www.microsoft.com/web/downloads/platform.aspx. Figure 16-3 displays the interface of Web Platform Installer 4.5 when installing Workflow Manager 1.0.

Figure 16-3. The Web Platform Installer UI during the installation of Workflow Manager 1.0.

To install Workflow Manager 1.0, you need the following:

If you are installing Workflow Manager 1.0 on the same servers where you are running the SharePoint 2013 farm, all these requirements will be already satisfied. Otherwise, if you plan to install Workflow Manager on-premises on a dedicated set of servers, you will have to install all of them, and you will have to install Workflow Client 1.0 only onto the SharePoint servers.

After you install Workflow Manager 1.0, you must run the Workflow Manager Configuration Wizard, which will walk you through the various configuration steps. The configuration wizard starts by asking if you want to configure a new Workflow Manager farm or if you want to join an already existing farm (Figure 16-4).

Figure 16-4. The first step of the Workflow Manager Configuration Wizard.

Choose to configure a new farm, and select the second option—Configure Workflow Manager With Custom Settings—which will allow you to personalize the farm configuration for your testing, development, or production environment.

Next, the wizard asks you to provide some configuration information about the Workflow Manager farm (Figure 16-5). You will have to provide information about the following:

Figure 16-5. The second step of the Workflow Manager Configuration Wizard, for configuring the Workflow Manager farm.

After you configure the Workflow Manager farm, you must configure the Service Bus. Again, the wizard will drive you through the steps to accomplish this task. In particular, as you can see in Figure 16-6, you will be prompted for providing the following information:

Figure 16-6. The main step of the Service Bus Configuration wizard for configuring the Workflow Manager farm.

The Workflow Manager Configuration wizard also allows you to generate a PowerShell script for automating the installation process, just in case you want to repeat the same installation process using that script. After configuring a first server in the farm, you will be able to add as many servers as you want. It will suffice to download and install Workflow Manager 1.0 on any target server and to run the Workflow Manager Configuration wizard, choosing to join an already existing farm.

After having configured the Workflow Manager farm, you will have a wide set of database files configured on the target Microsoft SQL Server database engine, including

While on your development environment, you need not give these database files special attention, but in a real production environment, you should consider including these databases in you disaster-recovery and high-availability plans.

After you configure a Workflow Manager farm, you should have three services running on the target servers:

The last step before you can use Workflow Manager in SharePoint 2013 is to link the Workflow Manager farm with the SharePoint 2013 farm. To accomplish this task, you simply need to execute the following PowerShell cmdlet:

Register-SPWorkflowService -SPSite 'http://devbook.sp2013.local/' -WorkflowHostUri 'http://sp2013srv01:12291/' -AllowOAuthHttp –Force $wfproxy = Get-SPWorkflowServiceApplicationProxy $wfproxy.RegisterWorkflowLifecycleManagementEnvironment()

Table 16-1 lists all of the arguments available for the Register-SPWorkflowService cmdlet.

As already stated, in a development or testing environment, you could configure the Workflow Manager farm to use HTTP and port 12291, and not only HTTPS and port 12290. On the other hand, in a production environment, you should always configure HTTPS, and you should register as trusted the X.509 certificate used by the Workflow Manager farm on the SharePoint 2013 farm as well.

After linking the SharePoint 2013 farm with the Workflow Manager farm, you will be able to find a new service application proxy named Workflow Service Application Proxy under SharePoint Central Administration (SPCA), on the Manage Service Applications page. By clicking that service application proxy, you will be presented with a simple page stating that the workflow service is connected, as shown in Figure 16-7.

Figure 16-7. The service application proxy page of the Workflow Service Application Proxy.

One last test to check that the workflow service is properly configured and connected to SharePoint 2013 is to start a new instance of SharePoint Designer 2013 and access the site you just connected with the workflow service. Click the Workflows command on the left-hand accordion and add a new list workflow definition for any of the available lists or libraries—for example, choose the Documents library if it exists in the target site. In the Create List Workflow dialog box will be a drop-down list with a caption of Platform Type (see Figure 16-8).

Figure 16-8. The dialog window for creating a new list workflow definition in SharePoint Designer 2013.

If this drop-down list provides you both SharePoint 2010 Workflow (WF 3.x) and SharePoint 2013 Workflow (WF 4.5), then you are ready to start creating workflows with the new workflow engine. If you see only SharePoint 2010 Workflow, you need to double-check your farm configuration.

The best way to learn about a tool or technique is to see it in action, so in this section, you will create a SharePoint workflow from scratch with Microsoft SharePoint Designer 2013. For this exercise, imagine that you want to implement a sample approval workflow, which will assign an approval task to a target user as soon as a new document is uploaded to a target library.

To begin, open SharePoint Designer 2013 and connect to a target site configured for supporting the new workflow engine. Choose the Workflows section in the left-hand accordion and select the command to create a new List Workflow. For example, target the Documents library that is available by default in many site definitions, or create a new document library for using it as the target of your workflow definition. Choose the SharePoint 2013 workflow target platform.

SharePoint Designer 2013 will prompt you with a new design surface, which is made of stages. A stage is a piece of a workflow definition that allows grouping conditions and actions together. You can think of a stage as a state in a state machine workflow; you can go to a specific stage when a certain condition occurs, or you can repeat a stage until a condition ceases. Through stages, you can control the flow of your workflow definitions, and you can create repetitions. Stages are a new and fundamental feature introduced in SharePoint Designer 2013 thanks to the new workflow engine of SharePoint 2013. Each stage can be made of one or more conditions, steps, actions, or loops. On the top ribbon of SharePoint Designer 2013, as shown in Figure 16-9, you can choose to add any of these elements to the design surface.

Figure 16-9. The workflow design surface of SharePoint Designer 2013.

When designing an approval workflow, you first must define some infrastructural variables and startup parameters, which will be used to configure any workflow instance. On the ribbon, click the Initiation Form Parameters button. You will be prompted with a dialog box like the one illustrated in Figure 16-10.

Figure 16-10. The Association And Initiation Form Parameters dialog box of SharePoint Designer 2013.

As in SharePoint 2010, in SharePoint 2013 a workflow definition can have an association form, which is used to configure the workflow association with its target. It can also have an initiation form, which is used to provide startup parameters to a specific workflow instance. An association or initiation parameter can assume several types of values:

You can define every parameter by providing a name, a description, an underlying data type, and an optional default value. Assume that the current approval workflow needs to define a default request-for-approval message during association, as well as a target approver (person or group) during initiation. Add a couple of parameters that fit these definitions and name them ApprovalRequestMessage and TargetApprover. As you define each parameter, the interface of the dialog box adapts to the target data type you choose. For example, while configuring the TargetApprover parameter as a field of type Person or Group, you are prompted with a designer for configuring the behavior of the PeoplePicker control that will be used.

Now you can define some variables by clicking the Local Variables ribbon command. The variables should have a name and a data type. The available data types are:

First, define an ApprovalOutcome variable of data type Boolean. Now you are ready to design the real workflow. In order to ask to the TargetApprover subject to approve the document, add an action, evaluate its result, and change the status of the target document. The action for assigning a task to a target user is available in the Actions group. In Chapter 15 you learned how to create a very simple activity from scratch by writing some custom code. From a SharePoint 2013 viewpoint, an action is a wrapper around one or more activities that makes them available as a human-readable statement. Table 16-2 lists the default actions available in SharePoint Designer 2013. Although they are not listed here, some legacy actions of SharePoint 2010 are still available (for backward compatibility) in SharePoint 2013 via the interop bridge.

To monitor the outcome of actions and determine the flow of a process, you can use conditions. Table 16-3 lists the conditions available in SharePoint Designer 2013. Although not included here, some legacy SharePoint 2010 conditions are still available (for backward compatibility) via the interop bridge. In addition, in Chapter 18 you will learn how to extend the list of conditions and actions by creating custom code in Visual Studio 2012.

Lastly, you can define loops (Loop n Times and Loop with Condition action), as well as parallel blocks, which are useful for creating real workflow and business processes.

For the sample approval workflow, you need to add a few more actions from Table 16-2. Assume that the approval process should not take more than five days from the creation of the target item to approve. Thus, insert an Add Time to Date action to add five days to the current date and time, and store the result in a variable. Next, add an action to assign an approval task to the target approver user, providing values for task recipients, title, description, and due date, and reading them from the current workflow variables. Now rename the current stage by clicking the stage title and providing a Title value of “Assign Approval Task.”

Add a new stage and name it Check Approval Outcome. At the very end of the first stage, add a Go to Stage action, and set the target stage to the Check Approval Outcome stage. In the new stage, add a condition of type If Any Value Equals Value, and configure it to check the approval task outcome. If the task outcome is an approval, the workflow will set the workflow variable named ApprovalOutcome to a value of Yes; otherwise, it will set that variable to a value of No. Moreover, the workflow will save a message in the history list to track the approval result.

Lastly, the stage will read any comment from the approval task and save it into the ApprovalComment workflow variable. To complete the workflow definition, create the second stage to complete the workflow instance, configuring a Go to Stage action to go to the End of Workflow action. Figure 16-11 shows the resulting workflow definition.

Figure 16-11. The approval workflow designed in SharePoint Designer 2013.

To test the example workflow, you need to save and publish it using the corresponding ribbon commands on the ribbon of SharePoint Designer 2013. As soon as you publish the workflow definition, you can browse to the target library, upload a document, and start a workflow instance. To start an instance, click the ECB (Edit Control Block) menu of the newly uploaded item and choose the Workflows menu item. As shown in Figure 16-12, you will be prompted with the list of all the available workflow definitions, grouped by target platform type (SharePoint 2010 workflows and SharePoint 2013 workflows). Start the example workflow and follow the process.

Figure 16-12. The page for starting a new workflow instance in SharePoint 2013.

Upon starting the workflow instance, you will be prompted with the initiation form, which asks you to provide the initiation parameters that were defined at the very beginning of the workflow design process. Those are the ApprovalRequestMessage and TargetApprover parameters. Figure 16-13 shows the initiation form autogenerated by SharePoint Designer 2013.

Figure 16-13. The initiation form of the sample document approval workflow.

Start the workflow instance and follow the process. Notice the default view of the current library now displays the name of the running workflow instance as the title of the workflow status field. This field presents the status of the running workflow instances and behaves like any other list field, enabling you to filter and sort values. You can export the field into such client platforms as the Office 2013 client, and it provides a direct entry point to the workflow status page, which contains information about the currently running workflow instance, the pending tasks, and the history list. Figure 16-14 highlights the workflow status field.

Figure 16-14. The document library view with the approval workflow status field outlined in red.

The workflow status page provides information about the workflow initiator, the start date and time, the last run date and time, the SharePoint internal status of the workflow instance, and the workflow status. Table 16-4 lists the possible values for the workflow internal status field, while Figure 16-15 highlights two workflow status fields on the workflow status page.

Figure 16-15. The two workflow status fields provided by the workflow status page.

Figure 16-16 shows the form for editing the approval task. To reach that form, simply click any task presented on the workflow status page, and then select the Edit Task command from the ECB menu. As you can see, aside from the standard task fields, there are a few commands in the bottom area of the form for approving or rejecting the document.

Figure 16-16. The approval task form provided by default in SharePoint 2013 for a workflow approval task.

In SharePoint, tasks like the one illustrated in Figure 16-16 are a fundamental part of a workflow process and, in general, are among the most frequently used techniques to interact with end users. Before SharePoint 2013, a user had to browse all the lists of tasks of every different site to manage his or her assigned tasks—a complex and time-consuming process. Luckily, SharePoint 2013 introduces the new Work Management Service Application, which enables you to aggregate tasks from multiple systems into a unique and central location. This location is the user’s personal site and is provided through the User Profile service. Users can aggregate tasks from SharePoint 2013, Microsoft Exchange Server 2013, Microsoft Project Server 2013, and potentially any other provider that supports the Work Management Service Application. Thus, all the workflow tasks created by SharePoint 2013 workflows, regardless of the site where they were created, are aggregated and provided to the end users through a unique and consolidated UI, which improves usability and productivity of end users.

Back to SharePoint Designer 2013, you can experience one of the most brilliant features introduced in SharePoint 2013 workflows: the visual designer view. Click the Views ribbon command and choose Visual Designer view. Figure 16-17 shows the result.

Figure 16-17. The approval workflow in the visual designer view in SharePoint Designer 2013.

You can click the Export to Visio ribbon command to export the workflow definition into a VSDX file of Microsoft Visio 2013. This capability is useful if you need to share the workflow process definition with someone who is not an experienced SharePoint user or designer, but rather a businessperson with only Visio 2013 installed on his or her machine. In Visio 2013, you will have exactly the same user experience you have in SharePoint Designer 2013 while in the Visual Designer view. Lastly, consider that, at a later time, you will be able to import into SharePoint Designer 2013 a workflow definition designed or edited in Visio 2013.

Now that you have defined a basic workflow sample, you can tackle some more advanced and useful topics. For example, you will see how exceptions are handled in workflows and how they are presented to end users. You will also learn how to create reusable workflows and how to manage versioning of workflows definitions.

Exception management

Consider exception management, for example. SharePoint Designer 2013 does not include any actions or conditions to implement try…catch blocks for business logic. Instead, you must consult the workflow status page for details about exceptions that occur, as shown in Figure 16-18.

Figure 16-18. The workflow status page of a workflow instance that raised an exception while running.

As you can see, the stack trace message that pops up when you click the info icon is not completely user friendly and probably would be unintelligible to the average end user. Another common exception occurs if the user tries to start an instance of a workflow definition that is already running against the current item. The workflow instance will not start, because only a single instance of a workflow definition can be started against an item. The workflow instance will try to start, however, and will instantly fail with an internal status value of Terminated, providing a message like the one shown in Figure 16-19.

Figure 16-19. The workflow status page of a workflow instance that has been terminated because another instance of the same workflow definition is already running on it.

Reusable workflows

In SharePoint Designer 2013, you have the option to create a reusable workflow definition, which is almost the same as a classic list workflow, but you can reuse it by associating its definition with multiple targets. The design process is almost the same as the one for defining a classic list workflow as well. After saving and publishing the reusable workflow, however, you have to click the Associate To List ribbon command to effectively associate the workflow definition with a target. The association process starts your default web browser, after which you associate the workflow definition with its target using the web browser interface.

You can also save as a template a workflow definition created in SharePoint Designer 2013. A saved template is just a Windows SharePoint Services Solution Package (WSP) saved in the Sites Assets library of the current site and that you can download and reuse somewhere else.

Important

In Visual Studio 2012, you can import a saved WSP file using the project template called SharePoint 2013 - Import Reusable 2010 Workflow. However, be careful, because that project template works only with old-style WSP packages, which define SharePoint 2010 workflows. It does not handle SharePoint 2013 workflow definitions.

Remember, however, that when you define a workflow in SharePoint Designer 2013, behind the scenes SharePoint Designer creates a flowchart workflow model and produces only a XAML markup-based definition of the process, together with the VSDX file for Visio 2013 used for rendering the view illustrated in Figure 16-17, and any ASPX form file. You can check this behavior by browsing, using SharePoint Designer 2013, to the folder containing the source files of the workflow. In Figure 16-20 you can see the content of the folder representing the sample approval workflow.

Figure 16-20. The content of the folder containing the sample approval workflow defined in SharePoint Designer 2013.

Versioning workflows

Starting with WF 4.5, the workflow engine of .NET Framework can manage versioning of workflow identities. From a SharePoint 2013 perspective, however, the versioning of a workflow definition remains unchanged. The Workflow Settings page, which is the page from which you associate a workflow definition with a target, gives you the option to remove an existing workflow association. When you remove one workflow definition, you must choose what will happen to the running instances of that workflow. Figure 16-21 shows the Remove Workflows page that is displayed when you choose to remove an association.

Figure 16-21. The Remove Workflows page for a list.

You have the option to force workflow association removal, interrupting any running instances, by selecting the Remove option. Otherwise, you can select the No New Instances option, which allows the running instances to complete, but disables the capability to create new instances of that workflow. Usually, these options are very useful when performing workflow maintenance or an upgrade. In fact, an idle workflow instance is persisted in the Workflow Manager database and will be reloaded in memory when execution starts again as the result of an event like a user’s task change, a delay expiration, and so on.

When this occurs, you have no guarantee that the same workflow version will still be available in the current environment. For example, there could be a newer version, potentially different from the original one used during instance creation.

If you decide to forcibly remove the workflow association without waiting for any running instances to complete, the workflow engine of SharePoint will terminate running instances immediately, and thus avoid any kind of issues related to workflow versioning. Of course, you will lose any data or information status about the running workflow instances.

On the other hand, if you decide to prevent new instances of the workflow, but you leave all the running instances in their state, you will have the opportunity to wait for their completion. After all the running instances complete, you can forcibly remove the association from the target list. In the meantime, you can associate a new version of the workflow and start using it on the other items of the target list.

While working with workflows defined in SharePoint Designer 2013, the workflow publishing engine of SharePoint Designer 2013 will always upgrade existing workflow associations, keeping already running instances associated with the original workflow definition and starting the new instances using the new workflow definition. Moreover, be mindful that using the Remove Workflows page to remove a workflow association of a workflow definition that you defined in SharePoint Designer 2013 leaves the environment in an unstable state. In fact, you will still be able to associate that workflow definition to the target list, but you will no longer be able to edit its definition using SharePoint Designer.

Reading this chapter, you learned about the architecture of the new workflow engine of SharePoint 2013 by comparing it with the legacy SharePoint 2010 workflow engine. You learned how to deploy a Workflow Manager environment on-premises, and you saw how to connect a SharePoint 2013 farm on-premises with an external Workflow Manager. Then you created a simple approval workflow using SharePoint Designer 2013 in order to better understand how to design workflows based on markup, without writing any code. At the end of the chapter, you learned how errors, workflow statuses, and versioning are handled.