This walkthrough will demonstrate how to create a simple workflow that uses stages with Visio 2013 and SharePoint Designer 2013. Open Visio 2013 and create a new drawing based on the Microsoft SharePoint 2013 Workflow template, found in the Flowchart category. By using the Shapes task pane, look in the Components - SharePoint 2013 Workflow section and drag three more stages onto the design surface, as shown earlier in Figure 12-2. To make things easier to follow, rename each of the stages to the following names:

Now do the following to model the workflow stages:

Figure 12-3. This is a screen shot of the Visio 2013 Workflow Designer.

The next task is importing the workflow into SharePoint Designer, so open SharePoint Designer 2013 and do the following:

Open a browser and go to the Announcements list. Create a new item with no value in the body field and click Save. Now select the item and, by using the Items tab on the ribbon, select Workflows. On the Workflows page, select Update Announcement Item to start the workflow. When the workflow starts, you will be taken to the initiation form. Enter a value in the Body Value text box and click Start. The browser will redirect back to the list. Click the Workflows button again. This time, further down the page, notice that there is a workflow under Running Workflows or Completed Workflows (depending on whether it has already finished). Click the value of the Internal Status field to view the status page that shows all history log information. Go back to the actual list item and notice that the body value has also been updated.

The following walkthrough demonstrates how to create a custom workflow that calls the OData web service of the well-known Northwind database publically hosted at the http://www.odata.org site. The user enters a customer ID and then starts the workflow, which will retrieve additional customer information and update the list item with this data. First, start Visual Studio 2012 and create a new SharePoint-hosted app project, a task that has been shown repeatedly throughout this book. Next, create a new custom list named Customers in the project. Include the following fields, leaving their default data type of String:

After creating the list, add a workflow to the project by following these steps:

Visual Studio will then display the basic workflow design surface with a single Sequence activity. To keep things organized and easier to manage, rename this activity Root and add four more Sequence activities within the Root sequence, using the following names:

The first step in this workflow is to retrieve the customer ID entered by the user. For this, two variables are needed, so click the Variables tab at the bottom of the designer and create the following two variables:

Next, drop the LookupSpListItem activity in the Init sequence, found in the SP - List section of the toolbox, and use the values shown in Figure 12-8 to set the values in the Properties pane when this activity is selected. This activity tells Workflow Manager to use the SharePoint REST API to retrieve the properties of the current list item and store the JSON response in the DynamicValue variable previously created.

Figure 12-8. Use the Properties pane for the LookupSPListItem activity to modify settings.

To retrieve the customer ID from the item, click the Get Properties link within the LookupSpListItem activity, which will add a GetDynamicValueProperties activity to the design surface. In the Properties pane, click the ellipsis (...) button to bring up the Property selector wizard. In the wizard, set the Entity Type to List Item Of Customers and add a single property with Path = CustomerId and Assign To = CustomerId (the variable previously created).

The workflow now has a reference to the customer ID, so the next step is to call the web service. Select the sequence Get Customer Data from Service to set the current context, and create two new variables:

Create the URL that will be used to query the web service by dropping an Assign activity in the Get Customer Data from Service sequence. Set the left part of the Assign activity to NorthwindServiceUri and the right part to “http://services.odata.org/Northwind/Northwind.svc/Customers(‘” + CustomerId + “’)?$format=json”. Now add an HttpSend activity to the Get Customer Data from Service sequence immediately after the Assign activity, and use the values shown in Figure 12-9 to set the properties on this activity.

Figure 12-9. Use the Properties pane to edit the settings on the HttpSend activity.

After the web service request has been made and the results are stored in the local variable, the next step is to process the response. Each value in the response will need to be added to a different variable, so create string variables, scoped to the Root sequence, for each of the fields except customer ID in the list created at the start of this walkthrough. Next, add a GetDynamicValueProperties activity to the Process Service Request sequence. In the Properties pane, set the Source value to NorthwindServiceResponse. Now click the ellipsis button for the Properties property to map paths in the response to the local variables by using the settings shown in Figure 12-10. (Note that the Assign To column contains the variables created for each field in the Customers list.)

Figure 12-10. Use the Properties pane and dialog box to edit the settings of the GetDynamicValueProperties activity.

The last step is to update the list item. To do this, add an UpdateListItem activity to the Update List Item sequence, and use the Properties pane to set the following values:

