How to: Create and Deploy Workflow Actions in Sandboxed Solutions

Article
10/20/2016

This topic describes how to create and deploy a custom workflow action in a sandboxed solution in Microsoft SharePoint.

Applies to: SharePoint Foundation 2010

After the custom action is deployed, it is available for use in a declarative workflow designer such as Microsoft SharePoint Designer.

Tip

For another example, see How to: Create a Sandboxed Workflow Action.

Creating the Workflow Action

If you want to make a custom workflow action available for use in SharePoint Designer by users of a site collection, but you do not have permission to install a farm solution, you can install the action in a sandboxed solution. The process is different from how you would create and install a custom workflow action in a farm solution in two ways:

You must create a custom class and method that is called by the workflow engine and that runs in the sandboxed worker process. This method will constitute the workflow activity of the custom workflow action.
The declarative markup that defines the workflow action for SharePoint Designer is deployed in a Feature manifest to the content database, instead of in an .actions file to the file system of the front-end web servers, and the WorkflowActions markup used in the Feature manifest is somewhat different from the WorkflowInfo markup used in an .actions file.

To create the activity method

Start a Microsoft Visual Studio SharePoint project. It can be any of the project types that are allowed in sandboxed solutions, including Empty SharePoint Solution. (It cannot be Business Data Connectivity Model, Site Template, Visual Web Part, Sequential Workflow, or State Machine Workflow.)
In Solution Explorer, double-click the .feature file to open the Feature Designer.
In the Feature Designer, set the Scope to Site.
Add a Class item to the project.
Give the class and namespace appropriate names, and add using statements for System.Collections, Microsoft.SharePoint, and Microsoft.SharePoint.UserCode.

Declare in the class a method that will contain the logic for your custom workflow activity. It must meet the following conditions:

It must be public.
It must be static.
It must return a Hashtable object.
It must take, as its first parameter, a SPUserCodeWorkflowContext object. (It can have additional parameters as needed.)

The following is an example of what you should have at this point.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

using System.Collections;
using Microsoft.SharePoint;
using Microsoft.SharePoint.UserCode;

namespace Contoso.SharePoint.Workflow.Actions
{
    class ListCreation
    {
        public static Hashtable CreateList(SPUserCodeWorkflowContext context, String listTitle, String listDescription, String listType)
        {

        }
    }
}

Specify the logic of the activity inside the method.

Important

This method will run inside a sandboxed worker process, so it must conform to the restrictions on what can be done in that process. For example, the code cannot access anything outside the current site collection, nor can it read or write to the server's file system. For more information see Restrictions on Sandboxed Solutions in SharePoint 2010

The following continues the preceding example.

public static Hashtable CreateList(SPUserCodeWorkflowContext context, String listTitle, String listDescription, String listType)
{
    using (SPSite siteCollection = new SPSite(context.SiteUrl))
    {
        SPWeb currentWeb = siteCollection.OpenWeb(context.WebUrl);  
        SPListTemplateCollection availableListTypes = currentWeb.ListTemplates;
        SPListTemplate listTemplate = availableListTypes[listType];
        Guid listID = currentWeb.Lists.Add(listTitle, listDescription, listTemplate);
        Hashtable result = new Hashtable();
        result["ListID"] = listID.ToString();
        return result;
    }
}

To create the WorkflowActions markup

In the project, add an Empty Element item from the SharePoint 2010 templates in Visual Studio.
In Solution Explorer, open the Elements.xml file.
Add a WorkflowActions element as a child of the Elements element.

Add an Action child element to the WorkflowActions element, and set its attributes. The following is an example.

<Action Name="Create a List" 
        SandboxedFunction="true" 
        Assembly="$SharePoint.Project.AssemblyFullName$" 
        ClassName="Contoso.SharePoint.Workflow.Actions.ListCreation" 
        FunctionName="CreateList" 
        AppliesTo="all" 
        UsesCurrentItem="true"
        Category="Contoso Actions">
</ Action>

Add a RuleDesigner child to the Actions element, and specify its Sentence attribute.

<RuleDesigner Sentence="Create a %1 list named %2, and described as %3">

</RuleDesigner>

For each variable field in the Sentence, add a FieldBind child element, and configure its attributes.
```
<RuleDesigner Sentence="Create a %1 list named %2, and described as %3">
  <FieldBind Id="1" Field="listType" DesignerType="Text" Text="list type"/>
  <FieldBind Id="2" Field="listTitle" DesignerType="Text" Text="list name"/>
  <FieldBind Id="3" Field="listDescription" DesignerType="Text" Text="description"/>
</RuleDesigner>
```
Note

Although the previous example of a RuleDesigner does not use the Hashtable returned by the activity method, it is possible to use the returned value in a rule. If you do, there must be a FieldBind element for it in the RuleDesigner element. For example, you could add "Result: %4" to the Sentence attribute of the Action element, and then add an additional FieldBind element like this: <FieldBind Id="4" Field="result" DesignerType="Text" Text="ID of new list"/>.

Warning

