Change Control

Copyright

This is a preliminary document and may be changed substantially prior to final commercial release of the software described herein.

The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the date of publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of publication.

This document is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS OR IMPLIED, IN THIS DOCUMENT.

Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in, or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

© 2003 Microsoft Corporation. All rights reserved.

The example companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted herein are fictitious. No association with any real company, organization, product, domain name, e-mail address, logo, person, place, or event is intended or should be inferred.

Microsoft, Sharepoint and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

Contents

Introduction

Scope

References

An Overview of Document Library Event Handlers

Workflow Requirements

Custom Lists

The Workflow Definition List

The Workflow Instance List

The Workflow Rules List

Setting up the Workflow

Execute the RegisterSink.bat File

Execute the Setup Wizard

Use the Visual Designer to Configure the Workflow

Using the Instance Tracker

Implementation Details

Main Classes

Rules Classes

Utility Classes

Assemblies

Introduction

This document describes a simple method that has been employed for the implementation of Workflows with Microsoft Windows Sharepoint Services 2003 (beta 2 refresh).

This method leverages the power and ease of use of Sharepoint custom lists to store information about Workflow definitions and Workflow instances. Event Handlers are attached to Document Libraries in order to apply the appropriate logic when users approve or reject Documents.

Moderators are defined and organized into Steps, grouped by an ordinal number. For each Moderator in a step, different “Handlers” can be defined that execute business logic (for example, sending an Email warning or running a BizTalk Orchestration process) in response to these events. These Handlers are loaded by Reflection, any number can be defined.

Important Note:

It should be borne in mind that the purpose of this document is to show an example of how Workflow logic can be implemented with Microsoft Windows Sharepoint Services 2003 (beta 2 refresh). This document does not purport to serve as a guideline for the implementation of this kind of solution or as a blueprint for coding best practices.

Scope

The following areas are included in this document:

• Workflow Requirements.
• Event Handling Architecture.
• Installation of the Example.
• Implementation Description.

References

The following sources will be of use in conjunction with the reading of this document:

Microsoft SharePoint Products and Technologies "v.2.0" Beta 2 Software Development Kit.

Microsoft SharePoint Portal Server "v2.0" Beta 2 Administrator's Guide.

Microsoft SharePoint Portal Server 2001, Managing Content.

An Overview of Document Library Event Handlers

Document Library Event Handlers are the key enabling technology in Sharepoint 2003 for providing Workflow functionality. These components allow tracking of changes to documents. The following events can be tracked:

Cancel Check Out: Changes made to a checked out document are undone.

Check In: A document is checked in to the library.

Check Out: A document is checked out from the library.

Copy: A document in the library is copied.

Delete: A document is deleted from the library.

Insert: A new document is saved to the library.

Move or Rename: A document is moved or renamed.

Update: An existing document in the library is edited.

Document Library Events are asynchronous, which also implies that they cannot use callbacks

How are Document Library Event Handlers implemented? An Event Handler is a .dll that contains a .NET class that implements the IListEventSink interface. This interface is very simple, as it only contains one method, OnEvent, which is used within the handler. This method, in turn, receives and SPListEvent object which contains information about the type of event that has occurred, the properties of the document, etc.

There are several important points to note about the deployment of Event Handlers (for more details, consult the Sharepoint SDK, Handling Document Library Events):

To deploy an event handler on a server, event handling must be enabled on the Virtual Server General Settings page in SharePoint Central Administration.

The managed assembly dll that defines an event handler must be installed in the Global Assembly Cache (GAC). In a server farm configuration, it must be installed in the GAC of each front-end Web server.

The Document library must be configured with the assembly name, class name and any custom properties of the Event Handler.

Workflow Requirements

Our Workflow implementation responds to the typical business needs for this kind of functionality. Specifically, we aim to fulfill the following requirements that the system must provide:

Specify a list of Moderators for a Document Library in a certain order.

Specify more than one Moderator for a given step of the Workflow in parallel.

Specify a voting weight for each Moderator.

Specify a threshold weight for approval, which, when exceeded by the weights of all voting moderators, causes the workflow to move to the next step. This threshold values is multiplied by -1 in the case of rejection, for calculating whether the workflow should move back to the previous step.

Inform the Moderators when a document they have to approve changes its state:

Is waiting Approval.

Finishes its last Workflow Step.

Is Rejected.

Is Deleted.

Goes past its warning date.

Goes past its deadline date.

Is Approved or Rejected by a user who is not a valid moderator.

Allow tracking of a document’s progress in a workflow.

