July 2011

Volume 26 Number 07

SharePoint Development - Build Workflow Solutions for SharePoint Online

By Chris Mayo | July 2011

Many organizations have adopted SharePoint to facilitate collaboration among their information workers. These organizations often use SharePoint to store information in lists and document libraries to support a manual business process. While storing this information in SharePoint does make it easier to collaborate around that information much more effectively, a significant boost in information worker productivity can be realized by automating those business processes within SharePoint in the form of SharePoint workflows. 

With the release of Office 365, SharePoint Online gives organizations many of the same collaboration benefits as SharePoint while also providing the advantages of a cloud-based Software as a Service. SharePoint Online supports workflow through declarative workflows built in SharePoint Designer 2010 and deployed through sandbox solutions. If the built-in workflow actions don’t support the requirements of the workflow solution, you can build custom workflow actions using Visual Studio 2010 and deploy them to SharePoint Online via sandboxed solutions.

In this article, I’ll provide an overview of workflow support in SharePoint Online, build a declarative workflow using SharePoint Designer 2010, augment that workflow via a custom action and deploy it to run in the cloud as a sandbox solution in SharePoint Online.

For information on how SharePoint Online development is similar to and different from SharePoint 2010 development, see my article, “Cloud-Based Collaboration with SharePoint Online,” published in the March 2011 issue of MSDN Magazine (bit.ly/spodevmsdn). And for more details on SharePoint Online and Office 365, including how to sign up for a trial account, visit office365.com.  

SharePoint Online Development Overview

SharePoint Online lets you create collaboration solutions using the same skills and tools used in developing for SharePoint 2010, including Visual Studio 2010, SharePoint Designer 2010, C# or Visual Basic, and the SharePoint APIs and SDKs. While there are a number of similarities between developing solutions for SharePoint 2010 and SharePoint Online, there are differences that will affect what solutions can be built and how those solutions are built.

SharePoint Online only supports sandboxed solutions, which means you can’t deploy code-based workflows, including solutions built with the Sequential Workflow and State Machine Workflow project items. However, workflows built using SharePoint Designer 2010 are supported because these workflows are declarative rather than code-based and can be deployed either directly to SharePoint Online or via the Solution Gallery using package files. Furthermore, you can extend these declarative workflows via sandboxed solutions built with Visual Studio 2010 to provide custom workflow actions to support scenarios that SharePoint Designer 2010 doesn’t support out of the box.

This article will build on the concepts and solution covered in the previous article. I encourage you to read that article, follow the guidance provided to set up your SharePoint Online development environment and build the purchasing solution examples so you have a solid understanding of the development concepts for SharePoint Online. To illustrate workflow support in SharePoint Online, this article will extend the purchasing solution to include a workflow solution.

SharePoint Designer 2010 Overview

SharePoint Designer 2010 lets power users and developers customize SharePoint 2010 without code. SharePoint Designer 2010 also supports SharePoint Online, with the only differences coming from feature differences between SharePoint 2010 and SharePoint Online, such as BCS and External List support. SharePoint Designer 2010 is a great tool for navigating and managing artifacts in SharePoint, working with data, and for customizing the look and feel of your SharePoint sites. It also lets you create custom workflows that can be deployed as part of an overall collaboration solution. You can learn more about SharePoint Designer 2010 capabilities in the video, “Introducing SharePoint Designer 2010 for SharePoint Online” (bit.ly/spdspointro). SharePoint Designer 2010 is a free download and supports both 32-bit (bit.ly/spd201032) and 64-bit versions (bit.ly/spd201064).

The Purchasing Solution

In the examples in this article, I’ll be building on the fictional Contoso Corp. purchasing process introduced in the previous article by adding a SharePoint workflow to automate the approval of purchase requests. When a purchase request requires approval, the user will start the workflow and provide a business justification for the purchase. The workflow will initiate an approval process and create a task for the Approvers group with details on the purchase. After the approval or rejection, an e-mail will be sent to the requesting user about the outcome of the request. The workflow will then examine the request type and in the case of an approved travel request (such as to attend a technical conference), the workflow will create a sub-site for the user to fill out a trip report and upload slides. I’m going to add a RequestType field to the Non-Standard Business Purchase Requests for this purpose. 

