Workflow Actions Files

A workflow actions file (.actions) is an XML file that describes how SharePoint Designer should interact with your workflow activities. Primarily, this file provides a human-readable sentence structure that is wrapped around the mechanics of your activity. The workflow actions file consists of a parent WorkflowInfo element that can contain conditions and actions.

<WorkflowInfo>
  <Conditions And="and" Or="or" Not="not" When="If" Else="Else if">
    ...
  </Conditions>
  <Actions Sequential="then" Parallel="and">
    ...  
  </Actions>
</WorkflowInfo>

In the Conditions and Actions elements, the attribute values specify the sentence constructs that SharePoint Designer should use to describe the workflow when your activities are used in a particular way. For example, if two activities are used sequentially, SharePoint Designer will describe the workflow as activity Athenactivity B. If two activities are used in parallel, the resulting sentence will be activity Aandactivity B. In the Workflow Activities Reference Implementation (Workflow Activities RI), the workflow actions file is named ExecutionModels.actions.

Defining Actions

The Action element describes the CreateSubSiteActivity class. First, the Action element identifies the class name and assembly name for the workflow activity.

<Action Name="Create a Sub-Site" 
  ClassName="ExecutionModels.Workflow.FullTrust.Activities.CreateSubSiteActivity" 
  Assembly="ExecutionModels.Workflow.FullTrust.Activities, ..."
  AppliesTo="all" 
  Category="Patterns and Practices">

Next, a RuleDesigner element defines a sentence that will represent the workflow activity in SharePoint Designer. The sentence includes placeholders that are filled by parameters (which are defined in the next part of the Action element). The FieldBind child elements are used to map parameters to the placeholders in the rule designer sentence, as shown in the following code example. Some of the FieldBind elements have been removed from this example to aid readability.

<RuleDesigner Sentence="Create subsite at %3 using the site template %4 using the title %5 and description %6 and locale of %7.  The site will be converted if exists? %2 The site will use unique permissions? %1">        
  <FieldBind
           Field="UseUniquePermissions"                  
           DesignerType="Boolean"
           Text="Use unique permissions for the sub-site"
           Id="1"/>
  <FieldBind
           Field="ConvertIfExists"   
           DesignerType="Boolean"
           Text="Convert the sub-site to the template if it already exists"
           Id="2"/>
  <FieldBind
           Field="SiteUrl"
           DesignerType="Hyperlink"
           Text="The full URL of the site"
           Id="3"/>
  ...
</RuleDesigner>

Next, a Parameters element defines the inputs and outputs for the activity class, as shown in the following code example. Each parameter maps to a dependency property in the activity class. The parameters are referenced by the FieldBind elements shown in the preceding code example. Some of the Parameter elements have been removed from this example to aid readability.

<Parameters>
  <Parameter
           Name="UseUniquePermissions"
           Type="System.Boolean, mscorlib"
           DisplayName="Use unique permissions"
           Direction="In" />
  <Parameter
           Name="ConvertIfExists"
           Type="System.Boolean, mscorlib"
           DisplayName="Convert if exists"
           Direction="In" />
  <Parameter
           Name="SiteUrl"
           Type="System.String, mscorlib"
           Direction="In" />
  ...
</Parameters>

The second Action element, which describes the CreateSiteCollectionActivity class, follows a similar pattern.

Defining Conditions

The ExecutionModels.actions file includes a single Condition element that describes the SiteExistsActivity class.

<Condition 
    Name="Site Exists"
    FunctionName="DoesSiteExistCondition"        
    ClassName="ExecutionModels.Workflow.FullTrust.Activities.SiteExistsActivity"
    Assembly="ExecutionModels.Workflow.FullTrust.Activities, ..."
    AppliesTo="all"
    UsesCurrentItem="True">
  <RuleDesigner Sentence="The site %1 exists">
    <FieldBind Id="1" Field="_1_" Text=""/>
  </RuleDesigner>
  <Parameters>
    <Parameter Name="_1_" Type="System.String, mscorlib" Direction="In" />
  </Parameters>
</Condition>

This Condition element has a few key differences from the Action elements described earlier. First, you must provide a FunctionName attribute value to indicate that the condition logic is invoked through the DoesSiteExistCondition method. Next, note the naming convention for parameters. The parameter that will represent the site URL is named "_1_". This is because it is the first non-default argument that is provided to the DoesSiteExistCondition method. Additional parameters should be named "_2_", "_3_", and so on. It is essential to use this naming convention when you define a condition.

Deploying a Workflow Actions File

Workflow actions files are deployed to the TEMPLATE\[Locale ID]\Workflow folder in the SharePoint root folder (for example, TEMPLATE\1033\Workflow). The best way to deploy files to the SharePoint root from a Visual Studio 2010 project is to add a SharePoint mapped folder to your project. This creates a folder within your project that maps to a folder on the SharePoint file system. When you deploy your solution, any files in your mapped folder are added to the corresponding location on the SharePoint file system.

Note

To add a SharePoint mapped folder, right-click the project node in Solution Explorer, point to Add, and then click SharePoint Mapped Folder. This launches a dialog box that lets you browse the SharePoint file system and select a folder to map.

In the Workflow Activities RI, a SharePoint mapped folder maps to the SharePoint root folder on the file system. Within the mapped folder, there is the TEMPLATE\1033\Workflow subfolder and the ExecutionModels.actions file, as shown in the following illustration.

Using SharePoint mapped folders to deploy a workflow actions file

When you deploy your workflow actions file to this location, SharePoint automatically detects the new actions, and they are made available in SharePoint Designer for use in declarative workflows.

Note

In the Workflow Activities RI, there could also have been a mapped folder for the TEMPLATE\1033\Workflow folder directly. The reason for mapping the SharePoint root folder is to better illustrate the target folder structure on the server file system, and to allow for the addition of workflow action files for other locales at a later time.