• Category

  • Archives

  • Advertisements

SharePoint Designer Workflow (WSP) Packager source-code released!

Source-code on CodePlex!

Recently I got a lot of requests to release the source-code of the SharePoint designer workflow packager. My idea was to wait a bit until I got time to clean up the code and  to fix some bugs.  But since I am still traveling this could take a while.

If you find any bugs, please feel free to become a contributor and upload your fixes 🙂

Check it out here at: http://spdtoolkit.codeplex.com/

Installation notes

Be aware that there are still a couple of bugs in the code, and remember that you need C# 3.5 to be installed on your server to run this.

I won’t recommend running this on production servers unless you are a 100% sure that it works.

What’s next?

Depending on the feedback I might extend the workflow packager but it all depends on Microsoft’s roadmap on Workflows for SharePoint’s Next Release. Personally, I think that MS will port the web-based CRM 4.0 workflow editor to SharePoint, or create shared functionality for it, which would supersede this tool. Until then, I try to keep it updated with bug-fixes.


SPD Workflow Packer Source Release (And why I am a bit quiet)

Hi all,

First off, my apologies!The reason for me not blogging lately is because I am traveling Australia and New Zealand and it’s a bit hard getting wireless in my camper.

However, I am releasing the source code for the workflow packaging tool as soon as I can find a place to put it.

Until then, look at my view 🙂





I’m expected to be back and back to civilization in May 🙂

Packaging and re-using SharePoint designer workflows (Part 2)

Purpose of this article

The purpose of this article is to explain how to create SPD workflows which are portable using an approach as described in an previous post. I’ve written an small BETA tool to export, import and attach the workflows. The GUID replacement is not the most elegant approach, but is faster than rewriting Microsoft’s SPD activities. Anyway I wanted explain how it should work already.

UPDATE: The tool is live, more on this here: https://agiledirect.wordpress.com/2008/09/11/beta-spd-workflow-export-utility-on-codeplex/ 

Steps for getting it working

The best approach for working with the export workflows tool is as follows;


  1. Design and create the lists you want to use for you workflow.
  2. Export these lists for packaging as you are used to when packaging lists into features, you should already know how to do so.
  3. Create an empty site (blank site for instance) to validate and instantiate the lists in using your created feature. This blank site will be your workspace for creating and exporting the SharePoint Designer workflow.

Actual workflow activities

  1. Open op SharePoint Designer and create the workflows for that lists in that instantiated site.
  2. Use the workflow export utility to export the workflows and generate the workflow feature XML
  3. Package the feature in to an WSP (using WSPBuilder for instance), add the SPDToolkit.Workflows.Foundation.DLL to the GAC directory of your WSP solution.
  4. Activate the lists feature on an (empty) site and activate the workflow feature. The workflow should now be added to the site and associated with the lists.


Just for sample purposes I’ve created the very simple and silly “Beer Orders” and “Approved Beer Orders” lists in a site using the SharePoint UI. Both lists containing nothing more than just column with the default name ‘Title’. The idea of these list is that when user orders an beer with the Title “Heineken” it will immediately go to the approved orders (others will probably never be handled 🙂 ) . Maybe I will extend the sample later on to let it make more sense.


Now, since we want to use this lists in our workflow, and re-use them on multiple sites, it is important that we package the lists as an feature so we can activate the feature on multiple sites. Activating the feature will instantiate the lists on that particular site. 

So, first we need to convert our UI generated list into a way that we can package it using solution packaging. There are quite some tools out there that can export lists to an list definition XML. You can use whatever tooling you want to create the list definition. I’ve used some self written logic to export the list definition and create the list instance feature. 

The lists are both packaged in an feature cleverly called “Beer Lists Feature”


Since we have packaged the lists, we need to test whether the lists are correctly provisioned. We do this by creating an blank site and activating our “Beer Lists Feature”. When this is correctly provisioned we will use this site for creating our SPD workflows which we will export using our utility.

I’ve activated the “Beer Lists Feature” feature and instantiated the lists in an “Blank Site” which I created at http://litwaredemo:15000/BeerWorkspace/.

Creating the workflow

Now to create the SPD workflow we open up the site at http://litwaredemo:15000/BeerWorkspace/. We can use the new workflow option in SharePoint designer to create the workflow. The result looks a bit like this;


To explain what it does. The workflow checks whether an item is added to “Beer Orders” with the title “Heineken” (Case sensitive). If this is the case it will add an item to “Approved Beer Orders” for processing. 

Exporting the workflow

We will now export our created workflow using the export workflow utility. This utility will export the workflow files and create an analyze XML file to which we can later recreate the workflow.

To export the workflow to a feature we use the following syntax:

SPDToolkit.Workflows.Utility.exe -path C:\Feature\ -name AgileDirect.ExampleSolution.Workflows -title Beer workflow -description Simple beer driven workflow A -url http://litwaredemo:15000/BeerWorkspace/

The arguments should be quite self-explanatory.

This will result in an feature like this;


Packaging it up

Now that we have the feature we need to package it. I use WSP builder, and the solution looks a bit like this in the end. You can see that its nothing more than copying the resulting feature in to the FEATURES folder of the WSP structure.

Now what we need to do is add our custom feature receiver to the GAC, so when the feature gets activated it will execute our custom feature receiver and add and the workflow to the site. To do this add it to the GAC folder of the WSPBuilder folder structure.


