Subscribe to Slipstick.com's Exchange Messaging Outlook newsletter

The Microsoft Exchange Server 5.5 Routing Objects are a set of tools to help simplify the development of email-based routing and approval applications. There are three main components:

• Routing Engine – The Microsoft Exchange Server 5.5 Routing Engine is implemented as a custom event handler running on the Microsoft Exchange Server 5.5 Event Service. It acts as a simple state engine that executes and tracks multiple process instances within a public or private folder. The state is advanced when events fire within the folder. The Microsoft Exchange Server 5.5 Routing Engine supports the execution of flow-control activities directly, and it can call Microsoft Visual Basic Scripting Edition functions for other activities.
• Routing Objects – COM objects used to program the engine’s behavior. These objects allow the creation and manipulation of process maps, which define the series of states the engine will track, and what activities are to be performed at each step.
• Process Map Actions – A default set of common Microsoft Visual Basic Scripting Edition functions for routing is supplied, including functional activities such as Send, Receive, Consolidate as well as evaluation activities such IsTimeout and IsNDR. Developers can extend these with custom script functions as their application needs it.

Using these components, developers can create applications such as simple process designers, which allow users to define and create the steps in routing/approval application. An example of such a program is included with Microsoft Exchange Server 5.5 Routing Objects as a sample application.

It is a sample application, written in Microsoft Visual Basic 5.0, that allows authorized folder owners to define and install simple sequential or parallel routes into a folder. Once a route is installed into a folder, any document posted or dropped into that folder will automatically be routed to the specified people, and the server will automatically track the status of the item.

The Microsoft Exchange Routing Wizard works by installing a process map into an Microsoft Exchange Server 5.5 folder. This process map is a "definition" for either a sequential or parallel route. The map defines the steps in the route, how timeouts should be handled, etc. The Microsoft Exchange Routing Wizard asks a series of questions, and your answers are used to build and define the process map.

This Microsoft Exchange Routing Wizard is included in the Microsoft Exchange Server 5.5 Service Pack 1 (or higher) and must be installed separately on each machine where you want to create and modify Microsoft Exchange Server 5.5 Routing scripts. Also, it requires that Microsoft Outlook 98/2000 is installed on the same machine, because CDO 1.21 is used to run the Microsoft Exchange Routing Wizard. You can find the Microsoft Exchange Routing Wizard on the Microsoft Exchange Server 5.5 Service Pack 1 (or higher) CD-ROM at the Eng\Server\Support\Collab\Sampler\Routing directory. It is also included with the SP1_55SS.EXE (resp. SP2_55SS.EXE for Service Pack 2) file, which is available for download from the Microsoft FTP Server.

You can also use the Agent Editor, which is included at the MSDN October 98, Platform SDK Update. The source code source code of the agent editor is available at the Microsoft Exchange Application Downloads Highlights or at the CDOLive Code Sample Library (see: Microsoft Sample Applications). For more information about Microsoft Exchange Application Downloads Highlights, please take a look at Links @ Microsoft.

Another way is to install a Microsoft Exchange Server 5.5 Scripting and Routing script programmatically with a program developed in Microsoft Visual Basic for example. For more information, please take a look at The Secrets of the Exchange Server Scripting and Routing, Event Service Configuration Library.

There is also an excellent third party add-on from Micro Eye, called Script Director, which provide rich functions to maintain Microsoft Exchange Server Scripting and Routing scripts. For more information, please take a look at the Links @ the World.

Once you routing enables your chosen folder, the folder will use e-mail to forward anything posted to each defined recipient in turn. Each recipient will be able to review the item being routed, and vote to approve or reject the item. If the recipients are using Microsoft Outlook 9x/2000 clients, they will be able to use Microsoft Outlook 9x/2000 voting buttons to approve or reject. If the recipients are using most other mail clients, they will be able to click on URLs to send their approval or rejection.

