Workflow Development in Office

Microsoft never expected the out-of-the-box workflows to meet all possible situations, but it anticipated that users would develop their own custom workflow solutions for the Office platform. There are two methods that you can use to build custom workflows. The new SharePoint Designer application offers a wizard-based approach, and Visual Studio allows you to develop workflows as described throughout this book. The following sections discuss both methods, along with their pros and cons.

Developing in SharePoint Designer

SharePoint Designer 2007 is the replacement for FrontPage, but that description really doesn’t do it justice. SharePoint Designer adds functionality that was not available in the past. The new workflow-related tools allow users to build noncode workflows with a wizard-based user interface. The way in which workflows are developed in SharePoint Designer is surprisingly similar to defining rules in Outlook.

To create a new workflow using SharePoint Designer, launch the application and navigate to File New Workflow. This displays the initial screen in the Workflow Designer wizard process (see Figure 15-16).

Figure 15-16

There are options on this screen for naming the new workflow, the list that the workflow should be associated with, and when the workflow should start. In addition, there are buttons along the bottom left of the screen that enable the user to validate the workflow as it currently exists, create initiation fields, and create variables that will be used in the workflow. These three buttons are available throughout the workflow development process.

If you click the Initiation button, you are presented with a dialog box that allows the addition or modification of workflow parameters - more specifically, the values that will be set and passed to a new workflow instance when being created. When you create a new field, you must select one of the following field data types:

• Single line of text

• Multiple lines of text

• Number

• Date and time

• Choice (a list of items to choose among)

• Boolean (rendered as a check box)

Additionally, the Variables button presents a dialog box that allows the creation or modification of variables for use in the context of the workflow. Like the initiation fields, the workflow variables have associated data types. The data type options for variables are the following:

• Boolean

• Date/Time

• List Item ID (uniquely references some item in a given list; useful for task IDs)

• Number

• String

After you configure the initiation fields and variables, you need to define the workflow logic. To do this, click the Next button on the first screen; an interface like the one shown in Figure 15-17 is displayed. You use this interface to visually define a branch, which comprises the conditions and actions associated with the workflow logic. You can add multiple branches using the hyperlink under the default branch.

Figure 15-17

Conditions are expressions that evaluate to either true or false, just as with a standard if statement in any programming language. The condition does not have to be set if the associated action will always occur.

Conditions can be defined in a number of ways by using the Conditions button. First, an item’s fields can be compared with some other value, whether it is a static value, a variable, or the value another item’s field. This type of condition can be achieved by selecting Compare [workflow’s list name] field from the Conditions drop-down menu and then setting the appropriate options for the condition. Options that must be set for a condition or an action are indicated by a hyperlink. Clicking the hyperlink displays the necessary UI for setting the appropriate values.

Other options in the Conditions drop-down menu include prebuilt conditions, such as comparing an items title, its modification or creation date, its type, or size. In addition, the Compare any data source option allows you to set a condition to compare two values from any source, whether it is a field from an item, a variable, or a static value.

You define Actions in the Actions drop-down menu, which contains a list of possible units of work. Multiple actions can be defined for a single condition. Therefore, actions can either run in the sequence in which they are defined or in parallel. This execution option is set using the branch’s drop-down menu, which is designated by a down arrow toward the right side of the branch. Table 15-1 is an abbreviated list of available actions.

Table 15-1: Possible Workflow Actions
Open table as spreadsheet

Action	Description
Collect Data from a User	Allows the user to define a task that will be assigned to the appropriate party. When the workflow is executed, and after the task has been completed, the action is considered executed.
Update List Item	Allows the workflow to set a selected item’s field to a value.
Send an Email	Sends an e-mail to a specified user.
Set Workflow Variable	Sets the value of a workflow variable. Variables are defined using the Variables button of the Workflow Designer wizard.
Stop Workflow	Stops the workflow.
Do Calculation	Allows the computation of a simple mathematical expression.

Workflows built in the Workflow Designer also have steps. Steps allow the logical grouping of conditions and actions. All the branches of a step must complete before proceeding to a subsequent step.

After you define a workflow, click the Finish button in the Workflow Designer wizard. The workflow definition is saved and deployed to the current site. Several things happen during this save-and-deploy process. If initiation data or custom task fields were defined in the workflow, customer ASPX pages are generated to collect the necessary data from the user. In addition, the workflow definition (.xoml), rules (.rules), and configuration files are created and placed in a new path of the site. A new folder is generally created under the site’s Workflow folder. Figure 15-18 shows the SharePoint Designer’s Folder List window displaying a custom-developed workflow’s folder as well as all the configuration files.

Figure 15-18

After a workflow is deployed and activated, you can easily modify it using SharePoint Designer. To open a workflow’s definition, select File Open Workflow from the main menu. This displays a dialog box that lists all the custom workflows that were developed using SharePoint Designer. After a workflow definition is selected, you are taken to the Workflow Designer wizard UI.

Developing in Visual Studio

The ability to develop custom workflows in Visual Studio and have them execute in a hosted SharePoint environment is a powerful feature. Other parts of this book discussed Windows Workflow Foundation from the perspective that the developer is responsible for everything workflow related: hosting, persistence, and all the other necessary plumbing that comes along with hosting workflows. The ability to develop custom workflows in Visual Studio and then hand them off to SharePoint to handle the plumbing is a pretty big deal.

Developing custom workflows in Visual Studio that are meant to be executed in the SharePoint environment is not necessarily difficult. However, there are prescribed steps that need to be taken to develop, deploy, and properly configure a SharePoint workflow. This section covers these steps in detail. The following is an abbreviated list of the necessary steps that you can use as a quick reference:

1. Create a new SharePoint workflow project.

2. Add SharePoint activities to the toolbox.

3. Develop your workflow with required and optional SharePoint activities as well as standard workflow activities.

4. Sign the assembly.

5. Develop your workflow forms with InfoPath or ASP.NET.

6. Configure the workflow.xml, feature.xml, and install.bat files.

7. Copy everything to the server and run install.bat.

8. Associate the workflow with a list, library, or content type, and configure.

Getting Started

The first thing you need to do to get started is install the SharePoint workflow project templates.

As of this book’s writing, these templates could be obtained by downloading and installing the Enterprise Content Management Starter Kit from the Microsoft website. The delivery vehicle for these templates may have changed.

After the templates are installed and associated with Visual Studio, two new project types are available under the SharePoint Server item of the New Project dialog box. Like any other Visual Studio project, you launch this dialog box by navigating to File New Project or by pressing Ctrl+Shift+N on the keyboard. Figure 15-19 shows the SharePoint workflow project templates.

Figure 15-19

The SharePoint templates provide several things. First, necessary references to develop SharePoint workflows are added. Aside from the standard System.Workflow.* assemblies, references are added to Microsoft.Office.Workflow.Tasks, Microsoft.SharePoint, and Microsoft.SharePoint.WorkflowActions. In addition, there are files added to the project that support deployment to SharePoint. These files are workflow.xml, feature.xml, and install.bat.

The feature.xml file is shown in the following code. This file’s format is not specific to workflows; rather, it is used for describing all SharePoint features.

  <?xml version="1.0" encoding="utf-8"?> <Feature      Title="My Title"   Description="My description..."   Version="12.0.0.0"   Scope="Site"   ReceiverAssembly="Microsoft.Office.Workflow.Feature, Version=12.0.0.0,     Culture=neutral, PublicKeyToken=71e9bce111e9429c"   Receiver   xmlns="http://schemas.microsoft.com/sharepoint/">   <ElementManifests>     <ElementManifest Location="workflow.xml" />   </ElementManifests>   <Properties>     <Property Key="GloballyAvailable" Value="true" />     <Property Key="RegisterForms" Value="*.xsn" />   </Properties> </Feature> 

There are a few interesting workflow-specific parts of this file to check out. First, the ReceiverClass attribute tells SharePoint to use the WorkflowFeatureReceiver class when running this feature. SharePoint essentially hands off control to this class whenever this feature is called. The ElementManifest node points to the workflow.xml file. This node allows additional information not included in the feature.xml schema to be included. The Property node enclosed with the RegisterForms key tells the feature that there are forms to be included. In this example XML, all xsn (InfoPath) files are grabbed from the same directory as feature.xml.

The following code shows the workflow.xml file, which was referenced in the feature.xml file:

  <?xml version="1.0" encoding="utf-8" ?> <Elements xmlns="http://schemas.microsoft.com/sharepoint/">   <Workflow     Name="My Workflow"     Description="This workflow ..."          CodeBeside     CodeBesideAssembly="MyAssembly, Version=3.0.0.0,       Culture=neutral, PublicKeyToken=a7ae913b1faf46ca"     TaskListContentType     AssociationUrl="_layouts/CstWrkflIP.aspx"     InstantiationUrl="_layouts/IniWrkflIP.aspx"     ModificationUrl="_layouts/ModWrkflIP.aspx">     <Categories />     <MetaData>       <Association_FormURN>[valid URN]</Association_FormURN>       <Instantiation_FormURN>[valid URN]</Instantiation_FormURN>       <Task0_FormURN>[valid URN]</Task0_FormURN>       <Modification_GUID_FormURN>[valid URN]</Modification_GUID_FormURN>       <Modification_GUID_Name>My Modification Form</Modification_GUID_Name>       <StatusPageUrl>_layouts/WrkStat.aspx</StatusPageUrl>     </MetaData>   </Workflow> </Elements> 

This file defines some of the workflow-specific properties for deployment. At the top are attributes such as Name and Description. The Id attribute is simply a unique GUID, which cannot be the same as the feature’s Id attribute. The CodeBesideClass and CodeBesideAssembly attributes tell SharePoint where to find the workflow’s code-beside logic. Because the workflow’s assembly has to be installed in the Global Assembly Cache (GAC) and strongly signed, it is referenced as such with the public key token.

Three other interesting attributes of the Workflow node are AssociationUrl, InstantiationUrl, and ModificationUrl. In this example XML, these are all pointing to default values, which will likely be the same all the time. The paths in these respective attributes are specific to SharePoint and include web parts to handle appropriate actions for a workflow. These attributes are related to the values in the MetaData node for forms as well.

Notice that there are child nodes of MetaData called Association_FormURN, Instantiation_FormURN, and Modification_GUID_FomURN. These three properties point to InfoPath forms that have been deployed to SharePoint per the feature.xml file. Modification forms are not required for SharePoint workflows; therefore, the Modification_GUID_FormURN and Modification_GUID_Name nodes are optional.

Like the Url attributes of the Workflow node, the StatusPageUrl is a standard SharePoint path that can be universally used for different workflows.

The last file that is added to a SharePoint workflow project is install.bat. Although this file is not required, it is a great help when it comes time to deploy custom-developed SharePoint workflows. The following steps are executed in the batch file:

1. Creates a directory for the feature.

2. Copies feature.xml, workflow.xml, and all xsn files to the new directory.

3. Installs the strongly typed assembly (from the Debug folder) to the GAC.

4. Uses the stsadm.exe command-line utility to deactivate and uninstall the feature from SharePoint (if the line is uncommented). This is necessary if the feature had been previously deployed.

5. Uses stsadm.exe to install and activate the feature.

6. Resets IIS so that the changes take effect.

The install.bat file is shown in the following code. Some unnecessary or unused lines were removed from the file that would normally be found in a fresh SharePoint workflow project.

  echo Copying the feature... rd /s /q "%CommonProgramFiles%\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES\MyFeature" mkdir "%CommonProgramFiles%\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES\MyFeature" copy /Y feature.xml  "%CommonProgramFiles%\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES\MyFeature\" copy /Y workflow.xml "%CommonProgramFiles%\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES\MyFeature\" xcopy /s /Y *.xsn "%programfiles%\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES\MyFeature\" echo Adding assemblies to the GAC... "%programfiles%\Microsoft Visual Studio 8\SDK\v2.0\Bin\gacutil.exe" -uf MyFeature "%programfiles%\Microsoft Visual Studio 8\SDK\v2.0\Bin\gacutil.exe" -if bin\Debug\MyFeature.dll echo Activating the feature... pushd %programfiles%\common files\microsoft shared\web server extensions\12\bin :: Only have the following 2 lines uncommented if you've previously deployed this feature ::stsadm -o deactivatefeature -filename MyFeature\feature.xml -url http://localhost ::stsadm -o uninstallfeature -filename MyFeature\feature.xml stsadm -o installfeature -filename MyFeature\feature.xml -force stsadm -o activatefeature -filename MyFeature\feature.xml -url http://localhost echo Doing an iisreset... popd iisreset 

Developing the Workflow

Now that the default files in a workflow project have been inspected, it’s time to get down to business. The first thing that needs to be done, if this is the first time a SharePoint workflow has been developed on a workstation, is to add the SharePoint-specific tasks to the Visual Studio Toolbox. Because it is easier to have the SharePoint activities logically grouped together, first create a new Toolbox tab by right-clicking an empty area of the Toolbox and clicking Add Tab. Name it something useful like SharePoint Workflow Activities.

To add the activities to the newly created tab, right-click an empty area of the tab’s background and click Choose Items. This displays the Choose Toolbox Items dialog box, which contains a list of the components in referenced assemblies on the .NET Framework Components tab. To find and select the SharePoint activities, sort by the Namespace column and scroll to Microsoft.SharePoint.WorkflowActions. Select every item in this namespace and click OK. This adds all of the SharePoint-specific activities to the Toolbox tab that was just created. Now you are ready to develop a custom SharePoint workflow.

To illustrate developing custom SharePoint workflows in Visual Studio, an example of an art request process is used here. Many organizations have an art department that is responsible for creating artwork for products and marketing materials. This example uses an InfoPath form to collect some basic information from a user in need of some art. The user will have the option of specifying whether the request is of high importance - this request will be given greater priority. After the request is generated in a forms library, a task will be created for the user specified in the InfoPath form. That person will then start creating the artwork.

After the art has been created, the artist will set the task to complete, which will then notify the original requestor that the art is available. The requestor will then approve or reject the artwork and provide comments. If the artwork is approved, the workflow will send an e-mail to the person who requested the art as well as the artist, and the workflow will be considered complete. If the artwork is rejected, a new task will be created for the artist, and a loop will continue until the artwork is approved.

The development of the workflow and associated code is covered here first, with the forms development covered in the next section. To get started, rename the default workflow that was added to the project to something more useful, such as ArtRequestWorkflow.cs. Visual Studio asks you whether you want to rename all references of the class name. You should say yes, but not all references to the old class name will be changed. The workflow has an OnWorkflowActivated activity added and configured by default, and its CorrelationToken property still points to the old class name. Simply expand the property in the Properties window and change OwnerActivityName to the new class name.

The OnWorkflowActivated activity has a property called WorkflowProperties, which is already pointing to a class field in the code-beside file. This property is of type SPWorkflowActivationProperties and is the workflow’s portal to the outside SharePoint environment. This object is used later, when the association and initiation data needs to be accessed. To gain access to the data passed to the workflow from SharePoint you must handle the OnWorkflowActivated activity’s Invoked event. This workflow’s event handler is shown in the following code:

  private void WorkflowInvoked(object sender, ExternalDataEventArgs e) {     Hashtable data = Form.XmlToHashtable(workflowProperties.InitiationData);     this.artRequestDescription = (string)data["requestDescription"];     this.thePeople = Contact.ToContacts((string)data["thePeople"],         workflowProperties.Web);     this.theRequestor = workflowProperties.OriginatorUser; } 

There are a few new things going on here. First, the workflow’s initiation data is obtained using the workflowProperties.InitiationData property. This property is simply a string representation of XML because InfoPath is being used for the initiation form, and there are a couple of options for accessing its contents. One option would be to use the InfoPath form’s XML Schema Definition (XSD) to generate a .NET class and deserialize the initiation data XML. Although this is a perfectly viable technique, this example uses a helper class from the Microsoft.Office.Workflow.Utility.Form class. The XmlToHashtable method does what its name describes and returns a Hashtable instance, named data in the code. The data object is then used to gain access to the request description that was entered by the user on the initiation form.

In addition, the data object is used to gain access to the people who were assigned to this art request by the originator. As you will see in the next section, which covers the development of the InfoPath form, the list of people is represented by a structured XML schema. Because of this, the Office API exposes a class called Contact, which has a helper method called ToContacts. This method takes a string representing the XML containing user information as well as an instance of the SPWeb class. The return value is set to a class field of type Contact[. Finally, the code in the WorkflowInvoked event handler obtains a reference to the object representing the user who started the workflow.

The first step in the example workflow is for a task to be created for an artist. However, consider for a moment whether the requestor of the art wants to have more than one artist take a stab at the request. In this case, the initiation form needs to provide a way to enter more than one user. Because a well-designed workflow should be able to account for this situation in an elegant fashion, the Replicator activity from the base activity library is used to design for multiple artists. The Replicator activity takes whatever its children are and replicates them the number of times defined by its InitialChildData property. The thePeople array in the WorkflowInvoked event handler is used for the InitialChildData. The code for the Replicator activity’s Initialized event is as follows:

  private void replicateOnPeople_Initialized(object sender, EventArgs e) {     this.childDataForReplicator.AddRange(this.thePeople); } 

The workflow logic is defined within the Replicator activity and its required Sequence activity child. This starts with a SharePoint activity called CreateTask. The CreateTask activity is a custom activity developed for SharePoint that inherits from the out-of-the-box CallExternalMethodActivity class to call external code in SharePoint. One of this activity’s required properties is CorrelationToken, which allows the workflow runtime to know which activity a particular event from the outside is associated with. This property should be set to a new value, not to workflowToken, which was created with the workflow. You can do this by typing a name in the Properties window. In addition, the TaskId and TaskProperties properties should be bound to new fields in the code-beside class. Finally, the activity’s MethodInvoking event should be wired so that the task’s necessary properties can be set before the activity is executed. The handler for the MethodInvoking event is shown in the following code:

  private void createNewTask_MethodInvoking(object sender, EventArgs e) {     this.taskGuid = Guid.NewGuid();     this.taskProperties.AssignedTo = CurrentArtist.LoginName;     this.taskProperties.Title = "New Art Requested by " +         this.theRequestor.LoginName;     this.taskProperties.Description = "Description from user: " +         this.artRequestDescription;     this.taskProperties.TaskType = 0;     int daysToComplete = 21;     if (this.isHighPriorityRequest)         daysToComplete = 14;     this.taskProperties.DueDate = DateTime.Today.AddDays(daysToComplete); } 

In this code, a new Guid instance is created and assigned to a class-level member. This is the member that the TaskId properties of the task-related activities are bound to. Also, the task has several of its properties set. The AssignedTo property is set to the current artist’s LoginName property. Also, the task type is set to 0. This separates different task types so that each type can have its own task-editing form. The form to task type mapping is defined in the workflow.xml file. Finally, the task’s due date is set using logic based on the high-priority flag set in the workflow initiation form.

The next few pieces of logic in the workflow follow what will likely be a very common pattern in task assignment in SharePoint. There is a While activity that loops over an OnTaskChanged activity until a flag tells the loop that the task is completed. After the loop is exited, a CompleteTask activity is used to mark the task in SharePoint as completed. The CreateTask, OnTaskChanged, and CompleteTask activities all point to the same task reference through their respective TaskId properties as well as their CorrelationToken properties.

From here, additional logic is defined in the workflow that implements the art-request algorithm described earlier. In addition to the SharePoint activities introduced thus far, LogToHistoryListActivity is used numerous times to track potentially useful data about the execution of the workflow. Figure 15-20 shows a partial screen shot of the completed workflow.

Figure 15-20

Implementing Forms Using InfoPath and Forms Server

So far in this chapter, there has been a lot of talk about the various forms for SharePoint workflows. This section shows you how to develop and use custom forms. To develop custom workflow forms for SharePoint, you use Microsoft Office InfoPath, which includes the InfoPath 2007 client and Forms Server. However, you can use Forms Server only with Microsoft Office SharePoint Server (MOSS), which is not free. If you are developing against WSS, you need to use ASP.NET to develop custom forms.

Although InfoPath forms development is a topic all to itself (it has whole books devoted to it), there are some specific steps you must be take to successfully develop forms for SharePoint workflows. To illustrate these steps, the art-approval example is continued. Developing an InfoPath form for use in a SharePoint workflow is somewhat tedious, as the steps to configure the forms correctly are prescribed.

To get started, launch Microsoft Office InfoPath 2007 and select Design a Form Template from the Getting Started dialog box. In the next screen, choose to design a new form template and make sure that Blank is selected from the list view. Uncheck the Ensure browser-compatible features only check box and then click OK to design the new form.

Another housekeeping task you must do to make sure everything works as it should is to set the forms trust level. To do this, navigate to Tools Forms Options and then click Security and Trust in the left pane of the options window (see Figure 15-21). To allow the form to access information in SharePoint, which is outside the context of the form, you must select the domain option. Uncheck the Automatically determine security level check box and select the domain-level trust.

Figure 15-21

The form needs domain-level trust because it has to access information about users in order to create tasks. The way this user information is accessed is through the Contact Selector control that was developed by Microsoft for InfoPath workflow forms. This control works a lot like the check names feature in Microsoft Office Outlook. However, by default the InfoPath controls toolbox does not contain this control. To add it, you need to access the controls panel from InfoPath’s Task Pane.

At the bottom of the controls toolbox, click the Add or Remove Custom Controls link. The Add/Remove dialog box is displayed. Click the Add button. The resulting wizard asks whether you want to add a Template Part or an ActiveX control. Because the Contact Selector is an ActiveX control, select that option and click Next. The contact control can be found in the list on the next screen. Next, the wizard asks whether you want to include a cab file. Because this solution needs to be rendered only in the browser, choose to not include a cab file. On the binding screen, select Value and click Next. In the final screen of the wizard, select the Field or group (any data type) option from the field or group type dropdown menu. Click Finish to complete the wizard. The Contact Selector control is now listed in the controls toolbox under the Custom heading.

InfoPath uses XSD to define a form’s data. Consequently, some entities need to be defined to hold the data returned by the Contact Selector control. This data structure must be defined in the Data Source section of the Task Pane. Before defining this structure, rename the Contact Selector from group1 to something useful. To do this, hover over the control and then double-click the tool tip showing the name to display the control’s properties. As you may recall from previous workflow code, the artists chosen were obtained by accessing an extended property of the initiation form called thePeople. Therefore, this Contact Selector control should be named the same thing.

Now that you have changed the name, you need to modify the form’s data source to contain the necessary fields and groups. The Items tab of the Contact Selectors properties shows you the XML structure to which the form must conform. The following code shows the XML. In addition, Figure 15-22 shows the structure of the form’s data source.

Figure 15-22

  <thePeople>   <Person>     <DisplayName />     <AccountId />     <AccountType />   </Person> </thePeople> 

Now you can use the Data Source section of the Task Pane to define this data structure using a group for the Person element and fields for the DisplayName, AccountId, and AccountType nodes. The requestDescription and highPriority nodes are added automatically when controls are added to the form (do not add them manually).

Next, you need to design the form. In addition to the Contact Selector that is already on the form, it needs a text box for the request description, a check box for the high-priority flag, and a submit button. Add these to the form by dragging them from the Controls section of the Task Pane. Aside from visual modifications, such as sizing, the text box and check box do not need any of their properties changed. The button, however, needs some tweaking before it is ready to be used.

When the button is clicked, it will need to submit the form data to SharePoint, which is an outside environment as far as InfoPath is concerned. To configure the button in this way, double-click it to access its properties. The action needs to be set to Rules and Custom Code, which it is by default. Next, click the Rules button to launch the Rules dialog box and then click the Add button. From here, you need to add two actions: one to submit the form to the outside host and one to close the form.

To add the submit action, click the Add Action button and select the Submit using a data connection option from the drop-down menu. You can either select an existing data connection or create a new one. Click the Add button to create a new data connection, which launches a wizard. Choose the option that enables you to create a new connection to submit data and click Next. In the next screen, choose the destination for the form submission, which is the hosting environment. The next screen enables you to name the new data connection - the Submit default name is fine for this example, so don’t change it.

Now the button rule needs a new action to close the form after submission. Click the Add Action button, select the Close the form option from the drop-down menu, and then click OK. Finally, click OK three more times to get back to the form. Now the form is correctly configured and ready to be deployed. Figure 15-23 shows the final form.

Figure 15-23

All you have left to do with the form is save it and then publish it to a network location. However, for this example, simply publish the form to a local folder on your drive, such as the folder in which your workflow project is located. This will make it easy to deploy everything to the SharePoint server.

Deploying and Configuring Custom Workflows to SharePoint

The install.bat file, which is included in new SharePoint workflow project, was introduced earlier as an easy way to deploy custom SharePoint workflows. Although this is certainly true, and there is nothing wrong with using this method, you need to fully understand what is going on during the deployment process. First, whether or not you are using install.bat, the necessary files need to be copied to the SharePoint front-end server. This includes feature.xml, workflow.xml, and the InfoPath forms developed for the workflow.

After all the necessary files are on the server, they must be installed so that SharePoint is aware of the feature. You do this by using the SharePoint command-line utility called stsadm.exe. This executable not only allows the installation of SharePoint features, but also enables you to perform administrative functions such as adding or deleting users, modifying configuration properties, and managing SharePoint sites. Refer to the preceding install.bat listing for how to install and activate a SharePoint feature.

After the feature is installed and activated, it helps to perform an iisreset to ensure that the changes can be seen. At this point, the new workflow feature is visible on the Site Collection Features page in Site Settings. To get to this page, click the Site Actions menu in the upper-right of any page and then select Site Settings, followed by Modify All Site Settings. On the succeeding page, click the Site collection features link under the Site Collection Administration heading. Figure 15-24 shows what this page looks like with a custom feature installed and activated. Now that the workflow is deployed, it can be associated with a list or content type just like any of the workflows covered so far in this chapter.

Figure 15-24

After you have deployed a SharePoint workflow to the server, you can make changes by copying the updated assemblies to the server and performing an iisreset. However, you can use this method only when you are making changes to the workflow itself, not to any of the workflow forms of the workflow.xml and feature.xml files.

Debugging Custom Workflows in SharePoint

Debugging custom workflows that are deployed and running in a SharePoint site is fairly straightforward. The debugging process involves attaching the Visual Studio debugger to the process that is hosting the workflow. SharePoint is an Internet application, so the process you use is w3wp.exe (World Wide Web Worker Process).

Because debugging workflows involves attaching to a process on the server, and because certain required DLLs are only on the server, you must do all debugging on the server itself. This means that Visual Studio needs to be installed on the server, and physical or remote access to the server (through a Remote Desktop or VNC) is required. Under optimal conditions, remote debugging of workflows may be possible; however, it is likely more trouble than it is worth.

If a workflow needs to be debugged from a SharePoint site, it must be compiled and deployed in Debug mode. After you have a workflow deployed that needs to be monitored, open the project in Visual Studio and select the Attach to Process item from the Debug menu. This opens a dialog box with the w3wp.exe process selected (see Figure 15-25).

Figure 15-25

Click the Attach button. The debugger is attached, and the required debugging symbols are loaded. Perform the steps required in SharePoint to start the workflow instance that needs to be debugged. After the workflow is loaded and executed, any breakpoints that have been defined in the code windows are monitored, and execution halts when a breakpoint is hit. The debugging process from here is the same as debugging any other type of code in Visual Studio.

Another way to troubleshoot problem workflows is to use the Cancellation & Error Report discussed earlier in this chapter. This Excel report contains two tabs, the second of which holds data related to errors that occur in workflow instances. The columns in this report include the workflow instance’s ID, the list and item the workflow instance was associated with, and the date and time the error occurred, among other data points. The last column of the report, labeled Data, includes any error messages received through a .NET exception. This column alone is quite helpful for developing new custom workflows.