Before studying the details of the SharePoint workflow architecture, it is important to understand the basic building blocks of .NET 3.5 workflows and to comprehend what is special about SharePoint workflows.

SharePoint Foundation 2010 workflows are based on the Windows Workflow Foundation 3.5 to offer workflow support within the SharePoint environment. WF provides a programming model, runtime engine, and tools for building and executing workflow-enabled applications. SharePoint uses the Workflow Designer in Visual Studio for custom workflow development and uses the WF runtime engine to host workflows inside SharePoint.

Workflow Hosting Environment

WF allows any process or application to run workflows by hosting the WF runtime engine, which provides standard services required by any workflow solution, such as persistence, state management, tracking, and transactions. SharePoint also hosts the WF runtime engine, but because of the SharePoint-specific behavior such as its data-centric nature and wide support for human interaction, some implementations of standard WF services have been replaced with custom implementations in SharePoint: transactions, persistence, notifications, roles, tracking, and messaging. Figure 16-1 shows the relationships between WF and SharePoint Foundation. You can use SharePoint Designer and Visual Studio to develop workflow templates that are based on special SharePoint Workflow Activities and work with the SharePoint Workflow Object Model. In addition, these workflow templates are based on the Basic Activity Library of WF. SharePoint Workflow Services uses the WF Runtime and WF Runtime Services to provide a custom workflow runtime environment.

Figure 16.1. Workflow architecture in SharePoint Foundation 2010

The custom implementation of workflow services results in a specific behavior for SharePoint workflows that requires special attention. Since workflows in SharePoint usually incorporate substantial user interaction, persistence of workflows is particularly important. To avoid long-running workflows wasting valuable computing resources, workflows waiting for user input are dehydrated. This means that the workflow object is serialized and stored into the SharePoint database. Hence, the workflow is not wasting memory. Whenever an event occurs, such as when a user updates a task, the dehydrated workflow instance will be reactivated and loaded into the memory to continue its work. To find and associate events to workflows, SharePoint uses correlation tokens along with GUIDs. (Refer to the "Custom Workflows with Visual Studio" section for more details on correlation tokens.)

Another important aspect to understand is the way that SharePoint uses transactions to process workflow activities. SharePoint executes a series of workflow activities until a commit point is reached. Changes made in the activities are committed only at the commit point, which is essentially a point where the workflow is serialized to wait for an event to occur. This behavior was chosen to pack all activities into a single batch for increased performance and to allow a rollback if errors occur—but it could result in unexpected behavior. The described batching feature applies only to SharePoint-specific workflow activities, whereas custom code activities will be processed immediately.

Workflow Types

Workflow Foundation supports two different styles of workflow:

• Sequential workflows

• State machine workflows

A sequential workflow contains a series of steps that will be executed in the specified order, from the start of the workflow to the end. The individual steps of the workflow will be executed one after the other. To control the flow within a sequential workflow, events and flow structures such as If-Else, loops, and parallel branches can modify the workflow execution order. Figure 16-2 shows a simple example that was modeled using the Visual Studio 2010 Workflow Designer. You can see the flow of events from the start, represented by the green arrow symbol at the top, down to the end, which is depicted by the red symbol. Depending on the result of the CheckValue shape, either the left or right branch is executed. Sequential workflows are supported by SharePoint Designer workflows as well as by workflows created with Visual Studio.

Figure 16.2. Sequential workflow

A state machine workflow adopts a different approach, because it does not model the flow of activities but instead defines several states that represent the system. It describes the events that transition from one state to another state. Figure 16-3 shows a very simple state machine workflow. You can see the different states represented by rectangles and the arrows denoting transitions from one state to another. SharePoint Designer workflows do not support this workflow type, and thus, state machine workflows can be developed only as custom workflows using Visual Studio.

Figure 16.3. State machine workflow

The life cycle of SharePoint workflows is very specific to SharePoint, because of its focus on content and the way user interaction is handled. Figure 16-4 illustrates the four stages of the SharePoint workflow life cycle. These stages allow for the assignment of workflows to content type, handle the different ways for starting workflows, and keep the workflow infrastructure flexible during execution. This custom life cycle is provided by the SharePoint-specific workflow hosting environment. During some of the following stages, forms can be used to gather additional user input as parameters, which are required for this stage to execute.

Figure 16.4. SharePoint workflow life cycle

Initiation

As soon as a workflow is started—either manually or automatically, depending on its association parameters—it will be initiated. During initiation, a new instance of the workflow is created and assigned to a concrete item, either a list item, a document in a library, or a site. As with the association event shown earlier, workflow developers can add an initiation form to a workflow that will be displayed to the user who triggered the workflow. Parameters entered during initiation can be used to overwrite default parameters or to provide additional information.

Both association and initiation forms can be implemented using either ASP.NET (as an .aspx file) or an InfoPath form. We demonstrate how to integrate InfoPath forms into your workflow solutions later in this chapter. Figure 16-5 shows an example form that is used as both an association and an initiation form, for the approval workflow that ships with SharePoint. (This form is based on InfoPath Forms Services; see Chapter 15.)

Warning

If a workflow is started automatically, such as when a new item is created or when an existing item is updated, the initiation form will not be displayed to the user. You should keep this in mind when creating your own workflows. Thus, initiation forms should be used in combination with workflows that are started manually and therefore will always show the initiation form, or they should contain only optional parameters for a workflow.

Figure 16.5. Example association and initiation form based on InfoPath

This chapter is aimed at developers who want to build their own SharePoint workflows using either SharePoint Designer or Visual Studio. However, SharePoint also provides a small collection of canned out-of-the-box workflows that are shipped with the different versions of SharePoint Foundation and SharePoint Server. Before starting to develop a new workflow from scratch, it is a good idea to examine these workflows first. Even if they do not meet the requirements completely, they might be a head start for development. Since SharePoint 2010, it is possible to edit these out-of-the-box workflows and customize them to meet special requirements. Most of these workflows also offer some additional configuration options through the workflow association form. Table 16-1 lists the available workflows together with the SharePoint version that offers the workflow.

Using some of the out-of-the-box workflows, we demonstrate in the following sections how to use workflows in SharePoint and how to develop your own custom workflows.

To add a workflow to your SharePoint environment and associate it with a list or library, use the Workflow Settings page (shown in Figure 16-7), which is available through the ribbon bar by selecting List Tools

Figure 16.6. List Settings ribbon

To associate a workflow to a content type, navigate to the content type under "Site Settings" and you will also find the "Workflow settings" dialog. (This is analogous to associating a workflow to a site—you find the workflow settings from the Site Settings dialog.)

Figure 16.7. Workflow Settings page

On the Workflow Settings page, shown in Figure 16-7, is a summary of the workflows that are currently associated with your list, including the number of currently running workflow instances for each workflow template. You can add workflows to your list, which means associating the workflow to your current list. When you select "Add a workflow" to associate a workflow template with your current list, you will see a dialog similar to Figure 16-8.

Figure 16.8. Adding a workflow to a list

In the Add a Workflow dialog are some important settings for workflow association:

If an association for the workflow has been specified, this form will be displayed after clicking the Next button. In the case of the Approval workflow in the previous example, the association form as shown in Figure 16-5 will be displayed.

After a workflow is associated with a list, library, content type, or site, it may be necessary to manually start the workflow on a specific item, if this option was selected during association. The workflow overview page allows you to start a new workflow and shows you currently running or already finished workflows for an item. It can be reached in different ways:

The workflow overview page of an item is shown in Figure 16-10. If you have one or more workflows associated, as in the figure, you can start a new workflow instance by simply clicking the workflow. This will set up the workflow, and if an initiation form has been defined, this form will be displayed to the user who started the workflow.

After you have started the workflow, it will appear under Running Workflows. You will not be able to start another instance of this workflow until the running instance has finished. SharePoint allows only one running instance of a workflow template on an item at a time.

Figure 16.9. Selecting workflow overview page on a list item

Figure 16.10. Workflow overview: Manually starting a workflow

SharePoint has many facilities for managing and monitoring running workflows, providing users insight into the current status of their workflows and allowing them to interact with running instances. This information is also helpful to workflow developers. The first place to look for the current status of a workflow is the list or library on which the workflow has been started. Since for each item in the list, a column for each workflow has been added, you can immediately see the status of the workflow in the corresponding column.

From here, or via one of the different ways to access the workflow overview page, you can then reach the workflow overview. If you have running workflow instances for your item, you will see a page similar to the one shown in Figure 16-11.

Figure 16.11. Workflow overview for an item: running instances

It displays again the current workflow status and by clicking the link on either the workflow name or the status, you navigate to the detailed workflow information for this workflow instance. The Workflow Information page (see the example in Figure 16-12) lists basic information about the initiator, the time the workflow was started, the current status, and a link to the item on which the workflow is executed.

Below this is a graphical visualization of the workflow, rendered using Visio Web Access. This diagram not only shows a static representation of the workflow but also mirrors the current state of the workflow. Each activity that has been processed is marked by a special symbol. The green tick symbols in Figure 16-12 indicate that the first "Compare date source" activity and the "Set workflow variable" activity at the bottom have already been processed.

Since Visio 2010 supports shapes for SharePoint 2010 workflows and an import for SharePoint workflows into Visio 2010 has been implemented, this is a great example of converting workflows from SharePoint to Visio 2010. Unfortunately, this feature is available only with SharePoint Server 2010 and not with SharePoint Foundation.

Figure 16.12. Workflow information and Visio visualization

Beneath the workflow visualization, additional information about this workflow is displayed, shown in Figure 16-13. Immediately above the Tasks section are additional commands that can be used to modify the Approval task.

The link "Terminate this workflow now" is displayed in any workflow to users with the required permission. Clicking the link terminates the workflow instance, stopping the workflow in the current state and setting the workflow status to Aborted. This command is useful during workflow development when your workflow errors. Workflows in Error state are incomplete, and you can use this link to terminate your instance, before rerunning the workflow with a new version where your error is fixed. Remember, that you can have only one instance of a workflow running at the same time, so you need to terminate the running instance before you a start a new one.

