Building Custom Workflow Conditions for SharePoint Designer
Summary: You can build custom workflow conditions for Microsoft Office SharePoint Designer 2007. Learn how to create a workflow condition assembly, sign the assembly, write the actual condition, and deploy the assembly to your SharePoint site.
Applies to: 2007 Microsoft Office System, Windows SharePoint Services 3.0, Microsoft Office SharePoint Designer 2007
Joel Krist, iSoftStone
A workflow allows a business process to be attached to items in Windows SharePoint Services 3.0. This process can control almost any aspect of an item in Windows SharePoint Services 3.0, including the life cycle of that item. For example, you could create a simple workflow that routes a document to a series of users for approval. A workflow can be as simple or complex as a business process requires. Windows SharePoint Services 3.0 includes pre-built workflow templates, but you can create custom workflow templates in either Microsoft Visual Studio 2005 Designer for Windows Workflow Foundation, or in a declarative rules-based, code-free workflow editor, such as Microsoft Office SharePoint Designer 2007.
Conditions are one of the building blocks of workflows. When designing a workflow, you can create rules that apply conditional logic to SharePoint lists and items. A rule establishes a condition where the workflow performs the associated action only if that condition is true. Office SharePoint Designer 2007 provides several ready-made, reusable conditions that you can incorporate into a workflow. In addition, you can create custom conditions and advanced conditions that accept a wide range of parameters. This Visual How To illustrates how to build custom workflow conditions for Office SharePoint Designer 2007.
To illustrate how to build custom workflow conditions for Office SharePoint Designer 2007, this section walks through six key steps:
Creating a Class Library Project in Visual Studio 2005
An easy way to create a custom workflow condition assembly is to use the Visual Studio 2005 Class Library template. To create a Class Library project in Visual Studio 2005, do the following:
Adding a Reference to the SharePoint Workflow Actions Assembly
The method that implements the custom workflow condition uses several SharePoint classes. References to the required SharePoint assemblies need to be added to the project to allow these classes to be used. If Visual Studio is running on a computer that has Microsoft Office SharePoint Server 2007 installed, do the following:
If Visual Studio is running on a computer that does not have Office SharePoint Server 2007 installed, the SharePoint assemblies are not available. In this case, copy the assemblies from a computer that has Office SharePoint Server 2007 installed to a local project folder on the development computer. The SharePoint assembly files needed to create the custom workflow condition are Microsoft.SharePoint.dll and Microsoft.SharePoint.WorkflowActions.dll. By default these assemblies are located in the following folder on a computer that has Office SharePoint Server 2007 installed:
%Program Files%\Common Files\Microsoft Shared\web server extensions\12\ISAPI
After you make local copies of the SharePoint assemblies, you can add references to them by browsing for the local files. To add references to local copies of the assemblies, do the following:
Signing the Class Library Assembly with a Strong Name
To allow the custom workflow condition assembly to be installed in the global assembly cache so that it can be used by SharePoint Designer, it must be signed with a strong name. A strong name consists of the assembly's identity—its simple text name, version number, and culture information (if provided)—plus a public key and a digital signature. To assign a strong name to the custom workflow condition assembly in Visual Studio, do the following:
Creating a method that Implements the Custom Workflow Condition
After adding the reference to the required assembly and signing the assembly, the next step is to create the method that provides the implementation of the custom workflow condition. A custom workflow condition is implemented as a static method that evaluates a condition and returns a Boolean value representing the result of the evaluation. The default signature of a custom workflow condition method is:
Static Bool functionName(WorkflowContext context, string listId,
The context, listId, and itemId parameters are required by SharePoint Designer. You can add parameters to the method after the required parameters to allow the condition to have access to additional data. For a description of how custom data values are gathered by SharePoint Designer and then passed to the custom condition method, see the following section that covers creating a .Actions file for the custom condition.
The example custom workflow condition shown here works with the items in a fictional Project Status Report document library. One of the properties of items in the Project Status Report document library is the Last Status Date, which is the date and time the status of the project was last updated. The custom workflow condition accepts a single parameter, an integer representing a number of days. It determines whether the date span between the current date and the Last Status Date property of an item in the document library is greater than the number of days specified by the parameter. If the date span is greater than the value passed with the parameter, the condition returns True; otherwise it returns False.
Add the following Imports or using statements to the top of the CustomConditions.cs or CustomConditions.vb source file, replacing the Imports or using statements that were generated by Visual Studio when the project was created.
The Imports and using statements let you use the classes and types defined in the referenced namespaces without having to use fully qualified namespace paths. The next step is to add the code for the method that implements the custom workflow condition. Add the following code to the CustomConditions class:
Creating a .Actions File for the Custom Condition
The next step in preparing a custom workflow condition to work with SharePoint Designer is to create a .Actions file. .Actions files are XML files that describe custom actions and conditions to SharePoint Designer.
First, use the Strong Name (sn.exe) utility that is included with Visual Studio to determine the public key token of the workflow condition assembly. Build the assembly in Visual Studio and then run sn.exe with the -T option, like this:
sn.exe -T WorkflowConditions.dll
Make a note of the returned public key token for later use.
Next, create a text file named CustomConditions.Actions and add the following XML to it:
Replace the <Public Key Token> placeholder with the public key token for the condition assembly as returned previously by the Strong Name (sn.exe) utility.
The preceding XML markup contains tags and attributes that SharePoint Designer uses to determine how to display the condition as a rules sentence and how to bind a value to the parameters accepted by the condition.
The Conditions tag starts a list of available conditions. It is possible to put multiple conditions in the same actions file by including them inside this tag.
The Condition tag defines basic information about a condition via the following attributes:
The RuleDesigner tag describes a rule sentence for the condition and how to bind values to the parameters of the method that implements the condition. This is the sentence SharePoint Designer 2007 displays for the condition in its rules wizard. The variable parameters in the sentence (%1, %2, and so on) are exposed as customization links. When displayed, they are replaced by the FieldBind tags described below, where %1 is replaced by the FieldBind that has an Id = 1, and so forth.
The FieldBind tag describes each variable parameter. The Field attribute corresponds to the condition parameter as it is described in the Parameter tag in the markup. The Text attribute specifies how the field is initially displayed in the rule sentence.
Finally, the Parameters tag tells the RuleDesigner how to map the fields to the parameters of the method that implements the custom workflow condition. Each Parameter tag describes the name of the parameter as specified by the corresponding FieldBind, the system type of the parameter, and the direction. The order of Parameter tags maps to the order of parameters in the function after the default context, listId, and itemId parameters. In this example, because "days" is the first non-default parameter in the StatusNeedsUpdating function shown previously, it is mapped to the first Parameter tag in the Parameters section. From a coding perspective, the parameter names in the function declaration for the method that implements the custom workflow condition don't need to match anything in the Condition node in the .Actions file.
Deploying the Custom Condition to a SharePoint Site
Deploying the custom workflow condition to a SharePoint server involves three steps:
Because workflow authors in Office SharePoint Designer 2007 cannot create custom activities or conditions for use in their workflows, they are limited to the activities and conditions that appear on the "safe list" in Office SharePoint Designer 2007. Developers can create custom activities and conditions, and make them available on the safe list.
This article illustrated how to build custom workflow conditions for Office SharePoint Designer 2007. The key steps include:
Length: 8:25 | Size: 9.8 MB | Type: WMV