Extending Workflow Actions for SharePoint Designer

Hi there.  My name is Rodney Farris and I’m one of the newest Programming Writers on the Windows SharePoint Services SDK team.  I’ve been assigned to cover SharePoint Workflows as well as the developer aspects of SharePoint Designer 2007.

For the last 8 years I’ve been with Microsoft supporting customers, 4 of those being with the SharePoint Developer Support team.  I have a good deal of experience talking to customers and dealing with the problems that they encountered in developing SharePoint applications.  Hopefully this experience will help me to focus my writing on helping you to find answers to your questions about SharePoint workflows.

In the coming months I will be posting about the content that’s on the publishing horizon.  The first of which is rounding out the documentation for declarative, code-free, rules-based workflows.  This is a powerful means of developing workflows without needing to know the architecture of workflow or how to code. 

In my first few months in this new position, I’ve been doing a lot of research on the topic by talking to the product team, customers, and product support as well as reviewing existing documentation and reading blog posts.  I’ve seen a lot of good information written about extending the list of workflow activities provided by Windows SharePoint Services 3.0, but I’ve also seen just as many questions.

A lot of those questions are around how to extend the list of Actions, or workflow activities, and Conditions for use in SharePoint Designer.  This being the case, my first duty was to research and work with the product team to describe the schema that governs their development. 

The following is a somewhat abridged version of what you will see in the upcoming SDK update, in that I have removed all of the in-line syntax and examples.  Not to worry, I will be posting those shortly along with a developer’s version of the schema in an XSD format. 

 

Workflow Actions Schema Overview

You can build powerful and robust workflows to automate most of their common business processes by using a declarative, rules-based, code-free workflow editor such as Microsoft Office SharePoint Designer 2007. Windows SharePoint Services provides 23 built-in workflow actions and 9 workflow conditions that can be incorporated in these workflows.

However, sometimes it is necessary to build workflows around very complex and unique business requirements that cannot be accommodated by the default lists provided by Windows SharePoint Services.

In order to allow a code-free editor to work with more complex business logic, you must create customized workflow libraries and deploy them to the server that is running Windows SharePoint Services. After you have deployed your customized workflow objects, the new actions and conditions will be visible to the workflow editor.

XML schema definition files (XSD) are commonly used to validate XML structure and syntax. However, in the case of Action and Condition elements, the information that is normally contained in an XSD file, and is easily readable, is contained within Windows SharePoint Services internal code.

Schema Elements
I placed these in alphabetical order for easier reference, not in order of hierarchy.  I will post the hierarchy the next time.

Action
Actions
Condition
Conditions
Default
FieldBind
Option
Parameter
Parameters
RuleDesigner
WorkflowInfo

Action Element

Contains the information needed for the workflow engine to process a workflow activity, which is called an action in Windows SharePoint Services 3.0. A workflow Action element represents a workflow activity, such as sending e-mail notifications, updating Windows SharePoint Services 3.0 list items, creating and assigning tasks, as well as many other activities.

By default, Windows SharePoint Services 3.0 provides 23 built-in workflow actions. These are defined in the WSS.ACTIONS file.

Attributes

 

Attribute

Description

Name

Required text. Represents the description of the workflow action that is displayed to the workflow editor.

ClassName

Required text. Fully qualified name of the class that implements the workflow action. For example: Microsoft.SharePoint.

WorkflowActions.EmailActivity.

Assembly

Required text. The .NET assembly name that contains instructions to implement the Action element. The text should include the PublicKeyToken, Version and Culture.

Category

Optional text. Provides a category for the workflow action. This text is used to filter the list of available actions.

CreatesTask

Optional Boolean. If set to true, a task list item is created in the workflow. If left blank, the assumption is false and no task list items are created.

CreatesInList

Optional text. If a value is set for this attribute, the workflow creates an item in a list. Values must map to a parameter name that contains the ID of the list or document library.

AppliesTo

Required text. Indicates whether this workflow action should be available for lists, document libraries, or both. Valid values include list, doclib, and all.