Click the ellipsis button for the ListItemPropertiesDynamicValues property. In the dialog box, set the Entity Type to List Item Of Customers and, for each of the values extracted from the web service, set the value of the list item to the variable within the workflow, as shown in Figure 12-11.

Figure 12-11. Use the Properties dialog box to edit the settings on the ListItemPropertiesDynamicValue activity.

At this point, the workflow is complete, so press F5 to start debugging. Visual Studio will build and deploy the SharePoint-hosted app.

When the browser opens, find the Customers list, create a single customer with an ID of ALFKI, and save the item. Next, manually start the workflow by using the same process outlined in the previously created SharePoint Designer 2013 workflow, and then go back to the list item and keep refreshing the page to observe the workflow update the list item.

The following walkthrough demonstrates how to create a custom activity for use within a workflow hosted in a SharePoint app. It will use the workflow project previously created in this chapter that calls the Northwind OData service as a starting point to retrieve additional customer data. The custom activity will refactor the process of querying the web service and processing the response so that the workflow can call this activity by passing in a customer ID and get back the additional customer details without having to deal with the web service.

First, add a new item to the project by using the Workflow Custom Activity template and name it GetCustomerDetailsActivity. Next, cut and paste the sequences Get Customer Data from Service and Process Service Response from the previously created workflow into the sequence in the custom activity. Rename the default Sequence activity to Root. Now create two variables by clicking the Variables tab at the bottom of the designer. These variables will be used in the workflow to store the URL of the service and the response:

The next step involves modifying the arguments used to pass data to and from the activity. Within the activity, click the Arguments tab at the bottom of the designer, as shown in Figure 12-15. Create one input argument for the customer ID that the calling workflow will supply, and output parameters for all the values extracted from the web service response, as shown in Figure 12-15. As long as the argument names are the same as the variable names in the previous workflow, the activities will not need to be updated.

Figure 12-15. Add arguments to the activity to pass values in and out.

The custom activity is now finished, and the next step is to update the workflow. With the workflow open in the designer, remove the two variables NorthwindServiceUri and NorthwindServiceReponse; they are no longer needed, because the activity handles them. To add the activity to the workflow, you must compile the project so that the toolbox will show the activity as one to use in the workflow. Build the project, and then drag the custom activity into the designer between the Init and Update List Item sequences, as shown in Figure 12-16.

Figure 12-16. Add the custom activity, GetCustomerDetailsActivity, to the workflow.

The last step is to select the custom activity in the designer and associate all the input and output parameters with the variables in the workflow.

This example showed how to use a custom activity within a workflow deployed as a SharePoint app. This is great for many solutions, but many business requirements demand that the activity be used in multiple workflows. Sharing a single activity XAML file between projects and limiting it to workflows built with Visual Studio 2012 is cumbersome. Another option is to deploy the activity to Workflow Manager and advertise the existence of it to SharePoint so that workflows authored by using SharePoint Designer 2013 can use it. There are two extra requirements to creating a custom activity for use in SharePoint Designer 2013 workflows.

First, the activity must be deployed by using a solution, not in an app. Deploying it in an app would make the activity available only within the AppWeb, which is quite limiting. The solution used for deployment can be a sandboxed or fully trusted farm solution, but it probably makes the most sense to do it as a sandboxed solution. Because the custom activity will be fully declarative like workflows authored in Visual Studio 2012, there is no custom code, and thus it can be deployed by using a sandboxed solution. Further, because fully trusted farm solutions are supported only in on-premises deployments, the sandbox makes more sense because it can be used in either on-premises or hosted deployments such as Office 365.

The other requirement in creating a custom activity that will be used in SharePoint Designer 2013 workflows is that the activity must be advertised to SharePoint Designer. This is achieved by using an actions file. When you are creating a new workflow with SharePoint Designer 2013, the site collection interrogates the target site collection for all available actions supported by the site collection. These actions map to activities and tell SharePoint Designer how the user-friendly designer should work, what the inputs and outputs are, and where it should appear in the SharePoint Designer user interface—for example, which category it should be present in. Actions files are deployed as part of the SharePoint solution package that includes the custom activity.

The following walkthrough demonstrates how to create a custom activity that can be used within SharePoint Designer 2013. It is a variant of the one included in the previous walkthrough that addressed creating a custom action for Visual Studio 2012, so the differences between the two will be easily noticeable. First, create a SharePoint 2013 empty project, making sure that it is a SharePoint solution and not a SharePoint app project. When prompted, specify that the project is a sandboxed solution.

