Building Document Workflows in SharePoint

2007 Part 1: Basic Document Workflow

Robert Shelton

8/13/2007

TABLE OF CONENTS

THE WORKSHOP SCENARIO ................................................................................................... 3

MY DEVELOPMENT ENVIRONMENT & SETUP ......................................................................... 4

THE WORKSHOP STEPS .......................................................................................................... 6

Creating a Sample Team Site and Two Document Libraries ................................................................................. 6

Upload a Sample document .................................................................................................................................. 6

Create a Visual Studio Solution and Project .......................................................................................................... 7

The Visual Studio solution and project (Explaining the Parts)............................................................................. 11 The Project Files ............................................................................................................................................................... 12 Feature.xml ...................................................................................................................................................................... 12 Key.snk ............................................................................................................................................................................. 12 Workflow.xml ................................................................................................................................................................... 13 Workflow1.cs ................................................................................................................................................................... 13

Building the Workflow ........................................................................................................................................ 14 The “Entry Point” of your workflow ................................................................................................................................. 14 Adding our workflow Activity Logic .................................................................................................................................. 16 Adding our workflow “OnWorkflowActivated” code and our Constructor code ............................................................. 17 Adding our Code for the FileCopy Activity (codeActivity1 Shape) .................................................................................... 18 Logging what happened to Workflow History List ........................................................................................................... 20

Deploy and Debug our Workflow ........................................................................................................................ 22

WRAP UP ............................................................................................................................ 26

WHERE TO GET MORE INFORMATION .................................................................................. 26

LEARNING AND RESEARCH RESOURCES USED FOR THIS WORKSHOP .................................... 27

The Workshop Scenario

The purpose of this workshop is to show you how to do a very basic, almost “Hello World” workflow in

SharePoint. I am going to use Visual Studio to do a simple step in a typical Document Workflow

scenario. I will do a “Document Copy” from one folder to another and then log what I did in the

SharePoint logs for the original document.

I hope to explain the process and the pieces that you’ll need or want to understand as you go forward to

build more complex SharePoint Document Workflows.

My Development Environment & Setup

Just in case you find yourself facing screens that look different than mine, or not seeing certain screens

at all, I feel that it’s important to describe my Development Environment. Although my setup is not

required to do SharePoint Development, I would also STRONGLY, STRONGLY suggest that you setup

your developer environment in a very similar way.

Note: For reference sake, I will define “SharePoint” as either just Windows SharePoint Server 3.0 (WSS

3.0) and/or Microsoft Office SharePoint Server 2007 (MOSS 2007). The demonstration that I am building

will work on both setups.

Here’s my setup:

1. Use a Virtual Desktop Environment, I cannot stress that enough. I use Virtual PC 2007 (which you can get free from www.microsoft.com/download, search for Virtual PC 2007), but you can use Microsoft Virtual Server (also free from Microsoft, but it is typically installed on Servers versus desktops). You can also use some non-Microsoft Virtual Machine technology, there are several out there including Parallels and VMWare. I cannot attest to their capabilities, pricing, etc., since I don’t use them.

2. Install Windows Server 2003 or Windows Server 2008 (in Beta as I write this). Install it into your Virtual Desktop Environment. The directions for installation vary by product, so see your Virtual Desktop instructions for that.

3. Install Windows SharePoint Server 3.0 (WSS 3.0). You can also get this freely from Microsoft, if you have a legal license for Windows Server 2003 or Windows Server 2008. You can get this from www.microsoft.com/download, search for “WSS 3.0”.

