Windows SharePoint Services (WSS) 2007 is the first Microsoft server that has native support for the Windows WorkFlow Foundation (WF). The integration of WF and the 2007 release of SharePoint provides an infrastructure that drives processes around SharePoint's strong suit: collaboration and sharing of information. This release focuses on document-centric workflows, the procedures that a particular document goes through in its lifecycle (be they reviewing, editing, or approval). The new edition enables you to attach and run a process directly in a SharePoint document or list item. Additionally, the workflows within SharePoint spotlight human-based endeavors, tasks driven by human interaction as opposed to static, automated programmatic steps.
To examine the process, this article follows a report that needs to be approved before publication:
1. A document containing a report can automatically generate an Approval workflow, or the author can initialize it manually and select the individuals who need to approve it.
2. The workflow assigns approval tasks to those people and they are notified of their tasks via email.
3. They can assign their choice by clicking "approve" or "reject" on a special form provided by the workflow.
4. When all approvals are completed, the author receives notification that the report has been approved (or rejected) and it is ready for publication.
The BasicsSharePoint Server 2007 provides various out-of-the-box workflows that require no additional attention before using. These workflows include Approval (routes a document for approval), Collect Feedback (routes a document for review), Collect Signatures (gathers signatures), Disposition Approval (manages document expiration and retention), Group Approval (similar to the Approval workflow, but designed specifically for East Asian markets), Translation Management (manages document translation), and Issue Tracking (manages the issue tracking process by creating tasks for active issues assigned to users).
Many processes are very specific to an individual company's needs. Therefore, the WorkFlow Foundation provides an extensible infrastructure that can be used to create sophisticated workflows. WF provides a powerful platform with a unified programming model, and it works with familiar developmental tools such as Visual Studio 2005. Less powerful SharePoint workflows also can be created with SharePoint Designer (formally FrontPage), a web design and customization tool that allows users to create workflows without writing any code.
Using the Right ToolsA standard Visual Studio installation lacks the necessary tools to work with the WorkFlow Foundation, so to put things in motion you must install the Visual Studio 2005 extensions for .NET Framework 3.0 (Windows Workflow Foundation). The extensions provide the required references to the Foundation assemblies, the essential Activities needed, as well as the WorkFlow designer within Visual Studio and a number of project templates. Keep in mind that you must install DotNet Framework 3.0 as a prerequisite to working with WF.
A Visual Studio 2005 extension that is compatible with the WorkFlow Foundation to work with SharePoint is available, but at the time of writing it was in beta (Workflow Developer Starter Kit for Windows SharePoint Services 3.0). Note that this extension is not required if you are developing workflows for SharePoint (the extension makes a new template to initialize a project).
The first step in creating a workflow for SharePoint is crafting a new project in Visual Studio 2005 based in the Sequential Workflow Library (or in the State Machine Workflow Library, if you are making a state machine workflow) and assigning it a name. Visual Studio will generate the necessary code and configuration files. Add a reference to Windows SharePoint Services (Microsoft.SharePoint.dll) and, if you need to work with Microsoft Office SharePoint Server, a reference to Microsoft Office SharePoint Server component (microsoft.sharepoint.portal.dll). This establishes references to the object model of SharePoint, opening the door to interactions with it.
Although it's not compulsory, it simplifies coding if you write directives to the next namespaces in the code behind file, for example:
using Microsoft.SharePoint;
using Microsoft.SharePoint.Workflow;
using Microsoft.SharePoint.WorkflowActions;
Finally, you need to add an activity to the Visual Studio toolbox. Using the context menu (right-click into the toolbox), select Choose items and in the .NET Framework Components tab, check the OnWorkflowActivated activity to activate it in the toolbox. This activity is indispensable for running workflows in SharePoint.
As a demonstration, the following example builds a simple workflow that illustrates the lifecycle of a WF within SharePoint: initializing the workflow, transporting information from SharePoint, processing it, and feeding it back to WSS (see Figure 1).
Figure 1. The Example WorkFlow in the Visual Studio WorkFlow Designer
You initialize the process by creating the workflow using the WorkFlow Designer in Visual Studio. The opening activity is always the OnWorkflowActivated for workflows in SharePoint. Next, install a While activity with a Code Activity inside to process the information. Finally, install another Code Activity to return information to SharePoint. Bear in mind that this is not a functional workflow you would use in a business application, but a demonstration of each part of the interaction between WF and SharePoint.
Extracting Information from the External World: SharePoint to the WorkFlow
The first stage in the codification of the workflow involves defining some variables in the code behind page to be used later, for example:
public SPWorkflowActivationProperties FlowProperties =
new SPWorkflowActivationProperties();
private string _myDocument = string.Empty;
private int _CounterLetters = 0;
private int _CounterVowels = 0;
The activation properties will be stored in the FlowProperties variable, and extra global variables for the internal work are defined.
As Figure 1 shows, each activity has a red mark at the right corner, indicating that the configuration is incomplete. Returning to the Designer, you now can configure the OnWorkflowActivated activity using the defined variables (see Figure 2).
Click here for a larger image.
Figure 2. Configuration Panel of the OnWorkflowActivated Activity
In the Properties panel, create the subsequent configurations:
1. Correlation Token: Choose a distinctive name (FlowToken, for example). After the name configuration, a plus symbol will appear where the OwnerActivityName can be selected (Workflow1 in the example).
2. Click the ellipses button of WorkFlowProperties and, in the new window, choose the code defined previously in FlowProperties.
If the configuration parameters are correct, the red mark in the activity will disappear.
As with all Visual Studio projects, if you double-click on an activity, Visual Studio will fashion the corresponding event handler. When you double-click the OnWorkflowActivated activity, Visual Studio writes the event handler method automatically and the user writes the corresponding logic inside:
private void onWorkflowActivated1_Invoked(object sender,
ExternalDataEventArgs e)
{
SPListItem myActivator = FlowProperties.Item;
_myDocument = myActivator.Name.ToLower();
_CounterLetters = _myDocument.Length;
}
By using this activity, you can find all the relevant information from the SharePoint context. The flow is initialized by an element of a List (of the SharePoint type SPListITem), and from the object that contains the element information, you can find its name (located in the variable _myDocument) and the number of letters in the document name (stored in the _CounterLetters variable).
In the FlowProperties object, you can find all the necessary information from the SharePoint context. The SharePoint web, site, and list objects are present, as well as the Task List that generates alerts for other users. Everything you need to process the variable later is present.
Processing the Information: the WorkFlow in Action
Once the information from SharePoint has been captured, the next step is to process it. With a double-click on the activity inside the While loop, Visual Studio generates the corresponding event handler, where you can write the business logic:
private void codeActivity1_ExecuteCode(object sender, EventArgs e)
{
_CounterLetters--;
char[] AllVowels = new char[] { 'a', 'e', 'i', 'o', 'u' };
Array.Sort(AllVowels);
if (Array.BinarySearch(AllVowels,
_myDocument[_CounterLetters]) >= 0)
_CounterVowels++;
}
The procedure for the example will count the number of vowels in the name of the document. The algorithm is not optimal for a large number of instances of the workflow, but sufficient for the example (the method IndexOf of the array may be a more effective way to calculate the number of vowels).
At this point, it is important to construct the configuration of the While activity. From the Properties panel, compose the following configurations:
1. Condition: Choose "Declarative Rule Condition."
2. ConditionName (expanding the Condition property): Give it a recognizable name.
3. Expression: In the "Rule Condition Editor," which can be activated by using the ellipses button, write the condition necessary to remain in the loop (for the example, "this._CounterLetters > 0"). Until all the letters are "read" and the vowels are counted, the loop statement will continue.
This step is essential to the overall workflow because it implements the flow's logic. The example uses only one code activity inside a loop activity, but in an actual situation it would be composed of many different kinds of activities.
Taking Information Back to the External World: From the WorkFlow to SharePoint
The second Code activity in the example controls returning the processed information from the WorkFlow engine to the SharePoint context. You can use the event handler of the activity to write information back into SharePoint as follows:
private void codeActivity2_ExecuteCode(object sender, EventArgs e)
{
SPListItem myActivator = FlowProperties.Item;
myActivator["Title"] = _myDocument + " has " +
_CounterVowels.ToString() + " vowels";
myActivator.Update();
}
Initially, the code crafts an object of the type Microsoft.SharePoint.SPListItem, calling the Item method of the SharePoint properties, and then changes the title of the element that has begun the WorkFlow, appending a string and the calculated number of vowels in the name of the document.
Because the workflow has access to the complete context of SharePoint, it can perform internally any authorized modification (write to lists and libraries, change properties, as well as create, edit, and delete elements). Everything, that is, within the authorization and authentication context of the user who has initialized the WorkFlow.
An additional method of interaction with users is to employ ASP.NET forms that you apply with your Windows SharePoint Services workflow. You then display these forms in the SharePoint user interface at the appropriate stages in the workflow. There can be four types of forms:
• Association: This form will be displayed to administrators when they first add or associate the WorkFlow with a particular List or document Library.
• Initialization: A user starting the WorkFlow manually will be confronted with this form. At this point, the user may override or append the association parameters.
• Modification: The form that enables users to alter the WorkFlow while it is running.
• Task: This form assigns jobs to the flow participants.
Deploying and Using the WorkFlow
Because the assembly of the workflow generated by the compilation in Visual Studio must be installed in the Global Assembly Cache (GAC), it needs to be signed as strong. You can use the standard Visual Studio 2005 infrastructure to sign it or the sn tool with the parameter -T. After the compilation is complete, you can use the gacutil tool to install the assembly in the GAC.
You use features to deploy workflows in SharePoint. As a new paradigm in SharePoint 2007, the feature was created as a way to encapsulate solutions and functionality for ease of deployment. Additionally, it provides a mechanism by which developers can package the files needed for a solution (as a workflow) intended for distribution.
Each feature must include a WorkFlow definition template (an XML file) that contains the information SharePoint requires to instantiate and run the WorkFlow, as well as a feature definition (also an XML file) with information concerning the feature itself. To install the example workflow, create a new Feature.xml file with the following code:
Title="JupiterMediaWorkFlow"
Description="Example WorkFlow"
Version="12.0.0.0"
Scope="Site"
xmlns="http://schemas.microsoft.com/sharepoint/">
The Feature Id parameter is a Windows GUID that you can fashion with the GUID Generator component included in Visual Studio. A second file called Flow.xml, with the following code, defines the WorkFlow for SharePoint:
Description="Example WorkFlow"
Id="B2196C5B-1579-4bb7-B23E-01DC6A898ABC"
CodeBesideClass="JupiterMediaWF.Workflow1"
CodeBesideAssembly="JupiterMediaWF, Version=1.0.0.0,
Culture=neutral,
PublicKeyToken=99ca3967f3ef49e3">
_layouts/WrkStat.aspx
Copy both files to a new directory under the hive:
C:\Program Files\Common Files\Microsoft Shared\
web server extensions\12\TEMPLATE\FEATURES\JupiterWF
And install and activate the workflow using the SharePoint Administrators tool stsadm, with the following syntax:
To install the workflow:
C:\Documents and Settings\Administrator>"C:\Program Files\
Common Files\Microsoft Shared\web server extensions\12\BIN\
STSADM.EXE" -o activatefeature -name JupiterWF -force
To activate the workflow:
C:\Documents and Settings\Administrator>"C:\Program Files\
Common Files\Microsoft Shared\web server extensions\12\BIN\
STSADM.EXE" -o installfeature -name JupiterWF -force
At this point, you must link the workflow with the document library where it will operate (see Figure 3).
Click here for a larger image.
Figure 3. Setup of the Workflow in a Document Library
From the Document Library Settings page, proceed to Workflow Settings and, using the page Add a Workflow, select the workflow from the ComboBox. Give it a name, decide on a List to be used for its tasks and another one for the History (either use an existing list or create a new one), and select the start options (you can start it manually or automatically).
After creating a new document in the library, the user can utilize the context menu of the element to proceed to the page where he or she can select and activate the workflow (see Figure 4).
Click here for a larger image.
Figure 4. Activating a WorkFlow for a Document
Multiple workflows can run simultaneously on the same item, but only one instance of a specific workflow can run on a specific item at any given time. At the end of the working process of the flow, the result appear in the properties page of the document (see Figure 5).
Click here for a larger image.
Figure 5. Properties of the Document After Completing the WorkFlow
Note: In the properties page, the workflow has made a count of the vowels in the document's name and has altered its title to include the counter.
Integrating Divergent Worlds
The interaction between the Windows WorkFlow Foundation and Microsoft SharePoint 2007 offers an excellent way to attach business processes to items, and it provides the opportunity to control almost any aspect of a document's lifecycle and user interaction within SharePoint. A workflow can be as simple or complex as your business process requires, and it can be initiated either by users or automatically based on some event.
The architecture of the Foundation and its implementation in SharePoint allows for substantial flexibility to make changes in the business layers. It provides the option of reuse without having to alter the portal's deep infrastructure and unlocks new prospects for software architects, developers, and system administrators.
Download the Code
You can download the example workflow here.