The Microsoft Exchange Server 5.5 Routing Engine on the server automatically tracks the status of each item in the folder. It adds any comments made by recipients to the body of the original message, and it keeps track of who has approved or rejected the item so far. To view the "status tracking" information, you need to use Microsoft Outlook 97 8.03 or Microsoft Outlook 98/2000. Go to the Microsoft Exchange Server 5.5 folder where the routed items are being stored, and double-click on any of the items to examine their status.

If the original item posted to the folder was a regular document or email message, then you will see a Tracking tab when you open the item in Microsoft Outlook 9x/2000. This tab displays which recipients have responded, whether they have approved or rejected, and what time they responded.

If the original item posted to the folder was a custom form, then you will not automatically see a Tracking page in Microsoft Outlook 9x/2000. The custom form will have to be modified to include the status tracking information in its display. This information is available via the Microsoft Exchange Server 5.5 Routing Objects.

As described above, the Microsoft Exchange Server 5.5 Routing Engine is a basic state engine component designed to execute and track multiple process instances in a Microsoft Exchange Server 5.5 folder. The engine is driven by events – OnMessageCreated and OnTimer that occur in the Microsoft Exchange Server 5.5 folder where the engine is installed. Whenever a new message arrives in the folder, or a timer (expiration) event is evaluated, the execution state of a process may get updated.

Microsoft Exchange Server 5.5 Routing Engine uses a server-side, hub-and-spoke architecture. A Microsoft Exchange Server 5.5 public or private folder (e. g. the inbox of a mailbox) acts as the hub, and the spokes are e-mail messages sent between each recipient and the hub folder. Logically, a route could be designed to move an item from user A to B to C, but each of these steps must go through the central hub in order for the state to be tracked centrally and for errors to be handled.

In this release, the primary focus of the engine is to simplify email-based routing applications. The engine routes Work Items to participants via email. Participants send email replies back to the engine in order to approve, reject, or comment on the item being routed. The engine tracks the responses and comments on the server, and provides support for exception handling in the event a timeout occurs, duplicate mail is received, etc. Email-based applications are only one class of workflow-enabled application, but they are an important one for Microsoft Exchange Server.

Route	Description
Start	A user instantiate a process by submitting an item using an e-mail client (e. g. Microsoft Outlook 9x/2000, Microsoft Outlook Web Access, etc.) to the hub folder.
Hub Folder	The hub folder is a Microsoft Exchange Server 5.5 public or private folder, which contains the process definition.
A	The Hub sends the item to recipient A who advances the route by replying to the hub.
B	The Hub sends the item to recipient B who advances the route by replying to the hub.
C	The Hub sends the item to recipient C who completes the process by replying to the hub.

The details of a route are exposed by the RouteDetails object. The Microsoft Exchange Server 5.5 Routing Engine exposes four, so called, intrinsic objects. These objects are passed to the Microsoft Exchange Server 5.5 Routing script in the same way it supplies EventDetails to the agent script. The RouteDetails object is a top-level object that script writers must use to obtain objects on the next level:

Object	Description
RouteDetails.ProcInstance	The currently executing process instance.
RouteDetails.Msg	The application item from the current process instance, as a CDO 1.x message object.
RouteDetails.Folder	The current folder, as a CDO 1.x folder object.
RouteDetails.WorkItem	Used to create a new message (WorkItem) with RouteDetails.Msg as an embedded message. Any new item in a folder is modeled as a work item until the process instance it relates to is found, or if none is found it is used as the basis from which to create a new process instance.

The Microsoft Exchange Server 5.5 Routing Engine is programmed by creating a data structure called a process map, or map for short. This map can be thought of as a low-level description of the logic in a given process or route. You can create and manage process maps, control process instances, and more by using Microsoft Exchange Server 5.5 Routing Objects. Microsoft Exchange Server 5.5 Routing Objects are designed to be used in conjunction with CDO, version 1.21. Many of the data types used in the following topics (for example, Message and Folder) are defined in CDO 1.x.

