Packaging SharePoint 2013 List, Site, and Reusable Workflow and How to Deploy the Package

Hello. This is JongHwa Lim – a Program Manager from SharePoint Designer (aka. SPD) team.

Today I’d like to introduce a feature which has been enhanced a lot from SharePoint Designer 2010 and SharePoint Server 2010. It is the workflow package feature. A very common scenario for those who used this feature in SharePoint Designer 2010, was to develop one workflow in a development environment and then deploy it to a production environment. Unfortunately, the bad news was that this was supported only for reusable workflow types in SharePoint Designer 2010.

In SharePoint Designer 2013 along with SharePoint Server 2013 and Azure Workflow Service, we now support all three workflow types – list workflow, site workflow, and reusable workflow. This is superb. This means you don’t have to confine yourself only to the reusable workflow and the old story that you had to migrate your list workflows to reusable workflows for this purpose are all now gone.

An example will help tell this story much better. I will build a sample workflow and show how it can be reused in a target site.

Example: a Vacation Request list workflow

Let’s say you are going to create a list workflow on a development environment. The workflow has two lists – Vacation list and Vacation Request list. Vacation list keeps the number of remaining vacations for all the employees and Vacation Request list is where the requestor will create a request item to request approval for vacation.

Create necessary lists (development environment)

As said, we need two lists so I created two lists as below. Note that we will use the default settings for the ‘Task List’ and ‘History List’.

Create list workflow on Vacation Request list

Now that you have the necessary lists ready, use SPD to connect to the server, click ‘List Workflow’, and then choose ‘Vacation Request’ list. You will be shown a dialog below and make sure you choose ‘SharePoint 2013 Workflow’ type after you type in the workflow name.

Fill in the logic and Publish the workflow

In the SPD canvas, you can choose text-based designer or if Visio Professional is installed you can choose the visual designer to author the workflow. In this blog, I will use the text-based designer but if you are interested in the visual designer, please refer to another blog post on the visual designer, which will be available soon.

Please add the following logic. In general, it is very straight-forward except for a couple points. It consists of five stages. Each stage’s title explains what it is for but to explain it in more detail, I’ve described them below:

• ‘Check if remaining vacation exists’ stage – fetch the remaining vacation days for the initiator and compare it to the requested vacation days
• ‘Approval Process’ stage – request approval for the requested vacation days
• ‘Approved’ stage – when approved, update the Vacation list with the new calculated value
• ‘Rejected’ stage – send rejection mail
• ‘insufficient vacation’ stage – send mail on the insufficient remaining vacation days

The tricky parts are these lookup UIs to fetch the remaining vacation days from Vacation list or to update the Vacation list.

You can opt to turn on ‘auto start by item creation’ option if it makes more sense.

And when you publish the workflow the workflow association will be created and the status column will be made behind the scenes.

Package the lists into STP packages

There are several ways by which you can guarantee that the target server has the necessary lists and schemas but leveraging STP package is a good practice. So let’s package Vacation list and Vacation Request list into a STP packages.

You can do this via either server UI or SPD UI as shown below.

Then, you will see the following screen where you can type in the name and choose to package the contents as well.

Note that SharePoint 2013 list workflow is not packaged together whether you choose to ‘Include Content’ or not.

And if successful, it will guide you to a place where you can download the package.

Click the link and download the package for later use.

If successful, you must have two STP packages now, one package for the Vacation Request list and another for the Vacations list (the list that contains the remaining vacation days).

Package the workflow into WSP package

To package the list workflow, go to the workflow summary page and click the ‘Save as Template’ button in the Ribbon.

The following dialog will be shown.

You can find ‘Site Assets’ library in the Navigation pane and you can find the list workflow package in it. (You may need to refresh the page to see the package.)

Use the ‘Export File’ Ribbon button to save it to the local machine.

Deploy the STP packages

Open the target site(or production environment) in your browser and go to ‘Site Settings’. You can find ‘List templates’ menu under ‘Web Designer Galleries’ group.

