How to: Create and Deploy Declarative Workflows in Sandboxed Solutions
This topic explains how to create and deploy a declarative workflow, sometimes called a "no code" workflow, in a sandboxed solution.
Applies to: SharePoint Foundation 2010
Available in SharePoint Online
A declarative workflow is created in Microsoft SharePoint Designer and is saved as one or more XOML files instead of compiled C# or Microsoft Visual Basic code. The workflow is then saved to a website's Site Assets library as a SharePoint solution package (.wsp file), which can be downloaded and then installed to any site collection as a sandboxed solution. At run time, the XOML markup is converted to code, compiled, and executed.
Consider the following points about declarative workflows:
Only sequential workflows can be created in SharePoint Designer; state machine workflows cannot be created in SharePoint Designer.
Only a Reusable workflow—not a List workflow or a Site workflow—can be saved as a sandboxed solution in SharePoint Designer.
A declarative workflow that was created when SharePoint Designer was working with a website on a SharePoint Server 2010 farm cannot be deployed to a site collection on a SharePoint Foundation farm.
A workflow that is published as a Global Reusable workflow cannot be directly saved as a sandboxed solution in SharePoint Designer. However, you can copy it as a non-global workflow, which you can then save as a sandboxed solution. For more information, see the following sections.
A declarative workflow that is downloaded from a Site Assets library can be imported into Microsoft Visual Studio and modified before it is installed as a sandboxed solution; but there are some nuances to the process. For more information, see the following sections.
Creating and Packaging Declarative Workflows
To create the declarative workflow in SharePoint Designer
In your development environment, make sure that there is a website that contains all the entities whose existence is presupposed by your workflow, such as lists and content types.
Navigate to the website in a browser, and on the Site Actions menu, select Edit in SharePoint Designer to start SharePoint Designer.
In the Navigation pane, click Workflows.
On the ribbon, click Reusable Workflow. In the dialog box that opens, give it an appropriate name and description, and then click OK.
Create the workflow just as you would if it was going to be used only on the current site. The fact that you will package it as a sandboxed solution that can be deployed to other site collections does not affect how you create it.
Recommended: When the workflow is finished, save it, and then click Publish (not Publish Globally) on the ribbon. Test the workflow on the website, and re-edit it as needed.
To package the workflow as a SharePoint solution
When the workflow is completed, open the Workflow Settings view of it in SharePoint Designer. (If you are in edit mode, click Workflow Settings on the ribbon.)
On the ribbon, click Save as Template. The workflow is saved to the website's Site Assets library as a SharePoint solution package (.wsp file).
Note
If you are packaging a workflow that was published globally in SharePoint Designer, the Save as Template button is disabled. To package the workflow, you must first copy it.
-
In the Globally Reusable Workflow node of the Navigation pane of SharePoint Designer, right-click the workflow, and then select Copy and Modify.
-
In the dialog box that opens, give the workflow an appropriate name, and then click OK.
-
Click Save on the ribbon. The new workflow is automatically created as a non-global workflow that you can save as a template.
-
To modify the workflow in Visual Studio (optional)
Download the workflow's solution package from the Site Assets library.
In Visual Studio, start a project using the Import SharePoint Solution Package template. Do not use the Import Reusable Workflow template. This template automatically converts the declarative workflow into a coded workflow, and it cannot be deployed as a sandboxed solution.
Note
There is an alternative to the remaining steps of this procedure that is described in How to: Import and Package a Declarative Workflow in Visual Studio. The advantage of the alternative is that when the Feature in the project is set to a scope of Site, activating the Feature in the site collection's Features gallery makes it available to every website in the site collection without requiring it to be separately activated on every website on which it is going to be used. The disadvantage of the alternative method is that the resulting solution package (.wsp file) can be installed only on Microsoft SharePoint Server site collections, not SharePoint Foundation site collections. The steps of this procedure produce a package that can be deployed to any SharePoint site collection, but the Feature has to be separately activated on each website on which it is to be used.
In the SharePoint Customization Wizard, specify any local site for debugging. It does not have to be the site that SharePoint Designer was working with when the workflow was created.
Select Sandboxed solution, and then click Next.
On the next wizard page, enter the path to the solution package that you downloaded in step 1, and then click Next.
On the next wizard page, leave all items selected (the default), and then click Finish. When the project opens, in Visual Studio, you will see that there are no C# or Visual Basic code files. Instead, the workflow is defined with an .xoml file. You will also see that Visual Studio has created a Feature for the project.
In Solution Explorer, double-click the *.feature file to open the Feature Designer, and set the scope of the Feature to Web.
Note
The only other possible scope is Site. However, if you select Site, the workflow Feature can be activated on only the root website of the site collection, so the workflow cannot be used on any subsites. The scope of Web makes the Feature available on the Features gallery of every website in the site collection, including the root website. It must be separately activated on each website on which it is going to be used.
Add elements that you want to package and deploy together with the workflow. (Be sure to include only elements that can be deployed in a sandboxed solution.) For example, if the workflow assumes the existence of a certain custom content type, and the site collections to which you plan to deploy the workflow do not have that content type, you should consider adding the content type to the Visual Studio project.
In Solution Explorer, open the *.oxml.wfconfig.xml file.
Verify that the Visibility attribute of the Template element has the value "Public". If it does not, change the value to "Public".
Note
SharePoint Designer must always be working with some specific website, even if you are using it to create a Reusable workflow that you plan to deploy to other sites. If at any time during the development of the workflow in SharePoint Designer, you clicked the Publish button (as you would if you took recommended step 6 in the procedure To create the declarative workflow in SharePoint Designer earlier), the Visibility attribute of the Template element gets the value "Public". But if you did not publish the workflow before saving it as a template, the Visibility attribute of the Template element gets the value "DraftPublic". It must be changed to "Public" before you repackage the solution in Visual Studio.
Open the elements.xml file in the PropertyBags folder in Solution Explorer.
Scroll to the PropertyBags element whose Url attribute points to the .xoml.config.xml file, and then verify that the value of the NoCodeVisibility property is "Public". If it is not, change it to "Public".
Optionally, you can edit the .xoml file, but note carefully the following points:
If you double-click the .xoml file in Solution Explorer, it will open the Visual Studio Workflow Designer. You cannot use this designer. There are some incompatibilities between SharePoint Designer and the Visual Studio Workflow Designer. (In fact, if you do open the file in the Workflow Designer, you will likely see error symbols on elements in the design surface—a white exclamation mark in a red circle.) Instead, you must right-click the .xoml file and select an XML editor or text editor in the Open With dialog box.
Editing the .xoml file is an error-prone process. You should do it only to make changes that cannot be made in SharePoint Designer.
When the project is finished, on the Build menu, click Deploy, and test the solution.
To deploy the workflow to a site collection
When your solution is ready for distribution, make the final solution package (the .wsp file) available to site collection administrators.
Note
If the workflow assumes the existence of entities—such as content types, list types, and list instances—that are not deployed with the solution itself, you must make the site collection administrators aware of what these entities are.
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:
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.
See Also
Concepts
What Can Be Implemented in Sandboxed Solutions in SharePoint 2010
Restrictions on Sandboxed Solutions in SharePoint 2010
Sandboxed Solutions Architecture in SharePoint 2010