Given these requirements, we can now describe the way a typical use case scenario unfolds for a workflow:

Custom Lists

How have we implemented the Workflow? We leverage Sharepoint 2003 custom list features to define 3 lists:

Workflow Definitions: defines the moderators in the workflow.

Workflow Instances: maintains state and tracking information.

Workflow Rules: (optional) maintains a list of rules that are evaluated on document attributes. This list is used in conjunction with the RuleHandler class (see implementation details later on in this document).

The next sections describe these lists.

The Workflow Definition List

This list defines the Steps planned in the approval route of a document. The list contains the following fields:

Title: arbitrary text name (Type:Text, Required)

Ordinal: the order in which the Step is executed. Giving the same number to more than one step means a parallel workflow is followed (Type:Integer, Required)

Moderator: User name of the Moderator (Type:Choice, Required)

Email: email used to inform the Moderator (Type:Text, Required).

Weight: Voting weight given to this Moderataor. The total weight must be reached for on approval to move to the next step, or (reached * -1) to go back to the previous step. (Type:Integer, Required)

Approve To Ordinal: Ordinal of the step the workflow will move to on Approval. This field allows branching of approval routes. (Type: Integer, Not Required)

Reject To Ordinal: Ordinal of the step the workflow will move to on Rejection. This field allows branching of approval routes. (Type:Integer, Not Required)

Warn At: The number of days that, when elapsed, cause a warning to be sent to Moderators of that Step. (Type:Integer, Not Required)

Deadline: the maximum number of days that may elapse before the document is rejected and passed back to the previous Step (Type:Integer, Not Required)

Library: Name of the document Library to which the Workflow applies. (Type:Text, Required).

Handler: User friendly name of the class that implements the IWorkflowHandler interface. The assembly and type details of the Handler must be included in the configuration file. This system allows us to define different handlers for different moderators and/or steps within the same workflow.

Here is an example of how simple workflows are defined in this list:

The Workflow Instance List

This list tracks the progress along the approval route of a document. The list contains the following fields:

Title: arbitrary text name (Type:Text, Required)

Ordinal: the order in which the Step is executed. (Type:Integer, Required)

Item ID: Document Identifier. (Type:Integer, Required)

Moderator: User name of the Moderator. (Type:Text, Required)

Entry Date: date the Step was entered. (Type:Date, Required)

Exit Date: date the Step was exited. (Type:Text, Not Required) [Note this is Text type, not Date, in order to allow null values]

State: Approved, Rejected, Pending (Type:Text, Required]

Weight: Voting weight given to this Moderataor. The total weight must be reached for on approval to move to the next step, or (reached * -1) to go back to the previous step. (Type:Integer, Required)

Approve To Ordinal: Ordinal of the step the workflow will move to on Approval. This field allows branching of approval routes. (Type: Integer, Not Required)

Reject To Ordinal: Ordinal of the step the workflow will move to on Rejection. This field allows branching of approval routes. (Type: Integer, Not Required)

Warning Date: Date when a Warning message will be sent (Type:Text, Not Required)

Deadline Date: Date when a Deadline message will be sent (Type: Text, Not Required)

EMail: Email of the Moderator (Type:Text, Required)

UrlAfter: Library/Title of the Document (Type:Text, Required)

WebUrl: Full url of the web involved.

Handler: User friendly name of the class that implements the IWorkflowHandler interface. The assembly and type details of the Handler must be included in the configuration file.

Moderation Comments: Contains the Approval Status comments that can be entered when changing moderation status. This is useful for tracking purposes.

Here is an example of how workflows are followed in this list:

Workflow Instance List

The Workflow Rules List

This optional list allows automatic approval routing based on field values of a document. For example, an action could be executed during the workflow based on the Amount attribute in a document: “if Amount is > 10000€ and < 20000€ then move the document to another library”.

The Rules list must be used in conjunction with the RuleHandler in the workflow Definition. Different Rules can be defined according to specific needs.

The list contains the following fields:

Title: arbitrary text name (Type:Text, Required)

Libray Field: Library in quesiton. (Type:Integer, Required)

Libray Field Type: Data type. (Type: Text, Required)

Rule Value: Variable to be evaluated. (Type:Text, Required)

Operator: Operator (<,>, etc). (Type:Text, Required)

Group: Groups rules in an AND condition. (Type:Text, Required)

Event: OnApprove, OnReject, etc. (Type:Text, Required)

Rule Type: Class instantiated to handle the rule. (Type: Text, Not Required).

Rule Parameters: Values passed as parameters to the Execute method of the Rule. (Type: Text, Not Required)