Next, add a Workflow Custom Activity item to the project and recreate the activity from the previous example, including the variables and arguments. Essentially, what you should be left with is a sandboxed solution with no workflow, but the same activity from the previous project. There is one very important difference in that there is now a *.actions4 file in the project item, as shown in Figure 12-17.

Figure 12-17. This project’s Solution Explorer pane shows the activity and associated *.actions4 file.

After the activity has been created, it must be exposed as an action for it to be accessible in SharePoint Designer 2013 workflows. This is done by using the *.actions4 file. Open this file and add the contents shown in the following code. This file dictates how the activity will appear in SharePoint Designer 2013 and how the values entered by the workflow author will be passed to and from the activity:

<Action Name="GetCustomerDetailsActivity"
       ClassName="GetCustomerDetailsActivity.GetCustomerDetailsActivity"
       Category="Custom Activities"
       AppliesTo="all">
 <RuleDesigner Sentence="Fetch customer details for
                              customer %1 from Northwind as %2, %3, %4, %5, %6 and %7">
   <FieldBind Field="CustomerId" Id="1"
                DesignerType="TextBox" Text="id" DisplayName="Customer Id" />
   <FieldBind Field="CustomerName" Id="2"
                DesignerType="TextBox" Text="fullName" DisplayName="Customer Name" />
   <FieldBind Field="CustomerTitle" Id="3"
                DesignerType="TextBox" Text="jobTitle" DisplayName="Customer Job Title" />
   <FieldBind Field="CustomerAddress" Id="4"
                DesignerType="TextBox" Text="address" DisplayName="Customer Address" />
   <FieldBind Field="CustomerCountry" Id="5"
                DesignerType="TextBox" Text="country" DisplayName="Customer Country" />
   <FieldBind Field="CustomerPhone" Id="6"
                DesignerType="TextBox" Text="phone" DisplayName="Customer Phone" />
   <FieldBind Field="CustomerFax" Id="7"
                DesignerType="TextBox" Text="fax" DisplayName="Customer Fax" />
 </RuleDesigner>
 <Parameters>
   <Parameter Name="CustomerId" Type="System.String, mscorlib"
                Direction="In" DesignerType="Hide" />
   <Parameter Name="CustomerName" Type="System.String, mscorlib"
                Direction="Out" DesignerType="Hide" />
   <Parameter Name="CustomerTitle" Type="System.String, mscorlib"
                Direction="Out" DesignerType="Hide" />
   <Parameter Name="CustomerAddress" Type="System.String, mscorlib"
                Direction="Out" DesignerType="Hide" />
   <Parameter Name="CustomerCountry" Type="System.String, mscorlib"
                Direction="Out" DesignerType="Hide" />
   <Parameter Name="CustomerPhone" Type="System.String, mscorlib"
                Direction="Out" DesignerType="Hide" />
   <Parameter Name="CustomerFax" Type="System.String, mscorlib"
                Direction="Out" DesignerType="Hide" />
 </Parameters>
</Action>

In this markup, notice the <RuleDesigner> element, specifically the Sentence attribute. It contains a string that is shown in the SharePoint Designer experience. Each of the pieces of the sentence that start with the % character are treated as linked placeholders. They map to the <FieldBind> elements in the markup. For instance, %2 maps to the fullName field. What is shown in the design experience is a hyperlinked string fullName, which the workflow author can click. The <Parameters> section tells the designer how each field should be treated; for instance, whether it is an email address, string, number, or datetime field. Based on the type specified, the designer shows different designers and applies different validation rules.

When you are finished, deploy the sandboxed solution to a SharePoint 2013 site and create a new workflow. The activity will appear in the category that the *.actions4 file specified and will appear in the designer, as shown in Figure 12-18.

Figure 12-18. This shows using the custom activity, as shown in the text-based designer in SharePoint Designer 2013.

When creating custom tasks and custom task outcomes in workflows authored by using SharePoint Designer 2013, workflow authors needs to keep in mind that they are going to be responsible for creating the workflow task list. The basic steps for creating the custom outcome are as follows:

Following these steps will render a single set of outcome buttons, as shown in Figure 12-22.

Figure 12-22. Notice the corrected buttons for the custom task content type rendering only the custom outcome columns.