The Tasks section lists all tasks that have been assigned by this workflow instance. You can see the user assigned to the task, the current status, and the outcome of the tasks. This is a view of the task list that was specified during workflow association that shows all tasks that are related to the current item and the current workflow.

Figure 16.13. Workflow information: tasks and history

Finally, the last section of the workflow information page displays the workflow history list containing all entries for this workflow instance. This list summarizes the different actions that were taken throughout this workflow execution and shows you errors and other audit information that is written to the history. You can add activities to your workflow and write information to this history to share information about workflow progress with users and administrators. This is also a good method to debug your workflow during development.

As already mentioned, user interaction during workflow execution is accomplished using tasks. They can be assigned to a user by the workflow and will integrate seamlessly with any other tasks in SharePoint. You can use, for example, the User Tasks Web Part on your page to display all tasks that are assigned to the current user. This allows you to create intuitive solutions that follow your business processes with very little development effort by leveraging existing components.

To gather additional information from users required for your workflow, you can build task forms to display to the user on task completion. Independent of the tool you are using for workflow development, you can use either standard ASP.NET forms or even InfoPath forms as task forms. This again shows the broad application for InfoPath forms and how well they have been integrated into SharePoint 2010. Figure 16-14 shows a sample InfoPath-based workflow task form, which is used in the out-of-the-box Approval workflow.

Figure 16.14. Workflow task form using InfoPath

Visio 2010 offers process designers the prospect of designing workflows for SharePoint that can be used directly to develop custom workflows in SharePoint Designer. To design a SharePoint workflow, start a new Visio diagram by selecting the Microsoft SharePoint Workflow template in the Flowchart category. From that, you can design your workflow in the familiar Visio interface using the special SharePoint workflow shapes: SharePoint workflow actions and SharePoint workflow conditions. Figure 16-16 shows an example Visio workflow diagram.

Figure 16.16. Designing workflows with Visio 2010

Visio offers the Check Diagram feature in the Process ribbon. This check reports whether your workflow is correctly modeled or if you missed any connections or important shapes. You will also find an option to import and export SharePoint workflows.

SharePoint Designer 2010 allows you to create workflows without writing code, using a declarative workflow description. Usually SharePoint Designer is aimed at designers, information workers, and power users, but since it is now possible to export SharePoint Designer workflows and use them in Visual Studio, SharePoint Designer can also be a useful starting point for developers—especially for prototyping or for simple workflow scenarios. You can even use Visio to design your workflows in cooperation with the business units, import the workflow into the Designer, and later use this workflow to start developing with Visual Studio.

Workflows

After opening a site in SharePoint Designer 2010, you will see all the items of the site in the navigation pane. If you select the Workflows navigation tab, you will see all the workflows that are available to the site. Figure 16-17 shows a sample list of different workflows that are currently available. The workflows are categorized as follows:

• List Workflow: These workflows are developed for a particular list and are directly associated with that list. These workflows cannot be reused for any other list because they have direct access to all the columns of the list and thus are strongly tied to that list. Furthermore, list workflows cannot be saved as a template to be imported into Visual Studio, for the same reasons.

• Site Workflow: Instead of creating a workflow for a list or a library, with SharePoint 2010 you can also create workflows that can be executed on a site. In SharePoint Designer, you will always be working in the context of a site. When you add a site workflow, it will automatically be available only for the site on which you are working. Like list workflows, site workflows cannot be saved as a template for Visual Studio.

• Reusable Workflow: These workflows are not developed for a particular list or library. Instead, they can be associated with any list or library but not to a site. As they are not tied to a list, you can use the option Save as Template to save a reusable workflow to a WSP file, which can be opened in Visual Studio. Because these workflows are independent of lists and content types, you will not have access to any columns other than the base columns inside the workflow. You can use the options Associate to List or Associate to Content Type to associate the workflow from SharePoint Designer, rather than the SharePoint user interface. Reusable workflows, however, are available only to lists within the current site. To make them available to the entire site collection, you can use the option Convert to Globally Reusable.

• Globally Reusable: These workflows are reusable workflows that are available to the entire site collection instead of just the site. Unfortunately, these workflows cannot be saved to a template WSP file.

The ribbon bar of the workflows page contains buttons for creating new workflows and editing existing workflows (see Figure 16-17). In addition, the Manage section allows you to export the selected workflow to a WSP template file and to import and export Visio 2010 workflow diagrams. You can also associate workflows to a list or to a content type.

Figure 16.17. List of workflows in SharePoint Designer 2010

Workflow Settings

Clicking a workflow in the overview will take you to the Workflow Settings page for this workflow, as illustrated in Figure 16-18. This page presents all the relevant settings for a workflow, at a glance. Here you can alter similar settings to those exposed in the SharePoint user interface, such as start options and the workflow name. Using the ribbon or the Edit workflow link in the customization section, you can start editing the workflow. In addition to this, you can manage all the variables that are used by the workflow:

• Initiation Form Parameters: This allows you to specify variables that will be collected during workflow initiation or association. If not already present, SharePoint Designer will create an initiation form for you, which will appear in the Forms section of the Workflow Settings page. You can access these initiation parameters (and association parameters) within your workflow within conditions and actions.

• Local Variables: You can create variables that are available inside the workflow to store information. These variables are accessible throughout the workflow and can be used for conditions and actions. When you add task forms to your workflow, the results can be reached through such variables.

• Association Columns: These allow you to add fields to your list or library, when the workflow is associated with this list or library. Association columns enable you to store workflow-related data in the list. This is especially important for reusable workflows because this ensures that required columns are made available in the list to which the workflow will be associated later. Naturally, this is not available to site workflows.

Figure 16.18. SharePoint Designer 2010: Workflow Settings

The Forms section contains all the forms used by this workflow, including the initiation form and association form, as well as any task forms. These forms are created automatically by SharePoint Designer as soon as the workflow is published. When InfoPath is available to your SharePoint environment, XSN forms will automatically be created. Otherwise, ASPX forms are produced.

Warning

On the Workflow Settings page, the start options for Reusable workflows are different from all other dialogs where you can set the start options. In this section they are negated, which means you have to disable the options you don't want to be available.

Workflow Editor

To create and edit declarative workflows, SharePoint Designer 2010 uses the Workflow Editor page. You can reach this page by clicking Edit Workflow on the ribbon bar, using the link in the Workflow Settings page when editing a workflow, or using one of the buttons for creating a new workflow from various pages in SharePoint Designer. As you see in Figure 16-19, the layout of the workflow editor has been completely redesigned compared to previous versions.

Figure 16.19. Editing a declarative workflow in SharePoint Designer 2010

Workflows are structured using steps that are represented by gray boxes with a heading that can be renamed by clicking the text. You can add actions and conditions to your workflow at any location within a step.

Every action or condition is represented by a sentence that consists of several parameters. These parameters either can be set by the workflow editor to constant values or can be filled from workflow variables or item properties.

We will show how workflow can be designed with SharePoint Designer in more detail in the "Workflows with SharePoint Designer" section.

To leverage the full potential of SharePoint workflows, you can create custom workflows using Visual Studio. Although this allows full control and flexibility over workflows in SharePoint, the approach requires a thorough knowledge of SharePoint development and is solely aimed at professional developers familiar with .NET. Fortunately, Visual Studio 2010 contains project templates for SharePoint workflows and integrates well with SharePoint, which alleviates development complexity.

To get started with developing a custom workflow, create a new project in Visual Studio and select either Sequential Workflow or State Machine Workflow from the SharePoint 2010 templates (as displayed in Figure 16-20). Both templates will result in similar solutions, except for the type of workflow integrated into the project.

Figure 16.20. Creating a workflow project in Visual Studio 2010

Once you have started your project creation, wizards are used to gather basic settings for your project. At first you will be asked to enter a local site for debugging (see Figure 16-21). This SharePoint site is used when you debug your workflow (Microsoft often calls this the "F5 experience," since you are able to debug SharePoint solutions directly from within Visual Studio). In this dialog, the option to deploy as a sandboxed solution is disabled, because custom workflows always need to be deployed as a farm solution.

Figure 16.21. Creating a new workflow project

In the subsequent wizards, you can specify various settings that are used for debugging. These are the same settings as already described in SharePoint user interface in the "Using Workflows in SharePoint" section. They include a workflow name, the workflow template (list or site workflow), the list to which the workflow is associated, the task list and history list, and, finally, the options surrounding when the workflow should be started.

Once the solution is created, you should see a Visual Studio solution similar to Figure 16-22, depending on your Visual Studio configuration. In the central window is the graphical workflow designer, showing the sequential flow (or the states for a state machine workflow). The toolbox on the left side contains all the available shapes that you can drag on the designer surface to model your workflow. The shapes are categorized into the standard Windows Workflow Foundation shapes and the SharePoint-specific shapes. In the Solution Explorer are all the relevant items for a SharePoint solution including your workflow. The project structure created by the template builds a SharePoint solution including a feature that will be deployed to the local SharePoint when you debug or deploy your solution.

(We will show how to develop custom workflows using Visual Studio in detail in the "Custom Workflows with Visual Studio" section.)

Figure 16.22. Developing workflows in Visual Studio 2010

Both tools, SharePoint Designer and Visual Studio, support developing elaborate workflows for the SharePoint environment. Visio 2010, on the other hand, can be used only for designing workflows—to finally create a workflow, you always have to use either SharePoint Designer or Visual Studio. Table 16-2 compares the salient features of these two tools for creating workflows:

To start declaring a workflow, open the Workflows page in SharePoint Designer and select one of the available workflow types from the ribbon bar in the Workflows page. In the ensuing dialog, enter a name for the workflow and a description. The workflow is created, and you are able to start developing your workflow in the Workflow Editor page.

What follows is a description of actions and conditions using an example action. The steps for all actions and condition in the example are similar and can easily be comprehended following the basic description.

Looking at the editor window, you will notice a single, horizontal orange bar, which indicates the current cursor position. You can use the keyboard to control the cursor position and insert actions and conditions from the ribbon, or you can click the position where you want to insert an action and enter a part of the name of the action or condition you want to insert. SharePoint Designer will automatically show you a drop-down list of all available actions and conditions for your search, as shown in Figure 16-23.

