SharePoint Workflow Development with Office Developer Tools for Visual Studio 2012

The official release of Office Developer Tools for Visual Studio 2012 ( download ) is packed with great features for Office and SharePoint developers to quickly and efficiently create first class apps and solutions for Office 2013 and 2010. In this post, I'd like to introduce improvements to SharePoint 2013 workflow development in Visual Studio 2012, as well as walk through creating a SharePoint workflow app (Document Approval and Routing Workflow).

Apps for SharePoint can be developed remotely, to target either SharePoint online or on-premises. You no longer have to develop directly on the SharePoint server! Furthermore, you can now publish workflow apps to both the Office Store and the App Catalog. Actually, you can create SharePoint 2013 workflows in solution projects too, but trust me, you’ll miss the remote development feature that is available only with app for SharePoint projects.

In SharePoint 2013, workflows are built on Windows Workflow Foundation in .NET Framework 4.5, targeting Workflow Manager 1.0. Check out this MSDN article for more on SharePoint 2013 workflow fundamentals.

The major differences in workflow development experience that you'll notice are:

  • Instead of requiring you to write C# or Visual Basic code, the experience centers around workflow configuration with simple Visual Basic or C# expressions that can be represented declaratively.
  • Instead of Sequential or State Machine workflow templates, there is a single workflow template that is Sequential by default. To change to State Machine, simply swap out the Sequence activity with a State Machine activity.
  • Workflow activities operate via the SharePoint REST API.

For those of you who have used the preview versions of our tools, we hope that you will find workflow development with this release of Office Developer Tools to be easier and faster. Read on to find out about important changes and enhancements that affect existing workflow projects created using the Preview 2 version of our tools. We look forward to hearing more of your feedback!

Getting started - software

This release of our tools is designed to work with SharePoint 2013 RTM and the March 2013 SharePoint Server 2013 Update. In fact, even if you don’t plan on doing any SharePoint development in the near future, you should still install the March update on your SharePoint farm. We don’t recommend that you stay on the SharePoint RTM bits. Of course, if you’re using SharePoint Online, there's no need to worry about updating your SharePoint software; it's always up to date. If you don’t have SharePoint Online you can get a free trial in just minutes; signup for Office 365 for developers, which includes SharePoint Online.

If you plan to develop SharePoint 2013 workflows (or if you will install custom developed workflows), be sure to install Workflow Manager on the SharePoint server, and don't forget to install the Cumulative Update for Workflow Manager 1.0 as well.

Workflow development works best with Visual Studio 2012 Update 2. So if you haven't already, first install Visual Studio 2012 RTM on your development machine, and then install Visual Studio 2012 Update 2 and .NET update KB2750149.

Workflow projects created using Preview 2 of Office Developer Tools

If you previously created SharePoint 2013 workflow projects with the Preview 2 release of Office Developer Tools, please note these important changes in the SharePoint 2013 platform and SDK with the March update.

  • Better scalability and more reliable workflow app upgrade:
    • New workflow/custom activity packaging format in apps.
    • Usage of Item Guid is now deprecated and is replaced by Item Id (integer).
      What does this mean? LookupSPListItemGuid and GetCurrentItemGuid activities are deprecated; their new replacement activities are LookupSPListItemId and GetCurrentItemId. In all other activities that included usage of Item Guid, you will find Item Id added and Item Guid hidden. Your existing project that used Item Guid will still continue to work as it used to (except for on very large lists with more than 5000 items—this is one of the reasons for the change).
  • Optimized performance during workflow development and debugging:
    • Workflow activities assembly reference in XAML changed to point to a new design-time proxy assembly instead of the actual SP activities assembly.

Preview 2 workflow projects must be converted to be compatible with the official version of Office Developer Tools and the March SharePoint update. To make that process easier, use this CodePlex tool (SharePoint 2013 Workflow Converter for Visual Studio 2012) to convert your projects.

Walkthrough: Create a document approval and routing workflow app

Let’s walk through creating an app for a common SharePoint workflow scenario, Document Approval and Routing, from scratch.

Complexity: Medium