Using the ‘Upload Document’ under ‘Files’ menu, upload the two STP packages.

Create lists using the deployed list templates

You can create the two lists from the deployed list templates. Go to ‘Site Contents’ in the navigation menu in the server and click ‘add an app’. You should be able to find ‘Vacation’ and ‘Vacation Request’ icons.

Create ‘Vacation’ and ‘Vacation Request’ lists using those menus.

Deploy the WSP package and activate the package

Deploying WSP package is a bit different from deploying STP list templates. You must upload it to ‘Solutions’ library under ‘Web Designer Galleries’ group in Site Settings.

Then, you will be prompted with a dialog where you need to activate the package(solution).

Activate the Feature

After activating the solution, you will see there is a new site feature in ‘Manage site features’ under ‘Site Actions’ of Site Settings.

This is it. You can find this workflow by the name you used when you packaged it. Click the ‘Activate’ button and wait until the button changes to ‘Deactivate’ or the ‘Active’ icon is shown, which will mean that the feature is activated.

(Optional) Open the workflow from SPD

There are cases when you want to update the workflow in the target site. No problem. It is just the same as your development environment. You can find the deployed workflow correctly listed in SPD.

And it will open without any issues. You can see that the values in the summary page remain the same. And of course, the logic is preserved as well.

(Optional) Run the workflow

After you run the workflow from the server, you may find that there are two columns with the same name(workflow status column). This is a known issue. One column comes from the source server(packaged in STP) and the other column is created in the target site. Please update the list view to hide the old column.

What is the alternative to using STP package?

The solution will be properly deployed as long as the target site has the necessary lists – lists that are used in the workflow logic along with the Workflow Task and Workflow History lists. But it is best to create the lists and list columns referenced in the workflow using the same list template and same field type. If there is a type mismatch, the package can fail during the feature activation time or the workflow will fail at runtime.

What happens if the workflow package is deployed to a site where ‘Vacation’ or ‘Vacation Request’ lists don’t exist?

The site feature activation will fail.

The error message is not very detailed but if you look at the ULS log, you can find some hints like the following:

“Workflow XAML failed validation due to the following errors: Failed to create a 'ListId' from the text '$ListId:Lists/Vacation;”

But once the feature activation has failed, re-activation of the feature may fail again even after you create the necessary lists. This is because your workflow definition is deployed incompletely. You need to do the following:

• Open SPD and delete the workflow definition which failed during feature activation
• Deactivate the solution and remove the solution
• Upload the solution and activate the solution
• Activate the site feature

This should solve the problem.

Known Issues

These are the known issues of workflow package.

• You need to guarantee that the relative list urls (eg. ‘Lists/Vacation’) are the same. Even if you create a list with a given name and then change it to a different name, the list url will not change, this is because it is based on the original display name. As such, even though you packaged the workflow based on the list’s updated name, the workflow will still look for a list url based on the old name in the target site. Therefore, when you are recreating the lists in the target site, you must make sure that you initially give the lists the original name, and not the updated name. This way the list url will be preserved. After the list is created, you can change the list’s name to the updated one.
• Workflows with Unicode or DBCS names will be packaged into wsp files with the default hard-coded name of ‘WorkflowSolution.wsp’
• You need to manually refresh the page after you go to Site Assets to see the updated list of solutions.
• If the target server doesn’t have the Workflow Task list and Workflow History list, the below error can show up when you click on the workflow from the Workflow Settings page. This happens when you deploy the workflow to a target server where no workflows has ever been created before. As a workaround, you can create and publish a dummy workflow from SPD to create the Workflow Task list and Workflow History list. And then you can open the deployed workflow from SPD, adjust the Workflow Task list and Workflow History list settings and republish the workflow.
• Project workflow will be packaged like a regular site workflow. But to guarantee it works, you need to also package project entities such as EPT, Stages, custom columns, and so on. Please refer to the project workflow guideline which will be provided by the Project team.

Thanks,

JongHwa