An example of some entries in the Rules list is shown below:

Workflow Rules List

Setting up the Workflow

To install the example, you will need to follow these steps:

1. Execute the RegisterSink.bat File
2. Execute the Setup Wizard
3. Create a scheduled task for the TaskHandler. This executable will send warning and deadline messages if these dates are overrun. This task will typically be run nightly. Note that the program has one command line argument, the full name and path of the workflow.config file.
4. Define the workflow: use the Workflow Designer or do it manually in the Definition list.

Execute the RegisterSink.bat File

This .bat file registers the following required .NET components in the GAC:

Microsoft.Sharepoint.Workflow.EventSinks.dll

Microsoft.Sharepoint.Workflow.Utilities.dll

Execute the Setup Wizard

The Workflow example described in this document comes with a reentrant Setup Wizard to facilitate installation. This Wizard will configure the site and list details for your workflow, and can be executed any number of times to modify the setup details.

Double Click on the file Microsoft.Sharepoint.Workflow.Wizard.exe. The following screen appears. Click on Begin.

The Site screen shows, Type a valid Url for the Sharepoint Web you wish to use. Note: the site’s Virtual Server should be previously configured to allow Event Sinks. Then Click on Next.

The Web screen shows. Choose an existing Web or type the details of a new one. Then Click on Next.

The Document Library screen shows. There are three parts to this screen:

Document Library: Choose an existing Document Library or type the details of a new one.

Logging Directory: This is the folder where the workflow process will write log files.

Impersonation Credentials: This is the user identity that will be used by the Event Sink to work with Sharepoint. Note that this user must have write permissions on the site you will be using for the workflow.

Then Click on Next.

The Definition List screen shows. Choose an existing Definition List or type the details of a new one. (The Threshold Wgt field refers to the maximum weight needed for Approval or Rejection). Then Click on Next.

The Instance List screen shows. Choose an existing Instance List or type the details of a new one. Then Click on Next.

The Handler screen shows. There are three parts to this screen:

Handler Url: Browse to the location of the Microsoft.Sharepoint.Workflow.BasicHandler.dll file.

Smtp Server: write the SMTP server name you will be using for sending mail. Leave this blank if you are using your local machine SMTP server; otherwise, you will need to configure your SMTP server with all the SMTP domains you plan to use in your mails.

OnWait Approval, OnApprove, etc: adjust theses messages to your needs.

Then Click on Next.

The Rules list screen shows. This optional list allows approval routing based on field values of a document. You must create the list even if you do not plan initially on using rules. Fill in the list details. Then click on Next.

The last screen shows. As the screen indicates, you should now configure your workflow by launching the visual Designer or by adding items manuall to the Definition list.

If, in the previous step, you clicked on the Definition List url, your Browser opens at Workflow Definitions list, where you must now add the Workflow Steps required for your Workflow. (See the next section for details on using the visual designer).

Configure your Workflow Definitions

Use the Visual Designer to Configure the Workflow

The Workflow Designer is a Microsoft Visio 2003 enabled application that allows a visual configuration of the workflow definition.

(Note: the application is contained in the Microsoft.Sharepoint.Workflow.Designer.exe file, and requires Visio 2003 to be installed on the local machine.).

If you clicked on the “Launch Designer” button, the Workflow Designer will start up, showing the following screen:

This screen allows you to choose a Document Library for your workflow. Select a library and click OK.

The Workflow Designer main screen shows. This screen is a standard Visio drawing Page. On the left, the special workflow stencil has four kinds of shapes:

Step: Groups Moderators with the same Ordinal.

Moderator: corresponds to a Definition List Item.

• Dynamic Connector: straight style connector used for ApproveTo and Reject to relationships
• Curve Connector: curved style connector used for ApproveTo and RejectTo relationships

Note: these are the only shapes recognized by the workflow designer; other shapes are simply ignored. Their custom properties are used to define the workflow by right clicking a shape and choosing the properties item. The shape sheets should not be modified manually, as this could cause the Designer to function incorrectly.

The following picture illustrates the Moderator and Step shapes on a simple workflow diagram:

Note: It is not necessary to use any connectors to define the order in which the workflow executes: the order for each Moderator is taken from its position in its containing Step shape. Connectors are only needed for ApproveTo and RejectTo relationships

The Step shape only has one customer property: Ordinal. After dragging a Step shape to the drawing surface, right click the shape and choose Properties. The following dialog will show:

The Step shape groups Moderators with the same Ordinal. When a new shape Step is added, the Designer automatically assigns it an ordinal 10 greater than the largest currently on the diagram.