Figure 16.23. Selecting an action by entering its name

After you select an action or condition, an entry will be created that describes the action or condition in one sentence. This sentence contains a number of editable parameters. They are underlined and can be edited by a simple click (Figure 16-24).

Figure 16.24. A sentence with editable parameters

When you click a parameter, you will see different options for editing. You can directly enter a static value in the textbox, or you can click one of the buttons next to the text box. Depending on the parameter type, you may see the two buttons shown in Figure 16-25.

Figure 16.25. Editing an action parameter

The left button with the ellipsis symbol (...) opens the String Builder dialog, which can be used to construct dynamic strings. The button with the function symbol opens the Lookup dialog (Figure 16-26), which enables you to lookup a value from one of the following sources:

Figure 16.26. Lookup dialog

Figure 16-27 shows the String Builder dialog, used to create dynamic strings. Within the String Builder you can click the Add or Change Lookup button to invoke the Lookup dialog to insert dynamic values (described earlier). This dialog will be available whenever a string parameter is expected.

Figure 16.27. String Builder in SharePoint Designer

Instead of editing the properties of an activity by clicking the underlined parameters in the activity sentence, you can also select Advanced Properties from the ribbon to edit all the properties of an activity. For some activities, you will find additional parameters within the Properties windows, as shown in Figure 16-28. In this example, you can see that the action Log to History List shows additional parameters, whereas in the sentence shown earlier, you can only specify the text that should be logged.

Figure 16.28. Properties dialog for SharePoint Designer activities

SharePoint Designer offers a huge selection of actions that can be used to model elaborate declarative workflows. These actions are categorized according to their purpose and the items to which they apply. Table 16-3 lists all available actions and gives a short description for each of them.

To control the flow of a workflow, several conditions are available that allow you to include decisions into your workflow based on If-Else statements. You can concatenate conditions using "and" and "or" statements by adding another condition directly underneath the If statement. Furthermore, you can use multiple Else-If branches, each containing conditions to be evaluated. Table 16-4 shows the available conditions in SharePoint Designer 2010.

All available actions and conditions are defined within the following files in the SharePoint folder under TEMPLATE1033Workflow:

To structure your workflow, you can use different workflow steps. Each step can contain any number of actions and conditions. A step is displayed as a box with a gray border and has a name that can be changed. You can use steps to structure your workflow and make it comprehensible to others. Steps can be nested within other steps, offering useful flexibility in organizing your workflows. It is even possible to insert steps within If-Else branches. Actions and conditions can only be added within a step.

A step is implemented as a SequenceActivity in the resulting workflow. This WF activity is a container that executes all child activities in a forward direction until its last activity is finished. Since even the sequential workflow is itself derived from SequenceActivity, there is no difference in the execution of your workflow when adding extra steps. They are merely used for logical structuring.

One step is special in its execution behavior: the Impersonation Step. You can use this step like any other step. The difference is small yet very powerful—the activities inside this step will be executed with the permissions of the workflow author. Usually, every workflow is executed using the privileges of the user who started the workflow. This can be a significant limitation for workflow development, when the action to be executed depends on the user's permissions. The user starting the workflow needs access to the current list the workflow will be started on, but what if the workflow needs to write information into another list, on which the user has no permission to write? This is where the impersonation step can be used to overcome this issue. In previous SharePoint versions, this problem drastically limited the use of SharePoint Designer workflows.

Another option to organize your workflow is the use of parallel blocks. Whenever you want multiple actions to be executed simultaneously, you can employ a parallel block. Within the parallel block, you can specify actions, conditions, and steps that will be executed in parallel.

Tasks in a workflow handle user interaction with the workflow. Whenever you use an action related to a task in your workflow, the workflow execution will be paused until the task is completed by the assigned user. Within SharePoint Foundation, there are three task-related activities available: Assign a Form to a Group, Assign a To-do Item, and Collect Data from a User. For all these task activities, SharePoint Designer will automatically create a task form to display to the users. The information entered by users into the task forms is stored inside the task. The Collect Data from a User activity is especially designed to access this information from the workflow.

When you add this action to your workflow, a wizard is presented that lets you enter a name and description for that task. You can specify custom form fields for the user to fill in, as shown in Figure 16-29. You can define the field name, the data type, and the detailed settings depending on the data type, such as default values and constraints. The fields you enter in this dialog will be added as columns to the task list used by the workflow. When the workflow is published, SharePoint automatically creates a task form for that workflow. This form will be displayed to the user when they edit the task item.

Figure 16.29. Custom Task Wizard

To access the information that was entered by the users, the activity defines an output variable of type TaskId, which stores the list item ID of the task into a workflow variable. Using this ID, you can access the task item in your workflow that was edited by the user and access the fields, which were completed in the task form. To accomplish this, use a lookup within an action, for example Set Workflow Variable, and specify the Task List for your workflow as the data source and the field that was entered through the task form, as shown in Figure 16-30.

Figure 16.30. Lookup results of a custom task

To identify the correct item in the task list, you need to specify the Find the List Item setting properly. Select ID as the field that is used for comparison, and set the value to the workflow property containing the result of the task action (which is "collect" in the previous example). Now the lookup will select the task item that has the ID of the task that was created by the workflow and returns the selected field value.

You can use this procedure to access any list item or item in a library and select the desired field using the Lookup dialog. All you need is the ID of the list item. Of course, you can also specify any other field value combination to select list items.

As mentioned earlier, SharePoint Designer workflows are declarative workflows that are compiled at runtime. These workflows consist of the following files:

You can access these files via the All Files section in the SharePoint Designer navigation and then select Workflows. These files can be saved to a local disk using the Export File button in the ribbon bar.

Before you can implement your custom action using .NET code, you first have to set up your solution. Select the SharePoint 2010 Empty Project template as the basis for a new solution. This project will be used to deploy all the necessary files and configurations to the SharePoint environment. Add another project to the solution by selecting the Workflow Activity Library template from the Workflows category. This template is not specific to SharePoint workflow development and can also be used to develop reusable activities for WF workflows.

The WF project will contain the code for the custom activity and will be compiled into an assembly. Since the assembly needs to be registered in the GAC, you need to supply a strong name key file to sign the assembly. Add references to the following assemblies to your workflow project:

To deploy the solution to SharePoint, add a feature to the empty SharePoint project with its scope set to Web Application. This scope is required, because the feature needs to edit the web.config for the web application. In addition, the assembly that will be created by the workflow project needs to be added to the <SafeControl> section of the web.config file. You can do this by editing the properties of the package in the SharePoint project.

An additional file with the extension .actions needs to be deployed to the folder TEMPLATE/1033/Worfklow below the SharePoint 12 hive. This file is used by SharePoint Designer to gather all the relevant information about the custom action. (There are more details about this file later in this section.) To include the file, add a SharePoint-mapped folder to the SharePoint project, and select the target path for the file. Any subfolders created by Visual Studio can be removed. The .actions file will later be put into this mapped folder, which will cause this file to be deployed to the desired path during deployment.

Figure 16-31 illustrates the solution structure, and you can see all the relevant elements required for a custom action.

Figure 16.31. Solution for creating a Custom SharePoint designer action

To sum up, these are the essential steps for creating a solution:

After the project has been set up, you can begin implementing the custom activity in the Workflow Library project.

In general, the following steps are important for implementing a custom activity class:

First add a new Activity to your project, and switch to the code view of the activity. Listing 16-1 contains the code for the example activity. (A detailed explanation follows, later.)

The namespaces Microsoft.SharePoint and Microsoft.SharePoint.WorkflowActions should be included via suitable using statements to work with the SharePoint object model and to use the workflow context. The class can be implemented as a subclass of System.Workflow.ComponentModel.Activity. The Activity class already defines and handles the required events for interacting with the workflow. You only need to define the properties for your workflow activity and override the Execute method to define your business logic for this activity.

To access properties from the workflow environment, the DependencyProperty object must be used. In the Custom Workflows with Visual Studio section, dependency properties will be described in more detail. The DependencyProperty allows loose coupling between workflow activities and the workflow instances. Workflows store their properties in a dictionary, which can be accessed by the activities via dependency properties. The workflow runtime engine makes these properties available to all activities and manages all dependency properties from the activities within a workflow. To register a DependencyProperty with the workflow, you first have to define a static variable in your class of type DependencyProperty. Then you can call the static Register method on DependencyProperty, providing a name for the property, the type of the property, and the type of the activity class, and assign the result to your variable.

public static DependencyProperty ListIdProperty = DependencyProperty.Register(
                                "ListId", typeof(string), typeof(LookupItem));

Once the dependency property is registered, you can add a property to your class with the name that was registered with the dependency property earlier. This property is defined like any other property, except that instead of storing the value to a local variable, the getter and setter method will use the dependency property to access the value. The GetValue and SetValue methods are inherited from DependencyObject and can be accessed using the base keyword. Both methods require the DependencyProperty as a parameter and will store a new value or retrieve the current value from the dependency property in the workflow instance.

[BrowsableAttribute(true)]
[DesignerSerializationVisibilityAttribute( DesignerSerializationVisibility.Visible)]
[ValidationOption(ValidationOption.Required)]
public string ListId
{
    get
    {
        return (string)base.GetValue(LookupItem.ListIdProperty);
    }
    set
    {
        base.SetValue(LookupItem.ListIdProperty, value);

}
}

The properties exposed as dependency properties can be made available to SharePoint Designer as parameters for the workflow action.

All the properties in the example are built in the same way, though one property requires special attention: __Context. This property holds an object of type WorkflowContext, containing useful information about the context in which the workflow is running. This includes the current item on which the workflow was started and information about the workflow instance such as the WorkflowInstanceId or the StartedDateTime. SharePoint sets several parameters during workflow activation, and some of them are exposed by the SharePoint Designer workflow environment, like __Context. These parameters are automatically set to a certain value and are available to every workflow. You simply specify a property with the correct name and bind it correctly to the workflow using the .actions file. The parameters shown in Table 16-5 are made available.