When you are adding the task action in the workflow by using SharePoint Designer 2013, simply select the correct task content type and outcome column to ensure that the workflow uses the correct settings. Notice that the dialog box warns the author to ensure that the content type has been added to the associated workflow task list. This is not checked in the publication process of the workflow, nor at runtime. Instead, the workflow will produce an error during the process of creating a task, with a message about an ArgumentException on the ContentTypeId, as shown in Figure 12-23. This is something that might not be intuitive to the experienced user or end user, so make sure that this is set ahead of time.

Figure 12-23. Use the SharePoint Designer 2013 Assign A Task dialog box to modify the task settings.

The process of creating custom task outcomes for custom tasks with workflows built by using Visual Studio 2012 is similar to that of SharePoint Designer 2013. The most important difference is to keep in mind that the workflow author is responsible for binding the custom content type to the workflow task list. This can be done by opening the Elements.xml file for the WorkflowTaskList project item and adding a second <ContentTypeBinding /> element referencing the content type ID of the custom content type, as shown in the following code snippet:

<?xml version="1.0" encoding="utf-8" ?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
 <ListInstance FeatureId="{f9ce21f8-f437-4f7e-8bc6-946378c850f0}"
             TemplateType="171"
             Title="WorkflowTaskList"
             Description="This list instance is used for workflow Task items."
             Url="Lists/WorkflowTaskList"
             RootWebOnly="FALSE" />
    <ContentTypeBinding ListUrl="Lists/WorkflowTaskList"
                      RootWebOnly="FALSE"
                      ContentTypeId="0x0108003365C4474CAE8C42BCE396314E88E51F"/>
 <ContentTypeBinding ListUrl="Lists/WorkflowTaskList"
                      RootWebOnly="FALSE"
                      ContentTypeId="0x010800C5462A9EBAE14BFC8DA48A659BFC2C80"/>
</Elements>

This walkthrough demonstrates creating a custom association form and using it to collect some information that is then passed along to the workflow. Following the same setup process you used with the other workflows you built in Visual Studio 2012 in this chapter, create a new SharePoint-hosted app project with an Announcement list, and add a workflow, but this time do not associate the workflow with the list. Instead, the workflow will be manually associated after it is deployed.

To demonstrate how association forms work, the workflow will simply show the value of one field submitted from the custom association form. Right-click the workflow and add a new project item by using the Workflow Association Form template. Visual Studio will add the form to the Pages module in the project and update the workflow’s properties to point to the URL of the item. The ASPX page that is created for the association form is nearly complete because it will use the Workflow Services JSOM to create the workflow history list and task list (if necessary), as well as the association. First, notice that within the PlaceHolderMain section there is a server control that’s worth mentioning:

<WorkflowServices:WorkflowAssociationFormContextControl />

This control collects the input form controls from the HTTP POST submitted on the previous page, the one in which the user selects the workflow definition, task list, history list, and workflow start configuration. Without this, the association could not be created. The control simply adds a handful of hidden form controls on the page that are accessed by the JavaScript generated in this template. Scroll a little further down to find the core form within a table. By default, it includes a handful of form controls, but to simplify things, delete the two form controls and just leave the single textarea field control.

The form also includes a button that will call a JavaScript function on the page to trigger the association creation process. Scroll through the JavaScript to a section that creates a new variable called metadata. When you find it, change the key of the array item to AssociationFormValue:

var metadata = new Object();
// Get form input values and set workflow in-argument values
var strInputValue = document.getElementById("strInput").value;
if (strInputValue) {
   metadata['AssociationFormValue'] = strInputValue;
}

This block is collecting three form values and placing them in the metadata array. Remove the code block that creates intInputValue and dateTimeInputValue variables, because those were previously removed in an earlier step. Now scroll down to the comment “Add new workflow association”, past the code that creates a history list and task list if mandated on the previous form:

// Add new workflow association
var newSubscription = SP.WorkflowServices.WorkflowSubscription.newObject(context);
newSubscription.set_definitionId(definitionId);
newSubscription.set_eventSourceId(eventSourceId);
newSubscription.set_eventTypes(eventTypes);
newSubscription.set_name(workflowName);
for (var key in metadata) {
   newSubscription.setProperty(key, metadata[key]);
}
// Publish
wfManager.getWorkflowSubscriptionService().publishSubscriptionForList(newSubscription, listId);

This section uses the Workflow Service JSOM to do the following things:

Notice that the only things that need to be modified are the form and form controls, and the section in which those values are collected and saved into the metadata array. The next step is to add an activity to the workflow itself to collect these properties being passed in.

