Extending Workflow Actions for SharePoint Designer
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.
|
||||||||||
Assembly |
Required text. Specifies the .NET assembly that contains the implementation code for the Condition element.
|
||||||||||
ClassName |
Required text. Contains the fully qualified class name in which the Condition element code is implemented.
|
||||||||||
FunctionName |
Required text. Name of the Boolean method in the class that implements the Condition code.
|
||||||||||
Type |
Optional text. Specifies whether the Condition element is Custom or Advanced. The following values are not case sensitive.
|
||||||||||
UsesCurrentItem |
Optional Boolean. Specifies that the item currently selected is associated with the workflow.
|
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. |
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). |
Comments
Anonymous
November 14, 2007
Hi: I started reading this BLOG and though 'this is valuable stuff!' Then I came across the first table (Action - Attributes) - the right part is cut off. Same further down with the DesigerType Atrributes - right side cut off. I am using IE 7.0.6000.16546 so this ought not to be a browser issue. Thought you'd like to knowAnonymous
November 15, 2007
Yeah, I apologize for that. Converting this from an SDK document to a blog post is rife with HTML oddities. I've narrowed the columns on the tables so that you can see all the information now. There are a couple of gridlines missing on the wider tables, but all the info is there. Thanks for letting me know! Rodney FarrisAnonymous
December 04, 2007
Now that I’m managing a documentation team, I just don’t get to blog about SharePoint developer issuesAnonymous
December 16, 2007
[Cross-posting from Andrew May's blog ...] Now that I’m managing a documentation team, I just don’t getAnonymous
December 23, 2007
Una vez más, en esta nueva entrega recogemos el recopilatorio de enlaces, recursos y diferentes elementosAnonymous
November 06, 2009
Great post !!! Developing custom workflow action is very easy, try this, <a href="http://sarangasl.blogspot.com/2009/11/sharepoint-workflow-actions-for.html"><b>SharePoint Workflow Actions for Designer in Visual Studio</b></a>Anonymous
February 03, 2010
The comment has been removedAnonymous
September 25, 2011
The comment has been removedAnonymous
October 25, 2011
Hi, my company is using SharePoint 2007 and I am creating a vacation calendar that requires anyone to input vacation to get approval from their manager. When I created an approval workflow, how do you set a workflow to choose which manager to send the approval to? Right now if I put 3 approvers names it sends to all of themAnonymous
August 22, 2012
[quote] Alexander Gorlach 26 Sep 2011 4:17 AM The product is free to download from our site: www.harepoint.com/.../HarePointWorkflowExtensions [/endquote] Um, for the record that is not free. It is a free trial. Can anyone recommend a good set of activies that are truely free to extend SharePoint® 2010?