With the dependency properties implemented, it is time to write the business logic of the Action. Override the Execute method of the Activity class. This method is called by the workflow runtime environment when the activity is executed. Within the Execute method, you can access the properties of the action and create your own business logic. At the end of the Execute method, you need to return the appropriate ActivityExecutionStatus. This status can take several values throughout the life cycle of an activity. For the Execute method in custom SharePoint Designer actions, the status Closed should be used. It indicates that the activity has finished as expected.

using System;
using System.ComponentModel;
using System.Workflow.ComponentModel;
using System.Workflow.ComponentModel.Compiler;
using Microsoft.SharePoint;
using Microsoft.SharePoint.WorkflowActions;

namespace Apress.SP2010.Workflows.SPDActivities
{

    public partial class LookupItem : Activity
    {
        public LookupItem()
        {
            InitializeComponent();
        }

        // Bind Dependency Properties
        public static DependencyProperty __ContextProperty =
                DependencyProperty.Register("__Context",
                typeof(WorkflowContext), typeof(LookupItem));
        public static DependencyProperty ListIdProperty =
                DependencyProperty.Register("ListId", typeof(string),
                typeof(LookupItem));
        private static DependencyProperty SearchQueryProperty =
                DependencyProperty .Register("SearchQuery", typeof(string),
                typeof(LookupItem));
        public static DependencyProperty ResultItemIdProperty =
                DependencyProperty.Register("ResultItemId", typeof(int),
                typeof(LookupItem));

       [BrowsableAttribute(true)]
       [DesignerSerializationVisibilityAttribute(
                                      DesignerSerializationVisibility.Visible)]
       [ValidationOption(ValidationOption.Required)]
       public string ListId
       {
           get
           {
               return (string)base.GetValue(LookupItem.ListIdProperty);
           }
           set
           {
               base.SetValue(LookupItem. ListIdProperty, value);
           }
       }

       [BrowsableAttribute(true)]
       [DesignerSerializationVisibilityAttribute(
                                      DesignerSerializationVisibility.Visible)]
       [ValidationOption(ValidationOption.Required)]
       public string SearchQuery
       {
           get
           {
               return (string)base.GetValue(LookupItem.SearchQueryProperty);
           }
           set
           {
               base.SetValue(LookupItem.SearchQueryProperty, value);
           }
       }

[BrowsableAttribute(true)]
       [DesignerSerializationVisibilityAttribute(
                                      DesignerSerializationVisibility.Visible)]
       [ValidationOption(ValidationOption.Required)]
       public int ResultItemId
       {
           get
           {
               return (int)base.GetValue(LookupItem.ResultItemIdProperty);
           }
           set
           {
               base.SetValue(LookupItem.ResultItemIdProperty, value);
           }
       }


       [ValidationOption(ValidationOption.Required)]
       public WorkflowContext __Context
       {
           get
           {
               return (WorkflowContext)base.GetValue(
                                               LookupItem.__ContextProperty);
           }
           set
           {
               base.SetValue(LookupItem.__ContextProperty, value);
           }
       }


        // Override the Execute method of the Activity
        protected override ActivityExecutionStatus Execute(
                                     ActivityExecutionContext executionContext)
        {
            // Retrieve the listGuid using a Helper class in the WorkflowActions
            // namespace
            Guid listGuid = Helper.GetListGuid(this.__Context, this.ListId);
            if ((this.__Context != null))
            {
                SPWeb web = this.__Context.Web;
                if (null != web)
                {
                    SPList list = web.Lists[listGuid];
                    SPQuery query = new SPQuery();
                    query.Query = this.SearchQuery;
                    SPListItemCollection items = list.GetItems(query);
                    if (items.Count > 0)
                    {
                        ResultItemId = items[0].ID;
                    }
                }

}
            return ActivityExecutionStatus.Closed;
        }
    }
}

In the example in Listing 16-1, the Execute method runs a CAML query on the list to be searched. The ListId property is used to get access to the list that is selected in SharePoint Designer from the available lists. The __Context property provides access to the current web object. After the CAML query is processed, the first record of the query response is used to assign the ResultItemId parameter.

After the class has been implemented, there are further things to do in order to use the new Action in SharePoint Designer. You need to inform SharePoint about the new action and link the parameters in SharePoint Designer to the properties in the Activity class.

Workflow activities are defined in a special XML file, with the file extension of .ACTIONS. We mentioned previously the WSS.ACTIONS and MOSS.ACTIONS files in the SharePoint subfolder 14TEMPLATE1033Workflow, which describe the available actions and conditions for SharePoint Designer in SharePoint Foundation and SharePoint Server. SharePoint Designer parses this folder and reads all the files with the .ACTIONS extension to gather the available actions and conditions for the workflow designer.

Additional actions can be exposed to SharePoint Designer either by adding the relevant information into one of the existing files or by inserting your own .ACTIONS file to the folder. However, it is best practice to add a separate .ACTIONS file to the folder to avoid changes to the standard SharePoint functionality and to keep the system maintainable.

Listing 16-2 shows an example of an .ACTIONS file. The root element is defined as <WorkflowInfo>, which can enclose <Actions> and <Conditions> elements (along with some rather specific elements, which are used in the WSS.ACTIONS file). The two attributes, Sequential and Parallel, of the <Actions> element define the word that will precede the sentence whenever the custom action is placed in a parallel or sequential step. To add a custom action, an <Action> element needs to be inserted inside the <Actions> element.

The <Action> element requires the Name of the action, the full name of the Assembly, and the ClassName of the custom activity. Further, a Category can be specified that defines under which category in the Action ribbon this action will be listed. If a new name is supplied, a new category will be added.

<?xml version="1.0" encoding="utf-8" ?>
<WorkflowInfo>
  <Actions Sequential="then" Parallel="and">
    <Action Name="Lookup Item By Title"
      ClassName=" Apress.SP2010.Workflows.SPDActivities.LookupItem"
      Assembly="SPDActivities, Version=1.0.0.0, Culture=neutral,
                PublicKeyToken=07ca925dce31cf11"
      AppliesTo="all"
      Category="List Actions">
      <RuleDesigner Sentence="Find item in %1 with Query %2 (Output to %3)">
        <FieldBind Field="ListId" Text="this list" Id="1"
                   DesignerType="ListNames" />
        <FieldBind Field="SearchQuery" Text="CAML" Id="2"
                   DesignerType="StringBuilder" />

<FieldBind Field="ResultItemId"
                   DesignerType="ParameterNames" Text="result" Id="3"/>
      </RuleDesigner>
      <Parameters>
        <Parameter Name="__Context"
                   Type="Microsoft.SharePoint.WorkflowActions.WorkflowContext"
                   Direction="In" DesignerType="Hide" />
        <Parameter Name="ListId"
                   Type="System.String, mscorlib"
                   Direction="In"
                   Description="Canonical form of the list GUID
                                used by this action." />
        <Parameter Name="SearchQuery" Type="System.String, mscorlib"
                   Direction="In"
                   Description="Used to search for an item using CAML." />
        <Parameter Name="ResultItemId"
                   Type="System.Int32, mscorlib"
                   Direction="Out"
                   Description="ID of first item matching the search." />
      </Parameters>
    </Action>
  </Actions>
</WorkflowInfo>

The <RuleDesigner> element contains information necessary to render the declarative sentence that is used to describe and configure the action in SharePoint Designer. The mandatory attribute Sentence holds the text that is displayed in the workflow editor within the workflow declaration. This string can contain any number of dynamic variables, which are denoted with %1, %2, and so forth. They behave similarly to the dynamic placeholders you use with String.Format. Figure 16-32 displays the sentence that is created according to the specification in the previously shown .ACTIONS file.

Figure 16.32. Sentence in workflow editor for the example activity

To substitute the placeholders with dynamic values during workflow runtime, the element <RuleDesigner> can hold any number of <FieldBind> elements as children. Each <FieldBind> element describes one of the variables that were defined in the Sentence of the RuleDesigner. They are associated using the Id attribute of <FieldBind>, which is connected to the corresponding variable in the Sentence. For example, the FieldBind element with Id="1" is bound to the variable %1 in the Sentence.

The <FieldBind> element also requires the attribute Text to be set. This is the text that is displayed as a link in the sentence within workflow designer. More importantly, the Field attribute references a <Parameter> element, which defines input and output parameters to the custom activity.

Another important attribute of the <FieldBind> element is DesignerType. This defines the control that will be presented to the user in the workflow editor of SharePoint Designer. Table 16-6 lists the different designer types that are available and gives a short description of each. If no DesignerType attribute is provided, a text box will be displayed by default.

To connect fields that are configured in the workflow editor and are populated with concrete values during workflow execution to the Activity class, <Parameter> elements are used. They are defined in the <Parameters> container following the <RuleDesigner> element. Each <Parameter> describes a parameter for the rule sentence and references a DependencyProperty that is defined in the Activity class. The Name attribute specifies the name of the dependency property and must exactly match to the name that was used in the Register method in the code. The Type attribute defines the data type of that parameter and the Description can be used to further describe the parameter.

The attribute Direction indicates whether a parameter is used as an input or output parameter for the activity class. Specifying Direction="In" will cause the runtime to set the value for the corresponding DependencyProperty. Conversely, Direction="Out" will return the value to the workflow runtime after the activity has completed.

Configuring custom activities for the workflow editor in SharePoint Designer involves the following actions:

After the solution has been set up, the custom action has been implemented, and declarations for the workflow editor have been made, there is only one outstanding task: allow the assembly to be used as a custom activity in SharePoint. Because of security constraints, only custom activities with permission to be called as custom activities can be used. To allow your custom activity to be used in SharePoint Designer, you need to add an entry to the web.config file of your web application.

In the web.config file, the element <authorizedTypes> specified by the XPath expression configuration/System.Workflow.ComponentModel.WorkflowCompiler contains a list of <authorizedType> elements. Each defines one type, together with an assembly, that is allowed to be used in workflows. Besides the Assembly, the Namespace and the TypeName must also be supplied. Either the TypeName contains a class name or it can be set to * to authorize all classes within the namespace.

To make the required changes to the configuration, use a feature that is set to the web application scope. Within the SPFeatureReceiver event, these changes can be made during feature activation via the FeatureActivated event. Listing 16-3 shows how these changes can be made to the web.config file for the web application. The SPFeatureReceiver will add this string to the configuration:

<authorizedType Assembly="SPDActivities, Version=1.0.0.0, Culture=neutral, PublicKeyToken=07ca925dce31cf11" Namespace="SPDActivities" TypeName="*" Authorized="True" />

[Guid("e72495ca-9fdf-4d9b-8bf4-99df050b577d")]
public class ApressSPDActions_FeatureEventReceiver : SPFeatureReceiver
{
    public override void FeatureActivated(SPFeatureReceiverProperties properties)
    {
        // Get current web application.
        SPWebApplication wappCurrent = (SPWebApplication)properties.Feature.Parent;

        // Create a configuration object and set the parameters as required.
        SPWebConfigModification modAuthorizedType = new SPWebConfigModification();
        modAuthorizedType.Name = "AuthType";
        modAuthorizedType.Owner = "SPDActivities";
        modAuthorizedType.Path = "configuration/System.Workflow.ComponentModel.
                                  WorkflowCompiler/authorizedTypes";
        modAuthorizedType.Type = SPWebConfigModification.
                                 SPWebConfigModificationType.EnsureChildNode;
        modAuthorizedType.Value = "<authorizedType Assembly="SPDActivities, " +
        "Version=1.0.0.0, Culture=neutral, PublicKeyToken=07ca925dce31cf11" " +
        "Namespace="SPDActivities" TypeName="*" Authorized="True" />";

        // Perform the modification to the web.config file.
        wappCurrent.WebConfigModifications.Add(modAuthorizedType);
        wappCurrent.WebService.ApplyWebConfigModifications();
    }
}

Workflows are constructed from different activities. All those activities share a common base class: System.Workflow.ComponentModel.Activity. The Activity class is a subclass of DependencyObject, which is an abstract base class for all objects that use DependencyProperties. Figure 16-33 shows many of the basic activities in the workflow namespace and their relationships.

Figure 16.33. Basic activities in WF

An Activity defines properties for storing information about the runtime environment, such as the WorkflowInstanceId. In addition, an Activity defines methods that will be called by the runtime environment and that can be overridden in a derived class to provide custom behavior for an Activity. They are as follows:

These methods return the ActivityExecutionStatus indicating the current state of the activity in the workflow instance. It can take any of the following values—this list illustrates the life cycle of an activity:

Activities can also be enhanced with additional components that define a specific behavior component. This can be a validator, a serializer, a code generator, or a designer. Such components are attached to an activity using attributes. For example, you can add a custom designer for an activity by implementing a custom class that inherits from System.Workflow.ComponentModel.Design.ActivityDesigner. You can attach this designer to an activity via the following attribute:

[System.ComponentModel.Designer(typeof(MyCustomDesigner), typeof(System.ComponentModel.Design.IDesigner))]
Public partial class MyActivity : Activity
{
}

Both namespaces, System.Workflow.ComponentModel and especially System.Workflow.Activities, define a number of different activities offering common workflow behavior. These activities can be used by any workflow, including, of course, by SharePoint workflows. Table 16-8 lists all the activities that are available through the toolbox in the WF 3.0 and WF 3.5 sections, respectively.

This list of activities should summarize the capabilities and the application of each of the activities. If you need more detailed information on any of these activities, please refer to the MSDN online documentation.

Dependency properties were mentioned earlier regarding SharePoint Designer workflows. We touched on using a DependencyProperty to share properties among different activities. To reiterate, dependency properties allow loose coupling of properties in a workflow, because the other properties do not need to know about the concrete object and can instead get the required properties from the workflow runtime. These properties are stored in a dictionary that is maintained by the workflow, and the propagation of the value of a DependencyProperty is managed by the workflow.

When an Activity is developed, properties can be exposed to the workflow using a DependencyProperty. But how can they be consumed and used by another Activity? The answer is simply by accessing the property of the activity like any other property. But there is more to it. You can use the ActivityBind class to bind the property of one activity to the property of another activity. Since even the workflow itself is derived from Activity, this concept can be used throughout the workflow. ActivityBind creates a connection between two properties using the Name and Path members. The Name specifies the activity, and the Path represents the member to bind to. The following snippet shows an example of how to bind the property sourceProperty of the activity SourceActivity to MyActivityProperty in myActivity:

using System.Workflow.ComponentModel;

ActivityBind activitybind1 = new ActivityBind();
activitybind1.Name = "SourceActivity";
activitybind1.Path = "sourceProperty";
// Call the SetBinding method on the object and pass the static DependencyProperty
// of the class as first parameter.
this.myActivity.SetBinding(MyActivity.MyActivityProperty, activitybind1);

This means that at runtime MyActivityProperty gets its value from the SourceActivity.sourceProperty. The SetBinding method that is used to apply the binding is inherited from System.Workflow.ComponentModel.DependencyObject, which is a base class for all activity objects.

Activity binding becomes particularly interesting, since it can be configured using a dialog in Visual Studio to apply bindings. When a DependencyProperty is shown in the properties of an activity, you can select the ellipsis button (...), and the dialog for activity binding is displayed, as shown in Figure 16-34. Simply select the property of your class to bind the property of the existing activity to your property.

Figure 16.34. Activity binding dialog

One of the important concepts in workflow development is the concept of correlation tokens. Improper use of correlation tokens can result in unpredictable workflow behavior and a great deal of effort to find the origin of such problems.

Because of the loose coupling in the WF infrastructure, a mapping is required between items within a concrete workflow instance and the hosting environment. The workflow runtime environment offers communication capabilities that allow communication between workflow instances and external systems (such as SharePoint). To ensure the communication is addressed to the correct workflow instance and to the correct item within the instance, correlation tokens are used as an identifier.

Consider a correlation token as a meta-variable that defines a common variable across the workflow, such as a specific task that can be used by several activities, for example CreateTask, EditTask, or FinishTask. When multiple activities are working with the same task, they all need the same correlation token. Usually one token is required for the workflow itself and one token for each task that is used inside the workflow.

Correlation tokens can be set in the properties window of an activity, as shown in Figure 16-35. You can either specify an existing token or define a new correlation token.

Figure 16.35. Setting a correlation token

The OwnerActivityName defines the activity that owns the correlation token. This is especially important within composite activities, such as a sequence within a while loop. In this situation, you need to specify the sequence as the OwnerActivityName to ensure that for each new sequence a new correlation token will be created on each loop.

The SPWorkflow object is one of the central objects in the SharePoint.Workflow namespace. It represents a workflow instance that is currently running or has already finished running on an item. SPWorkflow has many properties containing detailed information about the workflow instance, including the current state, associated objects such as tasks and lists, and information about users involved in that particular workflow.

Since SPWorkflow represents actual workflow instances, you cannot create new object instances. You always need to provide the workflow instance ID, which will create a SPWorkflow object for this existing instance. You can get SPWorkflow objects as a result of querying an SPListItem for its workflows or by using the SPWorkflowManager to start or cancel workflows.

The following listing retrieves all the workflow instances of an SPListItem and illustrates some of the more significant properties for each workflow:

foreach (SPWorkflow wf in listItem.Workflows)
{
    // the ID of the WorkflowAssocation
    GUID associationId = wf.AssociationId;

    // State of the workflow
    SPWorkflowState state = wf.InternalState;

    // Lists for History and Tasks
    SPList historyList = wf. HistoryList;
    SPList taskList = wf.TaskList;

    // All tasks that belong to this instance
    SPWorkflowTaskCollection tasks = wf.Tasks;

    // The name of the SPListItem on which the workflow was created
    String itemName = wf.ItemName;
}

The SPWorkflowTemplate represents a workflow template that is deployed to a SharePoint site. It contains several members that return information about the template, such as the AssociationUrl and the InitiationUrl, which return the URLs of the forms that will be used for association and initiation, respectively. Furthermore, you can set various parameters affecting the start behavior of workflows based on this template. You can use the SPWorkflowTemplate and associate it with a SharePoint list or site. The following code selects one specific template from the template collection for a site:

// web is the instance of the current SPWeb object
SPWorkflowTemplate template = web.WorkflowTemplates[new GUID("workflowGUID")];

The SPWorkflowAssociation class represents the association of a workflow template with a list, content type, or site. Members of this class contain information about the associated template. You can use the BaseTemplate to get the associated template, the HistoryListId, or the TaskListId for the association. The properties AllowManual, AutoStartChange, and AutoStartCreate control the starting options for the workflow. These properties are exposed for workflow associations via the web interface, described earlier in this chapter. The following snippet selects a collection of SPWorkflowAssociation objects for a list and interrogates several interesting properties:

SPWorkflowAssociationCollection associationCollection =
                       parentList.WorkflowAssociations;
foreach (SPWorkflowAssociation association in associationCollection)
{
    // The template on which the association is based
    SPWorkflowTemplate template = association.BaseTemplate;

    // The number of currently running workflow instances that are based on this
    // association
    int runningInstances = association.RunningInstances;

    // The data that was entered during assoication in the association form
    string associationData = association.AssociationData;

    // Whether the workflow is based on declarative description - as a result of
    // SharePoint Designer - or a compiled assembly - the result of Visual Studio.
    bool isDeclarative = association.IsDeclarative;
}

To associate a workflow template to a list, content type, or site, you need to create an association object first and then add this object to the list, content type, or site. The creation of a new SPWorkflowAssociation object is handled by the following static methods of the class:

The following snippet shows how you can add a workflow association to an SPList by creating a new SPWorkflowAssociation and adding it to the SPWorkflowAssociationCollection of the SPList:

SPWorkflowTemplate template = web.WorkflowTemplates[new GUID("workflowGUID")];
SPList historyList = web.Lists["HistoryList"];
SPList taskList = web.Lists["TaskList"];
SPWorkflowAssociation association = SPWorkflowAssociation.CreateListAssociation(
    template, template.Name, taskList, historyList);
// Set the start option for the association
association.AllowManual = true;
association.AutoStartChange = false;
association.AutoStartCreate = true;

// Add the association to the list of WorkflowAssociation in the SPList
myList.WorkflowAssociations.Add(assocation);

The SPWorkflowManager class is used to control workflow templates and instances. It exposes several members that administer workflow instances across a site collection. You can start or cancel workflows and perform further administrative operations on workflows.