Now the feature needs to packaged into an WSP and an solution needs to be build, installed and deployed to an web-application. Again, I used WSPBuilder to do so.

Activating the workflows

To activate the workflows, create an empty site.I called mine, http://litwaredemo:15000/BeerWorkspaceTest/ Activate the “Beer Lists Feature” and the “Beer workflow” feature next. Please note that activating could take quite some time (up to 20 seconds for the first time). This should activate and enable the workflows on that site.


Testing the workflows

Add an item to the list “Beer Orders” with the name  “Heineken” and you will see that the workflow gets triggered and an message gets added to the history, and an item get put in the “Approved Beer Orders”


And you can see the item has appeared on the other list “Approved Beer Orders” as well.


Make it easier for your clients using feature stapling

Don’t forget that you can feature staple the features together so that the user only needs to activate one feature.

What’s next?

Well, next I will upload the utility, and I will create an screen-cast to explain how to work with the tool and export workflows. If this is still a bit too complicated to comprehend.

Its out now: Check the post https://agiledirect.wordpress.com/2008/09/11/beta-spd-workflow-export-utility-on-codeplex/

A couple of features on my wish list.

  • Create a CodePlex place for it, so I can upload the code and you guys can download and work with the tool.
  • Add support for versioning of workflows
  • More advanced support for workflows
  • Fix some bugs
  • Use the object model API instead of the webservice (avoids the long wait when activating)

Packaging and re-using SharePoint designer workflows (Part 1)

Purpose of this article

The purpose of this article is to explain some of the inner workings of SharePoint designer workflows. It will also explain why SharePoint designer workflows are not portable by default. Additionally, in the upcoming blog there will be a tool available that allows for basic packaging of  SharePoint designer workflows to features, thus enabling SPD workflows to become a part of your solution packaging process.

SharePoint Designer workflow creation process explained

When you create a workflow in SPD. There is a lot of server-client interaction involved cleverly hidden from the end user. In a nutshell, this is what happens behind the scenes when a user creates a workflow in SharePoint designer.

  1. User initiates the creation of a new workflow by choosing ‘New Workflow’ from the SPD menu.
  2. SharePoint designer queries the remote server and downloads any workflow activities registered in authorized types (in proxy form) from the server using web services. SPD opens the workflow editor, and allows the user to create the workflow using the available activities on the server.
  3. Upon save, SPD checks whether there is a Workflows library available in the site. If not it will create one. Additionally, SPD creates a folder in the Workflows library baring the same name of the workflow to store the files into.
  4. SPD serializes the workflow to its XOML (WFName.xoml) equivalent, if any rules logic is used; it will also serialize this information to a (WFName.xoml.rules file).
  5. SPD uploads the files into the folder using RPC.
  6. After uploading the files it will validate the XOML for any errors by calling a web service method on the server passing the workflow XOML.
  7. If the validation is passed it will create a configuration file that states which version of the workflow should (the actual version number of the xoml file) be used and to which list the workflow is associated. It will also specify workflow initiation conditions such as start on item creation, update or delete, and whether it should allow users to start workflow manually. This configuration file is uploaded to the server.
  8. The configuration file is processed and the workflow is associated to the list by the server by SPD calling a method on an web service passing the URL and version of the configuration file.

Anatomy of an SharePoint Designer workflow

When you create and save a workflow in SharePoint designer, it stores a couple of files in a folder baring the same name of the workflow in the workflows library as mentioned in the process above.


Each workflow folder consists out of the following files;

The workflow XOML file (My Workflow On Test A.xoml)

The workflow XOML file contains the serialized workflow markup. This is the serialized XML/XOML version of the workflow you’ve edited in SharePoint designer. It basically contains a serialized activity graph of all the workflow activities used in your workflow.


Additional rules file (My Workflow On Test A.xoml.rules)

if you have used rules logic in your workflow; Sharepoint will create a rules file in the folder as well. This file will contain all custom rules logic generated by the rules engine in the SPD workflow editor.


A workflow configuration file (My Workflow On Test A.xoml.config)
The workflow configuration file stores information on which version of workflow and rules file it should use upon workflow association. It will also contain initiation information such whether the workflow should be started upon creation of an item in the associated list, or when an item is updated and so on. Furthermore, the configuration file will have an id of a list to which it should associate the workflow to.


The reason why SPD workflows cannot be ported

So actually, there is nothing in the workflow engine and SharePoint object model that prevents you from using the same workflow XOML over and over in different sites, and thus packaging up and porting your SPD created workflows. Frankly, I think it’s pretty decent model if it was documented well. The actual thing that makes it impossible to port SPD workflows is the OOB activities that come with SharePoint itself. These activities when serialized to XOML, store GUIDS to lists itself instead of ‘pointers’ to list, or any other indirection or that matter. And here is the weakness exposed, because List-IDS are generated each time a list is instantiated the XOML workflows aren’t reusable, since they will most likely point to non existing lists.

You can see an example of this on line 26, of the XOML file (Lookup activity)

Also the configuration is hard bound to the list id.

In my opinion it feels like the workflow activities where a bit rushed, an that the indirection layer that made portability possible has somehow not survived the PBI prioritization queue.

In part two..

Well, this should be enough to explain how SPD workflows work, for now, in the next post we will go deeper into the workings and I will release an sample tool that can be used to export and import basic SharePoint designer workflows to overcome this problem.


Watch this space!