Meet me at Office DevCon 2008 in Sydney!

Hi! I will be at the office DevCon 2008 in Sydney, if you are interested in meeting me and would like to discuss a bit on SharePoint project management methodologies, or SharePoint development practices I would be pleased!

I would love to share experiences and knowledge on some real-life SharePoint implementations project management approaches – practices  instead all the ´How do I <Insert feature here>´,  sessions.

Since the real challenge of SharePoint, as I see it, doesn’t lie in technology but in specification, implementation and adoption.

Just drop me an e-mail and we’ll grab a couple of drinks!

SharePoint Internals Happiness!

Recently when I was trying to isolate out how the SharePoint internal authentication system (ACL / ACE) worked, I ran into the following documents describing the internals of SharePoint content databases quite detailed.

The documentation is major since august already, but I thought just to give it some more attention in cause you might have missed it.

You can find it here:

[MS-WSSFO]: Windows SharePoint Services (WSS): File Operations Database Communications Protocol Specification

http://msdn.microsoft.com/en-us/library/cc448602.aspx

It also lists the table and views used in the SharePoint content databases. Excellent information if you want to know more on the internals of SharePoint.

BETA SPD Workflow Export Utility on CodePlex!

Its on CodePlex!

In follow up of my two post regarding SharePoint designer workflows https://agiledirect.wordpress.com/2008/07/04/packaging-and-re-using-sharepoint-designer-workflows-part-1/ and https://agiledirect.wordpress.com/2008/09/10/packaging-and-re-using-sharepoint-designer-workflows-part-2/ I’ve now released the BETA utility to export the workflows and package them in a feature. However, its far from production ready, so I still need to do a lot testing and bug-fixing.

Note on this release

In this release you will find two zip files, one containing the beer sample as discussed in the previous post, and the utility it self.

I haven’t tested all the activities yet and I am not sure how it handles the task forms. If you have any comments or bugs please let me know by sending an mail to info@agiledirect.nl

You can download the utility at: http://www.codeplex.com/SPDToolkit

So, what’s next?

I’m releasing this tool as a part from a book I’m writing for my classes on building process and application templates for SharePoint. The book is expected to be released later this year.

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;

Preparation

  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.

Preparation

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.

image

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”

image

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;

image

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;

image

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.

image

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.

image

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”

image

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

image 

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)

I’m back from Hawaii

Back from Hawaii, need to get a couple of things in order and then I will post part deux (2) on SPD workflows!

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.

 xoml

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.

 xomlfile  

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.

untitled

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.

config

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.

image

Watch this space!

Happy 2008 all!

Yes I know! 7 days late but still I wish you all a good, healthy and successful 2008! Right now I am building an TFS2008 Continuous Integration / SharePoint solution, when this is done I’ll start blogging regularly again!

Regards,

Emile Bosch