To start a workflow, use the StartWorkflow method—it creates a new workflow instance and starts it. It requires an SPWorkflowAssociation object, a string with event parameters, and either an SPListItem or an Object representing the object on which the workflow should run. Since workflows can be attached to sites, the overloaded method that takes an Object as a parameter has been added to be able to attach workflows to sites as well as to list items.

// Create SPSite and SPWeb objects
SPSite site = new SPSite("http://server/site");
SPWeb web = site.RootWeb;

// Get SPList and SPListItem
SPList list = web.Lists[0];
SPListItem listItem = list.Items[0];

// Get the workflow association
SPWorkflowAssociation association = list.WorkflowAssociations[0];

// Get the SPWorkflowManager from the site
SPWorkflowManager manager = site.WorkflowManager;

// Start the workflow on the ListItem
manager.StartWorkflow(listItem, association, association.AssociationData);

You can also use the SPWorkflowManager to access several workflow objects for an SPListItem, such as GetWorkflowTasks, GetItemActiveWorkflows, or GetItemWorkflows.

As mentioned earlier, workflows in SharePoint use tasks for user interaction. Task lists in SharePoint contain all the tasks that need to be completed by users. Those tasks are well integrated into SharePoint. You can use Web Parts to display all the open tasks to the current user or filter the task list to only display all tasks for the current user.

SPWorkflowTask is a special type of SPListItem that is used in task lists, since it is derived from SPListItem. In addition to the members that are inherited from SPListItem, SPWorkflowTask has a property WorkflowId for the GUID of the workflow instance to which the task is assigned. You can use the following snippet to obtain the workflow instance from a task:

GUID workflowId = task.WorkflowId;
SPWorkflow workflow = new SPWorkflow(web, workflowId);

The SPWorkflowModification class represents a workflow modification. When workflow modification occurs, the modification form is displayed to the user, and the workflow is modified accordingly. The SPWorkflowModification holds the ContextData, which is a string representation of the data that the user submitted with the modification form. Another useful property is the TypeId. This is the ID of the workflow template on which the modification is based.

You can use the SPWorkflowManager to execute the workflow modification by calling the ModifyWorkflow method, as shown in the following snippet:

SPSite site = new SPSite("http://server/site");
SPWeb web = site.RootWeb;
SPList list = web.Lists[0];
SPListItem listItem = list.Items[0];

SPWorkflow workflow = listItem.Workflows[0];
SPWorkflowModification wfModification = workflow.Modifications[0];
String contextString = "<contextData><Value>test</Value></contextData>";
Site.WorkflowManager.ModifyWorkflow(workflow, wfModification, contextString);

This code is usually added to the ASPX modification form. The contextString is exposed to the workflow in the ContextData.

The SPWorkflowEventReceiver class handles workflow events throughout the lifetime of a workflow.

You can register the SPWorkflowEventReceiver with any site, list, or content type.

In SharePoint 2010, external data sources can be tightly integrated with SharePoint and used like any other SharePoint resource. It is even possible to execute workflows on these data sources, since they appear like a regular SharePoint list. Because list elements of external data source cannot be guaranteed to have an identifier of type Integer, like the Id of a list item in SharePoint, the SPItemKey was introduced. It encapsulates the identification of a list item and therefore contains an Integer value Id for internal lists and a string identifier called Key for external lists. Depending on the concrete list instance, it will offer the correct identification. Some of the activities for SharePoint Designer have been rewritten to support this new type.

Before starting to develop your workflow, you should always construct a detailed model for your workflow and describe what your workflow will do. This involves identifying the stakeholders involved in your business process, the flow of data, and the flow of activities. You can, of course, use Visio 2010 and its SharePoint workflow shapes to model the workflow or any other suitable graphical representation. More important than the tool you use is that you consider everything that is involved in your workflow before you start programming. Otherwise, you might encounter problems during development that necessitate changing the entire process and consequently losing a lot of time.

To demonstrate how to develop a workflow with Visual Studio 2010, the following simple scenario is used. Imagine a technical department for product development. Within this department different types of projects are initiated. To allow employees to request a new project and to view a summary of all the projects in the department, a project list should be introduced. Furthermore, a workflow is needed to handle the estimation and approval of new projects. Figure 16-37 shows a graphical representation of this workflow.

Figure 16.37. Example workflow for creating new projects in a department

Users can add new entries to the projects lists using the list edit form. After the project has been saved, the workflow will start automatically, and a task will be assigned to an estimation manager. The estimation manager has to decide whether to accept the new project and estimate the project costs. Depending on the outcome, an entry will be written to the history list.

To achieve this solution, the following items need to be developed:

To start developing the workflow, create a new project in Visual Studio 2010 using the SharePoint 2010 Sequential Workflow project template. Specify your workflow name, and select a List workflow in the resultant wizard. Further, specify the debugging options and the settings for starting the workflow in the development environment in the subsequent steps of the wizard.

Once the project is created, you should see an empty project, like the one shown in Figure 16-38. The template automatically creates a feature and a solution package to deploy the workflow. Under the workflow node in the Solution Explorer is an Elements.xml manifest file, together with the workflow file. (The feature and manifest, which are required to deploy the workflow, will be described in more detail in the "Developing the Workflow" section.)

When you select the workflow code file, the Visual Studio Workflow Designer opens and shows a basic workflow that consists of one activity, called onWorkflowActivated. This activity is required as the first activity in every workflow. It initializes the correlation token for the workflow and binds the WorkflowProperties to make them available throughout the workflow.

Figure 16.38. New Sequential Workflow project

You can start to develop your workflow by dragging activities from the toolbox—displayed on the left side in Figure 16-38—onto the Workflow Designer surface. Every workflow activity has a set of properties that can be managed in the Properties dialog. Assign values to the properties or use activity binding to bind them to properties within your code. You can access the code that is called through event handlers by double-clicking an activity, or you can edit the entire workflow code by selecting View Code from the context menu on the workflow file in the Solution Explorer.

The toolbox contains all the available activities for creating a SharePoint workflow. In addition to the basic WF activities described earlier, you can also choose the SharePoint-specific workflow activities. The different toolbox entries are separated into different categories according to their origin. Table 16-9 lists the available activities for the SharePoint Workflow category and gives a short description for each.

As you lay out the flow of activities on the design surface, whenever important settings for an activity are missing, the designer indicates this with a red exclamation mark in the upper-right corner of the shape or in the Properties window at the affected property. For example, if you place a CreateTask activity after the onWorkflowActivated activity, you are notified that the correlation token needs to be specified.

To implement the example workflow, drag the following activities to the design surface resulting in the sequential workflow, as shown in Figure 16-39 (the names of the activities have already been changed to reflect the flow of activities):

Figure 16.39. Layout of the example workflow

After the workflow flow is completed, you need to set the properties for the previous activities. To accomplish this, either you can define the required properties in the workflow code and bind them using the Properties window or you can select "Bind to a new member" from the binding dialog. In this case, enter a name for the new member, and select the option Create Field to have Visual Studio create and bind the member for you.

Specify the following properties for the activities in the workflow:

After the properties for the activities have been bound, further programming is needed to achieve the desired workflow behavior. Listing 16-4 shows the complete workflow code for the example. As you can see, the ProjectApproval class is derived from SequentialWorkflowActivity, which manages the execution of its child activities and is used for sequential workflows. The class contains all the members that were defined automatically when the properties of the different activities were bound to new members.

Furthermore, various methods for the activities are created when you double-click the activity shapes in the workflow designer. You can write code to be executed by the activity.

The method estimationTask_MethodInvoking is called when a new task is created. At first, a new Guid is assigned to the estimationTask_TaskId, which has been bound to the TaskId of the activity. Additional properties for the task are set, including the name of the user the task is AssignedTo and the Title of the task. The title is assembled using the workflowProperties and gets the title of the item on which the workflow is running.

The method taskNotFinished is used as a Code Condition for the WhileActivity. It assigns false to the ConditionalEventArgs that are passed as a parameter to the method, as long as the task has not been finished appropriately. The variable isTaskComplete is set to true in the method onTaskChanged1_Invoked as soon as the task is finished.

Finally, the onTaskChanged1_Invoked method saves two task properties that have been set in the task form into local variables. You can use the afterProperties to access all the properties of the task. Special properties that are not part of the task ContentType are stored by the task form in a HashTable called ExtendedProperties. Use a String key, such as _EstimatedCosts and _Outcome in the example code, to access the corresponding stored values.

using System;
using System.Workflow.Activities;
using Microsoft.SharePoint.Workflow;

namespace ProjectApproval
{
    public sealed partial class ProjectApproval : SequentialWorkflowActivity
    {
        public ProjectApproval()
        {
            InitializeComponent();
        }

        public Guid workflowId = default(System.Guid);
        public SPWorkflowActivationProperties workflowProperties = new
                                              SPWorkflowActivationProperties();
        public SPWorkflowTaskProperties estimationTaskProperties = new
                                                    SPWorkflowTaskProperties();
        public Guid estimationTask_TaskId = default(System.Guid);
        public SPWorkflowTaskProperties estimationTask_BeforeProperties = new
                                                    SPWorkflowTaskProperties();
        public SPWorkflowTaskProperties estimationTask_AfterProperties = new
                                                    SPWorkflowTaskProperties();
        bool isTaskComplete = false;

        public string costs = default(System.String);
        public string outcome = default(System.String);

        private void onWorkflowActivated1_Invoked(object sender,
                                                       ExternalDataEventArgs e)
        {
            workflowId = workflowProperties.WorkflowId;
        }

        private void estimationTask_MethodInvoking(object sender, EventArgs e)
        {
            estimationTask_TaskId = Guid.NewGuid();
            estimationTaskProperties.AssignedTo = "wapps\administrator";
            estimationTaskProperties.Title = "Approve_" +
                                                 workflowProperties.Item.Title;
        }

        private void taskNotFinished(object sender, ConditionalEventArgs e)
        {
            e.Result = !isTaskComplete;

        }

