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