This part of the Microsoft Exchange Server 5.5 Routing Objects is compiled from the AGENTS.HLP file, which is included in the Microsoft Exchange Server 5.5 Service Pack 1 (or higher). This information is only part of the AGENTS.HLP included in Microsoft Exchange Server 5.5 Service Pack 1 (note that an updated version is included with Microsoft Exchange Server 5.5 Service Pack 2), because the Microsoft Exchange Server 5.5 Routing Objects are introduced with Service Pack 1. You can also download the most current version of the AGENTS.HLP file from CDOLive agents.zip(206 Kbyte).

Object	Description
RouteDetails	The RouteDetails object contains the details of the route; the route engine supplies it to the routing script in the same way it supplies EventDetails to the routing script. The RouteDetails object is a top-level object that script writers must use to obtain objects on the next level. Specifically, it provides the process instance (ProcInstance object) and can also be used to create WorkItems. For more information, please take a look at Microsoft Exchange Server Routing Engine Route Details.
ProcInstance	The ProcInstance object represents an instance of a process being executed. Sometimes called the PIM (Process Instance Message), this object consists of the original MAPI message consisting of the WorkItem plus additional properties for the state and map information. The ProcInstance object is a top-level object that can be created independently, or obtained through the RouteDetails object. After creating the object, in order to use it you must associate it with the specific message that it is stored in by using the Open method.
Map	The Map object represents the process map used to execute and track a particular process instance. There must be a default map in every routing-enabled folder. The default map for a folder is stored on a hidden (folder-associated) message in the folder. This message is part of the event binding that is used to register the routing engine as an event handler in that folder. The EntryID of this message is obtained from the Binding.EntryID property. The OpenMap and SaveMap methods take this message as an argument. A Map is a top-level object and can be created independently. This means that you can place a map on a message, and it will override the default map of the monitored folder. Also see About Process Maps and Enabling a Folder for Routing for more information about maps. For more information, please take a look at Microsoft Exchange Server Routing Object Process Maps.
Row	The Row object represents a single row (a single activity) in the process map. A Row object is a top-level object and can be created independently. After creating a new row, you provide values for the Action, ActivityID, and Flags properties, where ActivityID is a unique line number identifying the row, Action is the name of the action to be performed, and Flags denotes the type of action (intrinsic or script). The remaining columns in a Row are an array of arguments, set using the SetArgs method. The number of arguments is dependent on the particular Action function used. Argc is the number of arguments, and Argv is a string array containing the argument values.
Log	The Log object provides a method of logging the execution of individual activities in the map. ISV's or other developers may wish to expose the log in their tools for debugging or other purposes. Log is not a top-level object that can be separately created. It must be obtained via the Log property of a ProcInstance object.
Participant	The Participant object provides an abstract way to refer to and manipulate the e-mail addresses to be used for routing applications. The ResolveRole method works in conjunction with specially constructed distribution lists in the Microsoft Exchange global address list to provide dynamically modifiable "roles" and "relationships."
VoteTable	The VoteTable object provides a way for server applications to programmatically create Microsoft Outlook-compatible "Voting Button" properties on a message.
WorkItem	The WorkItem object represents the data to be routed or approved. It is typically posted or mailed to the application folder in order to start a process. This object is essentially a CDO 1.x Message object, wrapped with additional interfaces for correlation and consolidation. In general, most user-level applications do not need to explicitly call the methods of WorkItem. The routing engine automatically handles item correlation in most cases, and the default VBScript action Consolidate can be used to consolidate response properties back onto the original message for tracking purposes.

The data for an individual routing process is stored in a process instance. This data includes the process map, a tracking table, a log, and the original posted message. All this data in other words, the process instance itself is stored on a hidden message in the folder being monitored. A process instance models a particular route and stores all the information for that route. Each row of a map consists of an Activity ID, an Action, and one or more parameters (arguments) for each action. For example, dropping a spreadsheet into a folder will cause a process instance to be created and the spreadsheet to be embedded in it. You can encode logic at this level more or less directly into the routing map, as shown in the following example table:

Activity ID	Action	Argument
1010	Send	Manager
1020	Wait	24 hours
1030	ORSplit	IsTimeout
1040	Goto	Timeout
1050	Receive
1060	ORSplit	IsApprove
1070	Goto	Approved
1080	Goto	Rejected