Do not add a FieldBind element for any parameter that is not referenced in your Sentence. Doing this does not prevent the workflow action from being deployed, but users will receive an error that they cannot fix when they try to use the action in a workflow.
Because the workflow engine will call your custom activity method, not your own code, you must tell it about the parameters of the method. Add a Parameters Element (WorkflowInfo) to the Action element.
The first parameter that is defined is always the mandatory SPUserCodeWorkflowContext parameter, and the markup for it is always the same. It is shown in this example.
```
<Parameters>
  <Parameter Name="__Context" Type="Microsoft.SharePoint.WorkflowActions.WorkflowContext, Microsoft.SharePoint.WorkflowActions" Direction="In" DesignerType="Hide" />
</Parameters>
```
Note that the type is identified as Microsoft.SharePoint.WorkflowActions.WorkflowContext, not Microsoft.SharePoint.UserCode.SPUserCodeWorkflowContext. This is because the workflow engine generates an SPUserCodeWorkflowContext object from property values in a WorkflowContext object.
Add another Parameter element for each of the FieldBind elements that you added to the RuleDesigner element. The Name attribute of the Parameter element must match the value of the Field attribute of the corresponding FieldBind element. The following continues the ongoing example.
```
<Parameters>
  <Parameter Name="__Context" Type="Microsoft.SharePoint.WorkflowActions.WorkflowContext, Microsoft.SharePoint.WorkflowActions" Direction="In" DesignerType="Hide" />
  <Parameter Name="listType" Type="System.String, mscorlib" Direction="In" DesignerType="TextBox"/>
  <Parameter Name="listTitle" Type="System.String, mscorlib" Direction="In" DesignerType="TextBox" />
  <Parameter Name="listDescription" Type="System.String, mscorlib" Direction="In" DesignerType="TextBox" />
</Parameters>
```
Note

If you have a FieldBind element for the returned value, you must also have a Parameter element for it. The value of the Direction attribute of the Parameter is "Out"; for example, <Parameter Name="result" Type="System.String, mscorlib" Direction="Out" DesignerType="ParameterNames" />
Build and package the solution and make the SharePoint solution package (.wsp file) available to site collection administrators.

Deploying and Testing the Workflow Action

The sandboxed solution is installed and deployed by the site collection administrator, who installs the solution to the site collection's Solutions Gallery. There are two steps to this process.

To deploy the workflow action to a site collection

The site collection administrator uploads the solution package to the gallery.
The site collection administrator deploys the package, which is called "activation" for sandboxed solutions. This step automatically activates any Features in the package. If any solution validators are registered with the site collection, they also execute at the activation (deployment) stage.

If the solution passes validation and has not been blocked by a farm administrator, it is ready for use on the site collection.

To test the workflow action

Open a website on which the Feature in your solution has been activated.
On the Site Actions menu, select Edit in SharePoint Designer.
Create a workflow that uses the new workflow action and test it. The following steps test the workflow action in the ongoing example.
1. After you open the website (that has an Announcements list) in SharePoint Designer, click Workflows in the Navigation pane.
2. On the ribbon, click List Workflow, and select Announcements in the drop-down list.
3. In the Create List Workflow dialog box, in the Name box, type Return From Trade Show, and then click OK.
4. In the workflow design surface, click Condition on the ribbon, and then select If current item field equals value in the drop-down list. The condition If field equals value appears in step 1.
5. Click the field link, and select Title in the drop-down list.
6. Click the equals link, and select ends with in the drop-down list.
7. Click the value link, and type trade show in the text box that opens. Press Enter.
8. Click the (Start typing area below the condition to give it focus.
9. On the ribbon, click Action. You will see your new category Contoso Actions on the drop-down list and the new action Create a list in the list.
10. Select Create a list. The "sentence" that you defined in your Action element appears.
11. Click the list type link, and type Contacts in the text box that opens. Press Enter.
12. Click the list name link, and click the ellipsis button (...) to open the String Builder dialog box.
13. Type Contacts met at (with a space at the end) in the text box.
14. Click the Add or Change Lookup button. This opens the Lookup for String dialog box.
15. In the Data source drop-down list, select Current Item.
16. In the Field from source drop-down list, select Title.
17. Click OK to close the dialog box, and then click OK again to close the String Builder dialog box.
18. Click the description link, and click the ellipsis button (...) to open the String Builder dialog box.
19. Type These are contacts we made at the (with a space at the end) in the text box.
20. Click the Add or Change Lookup button. This opens the Lookup for String dialog box.
21. In the Data source drop-down list, select Current Item.
22. In the Field from source drop-down list, select Title.
23. Click OK to close the dialog box, and then click OK again to close the String Builder dialog box.
  
  Your action should now read Create a Contacts list named Contacts met at [%Current Item:Title%], and described as These are contacts we met at [%Current Item:Title%].
24. On the ribbon, click Check for Errors, and fix any errors that are reported.
25. On the ribbon, click Workflow Settings.
26. In the Start Options area, enable Start workflow automatically when an item is created.
27. On the ribbon, click Save, and then click Publish. Close SharePoint Designer.
28. In a browser, open the website to which you published the workflow, navigate to the Announcements list, and click Add a new announcement.
29. For the Title, type Berlin trade show, and then click Save.
30. Refresh the Announcements list page. A new column named Return from Trade Show appears on the list, and the value for your new item is either In Progress or Completed.
31. Keep refreshing the page until the Return from Trade Show workflow says Completed.
32. Click Lists or All Site Content in the navigation pane. There will be a new list named Contacts met at Berlin trade show with a description that reads These are contacts we made at the Berlin trade show.

How to: Create and Deploy Workflow Actions in Sandboxed Solutions

Creating the Workflow Action

To create the activity method

To create the WorkflowActions markup

Deploying and Testing the Workflow Action

To deploy the workflow action to a site collection

To test the workflow action

See Also

Tasks

Concepts

Other Resources

Additional resources