SharePoint 2007 workflow with Visual Studio 2008
Before getting into this I thought developing workflow for SharePoint 2007 was a complex and daunting task to undertake. Whilst you still won’t find me saying it’s easy I will say that I’ve been pleasantly surprised at how intuitive the process has been. The following pages demonstrate the steps that are required to get a simple workflow going from setup to development and deployment.
Installation prerequisites
Visual Studio 2008 greatly simplified the processes of creating, deploying and even debugging workflows but if you need to it is possible to do all of this with Visual Studio 2005 and some additional work. The remainder of this document shows the steps required to create a simple workflow using the 2008 version of the product, so bear in mind that not everything will work as easily if you choose to use an older version such as 2005.
Visual Studio 2008
Software
Link for more information
Visual Studio 2008
Windows SharePoint Services (WSS)
Microsoft Office SharePoint Server (MOSS)
WSS Software Development Kit (optional)
MOSS Software Development Kit (optional)
Table 1 – Visual Studio 2008 components
Visual Studio 2005
Software
Link for more information
Visual Studio 2005 Professional or Team Suite
For Team Suite make sure you also download the latest Service Pack (SP1 at time of print)
.Net 3.0 (FX) Runtime
Windows SharePoint Services (WSS)
Visual Studio extensions for workflow
Visual Studio extensions for WSS
Microsoft Office SharePoint Server (MOSS)
WSS Software Development Kit (optional)
MOSS Software Development Kit (optional)
Table 2 – Visual Studio 2005 components
So what is a WSS workflow?
Firstly, it is assumed that you have a basic understanding of both workflow principles and development. Specifically though, when we talk about Windows SharePoint Services (WSS) and workflow we are talking about controlling events that can occur when an item in a list or library in a WSS site is changed. Typically this is either to model a business process through a level of automation (Business Process Engineering) and therefore minimising or to manage the lifecycle of content (Information Lifecycle Management).
Windows Workflow Foundation (WF) is the basic underlying technology that is used to define a workflow however WF alone does not make a workflow happen, it needs a host. WSS forms the host service that runs the workflow in conjunction with the WF run time. Together they will manage tasks, assignment of tasks, persist state over long running transactions (human intervention, scheduled tasks…), scheduling and tracking.
Sequential Vs State workflows, what is the difference?
Sequential workflow is nothing like it sounds. It does not mean that there is a single thread of activity with fixed route from start to end. A sequential workflow can have parallel tasks, can branch depending on state, properties, user response…In this case sequential simple means that the workflow has a single start point follows through a number of steps to reach a goal.
State (machine) workflows basically mean a workflow whereby the core component (a task, a document…) can have a number of states (draft, for review, reviewed, released, approved) and the movement between each of those states is controlled, for example it may be inappropriate to move state between draft and approved without passing the other state first. State workflow has a start and a number of activities that govern state but do not necessarily have to have an end state i.e. Approval can be the best state for content but after approval it’s entirely possible that the content may be reverted to draft for update.
Basic environment setup
You should now be able to load Visual Studio and within the workflow section of the new projects library you should have the option to create a number of different workflow types.
Figure 1- Setting the project name
At this point it depends on whether you are working on a MOSS2007 server or not as to what you do next. If you’re on a MOSS2007 server then simply create a new Sequential Workflow project. If not you’ll need to grab the SharePoint DLLs from the server, the easiest way of doing this is to take microsoft.sharepoint.* and microsoft.office * from the servers C:Program FilesCommon Filesmicrosoft sharedWeb Server Extensions12ISAPI directory and create and copy to the same path on your development machine. You will now have all the references you need to create a workflow project, go ahead and simply create a new Sequential Workflow project.
You will be asked to specify both the name of the workflow to display to users and also the initial library you want to use during development (for debugging the workflow). Note that in Visual Studio 2005 you do not get this prompt and need to manually set this up.
Figure 2 – Naming the workflow
You will now be asked for the library to attach the development workflow to, the workflow history list (tracks progress) and the task list that you want to use (if assigning tasks).
Figure 3 – Set workflow associations
You will then need to decide when you want your workflow to fire, there are three events that can cause a workflow to start.
ú Manually i.e. the user chooses to start a workflow on the current item
ú On creation, the workflow is started as soon as an item is created (this can be either saving a document to a library or list, uploading a document or simply creating a new item)
ú On change, the workflow will fire every time an item is changed, for document this means that the workflow will start if either the document itself is changed or any of the metadata associated with the document is changed.
I’m selecting all three because I want a user to be able to choose when to move an item and I want the item to be automatically moved if its metadata indicates that it is ready to move (that can happen on creation or as a result of the metadata changing).
Figure 4 – Select workflow triggers
I created a standard SharePoint Team site to use for developing the workflow and am using the default workflow history list, task list and document library, `Shared Documents’ as the workflow source.
Figure 5 – Team site
I have a simple workflow, so what now?
If you are using Visual Studio 2005 you will notice from the toolbox that although you have created a SharePoint workflow the extensions component does not automatically add the SharePoint items to the toolbox! To add them right click on the toolbox and choose “Add Items” sort the list by namespace and add the Microsoft.sharepoint.workflowactions namespace. If the namespace didn’t appear in the list then you’ll have to navigate to the DLL itself, click browse and usually you’ll find the DLL in C:Program FilesCommon Filesmicrosoft sharedWeb Server Extensions12ISAPI.
Now we’re ready to create a workflow, at last!
The first thing to do when creating a workflow is to simply draw it out on the page in its basic form. Don’t worry about the code yet, we’ll tackle that later. For my example I’m using the following workflow design:
Figure 6 – Simple workflow design
This is a very simplified process that when complete will check the metadata of a document and if it is ready to be moved will move it to the document centre in the top level SharePoint site. In anticipation of this I’ve added metadata to the default document library we specified when we created the workflow project. To do this load up the document library in your browser and from the settings menu choose `Create Column’, call the column `Approved for move’ and select the `Yes/No’ column type.
Once you’ve created your outline process / workflow map you can start defining in lower level detail how this is going to work. Before we dive into the code it’s important to understand two important aspects of the workflow. Firstly, the workflow need a unique identifier which it will `share’ with SharePoint basically it the mechanism the workflow runtime uses to identify the running instance of your workflow. This is called a correlation token and you need one for your workflow and one for each task you create during the workflow, so that when a user completes a task you have a unique identified with which to receive any input from the user into your workflow. If you click on the activation node of the workflow diagram you will see that you have been automatically assigned a correlation token. Secondly, it is important to know where you can find all the information about the source of the workflow (the SharePoint site, library and document or item that started the workflow off in the first place). Workflow Properties is an object that holds all the really important information about your workflow. When you create a workflow it is automatically set to the local variable workflowProperties. The following diagram shows the properties window showing both the correlation token and workflow properties settings.
Figure 7 – Workflow properties
Now that we have the principles out of the way we can move onto getting this fired up and running! Firstly we need to grab the ID that SharePoint has allocated to this instance of the workflow so that we can help SharePoint identify which instance of the workflow is running. SharePoint automatically allocated a workflow identifier in the workflow properties, it is this that we want to extract and store. To do this double click on the workflow activation node (the first node) and you will be taken into the code behind the node. Visual Studio automatically creates the method declaration and two variables for you to use. Your code should look like that shown below.
Figure 8 – Getting the workflow ID
Next we need some logic for our if statement, here you will see that I check the fields (metadata for the column we created earlier and return the value. To save confusion it needs to be said that the terms metadata, fields and columns are used pretty interchangably within the SharePoint world! To add the code for the if statement select the if/else node in the workflow designer and in the properties box set the condition type to `code condition’ and type the name of you condition. This will create a method stub for you to enter your code into.
Figure 9 – Setting branching logic
Now you will be placed into your workflow code again and you can add the required logic as such:
Figure 10 – Coding branch logic
So, there nothing too complex there we’re just getting the field back from the SharePoint item (document in this case) and reyrning the value to our workflow.
Now all we need is the code for the move and history log sections. Both are very simple, starting with the document move code, the following shows the code that’s required. Note there is no move function in the SharePoint object model so a copy then delete is required.
Figure 11 – Code document move
For the history log I will show two methods that can be used, the first and most simple is to add the required output to the properties of the node. Click on the `RecordNotReadyToMove’ node (the one without a code block above it) and set the `History Description’ property `Not ready to be moved’ and the `History Outcome’ property to `Not ready!’.
Figure 12 – Logging progress (simple)
Next, the more complicated (but flexible) method. Firstly declare two string variables for the history description and history outcome properties. IF you are not familiar with code then you do this after your class definition in such as.
Figure 13 – Logging progress (code), step 1
We now want to alter our document move code to update these variables to indicate the level of success. The following code is a good example of just how useful hat workflowProperties object is!
Figure 14 – Logging progress (code), step 2
Now we have the history variables set we can tell the history node in the workflow diagram to use these variables. To do that select the node and click first on history description, then the ellipses that appear to the right and then choose the _historyDescription variable we created earlier. Do exactly the same for the history outcome
Figure 15 – Logging progress (code), step 3
Ready to test
If your project will now build then you are bug free and ready to go. If not take a look at the errors that appear and try to fix them, it’s likely to be either a typo or a step you’ve missed as there’s not much that can go wrong at this stage.
In Visual Studio 2008 you can simply hit F5 or choose `Run’ from the debug menu and an the workflow will be deployed and an Internet Explorer window will be loaded with the document library you associated the development of the workflow with displayed. If you now upload a document to the library and make sure the `Approved for move’ checkbox is unchecked you will find that the library now has an extra column to tell you how the workflow is doing. If you check the items workflow history you will see that our code has been called and the expected output has been added.
Figure 16 – Reviewing workflow progress
Similarly, if you now edit the properties of the uploaded item and check the `Approved for move’ checkbox you will see the item disappear from the library you uploaded it to and it will appear in the Document Centre. Note though that when you do this the document that is copied to the Document Centre will not have any information relating to the workflow attached to it. To see the workflow history for the (now deleted) item you will need to go to the Workflow History list where you will find the expected output. There is no link to the Workflow History list but you can find it at http://[server]/[site]/Lists/Workflow%20History/AllItems.aspx and you should have an item such as:
Figure 17 – Hidden progress list
Deploy the workflow
So, that’s it – your workflow works and you’re ready to deploy. This is the easy bit! In essence the deployment of your workflow has already happened, if you’re using Visual Studio 2008 the workflow will have been automatically deployed to the site collection you specified as the development site when you first created the workflow project. However should you need to deploy the workflow to a different server or site collection then these are the steps that you’ll need.
The following steps will deploy your workflow to a site collection.
1. Copy the DLL your workflow creates from the build directory (inDebug) to the Global Assembly Cache (GAC)
2. Create a directory in the features directory [C:Program FilesCommon Filesmicrosoft sharedWeb Server Extensions12TEMPLATEFEATURES] and drop both the feature.xml and workflow.xml files into the directory.
3. Install the feature on your farm, using the following command line statements
stsadm -o installfeature -name DocumentMoveAndShortcut
Figure 18 – Install the feature
4. Activate the feature to a site collection
stsadm -o activatefeature -name DocumentMoveAndShortcut -url http://moss2007win2008
Figure 19 – Activate the feature
NOTE: You can usually find the STSADM command in the directory C:Program FilesCommon Filesmicrosoft sharedWeb Server Extensions12BIN
http://vspug.com/andynoon/2008/02/06/sharepoint-2007-workflow-with-visual-studio-2008/