The routing engine can be extended to perform application-specific actions that are implemented in script. Only the Microsoft Visual Basic Scripting Edition language is currently supported. The action's name is the name of a Microsoft Visual Basic Scripting Edition function; the action's parameters are the parameters of that Microsoft Visual Basic Scripting Edition function.

A default set of Microsoft Visual Basic Scripting Edition actions for common routing and approval applications is included in the file ROUTING.VBS, which is available for download at the Microsoft Exchange Applications Download Highlights (see Links @ Microsoft) or at the CDOLive Code Sample Library (see: Microsoft Sample Applications).

There is also a sample Microsoft Outlook 9x/2000 form template used for ad-hoc routing available for download at the Microsoft Exchange Applications Download Highlights (see Links @ Microsoft) or at the CDOLive Code Sample Library (see: Microsoft Sample Applications), which shows how to work with the routing map and the recipient table.

The Routing Wizard sample application uses the script activities extensively. Script actions are of two types:

Action	Description
IsTimeout	Branches if the current item has expired.
IsReceipt	Branches if the current item is a receipt, of one of the following three kinds: delivery receipt, read notification, not-read notification.
IsApprovalMsg	Branches if the reply is Approve or Reject.
IsApprovedTable	Branches on the overall approve/reject status for a set of parallel recipients (evaluates the complete list of votes).
IsInvalidRecip	Verifies that a response message received has come from the person in the routing sequence who received the item and from whom a response is expected.
IsOOF	Branches if the triggering message is an out-of-office message.
IsPost	Branches if the triggering message is a message with message class IPM.Post.

Action	Description
Send	Sends a "routing-slip" e-mail message to the specified participant. The routing-slip can contain either a Microsoft Outlook Web Access link to the WorkItem, or the WorkItem itself as an attachment. The participant address can be an explicit address or a role.
Receive	Processes any reply messages that successfully correlate to an existing PIM. Handles voting-button and status-tracking information.
Consolidate	Takes the message body and attachments of any reply messages, and merges them into the original PIM.
FinalizeReport	Creates/sends a summary report of the PIM status.
PreProcessing	Performs any necessary preprocessing on the PIM, such as changing its message class to the MAPI message IPM.Note in order to use Microsoft Outlook 9x/2000 tracking option.
AutoSet	Provides default approval or rejection functionality for participants.

 

Some of the actions used in a map are intrinsic, or built in to the routing engine. These actions are used primarily for process and flow-control; they control the execution of the map. Note that when creating a Row using these actions, the Flags property must be set to 0.

Action	Arguments	Description
AndSplit	Activities as Array of Long	AndSplit is used for parallel branching. It creates one or more new subprocesses that execute independently; the logic branches in parallel. The arguments are an array of Activity IDs (line numbers). The routing engine creates a new process instance for each entry in the array. The new process contains the same map but begins execution at the specified line number. Each subprocess executes separately until it encounters a Terminate statement. The main process continues executing only when all its subprocesses have terminated. It is the responsibility of the developer to ensure that each subprocess has a valid Terminate action. It's also the developer's responsibility to extract any necessary data from the subprocess's process instance message before the process terminates. Typically you would use the Consolidate script action to consolidate properties from the subprocess PIM onto the parent PIM as the last step before termination.
OrSplit	EvalFunction as String	An "IF" statement. Requires the name of a Boolean Microsoft Visual Basic Scripting Edition function that evaluates to either TRUE or FALSE. If TRUE, the next row of the map is executed. If FALSE, the next row of the map is skipped, and the following row executed.
New	ActivityID as Long	Instantiate a new route process instance.
Terminate	(None)	Ends the currently-executing process instance.
Wait	Time as Long	Wait the specified number of minutes; then execute the next row.
Goto	ActivityID as Long	Jump to specified activity in the map (line number) and begin executing there. ActivityID is the line number that identifies an activity (a row) in the process map.