The Moderator shape has several custom properties, corresponding to a Definition List item: Ordinal. After dragging a Moderator shape to the drawing surface, right click the shape and choose Properties. The following dialog will show:

The options in the drop down list boxes are automatically filled in from the workflow Definition List.

The following diagram shows the use of the ApproveTo and RejectTo connectors.

In the first Step, Operations, if the Business Unit Manager approves, the workflow jumps over the Finance Step, without passing through the Finance Step.

Likewise, in the last Step, Purchasing, if the Division Manager rejects, the workflow regresses directly to the Operations Step, without passing through the Finance Step.

To save your workflow, choose the File menu, option “Save Definition”. The application will prompt you for a Visio file name to save to and will also save the Definition items in the corresponding list in Sharepoint.

Using the Instance Tracker

The Workflow Designer also features a tracking facility that gives visual representation of the position of a document. Choosing the Tools menu, then the “Track Instance” item will open a dialog with a list of documents currently executing in the workflow.

After choosing a document, the designer will indicate the approval status of the Moderator shapes (Approved|Pending|Rejected), as shown below:

Implementation Details

The following sections detail the code implementation of the Event Sink and accompanying classes.

Main Classes

In this section we describe how we have implemented the workflow logic. The classes in the diagram are:

• WFBasicSink: base class that performs some useful functions in event handling, in particular obtaining properties from an SPListEvent
• WFSink: inherits from WFBasicSink, handles the OnEvent method by creating a new instance of WFEngine and WFEvent.
• WFEngine: is the class that actually implements the workflow logic. Delegating these activities to this class allows decoupling of the workflow logic from the IlistEventSink. The WFEngine constructor is passed a WFEvent object.
• WFEvent: contains all the information necessary to instaniate the workflow. This class allows decoupling from the IlistEvent.
• BasicHandler: implements IWFEventHandler by sending mail to Moderatos.
• TaskHandler: executable run as a scheduled task that checks for overrunning of warning of deadline dates.
• IWFEventHandler: defines the different events that can be called when the state of a workflow instances changes. WFEngine and TaskHandler only have dependencies on this interface, decoupling them from different implementations. The model is extensible: different handlers can be attached to different Workflow steps, such as the BasicHandler. Handlers are defined in the xml configuration file, and are instantiated by using Reflection.

The main class diagram follows:

Rules Classes

The rules functionality consists of a number of classes:

• RuleHandler implements IWFEventHandler This class is fired in response to workflow events such as OnApproval OnReject etc
• BaseRule: abstract class that defines the interface needed for loading concrete rule classes such as MoveDocumentRule, ChangeValueRule, etc.
• RuleListItem derives from BaseListItem to encapsulate Rules list items.

Utility Classes

We have also defined several utility classes. These classes add robustness to the model by providing accessor properties defined in the Xml configuration file and encapsulating logic specific to objects in the different Sharepoint Lists.

• DefinitionArrayList / InstanceArrayList: inherit from ArrayList to provide DefinitionListItems and InstanceListItems, respectively.
• WFListItem: Base class for items used in defining and instantiating workflows. Implements the IComparable interface to allow sorting on the Ordinal field.
• DefinitionListItem / InstanceListItems inherit from WorfklowListItem.
• ListConfig: Utility for obtaining configuration values from xml configuration file.
• DefinitionListConfig / InstanceListConfig: inherit from ListConfig, for obtaining conguration values for Definition and Instance lists, respectively.
• ListItemUtility: factilitates manipulating SPListitems.
• IWFEventHandler (see Main Classes description).

Here is the utilities class diagram:

Assemblies

The classes are implemented in several .NET assemblies:

Microsoft.Sharepoint.Workflow.EventSinks.dll: a COM+ dll that implements the Microsoft.Sharepoint IListEventSink interface, handling the Document Library events.

Microsoft.Sharepoint.Workflow.Task.exe: a .NET executable that runs nightly, warning Moderators that the Warning period has elapsed, and then rejecting documents if the Deadline is reached.

Microsoft.Sharepoint.Workflow.BasicHandler.dll: an example implemtentation of the IWorkflowHandler interface. This dll is loaded by Reflection.

Microsoft.Sharepoint.Workflow.RuleHandler.dll: contains all the classes used for Rule functionality.

Microsoft.Sharepoint.Workflow.SetUpWizard.exe: The set-up wizard.

Microsoft.Sharepoint.Workflow.Designer.exe: The visual workflow designer.

Microsoft.Sharepoint.Workflow.Utilities.dll: contains all the commonly used classes and interfaces.