In this third article in my series on Windows SharePoint Services (WSS) 3.0. I am going to demonstrate creating a more elaborate custom workflow with the tools available using Visual Studio 2008.
As a platform for designing and developing quick workflows SharePoint Designer is really valuable. However, when your workflow design gets complicated or there is a need for some action or custom code which is not supported within this product then you will need to look at creating a workflow from scratch using Visual Studio. Later on in this article I will discuss in more detail when you might need to look at Visual Studio as the platform for your workflow development.
To support the workflow I will be developing for this article I have expanded the sample site used in my previous article. I have added a new document library titled ‘Product Authorisations’. This library hosts a form which is completed to request that a new product line is authorised for sale.
The workflow we develop is going to be attached to this document library.
The idea for our new workflow is that once a new product request has been authorised, the Sales Team will be emailed and a new entry in the Products list will be created representing our new product.
A flowchart of the process looks like this:
Creating your workflow in Visual Studio 2008
- Start Visual Studio.
- Select File > New > Project.
- In the Project Types list select Workflow under your language of choice.
- Select the SharePoint 2007 Sequential Workflow template.
- In the Name field enter ‘ProductAuthorisations’
- In the Location field enter a directory to store your project.
- You will be prompted to give your Workflow a name and provide a local site for debugging. Simply enter the URL for a suitable development site.
- Click Next.
- You will now be prompted to select the appropriate lists for use in debugging. For this example you should leave the ‘automatically associate workflow’ option ticked. Select Product Authorisations as the library to associate the workflow with and use the default workflow history and task lists.
- Click Next. Then select only ‘When an item is changed’ from the final screen of the wizard.
- Click Finish.
Your project will now be created and you should be shown the workflow designer. This is the screen which allows you to configure the various elements of the process which will combine to form your workflow. You will notice that an onWorkflowActivated action has been added to your workflow already. This action is required for your workflow to work within the context of SharePoint and it includes key elements such as setting the CorrelationToken.
You will notice from looking in the Toolbox that there are various different actions that can be dragged across to the workflow designer. Some of these are specific to SharePoint such as CreateTask and others such as the basic Code activity are a part of the core Windows Workflow Foundation.
Because our workflow is conditional on the authorisation document having been approved the first thing we need to add is some conditional branching.
- In the Toolbox select the IfElse activity and drag this across to your workflow designer under the onWorkflowActivated activity.
- Select the ifElseActivity1 element and in the properties window change its name to ifApproved.
- Select the ifElseBrachActivity1 element and change its name to isApproved.
- Select the ifElseBrachActivity2 element and change its name to notApproved.
You will notice that our isApproved branch has a red exclamation marker. This is indicating that there is a problem with this activity. If you hover over the icon and select the down arrow you will receive a tool tip on what may be causing the problem.
In this case we can see that the issue is with the Condition property not being set. The condition is used to evaluate which branch of the ifElse activity the workflow should use when running. In our case we need to evaluate if the item is approved.
- Select the isApproved branch of your ifApproved activity and in the properties window select Code Condition from the Condition options.
- Expand the condition property and type IsItemApproved in the second Condition box.
You should automatically be taken to the code view in order to create the code to evaluate your condition. A method called IsItemApproved should have been created for you. This method should have EventArgs from the following class:
This class has a property named Result which allows us to specify whether or not our condition has been met.
- Copy the following code into your IsItemApproved method.
1234567Dim strApproval As String =CStr(workflowProperties.Item("Approval Status"))If strApproval = "0" Thene.Result = TrueElsee.Result = FalseEnd If
This code essentially evaluates the item’s Approval Status to see if it is approved.
- Drag a Terminate activity from the Toolbox into the notApproved branch of your ifApproved activity.
- Select this Terminate activity and enter the following text in the Description field of the Properties window:
The item is not Approved.
This will simply stop your workflow is the item is not approved. Your workflow should now look like this:
The next step is going to be to perform the action required if the item is approved. Looking at our workflow diagram we can see that we need to send an email and create a list item. However, in reality it would make sense to send the email AFTER the list item was created. After all if the list item creation fails then we don’t want to have already emailed the sales team.
- Drag a Code activity from the Toolbox into the isApproved branch of our ifApproved activity.
- Select the Code activity and change the Name in the properties window to CreateProductsListItem.
- Double click on the Code activity.
This should open the code editor and create an appropriate ExecuteCode method for your code activity. The Code activity allows a piece of entirely separate code to be run during the course of your workflow. You are going to use this activity to create a new list item based on your product authorisation data.
- Copy the following code into the method created for you:
123456789Dim currentItem As SPListItem = workflowProperties.ItemDim list As SPList = workflowProperties.Web.Lists("Products")Dim newItem As SPListItem = list.Items.Add()newItem("Product Name") = currentItem("Product Name")newItem("Price per Unit") = currentItem("Sales Price")newItem("Inventory") = currentItem("Initial Inventory")newItem.Update()
- Drag a SendEmail activity from the Toolbox into the isApproved branch of our ifApproved activity.
- Select the SendEmail activity and make the following changes in the properties window:
123456Name: SendSalesTeamEmailCorrelationToken: workflowTokenBody: A new product has been added to the Products list, please review it.From: email@example.comSubject: New Product AuthorisedTo: firstname.lastname@example.org (or your own email address to test)
Your workflow should now be completed. If you hit F5 to debug your project it should be built and deployed to the SharePoint site you specified when creating the project.
If you navigate to the Product Authorisations document library and create a new item you will notice that your workflow runs but terminates straight away, because the approval status is pending.
If you then approve the item you should see an email sent out and a new list item created in your Products list.
When should I use Visual Studio for Workflow?
As I mentioned earlier SharePoint Designer (SPD) is a great platform for developing basic workflows, however it has several limitations and in some cases these can mean that you have to look at Visual Studio as the solution for your workflow design.
In my experience the limitations of SPD are as follows:
- Workflows are bound to a specific list/site
In SPD any workflow you create can only exist on the list (and in the site) that you created the workflow on. You cannot design a workflow and then move it to another site.
- No code support
You cannot write custom code within the SPD workflow tools. You can write custom activities to include in SPD, but you would need to do that in Visual Studio anyway.
- No WSS Solution Package (WSP) support
Your workflow will be deployed to the site via SPD and there is no support for packaging these as WSP files, which provide a more maintainable and upgradeable method of deploying customisations to SharePoint.
- No support for State Machine workflows
You can only build Sequential workflows with SPD, there is no support for State Machine Workflows.
There are other reasons why you might choose to use Visual Studio (it might be an environment you are familiar and feel safe with) but if the points highlighted above are going to cause you a problem then you will definitely need to look at Visual Studio as your workflow development platform.
Hopefully this article has demonstrated the flexibility that can be seen within a custom workflow created in Visual Studio. The power is really in your hands as the workflow developer. As you will have seen the workflow designer will let you run any custom code you desire within a Code activity, so even if there is no activity to achieve your goals out of the box, you can still write a solution which fulfils the exact business requirements that your workflow is designed to achieve.
In my next article in this series I hope to take a look at Event Receivers within SharePoint. What are they? How are they different to Workflows? And most importantly how can you create one?