|
|
Home : Search : Code Sample Library : Downloads : About : Feedback :
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:
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.
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:
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.
The Premier Resource for
Microsoft Collaboration Data Objects