Microsoft SharePoint Developer Documentation Team Blog The Official Blog of the SharePoint Developer Documentation Team
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.
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.
Required text. Represents the description of the workflow action that is displayed to the workflow editor.
Required text. Fully qualified name of the class that implements the workflow action. For example: Microsoft.SharePoint.
Required text. The .NET assembly name that contains instructions to implement the Action element. The text should include the PublicKeyToken, Version and Culture.
Optional text. Provides a category for the workflow action. This text is used to filter the list of available actions.
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.
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.
Required text. Indicates whether this workflow action should be available for lists, document libraries, or both. Valid values include list, doclib, and all.
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.
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.
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.
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.
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.
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.
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.
Specifies that a condition statement is available to all list and document library types.
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.
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.
Specifies that a condition statement is hidden from the workflow editor.
Required text. Specifies the .NET assembly that contains the implementation code for the Condition element.
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=126.96.36.199, Culture=neutral, PublicKeyToken= 71e9bce111e9429c"
Required text. Contains the fully qualified class name in which the Condition element code is implemented.
Fully qualified class name in which the custom Condition element code is implemented. Example:
XML:ClassName="Microsoft. SharePoint. WorkflowActions. Helper"
Required text. Name of the Boolean method in the class that implements the Condition code.
Represents the method name in the class in which the Condition element code is implemented.
Bool myCondition(WorkflowContext context, string ListGUIDorName, int ItemWorkflowAttachedTo)
Optional text. Specifies whether the Condition element is Custom or Advanced.
Used to compare a value found in the current SharePoint list or document library item to a value specified by the workflow designer.
Used to indicate that a Condition can be used to compare two values of any type (for example, text, integers, and dates).
Optional Boolean. Specifies that the item currently selected is associated with the workflow.
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 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.
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.
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).
<Conditions Else="Else if">
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.
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).
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).
Each Conditions element can occur only once in an .ACTIONS file.
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.
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.
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.
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.
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").
Optional Boolean. When set to true, this attribute inserts the name of the Action method into the sentence.
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.
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.
Required text. Text displayed to the user as a hyperlink in the condition sentence.
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.
Reserved for future use.
Drop-down list box with the choices true and false populated.
Document library item selector.
Drop-down list box control. Static items can be populated by adding Option elements.
E-mail advanced control. The form displays standard e-mail fields including To, From, CC, Subject and Body.
Drop-down list box control populated with all field names in the current list or document library.
Text box. Allows entry of floating point values.
URL browser. Select local or remote resources using a standard link builder.
Text box. Accepts non-negative integer values.
Drop-down list box control populated with all lists in the current Web site.
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.
Drop-down list box populated with all local variables that have been entered for use by the workflow.
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.
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.
Inline text box editor. Use to create simple strings.
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.
Control that can be data bound to a SharePoint list or document library item.
Displays a button with ellipses. Depending on the DesignerType, this property opens either a Date/Time or Text Editor dialog box.
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.
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.
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.
String. The value displayed in the drop-down list box control.
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.
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.
String. Represents the value of the selected drop-down list item.
The following table contains attribute values that are used with a TypeFilter attribute of Operator that performs conditional comparisons. Custom values can be substituted.
Returns true if queried values are equal. Case sensitivity must match.
Returns true if queried values are equal. Case sensitivity does not need to match.
Returns true if queried values are not equal. Case sensitivity must match.
Returns true if queried values are not equal. Case sensitivity does not need to match.
Returns true if queried values start with a specific pattern.
Returns true if queried values do not start with a specific pattern.
Returns true if queried values end with a specific pattern.
Returns true if queried values do not end with a specific pattern.
Returns true if queried values contain the specified pattern.
Returns true if queried values do not contain the specified pattern.
Returns true if queried values match a specified regular expression.
Specifies empty string.
Used to describe the input and output parameters for a custom Actions or Conditions method call.
Required String. Partially qualified .NET data type. Values are not case sensitive.
Optional text. Specifies an input or output parameter. Valid values are In and Out. Values are not case sensitive.
Required text. Used to associate the FieldBind element with the parameter. Values are not case sensitive.
Optional text. Used to specify the default initial value that is passed to the parameter. Values are not case sensitive.
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.
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.
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 is the root element of the Actions schema. This element must be included in any .ACTIONS file that is installed on the server.
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).
Around the time work started on a long whitepaper about migrating content files from SharePoint server "A" to SharePoint server "B" using the migration and deployment APIs in the Microsoft.SharePoint.Deployment namespace, I came across a series of blog posts by Stefan Goβner that covered the subject matter in detail. Many of you have probably seen Stefan's work: Deep Dive into the SharePoint Content Deployment and Migration API, Parts 1-5.
I contacted Stefan and he agreed to collaborate. He's allowed me to use some of his code examples, and to expand on some of his points. Additionally, I've collaborated with the feature PM and lead developer on the migration/deployment APIs here at Microsoft, Patrick Simek, so the whitepaper treats the subject quite a bit more broadly than does Stefan's blog posts.
I'll chunk this article up into segments for posting to this blog. Comments are DEFINITELY welcome. I'll be converting much of the content of this article (and these posts) into Help content in the SharePoint SDK documentation, so anything that helps to improve the quality of the content is highly desired. Here's the first section:
Many scenarios require moving content from one SharePoint site to another. When the scenario calls for a full migration (that is, moving the entire contents of a SharePoint site or site collection), the task is relatively simple. Typically, you use either of two main approaches:
However, both of these methods have limitations. Both limit you to migrating only a full SharePoint site, or site collection. In addition, neither allows you to retain object identity during the migration operation. Retaining object identity is an essential feature of selective migration. Using Stsadm.exe and Sites Web service have other limitations as well.
Consequently, content migration scenarios that require you to export only selected content, or that require you to automate or customize migration operations, there is only one approach: you must write a custom solution that uses the APIs in the Microsoft.SharePoint.Deployment namespace.
Note Selective migration operates when there is an established source and a recognized destination for a known quantity of content. That is, selective migration requires that a full migration was initially performed so that the destination is a mirror image of the source.
Selective migration applies, typically, to content that needs to be migrated from server to server based on factors such as content version (current vs. future), time stamp, and content state (approved vs. in review, for example). Selection criteria provides a high degree of granularity from the scope of the site collection down; that is, you have selection control at the scope of the Web, the list, folder, and list item.
You can have any number of .cmp files in a migration operation, and you can also have multiple destinations. However, the objects contained in a given content migration package (.cmp) file must originate from a single site collection.
Typical Migration Scenarios
The APIs in the Microsoft.SharePoint.Deployment namespace provide a rich migration toolbox that gives you an enormous degree of flexibility to support wide ranging migration scenarios. Following is a list of migration and deployment features that are supported in Windows SharePoint Services 3.0. This list is only a high-level, generalized summary of supported migration scenarios. The Deployment APIs are sufficiently rich to support any number of special circumstances that you might face.
In my next post we'll continue with this high-altitude look at the subject of content migration. There, we'll talk extensively about key concepts in the migration/deployment feature area.
.ACTIONS files are used by Windows SharePoint Services 3.0 to compile a list of code-free workflow actions and conditions. The default file provided by Windows SharePoint Services 3.0 is called the WSS.ACTIONS file found under C:\Program Files\Common Files\Microsoft Shared\web server extensions\12.
By creating additional .ACTIONS files and placing them into the same directory, Windows SharePoint Services will read all of the files and create a single list of available workflow actions and conditions and present them to SharePoint Designer 2007 in the form of a cohesive, categorized list that can be used to build more complex workflows.
The following is an example of how to construct this file.
<?xml version="1.0" encoding="utf-8"?><WorkflowInfo Language="en-us"> <Conditions And="and" Else="Else If" Not="not" Or="or" When="If"> <Condition AppliesTo="list" Assembly="Assembly.Name, Version=0.0.0.0, Culture=neutral, PublicKeyToken=GUID" ClassName="Fully qualified class name" FunctionName="Boolean method name implemented in class" Name="Name to be displayed in workflow editor" Type="Advanced" UsesCurrentItem="true"> <RuleDesigner Sentence="Sentence to be displayed to the workflow editor"> <FieldBind DesignerType="Date" Field="Parameter that FieldBind maps to" Function="true" Id="Unique positive Integer" Text="Text to be displayed as a hyperlink" TypeFrom="Parameter that a non-Operator derives its type from" Value="Reserved for future use"> <Option Name="Option1" Value="Value1" /> </FieldBind> </RuleDesigner> <Parameters> <Parameter Direction="In" InitialValue="" Name="MyParameter" Type="System.String, mscorlib" /> </Parameters> </Condition> </Conditions> <Actions> <Action Name="Action name displayed in editor"> <RuleDesigner Sentence="Sentence to be displayed to the workflow editor"> <FieldBind DesignerType="CreateListItem" Field="Parameter that FieldBind maps to" Function="true" Id="Unique positive Integer" OperatorTypeFrom="Parameter Operator derives its type from" Text="Text to be displayed as a hyperlink" TypeFrom="Parameter non-Operator derives its type from" Value="Reserved for future use"> </FieldBind> </RuleDesigner> </Default> </Actions></WorkflowInfo>In my next post I will start going into details of each of the elements, so stay tuned.
Last week we added five new Resource Center pages to the Windows SharePoint Services developer portal on MSDN. Each Resource Center page focuses on a specific area of developer functionality in SharePoint, and contains links to information and resources from around the web, be it any source (Microsoft sites, sure, but also partners, consultants, MVPs, or anyone else who’s got useful information to share) and in any format (technical articles, blogs, Web casts, video downloads, you name it). Think of them as one-stop-shops for developer information around specific areas of interest.
Here are the five areas for which we added Resource Center pages:
· Pages and User Interface
· Web Parts
These are in addition to the Resource Center pages already up on the Office SharePoint Server developer portal:
· Business Data Catalog
· Enterprise Content Management
· Enterprise Search
· Excel Services
· Web Content Management
In the near future, we plan on adding more Resource Centers for areas such as upgrade and migration, deployment, email and alerts, and content management.
So what would you like to see in our Resource Centers?
If you’ve know of resources you think should be added to our existing Resource Center pages, or have areas you think warrant Resource Centers of their own, let us know! Just add a comment to this post, or email the blog directly. We’d love to hear from you.
Welcome to the official blog of the SharePoint Products and Technologies developer documentation team. My name is Andrew May; I’m a Content Publishing Manager for Windows SharePoint Services. My team produces the Windows SharePoint Services SDK, along with the developer help for SharePoint Designer. We also manage the Windows SharePoint Services and SharePoint Designer developer portals. My cohort, Randall Isenhour, manages the team responsible for the Office SharePoint Server and Project SDKs, along with the Office SharePoint Server and Project developer portals.
We created this blog in order to be able to:
· Present “draft” versions of SDK content before it’s available in the SDKs themselves. These drafts are tech-reviewed content that will end up in the SDKS; this is just our way of getting the information out to you as quick as we can.
· Promote content that we publish on MSDN. This includes giving you the latest news on new technical articles, SDK updates, code samples or tools downloads, and anything else new and noteworthy we think you’ll want to take a look at.
· Blog about the developer documentation we produce, and why. Ever wonder why we document what we do, in the way we do? In future posts we’ll explore the decisions we make when planning SharePoint developer documentation, and the data we base those decisions on.
· Engage with users, and find out just how developers are using (or would like to use) the documentation we produce.
· Experiment with presenting developer documentation in new and different formats.
So stay tuned. Over the next few days we plan introduce some of the writer on our teams, and to give you a first look at some documentation that’ll be included in the next updates of the WSS and MOSS SDKs.
And if you’ve got anything you want to talk about regarding SharePoint developer documentation, post a comment or drop us an email. We’d love to hear from you.
Erika Ehrli has the scoop on Office’s participation in the MSDN machine translation pilot project. As part of the pilot, you can try out beta versions of the machine-translated Windows SharePoint Services 3.0 and Office SharePoint Server 2007 SDKs in Portuguese. You can also test out beta versions of the machine-translated Office SharePoint Server TechNet materials in Spanish and Portuguese, side-by-side view with the original English content.
Erika has all the details here.