Within the workflow, create a new variable named AssociationFormValue of type string. Next, add a GetConfigurationValue to the workflow and set the Name property equal to the name of the property being passed in from the form via the Workflow Services JSOM, and set the Result property to the local variable: AssociationFormValue. Now the workflow has access to the values passed in from the association form!

To test it, deploy the SharePoint-hosted app and, when the browser opens, navigate to the Announcement list. On the List tab on the ribbon, click the Workflow button. Click the Add A Workflow link. Select the custom workflow, give it a friendly name, and select the history and task lists. When the Next button is clicked, the custom form is displayed.

This walkthrough demonstrates creating a custom initiation form and using it to collect some information from the user when the workflow is started manually. Following the same setup process you used for the other workflows you built in Visual Studio 2012 in this chapter, create a new SharePoint-hosted app project with an Announcement list, and add a workflow that is associated with the Announcement list and starts manually.

Right-click the workflow and add a new project item by using the Workflow Initiation Form template. Visual Studio will add the form to the Pages module in the project and update the workflow’s properties to point to the URL of the item. The .aspx page that is created for the initiation form, just like with the association form, is nearly complete because it will use the Workflow Services JSOM to start the workflow and pass in specific values.

Following the same process as the association form, find the form controls and remove the second textarea and datetime controls. Next, change the strInput textarea control to an input control. To make things a little interesting, add another control, the SharePoint server-side people picker:

<SharePoint:PeopleEditor runat="server" AllowEmpty="False"
                            ValidatorEnabled="False" MultiSelect="False" ID="peoplePicker" />

To make development a bit easier, add a reference to the included jQuery library to the head portion of the page, within the PlaceHolderAdditionalPageHead section, just after the sp.workflowservices.js reference.

Now, scroll down into the JavaScript code to the comment “Set workflow in-arguments/initiation parameters” section, which is where another array is created with all the things to send to the workflow. First, remove the two sections that are collecting the second textarea and datetime controls previously removed. Rename the parameter that is being passed in to SomeRandomString, and add some additional JavaScript that will get a reference to the people picker client-side control and extract the logon name of the selected user, as shown in the following code:

// get people picker value
var html = $("#ctl00_PlaceHolderMain_peoplePicker_upLevelDiv");
wfParams['UserLoginName'] = $("#divEntityData", html).attr("key");
// get string input
var strInputValue = document.getElementById("strInput").value;
if (strInputValue) {
 wfParams['SomeRandomString'] = strInputValue;
}

With the parameters selected, find the comment “Get workflow subscription and then start the workflow” further along in the JavaScript. This section obtains a reference to the Workflow Services Manager, the core component of the Workflow Services JSOM, in addition to references to the deployment and subscription services, which were covered earlier in this chapter, in the section Workflow services CSOM and JSOM. This code then obtains a subscription (association) by using the subscriptionID that was passed, by SharePoint 2013, into the page via a value on the query string.

The code then, by using an instance of the workflow instance service, starts a workflow on a specific list item by passing in the workflow subscription, the ID of the item the workflow should be associated with, and a collection of the parameters from the form:

// Get workflow subscription and then start the workflow
var context = SP.ClientContext.get_current();
var wfManager = SP.WorkflowServices.WorkflowServicesManager.newObject(context,
  context.get_web());
var wfDeployService = wfManager.getWorkflowDeploymentService();
var subscriptionService = wfManager.getWorkflowSubscriptionService();

context.load(subscriptionService);
context.executeQueryAsync( function (sender, args) {
// Success
 var subscription = null;
 // Load the workflow subscription
 subscription = subscriptionService.getSubscription(subscriptionId);
 if (itemId != null && itemId != "") {
     // Start list workflow
     wfManager.getWorkflowInstanceService().startWorkflowOnListItem(subscription, itemId,
wfParams);
 } else {
     // Start site workflow
     wfManager.getWorkflowInstanceService().startWorkflow(subscription, wfParams);
 }
 context.executeQueryAsync(
     function (sender, args) { window.location = redirectUrl; },
     function (sender, args) { ... }
 )
});

The last step is to configure the workflow to collect these values being passed in. Within the workflow, add two input arguments for SomeRandomString and UserLoginName, both strings. The workflow engine and SharePoint will handle sending the form values into the workflow and linking them up with these arguments, which can then be used within the workflow for various use cases.