4. Install Visual Studio 2008 (Beta 2 at the writing of this document) I have chosen to use Visual Studio 2008 instead of Visual Studio 2005 with the Workflow Extensions for SharePoint. The reasons are many fold, but primarily because it’s “easier” to do SharePoint development and debugging with Visual Studio 2008. At the time of writing this document, you can download Visual Studio 2008 Beta freely at www.microsoft.com/download, by searching for “Visual Studio 2008”. Now, that being said, if you choose to use Visual Studio 2005, then you will need the add-ins for Visual Studio 2005 found here (http://www.microsoft.com/downloads/details.aspx?FamilyID=19f21e5e-b715-4f0c-b959-8c6dcbdc1057&DisplayLang=en), and you may need other pieces (I am not sure since I am not using it). You can find out more about setting up on Visual Studio 2005 by searching the web. Whether or not you use Visual Studio 2008, as I am, or use Visual Studio 2005, most of what you will see in this document will work with the exception of:

- How you deploy your solution in Visual Studio 2008 is easier and different than Visual Studio 2005 (See this document for steps: http://msdn2.microsoft.com/en-us/library/ms460303.aspx).

- How you debug your solution in Visual Studio 2008 is easier and different than Visual Studio 2005 (See this document for steps: http://msdn2.microsoft.com/en-us/library/ms455354.aspx).

5. Lastly, you should download the WSS 3.0 SDK, which is essentially the “Help File” for SharePoint Development. You can get the SDK freely from www.microsoft.com/download, search for “WSS 3.0 SDK”

The workshop steps

Creating a Sample Team Site and Two Document Libraries

The first thing to do for this demonstration is to create a SharePoint Team Site and setup two standard SharePoint Document Libraries inside of my Team Site. Onc is called "Source Document Library" and the other is called "Destination Document Library."

I won’t go through the steps, since creating a SharePoint Team Site is pretty basic, but your resulting screen should look something like this. If you’ve never created one before, then see this web page for the walkthrough of doing so http://office.microsoft.com/en-us/sharepointtechnology/HA100215751033.aspx?pid=CH100649461033.

Upload a Sample document

In my experience, it’s smart to have a “test document” already loaded in your SharePoint List or Document Library upon which you can test your workflow. It doesn't matter what kind of file you use, I will use a Word document. I would not recommend using a Production Document/File or work on a product site, as you will not like the results. I will explain further during the debugging section.

Steps:

- Switch to the “Source Document Library” - Hit the “Upload” Tab

- Browse to your test document and hit the OK button - My file name is called “My Test Document”

Your screen should now look like this:

Create a Visual Studio Solution and Project

Now that we have a Test site, document libraries and test file, we can create our Visual Studio project and solution.

Steps:

- Open up Visual Studio 2008 (See the details of my configuration above, which also references VS

2005)

- Create a “New Project”

- Choose your language. I will be doing C#.

- Select the Office, and then 2007

- Name your solution. (I’ve called my project and solution SimpleCopyFileWorkflow)

(Your screen should look something like this, if you are using Visual Studio 2008)

- Name the workflow and location for local debugging

o Enter the Workflow Name

I left my workflow name as SimpeCopyFileWorkflow

o Choose the location for local debugging of your workflow. Warning!! Don’t try building

and debugging workflows on Production Servers. While you are debugging your

workflow, with break-points enabled, your SharePoint Site will be “halted” for other

users.

I am using the following URL: http://localhost/demosite1

- Attach or “Associate” the workflow to a SharePoint List.

o Choose a Document Library or SharePoint List as well as a Workflow History and a Task

List. I will explain the Workflow History and Task parts in a later post.

Library or List: Refers to the SharePoint Library (e.g., Document Library) or SharePoint

List to which your Workflow will be attached. This is very important during

development, because you need to be attached to a Library or List to debug, test your

workflow. Later you can attach your Workflow to other Libraries or Lists by “Packaging”

your Workflow and following a series of steps (see: http://msdn2.microsoft.com/en-

us/library/ms460303.aspx).

History List: The SharePoint List in which the workflow’s history events will be

recorded. I get asked if you can run reports on the SharePoint List, and the answer is

yes, it’s like any other SharePoint List. You can use Reporting Services, Export the

results to Excel, or use Access Reports.

Task List: The Task list is where the workflow will store Workflow Task data. For

example, if as a part of your workflow you send a user a task (in Outlook for example),

the results of that task interaction (like entering form data, or % of task done, etc.) the

data would be stored in this list.

o In my case, I am going to attach my workflow to my “Source Document Library”

o And hit the Next Button.

- Specify the conditions on which the workflow will be started

Manually by users: This option gives the user the option to start your workflow manually,

which is the option that I always choose when I am developing/debugging workflows, because it

allows me to run my workflow on a document anytime I want without having to go through

some “automated process.” I should also note, that this must be selected, if you are going to

use a Custom Workflow Form called an “Initiation Form,” which I will talk about in a later

document.

When Items are created: This option is does what you would think based on its name. It will

run your workflow whenever an item is created or “show’s up” in your SharePoint

List/Document Library.

When an item is changed: This option works a bit different than you might think, (or maybe it

was just me). If you choose this option, your workflow will run anytime any document in your

library or item in your list changes! For example, if you have five (5) documents in your

document library and a value in one of the columns (including the workflow status columns,

which will change as your workflow goes from started, to pending, to completed), your

workflow will run again, on all of the documents (all five). You might think that it would only run

on the document that changed, but this is not how it works. So, be careful when you choose to

use it.

- I will choose: “Manually by users” and “When an item is created”.

- Hit the “Finish Button”

The Visual Studio solution and project (Explaining the Parts)

The Project Files

When your Visual Studio Solution is created (in Visual Studio 2008), you will get a file structure that

looks like this.

If you open the “References” folder, you will see a series of .DLL’s referenced, but I want to point out the

important one from a SharePoint Workflow perspective (see image below).

Feature.xml

[From the SDK] The Feature.xml is the file that defines a feature and the location of assemblies, files,

dependencies, or properties that support the feature. See: http://msdn2.microsoft.com/en-

us/library/ms475601.aspx

From a Workflow perspective, a feature is a way of packaging all of the “stuff” (e.g., Images, icons, other

binary files, etc.) that you may need deployed with your workflow in a more easily distributable way.

When you deploy your Workflow Solution, Visual Studio will use this file to figure out what needs to be

deployed and where they reside in your solution. You can also set the name and description of your

workflow feature in this file.

Key.snk

This is the Strong-name key that your Workflow Solution will use for deploying itself within the Global

Assembly Cache (GAC). Since Workflows compile into .NET Assemblies (i.e., .NET .DLL’s), you have two

choices of getting SharePoint to accept and work with them. The most secure way is installing them in

the GAC, which requires that all assemblies must be “signed”, which requires a Strong-name Key. In

Visual Studio 2008 this is provided in the template for SharePoint workflows.

Workflow.xml

The Worfklow.xml file is the “Definition File”, if you will, for your Workflow (sometimes called Workflow

Template).

This is where you can set your Workflow’s:

- Name (that will be shown to users in the SharePoint UI )

- Description (that will be shown to users in the SharePoint UI )

- The Url’s for your Custom Workflow Forms

o Association Form: The form that is presented when a user/administrator first connects

a workflow to a SharePoint List or Document Library. This is where you can set the

“Default” values for the workflow.

o Initiation Form: The form that is presented to a user when they manually start a

workflow, and only when you have enabled a manual start of the workflow as described

earlier.

o Modification Form: A form(s) that you can present to the users at any stage of the

workflow process to get additional information from the user. Often this data will be

used to decide what branch of a multi-branch workflow a document will follow.

o Task-Edit Form: A form(s) that is associated with Tasks (e.g., Outlook Tasks) as a part of

a workflow.

o Status Page: A web page that users can access to inform them of the current state and

status of the workflow.

- See this link for additional Schema details: http://msdn2.microsoft.com/en-

us/library/ms439134.aspx

Workflow1.cs

This file represents the Workflow logic and backend business logic, and is the file that you will spend the

majority of your time working with. When you open it, you will see the Workflow Design Surface (see

picture below).

Building the Workflow

The “Entry Point” of your workflow

The OnWorkflowActivated Activity

When you open the Workflow1.cs “Design Surface”, as seen above you will see a single Workflow

Activity (Activities in Workflow are like Shapes in Visio, except with code), called

“OnWorkflowActivated1.” For all intent and purposes, all workflows should start with this activity, and

this activity will essentially “listen” for the event that SharePoint fires when your workflow should be

started.

There are two properties that we need to pay some attention to with this Workflow Activity. They are

the Correlation Token (CorrelationToken) and the Workflow Properties (WorkflowProperties), which are

the only properties that we must set or in the case of the Workflow Properties, take notice of.

Correlation Token: The correlation token for the OnWorkflowActivated Activity is a unique identifier

that enables mapping between the Workflow hosting environment (in this case SharePoint) and the

underlying Workflow Runtime Engine. One correlation token is required for the Workflow itself (this

one) and for each task that you have within the workflow (to be discussed in a future workshop).

Essentially the Correlation Token is how the Workflow Engine manages each of the active workflow

instances within the Workflow host (i.e. SharePoint in this case).

Since it is required to set this value, let’s do so now.

Steps:

- Select the “onWorkflowActivated1” workflow activity

- Set the CorrelationToken to something unique and that preferably makes sense to the

Workflow. I will set my CorrelationToken to “SimpleCopyWorkflowToken”.

- Expand the property (hit the + symbol) and you will see that the “OwnerActivityName” is

Workflow1, which is the name of our Workflow. If you change the name of your Workflow, you

have to change this as well.

Workflow Properties: Workflow Properties (WorkflowProperties) is one of the most powerful and

important properties within the workflow. In our case you see that it has already been assigned to a

local variable, called “workflowProperties,” which is a public property within the Workflow1 code-

behind file, which I will show later.

Why is the Workflow Properties (Property) so important? It is how SharePoint passes the workflow data

that we care about in the workflow, like:

- The object that caused the workflow to activate (e.g., the document that was loaded in our

Document Library)

- A myriad of information about the SharePoint List or Library

- Information about the Site that the SharePoint List or Library exists within (i.e., a SPList Object)

- An instance of the object that caused the workflow to activate (i.e., a SPListItem Object)

Since, in this case, the Workflow Properties is already assigned to a workflow variable, we will not

change it. Just keep in mind that the workflow variable name is “workflowProperties”.

Adding our workflow Activity Logic

In our case the Workflow Activity Logic is going to be pretty simple, we will add a “Code Activity” Shape

which will allow us to write our custom code for copying our file from one library to another. We will

also add a “Log To History List Activity” control to log what we’ve done.

After adding our two shapes, your workflow should look like this:

Adding our workflow “OnWorkflowActivated” code and our Constructor code

The first thing we must to do is give the Workflow a unique ID, which will be done by setting the

“workflowID” variable to a new “Global Unique Identifier” or GUID. We will also setup a couple of

variables to hold our logging information for later.

Steps:

- Double-click on the “OnWorkflowActivated1” activity, which will bring you to the code window.

Shown here:

- Add a couple of Variables for our Log History Description and Log History Outcome. I also

moved my variables for “workflowID” and “workflowProperties” above the constructor, because

that’s how I like to organize my code. This is not a requirement.

- Next add the following code to your “OnWorkflowActivated1_Invoked” method, to initialize the

Workflow ID (workflowID) to unique GUID. This will be passed to us by SharePoint through the

“workflowProperties” variable, and SharePoint will handle the creation of the new UniqueID.s

Keep in mind that you could have dozens of instances of this workflow running on a server

simultaneously (one for each file being dropped into the document library), and the Workflow

host needs a way to identify each of the workflow Instances.

Your screen should look like this (I had to do a word-wrap to make it fit)

Adding our Code for the FileCopy Activity (codeActivity1 Shape)

Now, we can add the code for our CodeActivity1 Shape to handle the File Copying.

Steps:

- Let’s rename the shape first.

o Switch back to the Workflow Design Surface

o Single-click on the codeActivity1 shape

o Change the “Name Property” to “copyFileActivity”

Your screen should look like this:

- Now let’s add our code to the shape

o Double-Click on the “copyFileActivity” and it should put you into the Workflow code

behind, and within, the “copyFileActivity_Execute” method.

o Now let’s add our code to actually copy the file from our Source Document Library to

our Destination Document Library. I should also note that you could do this with less

code than I will use here, but I want to point out a few things along the way, so I will add

a bit more code.

Your code should look something like this:

- If you want to see what the less verbose code would look like, here it is: (You can use whichever

you’d like, but I like the first version, from a readability perspective)

Logging what happened to Workflow History List

If everything works correctly in our code, the only thing that we have left to do is log the transaction in

the Workflow History List (Defined earlier in the document).

Keep in mind that in our “CopyFileActivity_ExecuteCode” section, we wrote two logging variables

“logHistoryDescription” and “logHistoryOutcome”. Those are the two variables that we are going to

connect to our “logToHistoryListActivity1” shape, and the shape will handle writing those values to the

SharePoint History.

Steps:

- Switch back to the Workflow Design Surface

- Click on the “logToHistoryListActivity1” Shape

- On the properties screen, let’s change or “set” the “HistoryDescription” property and the

“HistoryOutcome” property.

- Select the “HistoryDescription” property (put your mouse in the empty text box beside it)

- Hit the ellipses control (will show up at the end of the empty text box and looks like this )

o In the “Bind …. To an activity’s property” menu, choose “logHistoryDescription” which

represents our internal variable (the one that we set in code).

- Hit OK

Now look at the property for the control and it should look like this

- Do the same thing for the “HistoryOutcome” Property, choosing the “logHistoryOutcome”

variable

- Hit Ok

The property should now look like this:

Deploy and Debug our Workflow

This is where the advances in Visual Studio 2008 really come into play. To test our workflow, just hit

“Start Debugging” button or (F5), and Visual Studio 2008 will build, deploy and launch our

SharePoint site for us, assuming we had no build errors. If you are using Visual Studio 2005 with the

workflow extensions for SharePoint, then you’ll have a much more complex deployment, not that it’s

hard, but it is more involved. Check out this links in the “My Development Environment and Setup”

section for more information.

If you want to step through your code, which I would recommend, just to see what happens: Just put a

break point in your code or on your Workflow Design Surface and then hit the Debug Button (F5).

If everything worked correctly, you will end up at a screen that looks like this:

Now, let’s test our Workflow.

Steps:

- Select our Test Document and pull down the action menu.

- Select the “Workflows” option

Your screen should look like this:

- Once you’ve selected the “Workflows” option, the Workflow Status page will show.

Like this:

- Select our “SimpleCopyFileWorkflow” or whatever you called yours and it will compile and run.

Assuming that you had no errors in your code the resulting screen should look like this:

If you go back to the Workflow Status Page, it would look like this:

To go back, just hit the “Workfows” action again

Your screen should look like this. Notice the “Completed Workflows” Section.

Notice how it logs the date it was started and completed, and the end results “Status”. If you click on

the “SimpleCopyFileWorkflow” down in the Complete Workflow section, you will see even more detail.

Your screen will look like this:

Assuming everything was successful, we should also have a newly copied file in our Destination

Document Library. Navigate to it and see.

Your screen should look like this:

Wrap up Hopefully you see how easy it is to build a very basic document workflow with Visual Studio 2008. This

is a very long workshop (in pages) because of all of the pictures, but I hope that you see the amount of

code is minimal. With the advances in the Visual Studio 2008 IDE with respects to SharePoint workflow,

debugging and deployment is a synch.

Where to get more information Subscribe to my blog (www.sheltonblog.com) to see what other items I post around SharePoint

workflow.

Learning and research resources used for this workshop I used the following resources to help me understand SharePoint Workflow. I am not personally

recommending/endorsing any of the books, however, I did read them and you may find them helpful.

- The Windows SharePoint SDK

o Go to www.microsoft.com/downloads

o Search for “Windows SharePoint Services 3.0 SDK”

- (Book) Inside Microsoft Windows SharePoint Service 3.0

o By Ted Pattison and Daniel Larson

o ISBN: 0735623201

- (Book) Workflow in the 2007 Microsoft Office System

o By David Mann

o ISBN: 1590597001