ListModeration

Optional Boolean. If set to true, this Action element applies to a list or document library that has content approval enabled. If left blank, the assumption is false.

UsesCurrentItem

Optional Boolean. If set to true, indicates that the current item should be used or modified. If set to false or left blank, this Action element uses only the SharePoint list or document library item that is specified.

 

Actions Element

Windows SharePoint Services 3.0 provides a number of default actions to a declarative, code-free workflow editor, such as Microsoft Office SharePoint Designer 2007, that can be used to build workflows that address common business needs. However, complex business rules can sometimes require customized actions. You can use the Actions element to add custom workflow activities and expand the workflow actions available to you beyond those that are included in the default list.

Attributes

 

Attribute

Description

Parallel

Required text. If the user creating the workflow indicates that all workflow actions should be executed in parallel, the string defined in this attribute is used to join the Actions elements in the RuleDesigner sentence.

The default value for this attribute is and (which is defined in the WSS.ACTIONS file) and applies only to the English language version of Windows SharePoint Services . This value cannot be overridden in a custom .ACTIONS file.

Sequential

Required text. If the user creating the workflow indicates that all workflow actions should be executed in sequence, the string defined in this attribute is used to join the Actions elements in the RuleDesigner sentence.

The default value is then (which is defined in the WSS.ACTIONS file) and applies only to the English language version of Windows SharePoint Services .This value cannot be overridden in a custom .ACTIONS file.

 

Condition Element

Represents a Condition statement, which is part of a rule sentence that can be displayed in a declarative, rules-based, code-free workflow editor, such as Microsoft Office SharePoint Designer 2007.

When a workflow is triggered by an event corresponding to a SharePoint list or document library item in Windows SharePoint Services 3.0, it is often necessary to evaluate what workflow action should be taken or if an action is required. A Condition element allows the workflow to perform this evaluation with the values and arguments provided to it by the workflow editor.

Each Condition element also corresponds to a Boolean method inside a specified Windows SharePoint Services 3.0 workflow library. These methods are used to evaluate values passed by their parameters and return either true or false.

A Condition element contains information about the .NET assembly where the Condition code is implemented, as well as the parameters that are required to make the function call. It also contains information about how the Condition statement should be displayed to the workflow editor.

Attributes

 

Attribute

Description

AppliesTo

Required text. Specifies that the conditional statement being evaluated is applied to a SharePoint list or document library. By changing the value, you can show or hide a specific condition statement in the workflow editor, depending on the type of SharePoint list that the workflow is associated with.

The following values are not case sensitive.

 

Value

Description

all

Specifies that a condition statement is available to all list and document library types.

doclib

Specifies that a condition statement is visible to the workflow editor only when the workflow is associated with a document library. If the workflow is associated with any other type of list, the condition statement is hidden from the workflow editor.

list

Specifies that a condition statement is visible to the workflow editor only when the workflow is associated with a SharePoint list. If the workflow is associated with any type other than a list type, the condition statement is hidden from the workflow editor.

none

Specifies that a condition statement is hidden from the workflow editor.

 

 

Assembly

Required text. Specifies the .NET assembly that contains the implementation code for the Condition element.

 

Value Type

Description

String

Specifies the .NET assembly that contains the workflow code. The format should be as follows:

Assembly name, Version, Culture, PublicKeyToken

Example:
Assembly="Microsoft.SharePoint.
                             WorkflowActions,
                        Version=12.0.0.0,
                        Culture=neutral,
                        PublicKeyToken=  
                            71e9bce111e9429c"

ClassName

Required text. Contains the fully qualified class name in which the Condition element code is implemented.

 

Value Type

Description

String

Fully qualified class name in which the custom Condition element code is implemented. Example:

XML:
ClassName="Microsoft.
                           SharePoint.                           
                           WorkflowActions.
                           Helper"

FunctionName

Required text. Name of the Boolean method in the class that implements the Condition code.

 

Value Type

Description

String