        private void onTaskChanged1_Invoked(object sender, ExternalDataEventArgs e)
        {
            isTaskComplete = true;
            costs = estimationTask_AfterProperties.ExtendedProperties
                                                ["_EstimatedCosts"].ToString();
            outcome = estimationTask_AfterProperties.ExtendedProperties
                                                       ["_Outcome"].ToString();
        }
    }
}

As with any other SharePoint artifact, a workflow is deployed to SharePoint via a feature. The feature definition for a workflow is relatively straightforward, as you can see in Listing 16-5. Apart from the Title, Description, Id, and Scope attributes, the main aspect of the feature is the manifest file in the ElementManifest element.

<?xml version="1.0" encoding="utf-8"?>
<Feature xmlns="http://schemas.microsoft.com/sharepoint/"
    Title=" ProjectApproval Workflow"
    Description="Feature for ProjectApproval Workflow "
    Id="44f1409b-8578-4657-8810-bcf06aba7dfa"
    Scope="Site">
    <Properties>
        <Property Key="GloballyAvailable" Value="true" />
    </Properties>
    <ElementManifests>
        <ElementManifest Location="ProjectApprovalElements.xml" />
    </ElementManifests>
</Feature>

The manifest file describes a workflow, within a <Workflow> element, as shown in Listing 16-6. The Name, Description, and Id are similar to elements in a feature. CodeBesideClass and CodeBesideAssembly reference the workflow class that implements the workflow, which is ProjectApproval in our example.

To specify custom ASPX pages for association, initiation, modification, or task forms, use the following attributes of the <Workflow> element:

To stipulate the kind of SharePoint item to which the workflow will be assigned, enter a value (List, Site, or ContentType) for the element <AssociationCategories>.

<?xml version="1.0" encoding="utf-8" ?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
    <Workflow
        Name="ProjectApprovalWorkflow"
        Description="My SharePoint Workflow"
        Id="5d2fd6e5-996a-43c9-b8c1-5b1a27e9af33"
        CodeBesideClass="ProjectApproval.ProjectApproval"
        CodeBesideAssembly="$assemblyname$"
        AssociationUrl="_layouts/ProjectApprovalForms/
                                         ProjectApprovalAssociationForm.aspx"
        InstantiationUrl="..."
        ModificationUrl="..."
        TaskListContentTypeId="..."
     >
    <Categories/>
    <MetaData>
        <AssociationCategories>List</AssociationCategories>
        <StatusPageUrl>_layouts/WrkStat.aspx</StatusPageUrl>
    </MetaData>
  </Workflow>
</Elements>

After you deployed your workflow together with the missing forms, described next, you can test your workflow.

SharePoint uses either ASPX or InfoPath forms for user interaction in a workflow. However, in SharePoint Foundation, only ASPX forms are available. You can use APSX forms for association, initiation, and modification of a workflow. In addition, you can indicate custom task forms to be used to edit a task and thus collect additional information from users.

<asp:Content ID="Main" ContentPlaceHolderID="PlaceHolderMain" runat="server">
    <br />

    Approver: <asp:TextBox runat="server" ID="EstimationManager"></asp:TextBox>
    <br />
    <br />
    <asp:Button ID="AssociateWorkflow" runat="server"
                 OnClick="AssociateWorkflow_Click" Text="Associate Workflow" />
        &nbsp;
    <asp:Button ID="Cancel" runat="server" Text="Cancel" OnClick="Cancel_Click" />
</asp:Content>

using System;
using System.Globalization;
using System.Web;
using System.Web.UI;
using Microsoft.SharePoint;
using Microsoft.SharePoint.Utilities;
using Microsoft.SharePoint.WebControls;
using Microsoft.SharePoint.Workflow;
using System.Xml;
using System.IO;
using System.Text;

namespace EstimationTaskContentType.Layouts.ProjectApprovalForms
{
    public partial class ProjectApprovalAssociationForm : LayoutsPageBase
    {
        private const int CreateListTryCount = 100;
        private string historyListDescription = "Custom History List";
        private string taskListDescription = "Custom Task List";
        private string listCreationFailed = "Failed to create list {0} as a
                                           list with same name already exists";
        private string workflowAssociationFailed = "Error occured while
                                           associating Workflow template. {0}";

        protected void Page_Load(object sender, EventArgs e)

{
            InitializeParams();
        }

        // This method is called during form load and is used to populate form
        // fields with existing values when an existing association is edited.
        private void PopulateFormFields(SPWorkflowAssociation existingAssociation)
        {
            string data = existingAssociation.AssociationData;
            if (!string.IsNullOrEmpty(data))
            {
                XmlDocument doc = new XmlDocument();
                doc.LoadXml(data);
                XmlNamespaceManager nsmgr = new XmlNamespaceManager(
                                                                doc.NameTable);
                nsmgr.AddNamespace("my",
                    "http://schemas.microsoft.com/office/infopath/2003/myXSD");
                XmlNode node = doc.SelectSingleNode(
                                   "/my:myFields/my:EstimationManager", nsmgr);
                EstimationManager.Text = node.InnerText;
            }
        }

        // This method is called when the user clicks the button to associate the
        // workflow.
        private string GetAssociationData()
        {
            StringBuilder sb = new StringBuilder();
            XmlTextWriter writer = new XmlTextWriter(new StringWriter(sb));
            writer.WriteStartElement("my", "myFields",
                    "http://schemas.microsoft.com/office/infopath/2003/myXSD");
            writer.WriteElementString("EstimationManager",
                     "http://schemas.microsoft.com/office/infopath/2003/myXSD",
                      EstimationManager.Text);
            writer.WriteEndElement();
            writer.Flush();
            return sb.ToString();
        }

        protected void AssociateWorkflow_Click(object sender, EventArgs e)
        {
            // Optionally, add code here to perform additional steps before
            // associating your workflow
            try
            {
                CreateTaskList();
                CreateHistoryList();
                HandleAssociateWorkflow();
                // Redirect to the default SharePoint page for workflow settings
                SPUtility.Redirect("WrkSetng.aspx", SPRedirectFlags.
                                    RelativeToLayoutsPage, HttpContext.Current,

Page.ClientQueryString);
            }
            catch (Exception ex)
            {
                SPUtility.TransferToErrorPage(String.Format(
                         CultureInfo.CurrentCulture, workflowAssociationFailed,
                         ex.Message));
            }
        }

        protected void Cancel_Click(object sender, EventArgs e)
        {
            // Redirect to the default SharePoint page for workflow settings
            SPUtility.Redirect("WrkSetng.aspx",
                    SPRedirectFlags.RelativeToLayoutsPage, HttpContext.Current,
                    Page.ClientQueryString);
        }

        #region Workflow Association Code - Typically,
                                      the following code should not be changed
                ...
        #endregion
    }
}

Custom Workflow Task Form

Creating a custom ASPX task form requires a separate content type for each task form. Such a content type defines fields to store the values entered into the form and defines the forms that are used to edit and display the task.

To define and deploy this content type, add a project to the solution, based on the Empty SharePoint Project template. Add a SharePoint-mapped Layouts folder and a content type to this project. The Layouts folder will contain the task form, and the Content Type folder will specify the additional fields and the content type itself, as shown in Figure 16-42.

Figure 16.42. Add a project for the form content type.

Add a second XML file to the Content Type folder, which is used to define the fields for the content type. (In the example, it is named EstimationColumns.xml.) In this file, define your columns, as shown in Listing 16-9. (For more details on this, please refer to Chapter 7.)

For the example, two fields are defined for the estimation task: EstimatedCosts and Outcome. These columns are used in the content type definition for the workflow task form.

Example 16.9. Field Definitions for Custom Task

<?xml version="1.0" encoding="utf-8" ?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <Field ID="{6CBABC50-4BC1-4399-BDC0-7C0155F2CC89}"
         Name="EstimatedCosts"
         DisplayName="Estimated Costs"
         StaticName="EstimatedCosts"
         Description="The estimated costs for the project"

Type="Number"
      ></Field>
                <Field ID="{074AE023-34DD-4C2A-AA67-F9B88063C2BC}"
         Name="Outcome"
         DisplayName="Outcome"
         StaticName="Outcome"
         Description="The estimated costs for the project"
         Type="Text"
      ></Field>
</Elements>

In the content type definition shown in Listing 16-10, define an ID for the content type that inherits from Workflow Task, which has the ID 010801 in the following form: 0x010801 + 00 + < GUID>, where you have to generate a new GUID for your content type.

Add references to the fields that were defined in the Custom Columns definition earlier using <FieldRef> elements.

Finally, add an <XmlDocument> element to the <XmlDocuments> and indicate the custom form you want to use for the Edit, Show, and New forms.

Example 16.10. Content Type Definition for Custom Task

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <!-- Parent ContentType: WorkflowTask (0x01080100) -->
  <ContentType ID="0x0108010031cda7a5483c452f93520d98df2f824a"
               Name="EstimationTaskContentType"
               Group="Project Approval"
               Description="Custom Task for ProjectApproval"
               Version="0">
    <FieldRefs>
      <FieldRef ID="{6CBABC50-4BC1-4399-BDC0-7C0155F2CC89}" DisplayName="EstimatedCosts" Name="EstimatedCosts"/>
            <FieldRef ID="{074AE023-34DD-4C2A-AA67-F9B88063C2BC}" DisplayName="Outcome" Name="Outcome"/>
    </FieldRefs>
    <XmlDocuments>
      <XmlDocument NamespaceURI="http://schemas.microsoft.com/sharepoint/v3/contenttype/forms/url">
        <FormUrls xmlns="http://schemas.microsoft.com/sharepoint/v3/contenttype/forms/url">
          <Edit>_layouts/ProjectApprovalForms/EstimationTask.aspx</Edit>
          <Show>_layouts/ProjectApprovalForms/EstimationTask.aspx</Show>
        </FormUrls>
      </XmlDocument>
    </XmlDocuments>
  </ContentType>
</Elements>

To create the task form, add a new application page to the layouts folder that was mapped to the project earlier. In the markup code of the form, add the required controls within the PlaceHolderMain content placeholder. In the example shown in Listing 16-11, the controls are a TextBox for the estimated costs and a RadioButtonList for the outcome of the approval.

Example 16.11. Markup Code for Estimation Task Form

<asp:Content ID="Main" ContentPlaceHolderID="PlaceHolderMain" runat="server">
    <div>
        Task Title:
        <asp:Label ID="lblTitle" runat="server"></asp:Label>
        <br /><br />

        Please estimate the project costs:
        <asp:TextBox runat="server" ID="EstimatedCosts"></asp:TextBox>
        <asp:RequiredFieldValidator id="valRequired" runat="server"
             ControlToValidate="EstimatedCosts" ErrorMessage="* Enter Number"
             Display="dynamic" type="Integer">
        </asp:RequiredFieldValidator>

        <asp:radiobuttonlist id="Outcome" runat="server">
            <asp:listitem id="Approve" runat="server" value="Approve" />
            <asp:listitem id="Deny" runat="server" value="Deny" />
        </asp:radiobuttonlist>

        <br /><br />

<asp:Button runat="server" ID="btnSubmit" OnClick="btnSubmit_Click" Text="Submit" />
</div>
</asp:Content>

The code-behind for the task form is responsible for passing the information from the form to the workflow. This is done via the AlterTask method of the SPWorkflowTask class. This method requires a reference to the current SPListItem in the task list and a Hashtable containing the new values of the fields that should be set for the task.

SharePoint passes relevant information to the form through request parameters. This way, you can access the Guid of the list and the ID of the item in the list, allowing you to load the correct SPListItem.

The Hashtable can be created using the information from the form to set values in the task item. It is passed to the AlterTask method for processing. If a key matches one the task fields, this field will be populated with the corresponding value in the Hashtable. All the entries in the Hashtable are also available in the workflow through the ExtendedProperties collection of the SPWorkflowTaskProperties object of the task. Only keys that are available through the standard task content type can be accessed directly from the SPWorkflowTaskProperties object.

Listing 16-12 shows how to access the request parameters in the Page_Load method and how to use the AlterTask method in the btnSubmit_Click method.

The final lines of code in Listing 16-12 are responsible for closing the custom task form. Since the form is shown in a modal dialog using the SharePoint dialog framework, you need to close the dialog using JavaScript.

Example 16.12. Code-Behind for Task Form

using System;
using Microsoft.SharePoint;
using Microsoft.SharePoint.WebControls;
using Microsoft.SharePoint.Workflow;
using System.Collections;
using System.Globalization;

namespace EstimationTaskContentType.Layouts.ProjectApprovalForms
{
    public partial class EstimationTask : LayoutsPageBase
    {
        protected SPList _taskList;
        protected SPListItem _taskListItem;
        protected Guid _workflowGuid;
        protected string _listGuid;
        protected string _listItemId;

        protected void Page_Load(object sender, EventArgs e)
        {
            this._listGuid = Request.Params["List"];
            this._listItemId = Request.Params["ID"];

            using (SPWeb web = SPContext.Current.Site.OpenWeb())
            {
                this._taskList = web.Lists[new Guid(this._listGuid)];
                this._taskListItem = this._taskList.GetItemById(Convert.ToInt32(this._listItemId));
            }
        }

        protected void btnSubmit_Click(object sender, EventArgs e)
        {
            Hashtable hashTable = new Hashtable();
            hashTable["EstimatedCosts"] = EstimatedCosts.Text;
            hashTable["_EstimatedCosts"] = EstimatedCosts.Text;
            hashTable["Outcome"] = Outcome.SelectedValue;
            hashTable["_Outcome"] = Outcome.SelectedValue;
            hashTable["TaskStatus"] = "complete";
            hashTable["PercentComplete"] = "1";

            SPWorkflowTask.AlterTask(this._taskListItem, hashTable, true);
            this.Page.Response.Clear();
         this.Page.Response.Write(
                 string.Format(CultureInfo.InvariantCulture,
                   @"<script type="text/javascript">
                    window.frameElement.commonModalDialogClose(1, '{0}'),
                    </script>",
                   null));
            this.Page.Response.End();
        }
    }
}

Note

In the assignment of the Hashtable values, the two fields from the custom content type are defined twice. The second time, the field name is prefixed with an underscore, but the value is the same as before. The reason for this approach is that SharePoint allows you to access known columns in the ExtendedProperties collection only by the Guid of the column, if the key matches an existing column. Therefore, this workaround allows you to set the value in your task using the column name in the Hashtable and access the field by its name using the leading underscore. You can see that in Listing 16-4, the key with an underscore prefix is used to access the properties.

In SharePoint Server 2010, InfoPath forms can be used as workflow forms instead of ASPX forms. The type of forms you choose does not influence the overall workflow behavior, but working with InfoPath forms is slightly different at some points. In general, InfoPath forms are a little easier, because you don't need to build a separate content type for each task form, and you don't need to program the forms. The forms are rendered by existing application pages that already do some of the work, which needs to be done manually in the case of custom ASPX pages. The following description is based on the previous example for ASPX forms, and thus only the differences are noted.

The first step is to build the InfoPath forms similar to the ASPX forms: an association form with a field for the estimation manager and a task form with one field for the estimated costs and a second field for the outcome of the approval. Both forms need to be published to the local disk using the Publish to a Network Location Wizard. (For details on form publishing, refer to Chapter 15.)

To include these InfoPath forms into the workflow feature, you need to adjust your feature definition file as follows:

These settings include your forms into the feature, and the feature receiver will deploy them appropriately.

<?xml version="1.0" encoding="utf-8" ?>
<Feature xmlns="http://schemas.microsoft.com/sharepoint/"
    ReceiverAssembly="Microsoft.Office.Workflow.Feature, Version=14.0.0.0,
                             Culture=neutral, PublicKeyToken=71e9bce111e9429c"
    ReceiverClass="Microsoft.Office.Workflow.Feature.WorkflowFeatureReceiver"
    Title="ProjectApproval Workflow IP"

Description="My SharePoint Workflow Feature"
    Id="cb83bf08-3423-4c45-9396-ac5ff6b5043d" Scope="Site">
    <Properties>
        <Property Key="GloballyAvailable" Value="true" />
        <Property Key="RegisterForms" Value="*.xsn" />
    </Properties>
    <ElementManifests>
        <ElementManifest Location="ProjectApprovalElements.xml" />
        <ElementFile Location="ProjectApprovalAssociationForm.xsn" />
        <ElementFile Location="ProjectApprovalEstimationTaskForm.xsn" />
    </ElementManifests>
</Feature>

In the element manifest file, all that needs to be done is to change the URLs for the forms. The AssociationUrl, InitiationUrl, and ModificationUrl need to be set to special SharePoint application pages that work with InfoPath forms. Listing 16-14 shows how to set these attributes.

To specify the actual InfoPath association form to be used, add an <Association_FormURN> element to the <MetaData>. As the text for this element, enter the URN of the association form. You can get this number from the InfoPath Designer in the Form Template Properties dialog in the field called ID.

Task forms are specified using the <Task[X]_FormURN>, where [X] is the number of the task, starting at zero. Again, the content of the element needs to be set to the URN of the relevant InfoPath form.

<?xml version="1.0" encoding="utf-8" ?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
    <Workflow
        Name="ProjectApprovalWorkflowIP"
        Description="My SharePoint Workflow with InfoPath"
        Id="0AE6882C-C69E-4455-A2E5-463DA0957B19"
        CodeBesideClass="ProjectApprovalIP.ProjectApprovalIP"
        CodeBesideAssembly="$assemblyname$"
        AssociationUrl="_layouts/CstWrkflIP.aspx"
        ModificationUrl="_layouts/ModWrkflIP.aspx"
        InstantiationUrl="_layouts/IniWrkflIP.aspx"
        StatusUrl="_layouts/WrkStat.aspx">

        <Categories/>
        <MetaData>
            <AssociationCategories>List</AssociationCategories>
            <Association_FormURN>urn:schemas-microsoft-com:office:infopath
                                   :AssociationForm:-myXSD-2010-04-09T13-56-22
            </Association_FormURN>
            <Task0_FormURN>urn:schemas-microsoft-com:office:infopath
                                :EstimationTaskForm:-myXSD-2010-04-09T15-40-32
            </Task0_FormURN>
            <StatusPageUrl>_layouts/WrkStat.aspx</StatusPageUrl>
        </MetaData>
    </Workflow>
</Elements>

In the workflow code, working with InfoPath forms is similar to working with ASPX forms. You can access the form fields through the ExtendedProperties collection when using task forms. Association and Initiation forms store the InfoPath form as an XML string in the AssociationData property of the SPWorkflowAssociation.

When creating task forms, one additional property needs to be set to define which form is created, since the manifest file supports multiple task forms that are identified by an index, as shown in Listing 16-14. Use the CreateTask activity, and specify the index of the task in the TaskType property of the SPWorkflowTaskProperties object. For example, in Listing 16-15 the TaskType is set to 0, because only one task is specified in the manifest using the <Task0_FormURN> element.

private void createTask1_MethodInvoking(object sender, EventArgs e)
{
    estimationTask_TaskId = Guid.NewGuid();
    estimationTaskProperties.TaskType = 0;
    estimationTaskProperties.AssignedTo = "wapps\administrator";
    estimationTaskProperties.Title = "Approve_" + workflowProperties.Item.Title;
    estimationTaskProperties.ExtendedProperties["Title"] =
                                                  workflowProperties.Item.Title;
}

To pass parameters from your workflow to the InfoPath task edit form, you can use a special schema file called ItemMetadata.xml. This file is defined as shown in Listing 16-16. It contains only one element, <z:row>, and an attribute for every task property that should be passed to the form. The attributes are named with the prefix ows_ followed by the name of the attribute. For instance, ows_Title in the example will be used to pass the Title attribute to the form using the ExtendedProperties collection, as shown in Listing 16-15.

<z:row xmlns:z="#RowsetSchema" ows_Title="" />

The ItemMetadata.xml file must be added to the InfoPath form as a secondary data source that is loaded when the form is opened and included as a resource file. You can then select the fields from the secondary data source as default values for the fields in your form.

SharePoint passes the task data to the InfoPath task form during form load. The ItemMetadata schema enables the form to process this data and makes the data accessible to the form.