I’ve updated the PurchaseMgr project from the last article to include this RequestType field. If you followed that article, you can remove the prior package and deploy the one supplied with this article or add a required RequestType field with the choices Travel, Equipment and Service Request to the Non-Standard Purchase Requests list. I’ll start with the code from this article (bit.ly/spoworkmsdncode) and extract it to the Documents\Visual Studio 2010\Projects\SPOMSDN_Workflow directory on my local machine. I’ll then deploy the PurchasingMgr.wsp to the Solution Gallery of the site collection on my local SharePoint 2010 development environment (in my case, https://o365dpe.contoso.com/sites/spomsdnmag) and activate the Purchasing Manager–Content Types and Lists feature in my Purchasing site (https://o365dpe.contoso.com/sites/spomsdnmag/purchasing). 

Creating the Workflow

To get started developing my workflow, I’ll open the Purchasing site on my local SharePoint 2010 development environment site by opening SharePoint Designer 2010, selecting File | Sites | Open Site and entering the URL of my site (https://o365dpe.contoso.com/sites/spomsdnmag/purchasing). In the Navigation pane, I’ll select Workflows to show the currently published workflow and the Workflows ribbon, as shown in Figure 1.

(click to zoom)

Figure 1 Workflows in SharePoint Designer 2010

SharePoint Online supports List Workflows that act on a specific list, Site Workflows that work on a specific site and Reusable Workflows that can be bound to a list or specific content type at a later date. I want to be able to distribute my workflow as part of an overall solution, so I’ll create a Reusable Workflow, which is the only type of workflow that supports distribution.

When creating a workflow in SharePoint Designer, I have a number of choices. I can create my workflow based on one of the built-in workflows (including Approval, Collect Feedback or Collection Signatures) using the Copy & Modify button, import a Visio 2010 diagram based on the Microsoft SharePoint Workflow template using the Import from Visio button, or create the workflow from scratch using the New group on the Workflows tab of the Ribbon. I’ll create my workflow from scratch by clicking the Reusable Workflow button in the New group of the ribbon. In the Create Reusable Workflow dialog, I’ll name the workflow Non-Standard Business Purchase Request Approval and select Purchasing Manager – Non-Standard Business Purchase Request Content Type so the workflow will be bound to my content type, as shown in Figure 2.

(click to zoom)

Figure 2 Reusable Workflow Bound to the Content Type

Next, I’ll go to the Non-Standard Business Purchase Request Approval workflow settings page by clicking the Workflow Settings in the Manage group of the Workflows tab.

In the Settings group, I’ll check the “Show workflow visualization on status page” to give my users a real-time visualization of the status of each instance of the workflow. I’ll use the Start Options group to make this a human-driven workflow by unchecking “Disable manual start option” and checking the “Disable automatic start on item creation/change option” checkboxes. You can create a machine-driven workflow by doing the reverse.

In many situations, information I need to complete the workflow is not stored in the list or library. I can collect and store that information in workflow-specific variables and columns. This can be done with the Variables group in the Workflows ribbon, as described in Figure 3.

Figure 3 Workflow Variables

In this instance, I want to collect the business justification for the purchase when the workflow is started so I can provide that information to approvers to help them make a decision. To do this, I’ll click on Variables | Initiation Form Parameters | Add… and create a Business Rationale parameter in the Add Field dialog; then click Next and Finish.

Implementing the Workflow in SharePoint Designer

At this point, I’m ready to start implementing the workflow, so I’ll select the Editor workflow button in the Edit Group of the Workflow Settings tab. I’m now in the SharePoint Designer 2010 workflow designer where I can implement my workflow using the Condition, Action and Step options in the Insert group of the Workflow ribbon (see Figure 4).

(click to zoom)

Figure 4 Workflow Designer—Insert Section

Steps are used to organize the conditions and actions in a workflow and to control how those conditions and actions are executed, as Figure 5 describes.

Figure 5 Types of Steps

 For example, in Figure 6, Step 2 will be executed with the workflow author’s permissions while Step 1 will be executed as the user who started the workflow (either manually or automatically). Steps 5 and 6 will be executed in parallel while Steps 3 and 4 will be executed serially.

Figure 6 Steps—Effect on Workflow Execution

In my workflow, I’ll have just one Step. To document what the Conditions and Actions do in the Step, I’ll change the title by clicking on the text “Step 1” and entering “Request Purchase Approval.” I’ll then click inside the Step so the cursor is where I need to start adding Actions and Conditions.

Actions do work within the workflow and can include starting an approval process, modifying a list item, sending an e-mail and more. For a complete list of the supported actions, refer to the SharePoint Designer 2010 reference (bit.ly/spd2010act). For this scenario, I want to start an approval process for the purchase request, so I’ll select the Action drop-down from the Insert section of the ribbon and choose Start Approval Process. This adds a sentence to the designer with hyperlinks, allowing me to complete the Action by selecting each link and providing more information, as shown in Figure 7.

Figure 7 Adding the Start Approval Process Action

Clicking on the Approval link lets me customize the approval task, including changing both how the task is processed and the task outcomes. I can return to the editor by clicking the back button. I’ll click the “these users” link to customize the task and specify who will participate in the approval process. In the Select Task Process Participants dialog, I’ll select the Approvers group as the Participants and set the title of the task, as shown in Figure 8. For the Instructions, I want to provide details about the item and the business rationale to help the approver make a decision. For example, to include the list item title, I click the Add or Change Lookup button, select Current Item as the Data Source and Title as the Field from Source.

Figure 8 Customizing the Approval Task

The final task will look like Figure 9.

Figure 9 Customized Approval Task

At this point in the workflow execution, the workflow will pause until the task is approved or rejected or, if a due date was supplied, expired. To control the flow, I’ll use Conditions.

Conditions control the logic of the workflow based on values in workflow variables or fields. For example, if the item is approved, I want to send an e-mail to the requestor and create a site if the request type is of type Travel. If the item is rejected, I want to send e-mail and delete the item. To do this, I’ll place the cursor under the approval process, click the Condition drop-down and select “If any value equals any value.” I’ll click on the “value” hyperlink and click the button displayed to show the Define Workflow Lookup dialog. For the Data source I’ll select Workflow Variables and Parameters, and for the Field from source I choose Variable: IsItemApproved. This variable is added to the workflow when a Start Approval Process task is added.

I’ll then click the equals link and select equals from the drop-down displayed. Next, I’ll click the value link and select Yes from the drop-down. I’ll place an Else-If Block under this condition so I can take action when the item is rejected. I’ll add Send and Email actions to each branch and use the String Builder to set the e-mail title, as shown in Figure 10.

Figure 10 Approval E-mail

Next, I’ll add an “If current item field equals value” condition under the If condition and base it on the RequestType field so I can create a new sub-site when the request is a travel request. The designer now looks like Figure 11.

Figure 11 The Conditional Flow of the Workflow

To create the site for Travel requests, I’ll need to create a custom workflow action because this action isn’t built into SharePoint Designer 2010. To do this, I’ll save my workflow, close SharePoint Designer 2010 and open Visual Studio 2010.

Building a Custom Workflow Action in Visual Studio 2010

You can add custom workflow actions to SharePoint Designer 2010 using Visual Studio 2010 and sandboxed solutions. These actions can accomplish any task that can be done in a sandboxed solution, which provides a lot of flexibility to SharePoint Online workflows.

In Visual Studio 2010, I’ll select File | New Project and in the New Project dialog I’ll select SharePoint 2010 templates and the Empty SharePoint Template. I’ll enter PurchasingMgrActions for the Name and Documents\Visual Studio 2010\Projects\SPOMSDN_Workflow\ as the Location and Click OK. In the SharePoint Customization Wizard I’ll enter my local development site (https://o365dpe.contoso.com/sites/spomsdnmag/purchasing) for the local site and select “Deploy as a sandboxed solution” and click Finish.

In the Solution Explorer, I’ll right click on the PurchasingMgrActions project, select Add | Class…, then name the class CreateSiteAction and click OK. The CreateSiteAction class provides the method the workflow will call to create the new site. I’ll add the necessary using statements and implement the CreateSite method, as defined in Figure 12.

Figure 12 Implementing the CreateSite Method

using System;
using System.Collections;
using Microsoft.SharePoint;
using Microsoft.SharePoint.UserCode;
namespace SPDCustomWorkflowActions
{
  public class CreateSiteActivity
  {
    public Hashtable CreateSite(SPUserCodeWorkflowContext context, string siteName)
    {
      Hashtable results = new Hashtable();
      try
      {
        using (SPSite site = new SPSite(context.CurrentWebUrl))
        {
          using (SPWeb web = site.OpenWeb())
          {
            web.Webs.Add(
              siteName,
              "Trip Report: " + siteName,
              string.Empty,
              1033,
              "STS",
              false,
              false);
          }
        }
                
        results["success"] = true;
        results["exception"] = string.Empty;
      }
      catch (Exception e)
      {
        results = new Hashtable();
        results["exception"] = e.ToString();
        results["success"] = false;
      }
      return results;
    }
  }
}

The CreateSite method follows the method signature for custom actions, passing in SPUserCodeWorkflowContext to provide access to the context the workflow is running under and whatever other parameters I need (in this case the name of the site to create). The method gets access to the site collection (SPSite) and site (SPWeb) via the context and creates the new site via the SPWeb.Webs.Add method. Results are returned via the Results Hashtable variable.

For CreateSiteAction to be added to the Actions drop-down, I need to deploy an Elements.xml file with my Feature to describe the action to SharePoint Designer 2010. I’ll add this file to the project by selecting the PurchasingMgrActions project in Solution Explorer, right-clicking and choosing Add | New Item…, then selecting SharePoint 2010 under Installed Templates and choosing the Empty Element template. I’ll name the item CreateSiteActionDefinition and click OK. This definition is accomplished by implementing an Action element in the WorkflowActions elements, as seen in Figure 13.

Figure 13 Defining the Create Site Action via Elements.xml

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="https://schemas.microsoft.com/sharepoint/">
  <WorkflowActions>
    <Action Name="Create Site"
                      SandboxedFunction="true"
                      Assembly="$SharePoint.Project.AssemblyFullName$"
                      ClassName="PurchasingMgrActions.CreateSiteAction"
                      FunctionName="CreateSite"
                      AppliesTo="all"
                      UsesCurrentItem="true"
                      Category="Purchasing Manager Workflow Actions">
      <RuleDesigner Sentence="Create Site with name %1 (exceptions logged to %2)">
        <FieldBind Field="siteName" Text="Site Name" Id="1" DesignerType="TextBox" />
        <FieldBind Field="exception" Text="Exception" Id="2" 
          DesignerType="ParameterNames" />
      </RuleDesigner>
      <Parameters>
        <Parameter Name="__Context"
                      Type="Microsoft.SharePoint.WorkflowActions.WorkflowContext,
                        Microsoft.SharePoint.WorkflowActions"
                      Direction="In"
                      DesignerType="Hide" />
        <Parameter Name="siteName"
                      Type="System.String, mscorlib"
                      Direction="In"
                      DesignerType="TextBox"
                      Description="Name of the site to create" />
        <Parameter Name="exception"
                      Type="System.String, mscorlib"
                      Direction="Out"
                      DesignerType="ParameterNames"
                      Description="Exception encountered"/>
      </Parameters>
    </Action>
  </WorkflowActions>
</Elements>

The Action element and its attributes describe the assembly, class and method that will be called when the action is executed in the workflow. In this case, it will call the CreateSiteAction.CreateSite method. The RuleDesigner element and its FieldBind elements define the sentence that will be shown in the workflow designer and the name and type of the fields shown as hyperlinks in that sentence. The Parameters element and its Parameter sub-elements define how the RuleDesigner\FieldBind elements get passed in and out of the call to CreateSiteAction.CreateSite. For example, the __Context parameter is of type WorkflowContext and is used to pass that context into the call without being shown in the designer (by setting the DesigerType attribute to “Hide”). The siteName parameter will receive the value in the siteName field binding. This is done by giving the field and parameter the same name. Exceptions will be passed out via the exception parameter and into the exception field for the same reason.

Before I test my custom action, I’ll open Feature1 and give it a title of Purchasing Manager Workflow Actions to make it more descriptive, and change its scope to Site as required by custom workflow actions.

Deploying the Workflow Solution to SharePoint Online

To test my custom workflow action I’ll right-click on the PurchasingMgrActions project in Solution Explorer and select Package to package the solution. I’ll then upload the PurchasingMgrActions.wsp to the Solution Gallery in my local development site collection (https://o365dpe.contoso.com/sites/spomsdnmag) to deploy the custom workflow action.

Now, when I open SharePoint Designer 2010 and my Non-Standard Business Purchase Request Workflow Approval workflow in the workflow editor, my custom workflow action is displayed in the Action drop-down under the Purchasing Manager Workflows category, as shown in Figure 14.

Figure 14 Create Site Custom Action in Workflow Designer

After setting the Site Name variable to Current Item:Title, my workflow is complete and ready for testing (see Figure 15).

Figure 15 The Completed Workflow

To get ready for testing, I need to publish the workflow to my local development site and associate it to my list. To publish, I select Publish in the Save section of the ribbon. When the publication is complete, I’ll navigate to my Non-Standard Business Purchase Requests list on my local development site, click the List tab and select Workflow Settings in the Settings section of the ribbon. Under “These workflows are configured to run on items of this type,” I’ll select Purchasing Manager – Non-Standard Business Purchase Requests and choose the “Add a workflow” link. I’ll select my Non-Standard Business Purchase Request Approval workflow as the template and give the workflow the name Non-Standard Business Purchase Approval and click Next and then click Save.

At this point I can run my workflow. I’ll select the first item on my list, then choose Workflows in the Workflows section of the ribbon and click on the Non-Standard Business Purchase Approval workflow to start the workflow. I’ll then be prompted to enter a business justification as specified in my Business Rationale Initiation Form Parameter.

I’ll supply a justification like the one shown and click Start to start the workflow. I can then go into the Workflows page for the item and select the in-progress workflow to see the Workflow Information page, which includes a visualization of the workflow. When the task is approved, the diagram is updated, as seen in Figure 16.

(click to zoom)

Figure 16 Workflow Information Page with Visualization

I can then go to Site Actions | View All Site Content and see the site that was created by my custom workflow action.

At this point I’m ready to distribute my workflow solution to SharePoint Online. To get the package file for my Non-Standard Business Purchase Request workflow, I’ll open the workflow in SharePoint Designer 2010 and select the Save As Template option from the Manage section of the ribbon to save the workflow to the Site Assets library. I can then take the package files PurchasingMgr.wsp (or modify the existing list if already deployed), PurchasingMgrActions.wsp and Non-Standard Business Purchase Request Approval.wsp from the Site Assets library and upload them into the Solution Gallery in my SharePoint Online site collection. Note that the features must be activated in this order based on the 
dependencies between the features (this can be automated via feature activation dependencies). After activating the workflow feature in my site and associating the workflow to my list, I can follow the same steps to test my workflow in SharePoint Online.

Wrapping Up

Automating business processes via workflows in SharePoint Online can make collaboration even more effective beyond merely storing information in SharePoint Online. In this article I showed how to implement a workflow in SharePoint Designer 2010, extend that workflow with a custom workflow action developed with Visual Studio, and then distribute that workflow via package files created by SharePoint Designer 2010 and Visual Studio 2010. I encourage you to dive deep into workflow development in SharePoint Online. Your users will be impressed at how their manual, error-prone business processes become more efficient with less effort when automated in SharePoint Online workflows.

Chris Mayo is a technology specialist focusing on SharePoint Online and has been with Microsoft for 10 years. He coauthored “Programming for Unified Communications with Microsoft Office Communications Server 2007 R2” (Microsoft Press, 2009). Prior to joining Microsoft, he served as a developer and architect in the IT departments of Fortune 500 companies in the retail and finance industries. Keep up with Mayo at his blog, blogs.msdn.com/b/cmayo.

Thanks to the following technical experts for reviewing this article: Mark Kashman, Keenan Newton, AJ May and George Durzi