Represents the method name in the class in which the Condition element code is implemented.

Example method:

Bool myCondition(WorkflowContext context, string ListGUIDorName, int ItemWorkflowAttachedTo)

XML:

FunctionName="myCondition"

Type

Optional text. Specifies whether the Condition element is Custom or Advanced.

The following values are not case sensitive.

 

Value

Description

Custom

Used to compare a value found in the current SharePoint list or document library item to a value specified by the workflow designer.

Advanced

Used to indicate that a Condition can be used to compare two values of any type (for example, text, integers, and dates).

UsesCurrentItem

Optional Boolean. Specifies that the item currently selected is associated with the workflow.

 

Value Type

Description

Boolean

If set to true, the workflow binds to the SharePoint list item or document library item that started the workflow instance. When using a declarative, code-free workflow editor, this value always returns true and cannot be changed.

 

Conditions Element

Conditions are used by declarative, rules-based code-free workflow editors, such as Microsoft Office SharePoint Designer 2007, to build workflows. Conditions are simply functions, in code, that return a Boolean value when called by Windows SharePoint Services 3.0.

When using a code-free workflow editor to develop workflows, conditions are presented to the workflow designer in the form of a list of phrases. Each of the conditions in this list has a corresponding function in code that is used to evaluate values provided either by the user or by Windows SharePoint Services 3.0.

The Conditions element is the parent element for all Condition elements.

Note   The attributes listed below are only read from the default WSS.ACTIONS file and cannot be overridden in any custom .ACTIONS files.

Attributes

 

Attribute

Description

And

Required text. The text defined in this attribute is displayed in the rule designer sentence when two or more conditions are used in the same conditional branch, and when all conditions must be satisfied before workflow actions can execute. The value is not case sensitive.