Workflow overview:

  • A workflow instance kicks off whenever a document in a document library is updated.
  • If the document’s status is set to Ready For Review, the workflow assigns a task, along with an email notification, to the approver to conduct the review.
  • If the approver approves, the workflow copies the document into a published documents repository.
  • The original document remains in the Draft Documents library, but its status should indicate its final status as either Published or Rejected.

Let’s begin.

  1. In Visual Studio 2012, create a new App for SharePoint 2013 project, as shown in Figure 1.

    Full-size version of the screenshotFigure 1. Add new App for SharePoint 2013 project

  2. Create two document libraries named Draft Documents and Published Documents as customizable lists, as shown in Figure 2.

    Full-size version of the screenshotFigure 2. Create new document library

  3. Add these custom columns to both the Draft Documents and Published Documents libraries.
    (Do the following for each library.)

    1. Add a Person or Group list column and name it Approver.
    2. Add a Choice list column and name it Document Status. Then add five choices to it: Draft In Progress, Ready For Review, Approved for Publishing, Rejected, and Published.
      (To set the choices, in the property grid, expand the Type property and click the ellipsis button ( ) on the Items property. Enter the values into the dialog box that pops up, as shown in Figure 3.) Full-size version of the screenshotFigure 3. Customize list columns
  4. Create a SharePoint list workflow named DocumentApprovalWorkflow, as shown in Figures 4 and 5.

    Full-size version of the screenshotFigure 4. Add new workflow item

    Full-size version of the screenshotFigure 5. Configure basic workflow properties—name and type

  5. Associate the workflow to the Draft Documents library, and opt to create a new history list and a new workflow tasks list, as shown here.

    Full-size version of the screenshotFigure 6: Configure basic workflow properties—associate to lists

  6. Set the workflow association type to automatically start when an item is changed in the Draft Documents library.

    Full-size version of the screenshotFigure 7. Configure basic workflow properties—association type

    Note: If you want to change the workflow association type after the workflow has already been created, you can do so in the property grid (see Figure 8). (Workflow properties will appear in the property grid when the workflow item is highlighted in Solution Explorer.)

    Full-size version of the screenshotFigure 8. Workflow properties in property grid

  7. If it’s not already open, double-click the workflow project item in Solution Explorer to open the workflow designer. Figure 9 shows the workflow.

    Full-size version of the screenshotFigure 9. Empty workflow

  8. Now let’s design the workflow logic. First we need to know the status of the document.

    1. To retrieve this value, drag the LookupSPListItem activity from the toolbox onto the workflow designer canvas. This activity returns a DynamicValue object, which contains the set of properties (key-value pairs) from a specific SharePoint list item.
    2. Configure the LookupSPListItem activity so that it returns properties from the “current item” in the “current list” (see Figure 10). You can configure activities via the property grid while the activity is selected in the canvas. Use the combo boxes provided in the property grid to make these selections. Full-size version of the screenshotFigure 10. Configure the LookupSPListItem activity
    3. On the LookupSPListItem activity surface, click the Get Properties link. This automatically does a few things for you (see Figure 11):
      1. Creates a variable of the DynamicValue type and binds it to the out-argument of the LookupSPListItem activity, named Result. This stores the properties from the list item into the variable.
      2. Adds a new activity named GetDynamicaValueProperties, and sets the newly created DynamicValue variable as the in-argument of this activity. This activity allows you to extract the values of specific properties from the DynamicValue variable. Full-size version of the screenshotFigure 11. Configure LookupSPListItem activity—Get Properties
  9. On the GetDynamicValueProperties activity surface, click Define, and a dialog box appears, which allows you to pick the properties to extract.

    1. In the Entity Type list, select List Item of Draft Documents, as shown in Figure 12.
    2. In the data grid, click Create Property to activate a combo box containing properties available for list items in the Draft Documents library. Then select Document Status in the combo box. Full-size version of the screenshotFigure 12. Configure the GetDynamicValueProperties activity
    3. Add another row by clicking Create Property again, and then select Approver in the combo box.
    4. Click the Populate Variables link in the dialog box. This automatically creates a variable for each row of the appropriate data type, and as the Assign To variable (see Figure 13). Full-size version of the screenshotFigure 13. Get Document Status and Approver properties
  10. Now that we have the necessary list item values, we can check whether the document is Ready For Review.

    1. In the toolbox, drag the If activity onto the workflow designer canvas. (Hint: you can search in the toolbox for quick filtering.)
    2. Set the If condition to DocumentStatus.Equals(“Ready For Review”) , as shown in Figure 14. Full-size version of the screenshotFigure 14. Configure If activity to check whether the document is "Ready For Review"
  11. If the document is ready for review, then assign a task to the approver.

    1. From the toolbox, drag a SingleTask activity onto the canvas and drop it into the Then area within the If activity, as shown in Figure 15. Full-size version of the screenshotFigure 15. Add SingleTask activity
    2. Now assign the task to the approver. Click the Configure link on the activity surface. A dialog box appears, allowing for basic configuration of the task properties. Set the Approver variable to the Assigned To property, as shown in Figure 16. Click OK to save. Full-size version of the screenshotFigure 16. Configure the SingleTask activity
    3. At this point, you’ll notice a validation error on the SingleTask activity. Inspect it in the property grid to see that the AssignedTo property has an error. Hover over the property name to see a tooltip that indicates the property’s data type and a description of usage. We can see that this property expects a String value, yet the Approver variable is of Int32 type (see Figure 17). Full-size version of the screenshotFigure 17. Configure the SingleTask activity—AssignTo argument requires String type
    4. To correct this error, go ahead and append .ToString() to Approver, as shown in Figure 18. You also could have done this directly in the configuration dialog box before. At this point, you have configured a basic task that will send email to the Assignee (Approver in this case) notifying him/her about a new task waiting for action. Full-size version of the screenshotFigure 18. Configure SingleTask activity - AssignTo argument
  12. Take a closer look at the property grid for the SingleTask activity. Scroll to the bottom, and you’ll notice that variables were automatically created and set to Outcome and TaskItemId out-arguments. Note the name of the Outcome variable—it should be something like outcome_0. We will use this variable to check the outcome of the task in the next step, that is, whether the approver approved or rejected the document.
    (Note: The Outcome out-argument returns an Int32 value that corresponds to the index of the outcome that the approver chose, that is, 0 for “Approved”, 1 for “Rejected”. These are the default choice values within the out-of-the-box SharePoint site column named Task Outcome.)

  13. To check the task outcome, let’s add another If activity to the workflow, and place it after the SingleTask activity but inside the Then area. Set the If condition to outcome_0 == 0, to see whether the task was approved (see Figure 19).

    Full-size version of the screenshotFigure 19. Configure If activity to check whether the task was approved

  14. If the approver set the task to approved, then let’s update the document status to Approved For Publishing and then copy it to the Published Documents library; otherwise, let’s set the document status to Rejected.

    1. Add the UpdateListItem activity to the Then area within this If activity.
    2. Then configure it to update the “current item” in the “current list” by choosing the corresponding values in the combo boxes in the property grid.
    3. Next, click the ellipsis button ( ) for the ListItemPropertiesDynamicValue property. A dialog box appears, allowing you to specify the list item property that you want to update.
      1. Set Entity Type to List Item of Draft Documents via the combo box.
      2. In the data grid, click Create Property to activate a combo box containing properties available for list items in the Draft Documents library. Then select Document Status in the combo box, and set its value to Approved For Publishing, as shown in Figure 20. Full-size version of the screenshotFigure 20. Configure the UpdateListItem activity—approved status
    4. Add a CopyItem activity into the Then area, below UpdateListItem, as shown in Figure 21. Configure it to copy the “current item” from the “current list” to the Published Documents library. Set Overwrite to true—we’re going to assume that all published documents come from the Draft Documents library, thus no duplicate file names would exist within the same list. Full-size version of the screenshotFigure 21. Configure the CopyItem activity
    5. Now add an UpdateListItem activity into the Else area. This time, we want to set the document status to Rejected. Figure 22 shows the completed workflow. Full-size version of the screenshotFigure 22. Completed workflow

We’re now done creating a SharePoint Document Approval and Routing workflow from scratch. Go ahead, try it out for yourself, and let us know what you think of SharePoint 2013 workflow development with the Office Developer Tools for Visual Studio 2012!

Stay tuned for more online documentation and samples on SharePoint workflow development.

Enjoy! 

Grace Kochavi

Program Manager – Office and SharePoint Tools Team

Additional Information: