The best way to appreciate the real potential of SharePoint Designer 2013 as a mature workflow authoring tool is to put it to work. In this section, you will use it to create a workflow solution that consumes services via HTTP, as well as Representational State Transfer (REST) and JavaScript Object Notation (JSON). Imagine that you need to create a site workflow that manages all the documents in a library. You can consume the REST API offered by SharePoint 2013 to retrieve the collection of documents, and then you can manage them through the REST API or by using the out-of-the-box activities of SharePoint Designer 2013.

Start SharePoint Designer 2013 and create a new site workflow definition called Documents Maintenance Workflow. Insert a Call HTTP Web Service action, and click the configuration link, which is available in the shape of the action, to access the Call HTTP Web Service dialog box, shown in Figure 17-1.

Figure 17-1. The dialog window for configuring the Call HTTP Web Service action of SharePoint Designer 2013.

Choose the HTTP GET request method and provide a URL that retrieves the ID and the Title of all the documents in the library with title Documents. For the example environment, use http://devbook.sp2013.local/sites/Workflows/_api/web/Lists/GetByTitle(’Documents’)/Items?$select=ID,Title.

After defining the HTTP method and the URL, you can configure the request headers, the request body, the response body, the response headers, and the response status code through some dedicated workflow variables. To properly compile the request headers, you add a Build a Dictionary action prior to the Call HTTP Web Service action and configure a variable of type Dictionary to hold the headers’ values, including at least the Accept header for requesting a JSON response format (application/json;odata=verbose). To configure the request headers, right-click the Call HTTP Web Service action and choose the Properties menu. You will be prompted with a dialog box for configuring all the available properties of the Call HTTP Web Service action. There you will find the HTTP RequestHeaders property, as shown in Figure 17-2.

Figure 17-2. The dialog window for configuring the Call HTTP Web Service action during the configuration of the RequestHeaders property.

The variables for holding these values (request body, request headers, response body, and response headers) must be of type Dictionary, because they will keep a set of values. In particular, consider that the REST service will return JSON content according to the provided Accept request header. An excerpt of the JSON response provided by the REST API while querying the items of a library shows an excerpt of a sample JSON result.

{"d":
    {"results":
        [{"__metadata":
            {"id":"91f72d8d-cd93-4872-bc18-c2f612d15ad2",
            "uri":"http://devbook.sp2013.local/sites/Workflows/_api/Web/
                Lists(guid'c5be436f-89cb-48bb-b141-09decd4ed400')/Items(6)",
             "etag":""3"",
             "type":"SP.Data.Shared_x0020_DocumentsItem"},
          "Id":6,
          "Title":"Invoice-03-2013",
          "ID":6},
         {"__metadata":
             {"id":"85e0058d-b111-483f-a2a2-423bbde1fa01",
              "uri":"http://devbook.sp2013.local/sites/Workflows/_api/Web/
                  Lists(guid'c5be436f-89cb-48bb-b141-09decd4ed400')/Items(7)",
              "etag":""2"",
              "type":"SP.Data.Shared_x0020_DocumentsItem"},
          "Id":7,
          "Title":"Invoice-01-2013",
"ID":7},
         {"__metadata":
             {"id":"de91a68e-76df-4b39-b50f-5abab1529733",
              "uri":"http://devbook.sp2013.local/sites/Workflows/_api/Web/
                  Lists(guid'c5be436f-89cb-48bb-b141-09decd4ed400')/Items(8)",
              "etag":""2"",
              "type":"SP.Data.Shared_x0020_DocumentsItem"},
          "Id":8,
          "Title":"Invoice-02-2013",
"ID":8}]
    }
}

As shown in Figure 17-3, the JSON response has a hierarchical structure.

Figure 17-3. The hierarchical structure of a JSON response retrieved from a REST operation for enumerating the documents of a library.

To manage such a response within the workflow definition, you can use the Get an Item from a Dictionary action. For an input argument, provide the response content retrieved from the Call HTTP Web Service action, and configure the path according to the hierarchy illustrated in Figure 17-3. For example, to retrieve the collection of resulting items, you can provide a path value of d/results. To retrieve a single resulting item, provide a path value of d/results[{Index}], where the {Index} parameter is a numeric indexer.

Now imagine that the goal of the maintenance workflow is to retrieve the title and ID of each document, in order to write them and the number of items retrieved to the workflow history list. To get the number of items, you can use the Count Items in a Dictionary action, providing as input the collection of items (d/result). To extract the ID and the title of every document, simply iterate through them. SharePoint Designer 2013 offers the Loop n Times construct to handle this task. First, retrieve the total number of items returned using the Count Items in a Dictionary action. Then you can loop n times, where the value of n will be the number of retrieved items. Using a local variable to hold the currently selected item index, you can browse all the returned items and retrieve the ID and title of each via a couple of Get an Item from a Dictionary actions. Figure 17-4 illustrates the layout for this workflow.

Figure 17-4. The structure of a sample workflow definition for enumerating the documents of a library.

Note that when looping through the resulting items, the Index variable increments in a dedicated inner step. If you save, publish, and execute such a workflow, you will see the workflow status page of the workflow instance, which illustrates the history list with the ID and title of the items retrieved (Figure 17-5).

Figure 17-5. The workflow status page of a sample workflow definition.

By using the Call HTTP Web Service action and the other actions to manage dictionaries, you can invoke the native REST API available in SharePoint 2013, targeting your own farm or any other farm, as long as you provide the proper OAuth authentication HTTP headers. As you can see, SharePoint Designer 2013 is a powerful tool for creating workflows, but it’s not the only one.

Visual Studio 2012 offers its own advantages for creating workflow definitions. To get started with its creation wizard, launch Visual Studio 2012, create a new project of type SharePoint 2013 - Empty Project and choose to target a farm-level solution. Add a new item to the newly created project by right-clicking the project in Solution Explorer and selecting Add | New Item. Choose a new item of type Workflow, and name it MyFirstWorkflow. A wizard will ask you to provide some information about the workflow you are going to create (Figure 17-6).

Figure 17-6. The first step of the wizard for creating a new workflow definition in Visual Studio 2012.

The first step of the wizard asks you to declare if the workflow will target a list or a site. The second step (Figure 17-7) then prompts you to select the target list if you decide to create a list workflow, as well as the target history list and task list. You can also decide to create a new history list and/or new tasks list. In this step, you can also decide whether to associate the workflow definition with a target. Later, during the provisioning of the workflow, you will provide the lists with which you will associate the workflow definition.

Figure 17-7. The second step of the wizard for creating a new workflow definition in Visual Studio 2012.

The third and last step of the wizard asks you to decide when and how the instances of the workflow definition will be created and started. The available options, as shown in Figure 17-8, are the following:

While developing a new workflow, you should usually choose to manually start the workflow, just because it is easier to debug a workflow and manually start its instances while the debugger is active, rather than having to create or change an item to fire new instances of the workflow definition.

Figure 17-8. The third and last step of the wizard for creating a new workflow definition in Visual Studio 2012.

Keep in mind that all these options are mainly for debugging purposes. When you create a workflow definition in Visual Studio 2012, the resulting workflow will be available for association wherever you want to associate it. The result of this wizard will be a XAML file, together with a feature element and a SharePoint feature for provisioning the workflow. As you saw in Chapter 15 a XAML workflow file created from scratch is a whiteboard—from a designer viewpoint. Even in this case, by opening the XAML file created, you will have a whiteboard, with just a Sequence activity designed on it. You can now use the toolbox provided by Visual Studio 2012 to define activities on the target design surface. In particular, in the activity toolbox that is available when you are in the designer, you will find many groups of SharePoint-related activities (see Figure 17-9). In Table 17-1, you can see the list of all the SharePoint-related activities available out of the box, divided into functional groups.

Figure 17-9. The whiteboard for designing workflows in Visual Studio 2012.

The Workflow Manager infrastructure provides some additional activities that are useful while designing SharePoint 2013 workflows. Although these activities are not only for SharePoint workflows, they are surely useful when developing them. Table 17-2 lists these activities.

Now imagine that you want to create a simple workflow definition that targets a document library, retrieves the current item, checks out the document, and writes an item in the associated history list. Insert a CheckOutItem activity and configure it to check out the current item, configuring values of the ListId and ItemId properties with the values of the automatically provided values defined as (current list) and (current item).

Then add a WriteToHistory activity and configure its Message property to an explicit string value of Document checked-out!. Figure 17-10 illustrates the result in the workflow designer.

Figure 17-10. The sample workflow designed in Visual Studio 2012.

Notice that you have not defined any code. You simply configured the workflow definition using the designer and the properties of the defined activities with their underlying Microsoft C# or Visual Basic expressions. This is one of the key features of workflows in SharePoint 2013: they are markup based. You do not have to write any code, even if you define a workflow in Visual Studio 2012.

Now you are ready to build, deploy, and test your workflow definition. Right-click the project in Solution Explorer and select the Deploy menu item. Now open the browser and navigate to the Documents library. Open the Workflow Settings page, which is available on the Library ribbon tab, and check the available workflows. You should see the workflow you just deployed, as illustrated in Figure 17-11.

Figure 17-11. The Workflow Settings page of a document library.

To execute an instance of the workflow, select any of the documents in the target library, click the Files ribbon tab, and click the Workflows ribbon button. You will be prompted with the Workflows page of the selected item. Click the workflow name to start a new instance. As soon as you start the workflow, the target document becomes checked out. Click the ECB menu and select the Workflows menu item to access the Workflows page (Figure 17-12).

Figure 17-12. The Workflows page of a document item in a document library.

Click the Internal Status column, where you see a value of Completed, to access the Workflow Status page of that completed workflow instance. As shown in Figure 17-13, the workflow instance has an Internal State value of Completed, and the Workflow History list reports a single item with the description defined in the workflow definition in Visual Studio 2012.

The workflow instance you have just associated with the target library of orders does not provide a custom workflow status column. In fact, workflows created with Visual Studio 2012 by default do not provide implementation for such a column. Later in this chapter, in the “Workflow deployment” section, you will learn how to turn it on.

Figure 17-13. The Workflow Status page of a workflow instance executed against a specific document.

To test and debug your workflow definition, you can place a breakpoint within the designer on any of the activities you defined. Suppose you want to break and debug starting from the GetCurrentListId activity instance. Press F5 to start debugging the project. Visual Studio 2012 will deploy the workflow project to SharePoint, and will start a console process that acts as a Workflow Manager instance dedicated to debugging.

Starting a workflow instance while debugging will raise within Visual Studio 2012 any breakpoint you declared in the workflow definition. Figure 17-14 shows the console output of the Workflow Manager emulator.

Figure 17-14. The console screen of the Workflow Manager emulator available for debugging SharePoint 2013 workflows within Visual Studio 2012.

Here is the output, in the console window, provided by the emulator after executing a sample workflow instance:

Listening at http://sp2013srv01.sharepoint.local:12292/
Runtime and gateway started, press <Enter> to exit.
Instance '866d65ba-4870-4ef7-8730-2d48eb8fa9d6' of workflow fb5b0c53-2f56-46a3-b3db-c07f0c13e591

Status: Started; Details: .
Instance '866d65ba-4870-4ef7-8730-2d48eb8fa9d6' of workflow fb5b0c53-2f56-46a3-b3db-c07f0c13e591

Status: Completed; Details: .

While debugging the workflow, expect to have a slow environment, because the overall debugging infrastructure is a little bit heavy to run and manage, and it is resource-consuming, too.

The sample workflow you just defined requires a farm-level solution for deployment, so it is not suitable for publishing in Microsoft Office 365. If you instead define a workflow in a SharePoint app project, however, you can then publish it on-premises or on Office 365 via the cloud. Thus, the best practice is to create workflow definitions in apps, rather than in farm-level solutions.

To do so, create a new SharePoint 2013 app project—for instance, targeting an Office 365 tenant. Choose a SharePoint-hosted app, define a document library instance called Orders in the app website, and add a new item of type Workflow. Imagine that the library holds a set of orders that need approval by a manager, and name it OrdersWorkflow.

The sample will be a list workflow, and the workflow creation wizard provided by Visual Studio 2012 is smart enough to suggest that you associate the workflow with any of the libraries defined in the current SharePoint app (see Figure 17-15).

Figure 17-15. The wizard for creating a workflow definition in a SharePoint app, using Visual Studio 2012.

If the Workflow History list and the Workflows Tasks list are not already available in the SharePoint app, you can define them explicitly, or you can simply ask the wizard to create them for you in the target app website.

While a real approval workflow definition should handle such input arguments as the target approver and the approval request message, the sample approval workflow will define explicit and fake values for these arguments. Later, you will use an initiation form. For now, create variables for holding the TargetApprover (String), the ApprovalRequestMessage (String), the ApprovalTaskId (Int32), and the ApprovalTaskOutcome (Int32) values.

Insert a SingleTask activity instance into the sequence defining the workflow, and configure its properties by clicking the Configure link provided in the designer. You will be prompted with a pop-up configuration screen (see Figure 17-16), where you will be able to configure all the main properties of the task. As you will see, a SingleTask activity has many required properties. Table 17-3 lists the values configured in the current sample.

Figure 17-16. The Task Options designer provided by the SingleTask activity within Visual Studio 2012.

Notice that when you add a SingleTask activity or a CompositeTask activity to the workflow designer, the activity automatically adds variables to the current context for holding fundamental field values like task outcomes and others. You can use these automatically created variables, or you can replace them with custom variables of your own.

Now you need to determine if the task outcome is an approval of the order or a rejection. Insert an If activity, which is available in the Control Flow group of native activities. In the condition, enter the following expression:

ApprovalTaskOutcome == 0

The 0 value corresponds to the Approved outcome value, which is the first value defined in the underlying field type. In the left branch, which is the one labeled as Then, insert a WriteToHistory activity, providing a value of Approved for the Message property. In the right branch, which is the one labeled as Else, insert another WriteToHistory activity, providing a value of Rejected for the Message property. The sample workflow definition is now complete. Take a look at the final workflow outline in Figure 17-17.

Figure 17-17. The outline of the sample order-approval workflow in the designer provided by Visual Studio 2012.

Now press F5 to deploy and debug the SharePoint app, or deploy it and then test it through the web browser as if you were an end user. If you debug the app by pressing F5, because the project contains a workflow definition, the Visual Studio 2012 debugger will start the Workflow Manager emulator, too. If you simply deploy and test the app from the browser, you will use the standard Workflow Manager. You will not, however, be able to raise breakpoints and step into the workflow definition unless you do not attach the Internet Information Services (IIS) worker process with the debugger. Moreover, consider that workflow debugging is allowed only in on-premises environments and cannot be done while targeting Office 365. If you try to debug a workflow project targeting Office 365, Visual Studio 2012 will raise a debug error, providing you the pop-up message shown in Figure 17-18.

Figure 17-18. The pop-up error message raised by Visual Studio 2012 during the debugging of a workflow targeting Office 365.

Figure 17-19 shows the Workflow Status page of the sample workflow definition while running on a target document.

Figure 17-19. The Workflow Status page of a sample order-approval workflow defined in Visual Studio 2012.

Figure 17-20 shows the task form for completing the approval task. It is an ASP.NET form, which is almost the same as the one available while developing workflows in SharePoint Designer 2013. Moreover, consider that starting with SharePoint 2013, the workflow task forms cannot be created using Microsoft InfoPath Forms Services; the only option you have is to use ASP.NET forms.

Figure 17-20. The ASP.NET task form for approving an order for the approval workflow for the sample orders.

Lastly, while a workflow created in a farm-level solution by default does not present the workflow status column, a workflow defined in a SharePoint app does present that column, as do workflows created with SharePoint Designer 2013.

In this section, you will learn how to create custom workflow forms. To create a workflow association or initiation form, you can simply use Visual Studio 2012. Right-click the workflow element in Solution Explorer, and then choose to add a new item. From the resulting list of available items, choose a Workflow Initiation Form template type (see Figure 17-21). The suggested file name will be for an ASPX page file.

Figure 17-21. The Add New Item window for a workflow element in Visual Studio 2012.

After you add the Workflow Initiation Form item, Visual Studio prompts you with the source code of the ASPX page file, which will be placed in the Pages folder of the current SharePoint app project. The page is made of a Content control targeting the PlaceHolderMain region of the default master page of SharePoint. The Content control contains ASP.NET, HTML, and JavaScript code completely commented (and left there for the sake of providing an example of some of the most common ways of rendering input fields for initiation arguments of type String, Integer, and DateTime). The ASPX file provides a couple of sample buttons to start the workflow instance or cancel the initiation. Lastly, at the end of the file is a small piece of JavaScript code that, using the Client-Side Object Model (CSOM) and the Workflow Services Manager client library, starts a new workflow instance providing the arguments configured by the user through the initiation form.

An excerpt of the source code of a sample workflow initiation form shows an excerpt of the source code of the initiation form.

<asp:Content ID="Content4" ContentPlaceHolderId="PlaceHolderMain" runat="server">
<%--         The following sample code creates a simple workflow initiation form that allows end users to enter values for workflow parameters when initiating a workflow instance.
        The sample JavaScript below will start a workflow instance using the initiation parameter values provided by the user.
--%>
    <table>
        <tr><td>String:<br /><textarea id="strInput" rows="1" cols="50"">
</textarea>
            <br /><br /></td></tr>
        <tr><td>Integer:<br /><textarea id="intInput" rows="1" cols="50"">
</textarea>
            <br /><br /></td></tr>
        <tr><td>DateTime: <SharePoint:DateTimeControl ID="dateTimeInput"
            DatePickerFrameUrl="../_layouts/15/iframe.aspx" LocaleId="1033"
            DateOnly="false" runat="server"  /><br /><br /></td></tr>
        <tr><td>
            <input type="button" name="startWorkflowButton" value="Start"
                onClick="StartWorkflow()" />
            <input type="button" name="cancelButton" value="Cancel"
                onClick="RedirFromInitForm()" />
               <br />
        </td></tr>
    </table>
    <script type="text/javascript">
        // ---------- Start workflow ----------
        function StartWorkflow() {
            var errorMessage = "An error occurred when starting the workflow.";
            var subscriptionId = "", itemId = "", redirectUrl = "";
            var urlParams = GetUrlParams();
            if (urlParams) {
                //itemGuid = urlParams["ItemGuid"];
                itemId = urlParams["ID"];
                redirectUrl = urlParams["Source"];
                subscriptionId = urlParams["TemplateID"];
            }
            if (subscriptionId == null || subscriptionId == "") {
                // Cannot load the workflow subscription without a 
                // subscriptionId, so workflow cannot be started.
                alert(errorMessage + 
"  Could not find the workflow subscription id.");
                RedirFromInitForm(redirectUrl);
            }
           else {
                // Set workflow in-arguments/initiation parameters
                var wfParams = new Object();
                var strInputValue = document.getElementById("strInput").value;
                if (strInputValue) {
                    wfParams['strArg'] = strInputValue;
                }
                var intInputValue = document.getElementById("intInput").value;
                if (intInputValue) {
                    var intValue = parseInt(intInputValue);
                    if (intValue)
                        wfParams['intArg'] = intValue;
                }
                var dateTimeInputValue = document.getElementById(
                    "ctl00_PlaceHolderMain_dateTimeInput_dateTimeInputDate").
                    value;
                if (dateTimeInputValue) {
                    var dateTimeValue = new Date(document.getElementById(
                        "ctl00_PlaceHolderMain_dateTimeInput_dateTimeInputDate").
                        value);
                    if (dateTimeValue)
                        wfParams['dateTimeArg'] = dateTimeValue;
                }
                // 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
                        if (subscriptionId)
                            subscription = subscriptionService.
                            getSubscription(subscriptionId);
                        if (subscription) {
                            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) {
                                    // Success
                                    RedirFromInitForm(redirectUrl);
                                },
                                function (sender, args) {
                                    // Error
                                    alert(errorMessage + "  " + 
                                    args.get_message());
                                    RedirFromInitForm(redirectUrl);
                                }
                            )
                        }
                        else {
                            // Failed to load the workflow subscription,
                            // so workflow cannot be started.
                            alert(errorMessage + 
                                "  Could not load the workflow subscription.");
                            RedirFromInitForm(redirectUrl);
                        }
                    },
                    function (sender, args) { // Error
                        alert(errorMessage + "  " + args.get_message());
                        RedirFromInitForm(redirectUrl);
                    }
                )
            }
        }
        // ---------- Redirect from page ----------
        function RedirFromInitForm(redirectUrl) {
            window.location = redirectUrl;
        }
     // ---------- Returns an associative array (object) of URL params -------
        function GetUrlParams() {
            var urlParams = null;
            if (urlParams == null) {
                urlParams = {};
                var parts = window.location.href.replace
                (/[?&]+([^=&]+)=([^&]*)/gi, 
                    function (m, key, value) {
                        urlParams[key] = decodeURIComponent(value);
                });
            }
            return urlParams;
        }
    </script>
</asp:Content>

The JavaScript code that starts the workflow instance is highlighted in bold. Note that you can define the initiation form any way you want, from a markup and design viewpoint. The only important thing is to start the workflow instance using the JavaScript code. Of course, having a code excerpt for handling all the most useful data types and for starting a workflow instance is a great aid.

To start the workflow providing input arguments, the JavaScript code retrieves the current SP.ClientContext instance. Through this, it gets a reference to a new instance of the SP.WorkflowServices.WorkflowServicesManager class, which will be explained in detail in Chapter 18. For now, it will suffice to know that the WorkflowServicesManager instance retrieves a reference to the types useful for resolving the current workflow definition. Using the TemplateID query string parameter, which will be provided to the initiation form by SharePoint, the JavaScript code retrieves the workflow definition associated with the current initiation form, and starts the workflow instance using either the startWorkflow method or the startWorkflowOnListItem method of the WorkflowInstanceService class, depending on the target of the workflow.

Now go back to the OrdersWorkflow definition you designed in the previous section. To retrieve values provided through the initiation form, you need to define workflow arguments corresponding to the fields configured in the form. In the current OrdersWorkflow sample, delete the variables ApprovalRequestMessage and TargetApprover and replace them with a couple of arguments with the same name and type (String). You need to adapt the initiation form accordingly. Leave the String field in the page, deleting the Integer and DateTime sample code excerpts. Then change the JavaScript code to provide the right startup arguments. As you can see from reading the code highlighted in bold in An excerpt of the source code of the OrdersWorkflow initiation form, a client-side PeoplePicker control has been inserted, which is new in SharePoint 2013. This new control allows selecting a user, a group, or a distribution list from the client code using JavaScript. This control will be used to retrieve the value for the TargetApprover argument.

<asp:Content ID="Content2" ContentPlaceHolderId="PlaceHolderAdditionalPageHead"
    runat="server">
    <script type="text/javascript" src="../_layouts/15/sp.runtime.js"></script>
    <script type="text/javascript" src="../_layouts/15/sp.js"></script>
    <script type="text/javascript" src="../_layouts/15/sp.workflowservices.js">
</script>
    <!-- Scripts added to support client-side PeoplePicker -->
    <script type="text/javascript" src="../Scripts/jquery-1.7.1.min.js"></script>
    <SharePoint:ScriptLink ID="ScriptLink1" name="clienttemplates.js" 
    runat="server"
        LoadAfterUI="true" Localizable="false" />
    <SharePoint:ScriptLink ID="ScriptLink2" name="clientforms.js" runat="server"
        LoadAfterUI="true" Localizable="false" />
    <SharePoint:ScriptLink ID="ScriptLink3" name="clientpeoplepicker.js"      runat="server"LoadAfterUI="true" Localizable="false" />
    <SharePoint:ScriptLink ID="ScriptLink4" name="autofill.js" runat="server"
        LoadAfterUI="true" Localizable="false" />
    <SharePoint:ScriptLink ID="ScriptLink6" name="sp.core.js" runat="server"
        LoadAfterUI="true" Localizable="false" />
    <script type="text/javascript"
        src="../Scripts/ClientSidePeoplePicker.js"></script>
</asp:Content>
<asp:Content ID="Content4" ContentPlaceHolderId="PlaceHolderMain" runat="server">
    <table>
        <tr>
            <td>
               Approval request message:<br />
               <textarea id="ApprovalRequestMessage" rows="5" cols="50">
               </textarea>
               <br /><br />
            </td>
        </tr>
        <tr>
            <td>
               Target Approver(s):<br />
               <div id="peoplePicker"></div>
               <br /><br />
            </td>
        </tr>
        <tr>
            <td>
               <input type="button" name="startWorkflowButton" value="Start"
                    onClick="StartWorkflow()" />
               <input type="button" name="cancelButton" value="Cancel"
                    onClick="RedirFromInitForm()" />
               <br />
            </td>
        </tr>
    </table>
    <script type="text/javascript">
        // ---------- Start workflow ----------
        function StartWorkflow() {
            var errorMessage = "An error occured when starting the workflow.";
            var subscriptionId = "", itemId = "", redirectUrl = "";
            var urlParams = GetUrlParams();
            if (urlParams) {
                //itemGuid = urlParams["ItemGuid"];
                itemId = urlParams["ID"];
                redirectUrl = urlParams["Source"];
                subscriptionId = urlParams["TemplateID"];
            }
            if (subscriptionId == null || subscriptionId == "") {
                // Cannot load the workflow subscription without a 
                // subscriptionId, so workflow cannot be started.
                alert(errorMessage + 
                "  Could not find the workflow subscription id.");
                RedirFromInitForm(redirectUrl);
            }
            else {
                // Set workflow in-arguments/initiation parameters
                var wfParams = new Object();
                var approvalRequestMessageValue = $("#ApprovalRequestMessage").
                val();
                if (approvalRequestMessageValue) {
                    wfParams['ApprovalRequestMessage'] = 
                    approvalRequestMessageValue;
                }
                var targetApproverValue = getUserKeys("peoplePicker");
                if (targetApproverValue) {
                    wfParams['TargetApprover'] = targetApproverValue;
                }
                // 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
                        if (subscriptionId)
                            subscription = subscriptionService.
                            getSubscription(subscriptionId);
                        if (subscription) {
                            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) {
                                    // Success
                                    RedirFromInitForm(redirectUrl);
                                },
                                function (sender, args) {
                                    // Error
                                    alert(errorMessage + "  " 
                                    + args.get_message());
                                    RedirFromInitForm(redirectUrl);
                                }
                            )
                        }
                        else {
                            // Failed to load the workflow subscription,
                            // so workflow cannot be started.
                            alert(errorMessage +
                                "  Could not load the workflow subscription.");
                            RedirFromInitForm(redirectUrl);
                        }
                    },
                    function (sender, args) { // Error
                        alert(errorMessage + "  " + args.get_message());
                        RedirFromInitForm(redirectUrl);
                    }
                )
            }
        }
        // Code omitted for the sake of brevity …
    </script>
</asp:Content>

Because the OrdersWorkflow definition targets a list workflow, the JavaScript code will use the startWorkflowOnListItem method, providing as arguments the workflow subscription ID corresponding to the current workflow definition, the ID of the current item taken from the query string, and a dictionary of arguments that will have to match the arguments defined in the workflow designer of Visual Studio 2012. The sample workflow initiation form will also resolve the selected target approver user key using some custom JavaScript code, which is a modified version of the code provided by MSDN for using the client-side PeoplePicker control. An excerpt of the JavaScript code to retrieve the user key provided by the client-side PeoplePicker control shows the JavaScript code for resolving the target approver.

// Run your custom code when the DOM is ready.
$(document).ready(function () {
    // Specify the unique ID of the DOM element where the picker will render.
    initializePeoplePicker('peoplePicker'),
});
// Render and initialize the client-side PeoplePicker.
function initializePeoplePicker(peoplePickerElementId) {
    // Create a schema to store picker properties, and set the properties.
    var schema = {};
    schema['PrincipalAccountType'] = 'User,DL,SecGroup,SPGroup';
    schema['searchPrincipalSource'] = 15;
    schema['ResolvePrincipalSource'] = 15;
    schema['AllowMultipleValues'] = false;
    schema['MaximumEntitySuggestions'] = 50;
    schema['Width'] = '280px';
    // Render and initialize the picker. 
    // Pass the ID of the DOM element that contains the picker, an array of 
    // initial
    // PickerEntity objects to set the picker value, and a schema that defines
    // picker properties.
    this.SPClientPeoplePicker_InitStandaloneControlWrapper(
        peoplePickerElementId, null, schema);
}
// Query the picker for user information.
function getUserKeys(peoplePickerElementId) {
    // Get the PeoplePicker object from the page.
    var peoplePicker = this.SPClientPeoplePicker.SPClientPeoplePickerDict
        [peoplePickerElementId + "_TopSpan"];
    // Get information about all users.
    var users = peoplePicker.GetAllUserInfo();
    var userInfo = '';
    for (var i = 0; i < users.length; i++) {
        var user = users[i];
        for (var userProperty in user) {
            userInfo += userProperty + ':  ' + user[userProperty] + '<br>';
        }
    }
    // We do not use the userInfo variable, 
    // but just in case … leave it here …
    // Get user keys.
    var keys = peoplePicker.GetAllUserKeys();
    return(keys);
}

To test and check the arguments, you can add a couple of WriteToHistory activities for writing the two arguments to the Workflow History list.

However, to effectively use the initiation form, you will need to configure the workflow project item in the Visual Studio 2012 project. In Solution Explorer, click the OrdersWorkflow item to edit its properties using the standard property grid of Visual Studio 2012. There you will find a long list of properties, including one named InitiationUrl. Through the InitiationUrl property, you can define the ASPX page to use as the initiation form for your workflow. When you add an initiation form through Visual Studio 2012, it automatically adds the proper value to the workflow configuration.

Deploy the SharePoint app and start a workflow instance; you will be prompted with an initiation form like the one shown in Figure 17-22.

Figure 17-22. The workflow initiation form for the sample OrdersWorkflow definition in Visual Studio 2012.

The form displays a field for providing the content of the ApprovalRequestMessage argument, and the client-side PeoplePicker control for providing the value of the TargetApprover argument.

The workflow association form will be almost the same as the workflow initiation form. The only difference will be the JavaScript code behind the form. By using the association form, you will need to define the association, which in SharePoint 2013 is represented by a WorkflowSubscription type instance and its configuration properties. However, consider that in SharePoint 2013, many of the workflows you will develop in Visual Studio 2012 will be defined within SharePoint apps. Thus, the association of the workflow with its target list, library, or site will happen during the provisioning of the app, because end users usually do not configure lists, libraries, and the app website manually. Meanwhile, if you are developing a farm-level workflow, you may also need to create a custom workflow association form. In Chapter 18, you will learn how to publish a WorkflowSubscription instance, using the Workflow Services Manager client library, and write an association form page for a workflow defined in a farm-level solution.

You can further customize your workflows by creating custom tasks and defining custom task fields and custom task forms. To create a custom task, you first define a custom content type, inheriting from the basic Workflow Task (SharePoint 2013) content type.

Within the custom content type definition, declare a site column for holding a custom task outcome, which will be the customization defined in the custom task. The XML code declaring the custom OrderApprovalTask content type shows the source XML code declaring the new task content type.

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <Field ID="{919DEB5B-FB24-49B8-93E1-0EDE24947F9F}"
         Name="OrderApprovalOutcome"
         StaticName="OrderApprovalOutcome"
         DisplayName="OrderApprovalOutcome"
         Type="OutcomeChoice"
         Required="FALSE"
         Group="DevLeap Site Columns">
    <CHOICES>
      <CHOICE>Approved</CHOICE>
      <CHOICE>To Review</CHOICE>
      <CHOICE>Rejected</CHOICE>
    </CHOICES>
  </Field>
 <!-- Parent ContentType: Workflow Task (SharePoint 2013) (0x0108003365C4474CAE8C42BCE396314E88E51F) -->
  <ContentType 
ID="0x0108003365C4474CAE8C42BCE396314E88E51F00D46A33DB74E44810A5A763715BB0F727"
               Name="OrderApprovalTask"
               Group="DevLeap Content Types"
               Description="Orders Approval Content Type"
               Inherits="FALSE"
               Version="0">
    <FieldRefs>
      <FieldRef ID="{919DEB5B-FB24-49B8-93E1-0EDE24947F9F}" Name="OrderApprovalOutcome" />
    </FieldRefs>
    <XmlDocuments>
      <XmlDocument NamespaceURI="http://schemas.microsoft.com/sharepoint/v3/contenttype/forms/url">
        <FormUrls xmlns="http://schemas.microsoft.com/sharepoint/v3/contenttype/forms/url">
          <Display>Pages/OrderApprovalTaskForm.aspx</Display>
          <Edit>Pages/OrderApprovalTaskForm.aspx</Edit>
        </FormUrls>
      </XmlDocument>
    </XmlDocuments>

  </ContentType>
</Elements>

Notice that the custom task inherits from the Workflow Task (SharePoint 2013) content type (0x0108003365C4474CAE8C42BCE396314E88E51F), but it does not inherit the UI from the parent content type (attribute inherits with a value of FALSE). On the contrary, the ContentType element is configured to use a custom set of forms, which are configured as relative URLs mapping to custom ASPX pages defined in the Pages folder of the current SharePoint app project. Also notice that the custom site column for holding the task outcome is of type OutcomeChoice, which is a new SharePoint 2013 type defined for holding the outcome of a workflow task.

The custom ASPX page implementing the task form, which is illustrated in The ASPX code of the custom workflow task form, defines some custom UI elements and provides three buttons to approve, reject, or submit the order for review. Based on the JSOM, the code behind the page simply updates the current task item, which was retrieved using the List and ID query string arguments, and sets the OrderApprovalOutcome field according to the user’s choice.

<%@ Page language="C#" MasterPageFile="~masterurl/default.master" Inherits="Microsoft.SharePoint.WebPartPages.WebPartPage, Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@ Register Tagprefix="SharePoint" Namespace="Microsoft.SharePoint.WebControls" Assembly="Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@ Register Tagprefix="Utilities" Namespace="Microsoft.SharePoint.Utilities" Assembly="Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@ Register Tagprefix="WebPartPages" Namespace="Microsoft.SharePoint.WebPartPages" Assembly="Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<asp:Content ContentPlaceHolderId="PlaceHolderAdditionalPageHead" runat="server">
    <SharePoint:ScriptLink name="sp.js" runat="server" OnDemand="true" LoadAfterUI="true" Localizable="false" />
    <script type="text/javascript" src="../Scripts/jquery-1.7.1.min.js"></script>
</asp:Content>
<asp:Content ContentPlaceHolderId="PlaceHolderMain" runat="server">
    <h1>Order Approval Task</h1>
    <WebPartPages:WebPartZone runat="server" FrameType="TitleBarOnly" ID="full" Title="loc:full" />
    <table>
        <tr>
            <td>
               Please choose the outcome for the current task
            </td>
        </tr>
        <tr>
            <td>
                <input type="button" name="approveTaskOutcome" value="Approved"
                    onclick="setTaskOutcome('Approved')," />
                <input type="button" name="rejectTaskOutcome" value="Rejected"
                    onclick="setTaskOutcome('Rejected')," />
                <input type="button" name="toReviewTaskOutcome" value="To Review"
                    onclick="setTaskOutcome('To Review')," />
               <br />
            </td>
        </tr>
    </table>
   <script type="text/javascript">
        var ctx;
        var urlParams = null;
        function getUrlParams() {
            if (urlParams == null) {
                urlParams = {};
                var parts = window.location.href.
                replace(/[?&]+([^=&]+)=([^&]*)/gi, function (m, key, value) {
                    urlParams[key] = value;
                });
            }
            return urlParams;
        }
        function setTaskOutcome(outcome) {
            ctx = SP.ClientContext.get_current();
            var web = ctx.get_web();
            var tasksList = web.get_lists().getById(
                decodeURIComponent(getUrlParams()["List"]));
            var task = tasksList.getItemById(getUrlParams()["ID"]);
            task.set_item("OrderApprovalOutcome", outcome);
            task.set_item("Status", "Completed");
            task.update();
            ctx.executeQueryAsync(
                function (sender, args) {
                    redirFromInitForm();
                },
                function (sender, args) {
                    alert("Error while saving the task outcome: " + 
                    args.get_message());
                }
            );
        }

        function redirFromInitForm() {
            window.location = decodeURIComponent(getUrlParams()["Source"]);
        }
    </script>
</asp:Content>

To use the new task content type, you could add to the app website a new list of tasks of this type. A better practice, however, is to use the wizard that adds a new workflow definition. By default, this wizard creates a tasks list for you; you should edit the list definition of that tasks list instead of creating a new one from scratch.

Open the Elements.xml file related to the tasks list and add a ContentTypeBinding element using a code excerpt like the one highlighted in bold in The code for provisioning the Workflow Tasks list, including a custom task content type.

<?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="0x0108003365C4474CAE8C42BCE396314E88E51F00D46A33DB74E44810A5A763715BB0F727"/>
</Elements>

The ContentTypeBinding element binds the custom content type to the tasks list definition available out of the box in SharePoint, and referenced through its TemplateType ID, which has a value of 171. In the current example, the content type ID of the custom task content type is the ContentTypeBinding element (highlighted in bold). Now, moving to the workflow definition, you can insert a SingleTask activity or a CompositeTask activity, and you can configure the task content type to match the new custom content type (see Figure 17-23).

Figure 17-23. The property editors of a SingleTask activity configured for using a custom task content type.

You can configure the custom task using either the standard property grid of Visual Studio 2012 or the Task Options pop-up window available in the workflow designer.

Discussing the whole approval workflow is out of scope for this context. In short, you define the workflow process using whatever activities you like, and then deploy and test it. In Figure 17-24, you can see how the custom task form behaves in the web browser when the assignee edits it.

Figure 17-24. The custom workflow task form rendered in the web browser.

Now that you can develop a workflow definition, you’re ready to delve into the workings of the workflow deployment process. This topic varies depending on the type of project you are defining. For example, a farm-level solution behaves differently from a SharePoint app project.

<?xml version="1.0" encoding="utf-8" ?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <Module Name="MyFirstWorkflow" Url="wfsvc/5d8de52d6b344e0ba8d8da022449bb7b">
    <File Url="Workflow.xaml" Type="GhostableInLibrary"
        Path="MyFirstWorkflowWorkflow.xaml" DoGUIDFixUp="TRUE">
      <Property Name="ContentType" Value="WorkflowServiceDefinition" />
      <Property Name="isReusable" Value="true" />
      <Property Name="RequiresInitiationForm" Value="False" />
      <Property Name="RequiresAssociationForm" Value="False" />
      <Property Name="WSPublishState" Value="3" />
      <Property Name="WSDisplayName" Value="MyFirstWorkflow" />
      <Property Name="WSDescription" Value="My 'MyFirstWorkflow' Workflow" />
      <!-- If you change the name or Url of your custom initiation or association form, 
            remember to update the corresponding property value (InitiationUrl or
            AssociationUrl) to match the new web relative url.
      -->
      <Property Name="InitiationUrl"
      Value="wfsvc/5d8de52d6b344e0ba8d8da022449bb7b/MyFirstWorkflow/WFInitForm.aspx" />
      <Property Name="AssociationUrl"
      Value="wfsvc/5d8de52d6b344e0ba8d8da022449bb7b/MyFirstWorkflow/WFAssocForm.aspx" />
      <Property Name="RestrictToType" Value="List" />
      <Property Name="RestrictToScope" Value="{$ListId:Shared Documents;}" />
    </File>
    <File Url="WorkflowStartAssociation" 
     Path="MyFirstWorkflowWorkflowStartAssociation"
        Type="GhostableInLibrary">
      <Property Name="WSDisplayName" Value="MyFirstWorkflow - Workflow Start" />
      <Property Name="ContentType" Value="WorkflowServiceSubscription" />
      <Property Name="WSPublishState" Value="3" />
      <Property Name="WSEventType" Value="WorkflowStart" />
      <Property Name="WSEnabled" Value="true" />
      <Property Name="WSGUID" Value="a5fdbc8e-0132-4403-a919-74fcc088192d" />
      <Property Name="WSEventSourceGUID" Value="{$ListId:Shared Documents;}" />
      <Property Name="Microsoft.SharePoint.ActivationProperties.ListId"
          Value="{$ListId:Shared Documents;}" />
      <Property Name="HistoryListId" Value="{$ListId:Lists/Workflow History;}" />
      <Property Name="TaskListId" Value="{$ListId:Lists/Workflow Tasks;}" />
      <Property Name="StatusColumnCreated" Value="1" />
    </File>
    <File Path="MyFirstWorkflowWFInitForm.aspx" 
    Url="MyFirstWorkflow/WFInitForm.aspx" />
    <File Path="MyFirstWorkflowWFAssocForm.aspx" 
    Url="MyFirstWorkflow/WFAssocForm.aspx" />
  </Module>
  <ListInstance FeatureId="{2c63df2b-ceab-42c6-aeff-b3968162d4b1}"
                TemplateType="4501"
                Title="wfsvc"
                Description=
"This list instance is used by SharePoint to keep track of workflows. Do not modify."
                Url="wfsvc"
                RootWebOnly="FALSE" />
</Elements>

<Property Name="StatusColumnCreated" Value="1" />

SharePoint app workflow

When you deploy a workflow definition through a SharePoint app project, Visual Studio 2012 hides all the inner workings from you. The deployment is managed for you, and you simply have to configure a set of properties that determine the behavior of the deployment process. To edit these properties, click the workflow item in Solution Explorer and work through the property grid of Visual Studio 2012 (see Figure 17-25).

Figure 17-25. The property grid of a workflow defined in a SharePoint app in Visual Studio 2012.

As you can see, there are properties for managing all the most common configuration parameters, including description, display name, history list, tasks list, initiation and association form URLs, startup behavior, and target list. For instance, if you want to configure the workflow to start when a target item is added, you can simply change the value of the property Start On Item Added to true. Moreover, if you want to configure the URL of the initiation or association form, you need to choose or provide a value for the Initiation Url and Association Url properties.

Behind the scenes, the editor will configure some XML elements in a file named SharePointProjectItem.spdata, which is placed in the same folder as the XAML file with the source code of the workflow definition.

So far, using Visual Studio 2012, you have designed only sequential workflows. However, you can also use flowcharts and state machines in SharePoint 2013 workflows. From an operational viewpoint, designing a flowchart or a state machine is not that different from creating a sequential workflow. You simply need to delete the Sequence activity, which is provided by default by Visual Studio 2012 within the workflow item template for SharePoint, and replace it with a Flowchart or StateMachine activity. For example, Figure 17-26 illustrates a sample flowchart-based approval workflow for SharePoint 2013 in the workflow designer.

Figure 17-26. The workflow design surface of Visual Studio 2012 for a flowchart workflow.

More interesting than how to design the sequences, flowcharts, or state machines is when to use which kind of model. The answer depends on the functional requirements of your project:

In this chapter, you learned how to create advanced workflows using SharePoint Designer 2013, consuming REST services using the Call HTTP Web Service action and the Dictionary data type. Then you moved on to designing workflows using Visual Studio 2012. You saw how to implement custom workflows targeting an on-premises farm, as well as how to create SharePoint apps that internally use custom workflows. You learned how to create custom workflow forms, custom tasks, and custom task forms. Then you saw how the deployment process of a workflow works. The chapter ended by comparing the various models of workflow definitions available.