The default value is and (applies only to the English language version of Windows SharePoint Services 3.0.

Example:

<Conditions And="and">

Else

Required text. The text defined in this attribute is displayed in the rule designer sentence when a conditional branch activity is added to the workflow. The value is not case sensitive.

The default value is Else if (applies only to the English language version of Windows SharePoint Services 3.0).

Example:

<Conditions Else="Else if">

Not

Required text. The text defined in this attribute is displayed in the rule designer sentence when the condition must not contain a specified value or range of values. This value is not case sensitive.

The default value is Not.

Example:

<Conditions Not="not">

Or

Required text. The text defined in this attribute is displayed in the rule designer sentence when there are two or more conditions in the same conditional branch and any value will satisfy the conditions, allowing the workflow actions to execute. The value is not case sensitive.

The default value is or (applies only to the English language version of Windows SharePoint Services 3.0).

Example:

<Conditions Or="or">

When

Required text. The text defined in this attribute is displayed in the rule designer sentence when a conditional branch is added that requires the values or conditions that follow it to return true in order for the workflow actions to execute. The value is not case sensitive.

The default value is If (applies only to the English language version of Windows SharePoint Services 3.0).

Example:

<Conditions When="If">

 

 

Remarks

Each Conditions element can occur only once in an .ACTIONS file.

Default Element

The Default element is a container for other elements and has no definable attributes.

Note   The Default element is only read from the default WSS.ACTIONS file and cannot be overridden with a custom .ACTIONS file.

Attributes

 

None

 

Remarks

When you create workflows using a declarative, code-free workflow editor, such as Microsoft Office SharePoint Designer 2007, the .ACTIONS file that is installed on the server is combined into a single list of items and displayed to the workflow editor. Windows SharePoint Services 3.0 then searches for existing workflow conditions. If Windows SharePoint Services 3.0 finds a condition that is not represented by an entry in an .ACTIONS file, the Default element sentence is displayed for that condition.

FieldBind Element

The FieldBind element is a child of the RuleDesigner element. These elements are used together to create a readable sentence that describes a condition that needs to be evaluated or an activity that must be executed. When constructed properly, these elements can also be used to insert variables (such as hyperlinks) within the sentence, so that the code-free workflow editor can substitute dynamic values into the workflow while it is running. The FieldBind element maps the inputs from the workflow creator to parameters that are then passed to Windows SharePoint Services 3.0.

Attributes

 

Attribute

Description

DesignerType

Required text. Specifies the type of control or user input that is presented to the workflow creator when building sentences in the workflow editor.

Note   If you do not specify a DesignerType, the default DesignerType attribute is used. The default DesignerType is a text box followed by an ellipses button and a lookup button.

Note   A code-free workflow editor should treat the values returned to it from the server as case-insensitive.

Field

Required text. Represents a Parameter element used to build workflows. The Field attribute maps directly to one or more Parameter elements when a parameter type and direction are defined.

Note   If you use more than one parameter for a Field attribute, the parameter names should be separated by commas (for example, Field="Variable,ValueType").

Function

Optional Boolean. When set to true, this attribute inserts the name of the Action method into the sentence.

Id

Required Integer (non-negative). Id is used as the relational key between a FieldBind element and the Sentence property of the parent RuleDesigner element, much like a primary key is used in a database.

OperatorTypeFrom

Required text. Used only when DesignerType attribute is set to Operator. This attribute determines the types of operators that are available to the user, based on the .NET data type listed in the corresponding Parameter element. The parameter specified for the OperatorTypeFrom attribute can be different from the parameter listed in the Field attribute.

Text

Required text. Text displayed to the user as a hyperlink in the condition sentence.

TypeFrom

Optional text. Specifies the .NET data types that are valid for use with an instance of the FieldBind element. The TypeFrom attribute is associated with a Parameter element that contains the type definition.

Value

Reserved for future use.

 

DesignerType Attribute

 

Value

Data Bound

Default Builder

Show Drop-down

Adv-
anced Builder

Control Description

Boolean

Yes

No

Yes

No

Drop-down list box with the choices true and false populated.

ChooseDoclibItem

No

No

No

Yes

Document library item selector.

ChooseListItem

No

No

No

Yes

Default.

CreateListItem

No

No

No

Yes

Default.

Date

Yes

Yes

No

No

Date/Time selector.

Dropdown

No

No

Yes

No

Drop-down list box control. Static items can be populated by adding Option elements.

Email

No

No

No

Yes

E-mail advanced control. The form displays standard e-mail fields including To, From, CC, Subject and Body.

FieldNames

No

No

Yes

No

Drop-down list box control populated with all field names in the current list or document library.

Float

Yes

No

No

No

Text box. Allows entry of floating point values.

Hyperlink

Yes

Yes

No

No

URL browser. Select local or remote resources using a standard link builder.

Integer

Yes

No

No

No

Text box. Accepts non-negative integer values.

ListNames

No

No

Yes

No

Drop-down list box control populated with all lists in the current Web site.

Operator

No

No

Yes

No

Drop-down list box control that includes operators used to evaluate each side of the RuleDesigner sentence. Operators are static and must be added in Options elements.

ParameterNames

No

No

Yes

No

Drop-down list box populated with all local variables that have been entered for use by the workflow.

Person

Yes

Yes

No

No

Person or Group selector. You can choose only one person or group from either built-in, local users or groups or users and groups from a domain.

SinglePerson

Yes

Yes

No

No

Person or Group selector. You choose only one person or group from either built-in, local users or groups or users and groups from a domain.

Stringbuilder

No

No

No

Yes

Inline text box editor. Use to create simple strings.

Survey

No

No

No

Yes

Default.

Text

Yes

No

No

No

Default.

TextArea

Yes

Yes

No

No

Default.

UpdateListItem

No

No

No

Yes

Default.

writablefieldNames

No

No

Yes

No

Drop-down list box populated either with a list of fields in the current list or a list of document libraries that are editable. All other fields are hidden.

 

Properties of DesignerTypes

Property

Description

Data Bound

Control that can be data bound to a SharePoint list or document library item.

Default Builder

Displays a button with ellipses. Depending on the DesignerType, this property opens either a Date/Time or Text Editor dialog box.

Show Dropdown

Displays a control for a drop-down list box. Depending on the DesignerType, the values may be populated. You can add Options elements to any Show DropDown controls that are not already populated.

Advanced Builder

Displays advanced builders based on the DesignerType. Advanced DesignerTypes can have multiple properties. For example, the e-mail advanced builder allows entry of To, From, CC, Subject and Body fields.

 

Option Element

Used to populate DesignerType drop-down list box controls that are not data bound. Option elements contain text and value pairs that can be used to build a workflow sentence. They also contain information about their .NET data types.

Attributes

 

Attribute

Description

Name

String. The value displayed in the drop-down list box control.

TypeFilter

String. Used only if the parent FieldBind DesignerType is Operator. The TypeFilter attribute allows options to be hidden or displayed in the workflow editor, based on the data type of the parent element.

You can define multiple types for the TypeFilter attribute but they must be separated by commas.

UnaryHides

String. Used only if the parent FieldBind RuleDesigner type is Operator. The value specified in this attribute should be synchronized with the Field attribute of a FieldBind element. If this option is selected, then the FieldBind specified here will be hidden from the workflow editor.

Value

String. Represents the value of the selected drop-down list item.

 

Value Attribute

The following table contains attribute values that are used with a TypeFilter attribute of Operator that performs conditional comparisons. Custom values can be substituted.

 

Value

Description

Equal

Returns true if queried values are equal. Case sensitivity must match.

EqualNoCase

Returns true if queried values are equal. Case sensitivity does not need to match.

NotEqual

Returns true if queried values are not equal. Case sensitivity must match.

NotEqualNoCase

Returns true if queried values are not equal. Case sensitivity does not need to match.

StartsWith

Returns true if queried values start with a specific pattern.

NotStartsWith

Returns true if queried values do not start with a specific pattern.

EndsWith

Returns true if queried values end with a specific pattern.

NotEndsWith

Returns true if queried values do not end with a specific pattern.

Contains

Returns true if queried values contain the specified pattern.

NotContains

Returns true if queried values do not contain the specified pattern.

ContainsNoCase

Returns true if queried values contain the specified pattern.

Matches

Returns true if queried values match a specified regular expression.

IsEmpty

Specifies empty string.

Parameter Element

Used to describe the input and output parameters for a custom Actions or Conditions method call.

Attributes

 

Attribute

Description

Type

Required String. Partially qualified .NET data type. Values are not case sensitive.

Example:

System.Object, mscorlib

Direction

Optional text. Specifies an input or output parameter. Valid values are In and Out. Values are not case sensitive.

Name

Required text. Used to associate the FieldBind element with the parameter. Values are not case sensitive.

InitialValue

Optional text. Used to specify the default initial value that is passed to the parameter. Values are not case sensitive.

 

Parameters Element

Container for all Parameter elements and contains no definable attributes. Includes the descriptions of the parameters in a condition or action method signature.

The Parameters element is a complex element type and can be used with both Actions and Conditions elements to define their parameters.

Attributes

 

None

 

 

RuleDesigner Element

Complex type element. The RuleDesigner element contains information needed to render a workflow sentence in a declarative, code-free workflow editor such as Microsoft Office SharePoint Designer 2007.

Attributes

 

Attribute

Description

Sentence

Required text. Text displayed in the workflow editor that represents the workflow rule. The rule sentence can contain static text as well as text dynamically generated at run time.

Variables can be embedded into the sentence using the notation %1, %2, and so on. Each variable maps to a FieldBind element Id. Then, during workflow design, the text displayed for these variables is the Text attribute of the FieldBind element.

 

WorkflowInfo Element

WorkflowInfo is the root element of the Actions schema. This element must be included in any .ACTIONS file that is installed on the server.

Attributes

 

Attribute

Description

Language

Refers to the language of the server, not the client. This is notated as a language/culture pair. For example "en-us" is used to specify "English-United States" (See Locale Identifier Constants and Strings).