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.


 



















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).


 



 

Comments (10)

  1. JessGordon says:

    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 know

  2. RodneyFarris says:

    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 Farris

  3. Now that I’m managing a documentation team, I just don’t get to blog about SharePoint developer issues

  4. [Cross-posting from Andrew May’s blog …] Now that I’m managing a documentation team, I just don’t get

  5. Una vez más, en esta nueva entrega recogemos el recopilatorio de enlaces, recursos y diferentes elementos

  6. saranga says:

    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>

  7. DNelsonPMP says:

    Is is possible to create conditions in a Designer Workflow that evaluates the status of an Out of the Box workflow (e.g., Approval Workflow)?

  8. Alexander Gorlach says:

    Hi partners,

    btw, we make the product which contains 170+ ready to use workflow actions for SharePoint 2010. Including the one to execute C#/VB.NET code from workflows, it may help to avoid custom coding.

    The full list of actions is here: http://www.harepoint.com/…/ListActivities.aspx

    The product is free to download from our site: http://www.harepoint.com/…/HarePointWorkflowExtensions

    Hope, it save to you time and money.

    WBR, Alexander

  9. Aaliya says:

    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 them

  10. Mike (Certified SP Developer) says:

    [quote]

    Alexander Gorlach

    26 Sep 2011 4:17 AM

    The product is free to download from our site: http://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?

Skip to main content