Programming Microsoft Outlook and Microsoft Exchange, Second Edition (DV-MPS Programming)

The Exchange Server Routing Object library is provided by Microsoft so that you can create process instances, create and edit routing maps, and track the progress of your process instances. The Routing Object library, which is provided in the file exrtobj.dll, is a hierarchical object library like CDO. In fact, the Routing Object library was built with the expressed intention to be used with the CDO object library. Figure 13-10 shows the objects contained in the Routing Object library.

With this object library, you can create some interesting applications. To help demonstrate how useful and powerful this object library is, we will take a look at an update to the Agent Install program from Chapter 12. This program has been updated to allow you to edit routing maps and track the state or process instances in a folder. Before looking at the updated Agent Install program, however, you first must take a look at the objects in the library so that you have a firm understanding of their functionality. I'll provide the most important properties and methods you will likely use in your applications. Refer to the Agents.hlp file on the Exchange Server 5.5 Service Pack 1 CD for the full listing of properties and methods for the objects. Also, check out the Exchserv.chm file on the companion CD and the Microsoft TechNet site http://www.microsoft.com/technet/download/exchange/.

Figure 13-10 The objects in the Routing Object library.

RouteDetails Object

The RouteDetails object is a top-level object in the library. You should never explicitly create a RouteDetails object; it is passed to the VBScript subroutines that you write for the folder in the same way that the EventDetails object is passed to your VBScript event scripts. Since the routing objects are built on the Event Scripting technology, both the RouteDetails object and the EventDetails object are passed to your VBScript functions.

The RouteDetails object contains a number of properties that you will want to use in your VBScript functions, including the following:

• ProcInstance property. This property, when set to an object variable, returns the process instance object currently being executed. You can use this object to retrieve process-specific information, such as the row in the routing map that the process instance is currently executing.
• Msg property. This property, when set to an object variable, returns a CDO Message object that corresponds to the message received by the folder for the process instance. In your scripts, this message would be an approval or a rejection, or some other type of status message sent to the folder. This message would have an RUI number representing a currently executing process instance.
• Folder property. This property, when set to an object variable, returns a CDO Folder object that represents the current folder where the process instance is running. You can use this Folder object in your script to perform actions on the folder or on messages inside the folder.
• WorkItem property. This property returns the WorkItem object for the current process instance.

As you can see, the RouteDetails properties return full CDO objects, unlike the EventDetails object, which returns only EntryID properties for the message and the folder. Using the RouteDetails properties avoids the need to bind to a message or a folder in the Exchange Server store each time a script is run, so your scripts will achieve greater performance.

That said, there is one important object that is not available through the RouteDetails object and available only through the EventDetails object—the CDO Session object, which is the pre-logged-on CDO Session that the script is running under. To retrieve all the objects you want to use in your scripts, you must use both the RouteDetails and the EventDetails objects together. The following code shows how to initialize your VBScript objects with all the RouteDetails properties:

ProcInstance Object

The ProcInstance object is a top-level object that can be created independently of any other objects in the Routing Object library, or that can be obtained by using the ProcInstance property of the RouteDetails object. The ProcInstance object represents a process instance that is a work item and some additional properties for state and map information. When tracking processes in your routing object applications, you will use the ProcInstance object extensively. Some of the important properties and methods for this object include the following:

• CurrentRow property. This property returns a long value that represents the current row that the engine is executing. The value is not the same as the ActivityID of the current row that the engine is processing. To find the ActivityID, you must first scroll through the routing map and then retrieve the specific row the property corresponds to. You can then use the ActivityID property of the Row object, which you will see later in this chapter.
• Log property. When set to an object variable, this property returns the routing objects Log object. The Log object represents the custom log for a particular process instance. Don't confuse this Log object with the agent log which you saw in the previous chapter. These two logs are stored differently. The Log object in the routing objects should be used to store execution history and auditing information for the process. The Agent log should be used for debugging information about agents as well as general agent information, such as the time the agent completed execution. Note that if you want to write debugging information to the Agent log from a routing objects VBScript subroutine, you can use the Script.Response method in exactly the same way you use it in an Event Agent script.
• Map property. This property, when set to an object variable, returns a Map object that represents the map for the current process instance. Since you can have maps for individual items that are different from the default folder map, you should not assume that the default folder map and the process instance map are the same.
• Message property. Set this property to an object variable to retrieve the corresponding CDO message for the process instance. You can also set this property to a CDO Message object to tell the Routing Object library which process instance you want to work with—this is the most common use for the Message property. You will see how to use this property in the sample application later in this chapter.
• Participant property. This property returns the Participant object. The role of the Participant object is to let you quickly resolve custom roles stored in the Exchange Server directory.
• RUI Property. This property returns a long value that represents the unique RUI number for this process instance.
• Terminated property. This property returns a long value that represents whether the process instance is terminated—0 if the process instance is not terminated and is still executing, or 1 if the process instance has hit a Terminate command in the map.
• Timeout property. This property returns a Boolean that represents whether the process instance has timed out during a Wait action in a map. Timeout returns True if the process instance has timed out, and False if it has not timed out. You should use this property and the Wait action together to implement timeouts in your applications. You can then call automatic functions when the timeout occurs to either automatically move the item to the next participant or remind the current participant of the time limit for a response.
• VoteTable property. This property returns a VoteTable object that allows you to create and consolidate Outlook voting button-style messages.
• Wait property. This property returns a long value that represents the time when the process instance will expire. The Wait property is used by the engine at run time to determine whether the process instance has timed out. You probably will never use this property directly in your applications but instead will use the Timeout property just discussed.
• Open method. This method, when it has the Message property set and is called on a ProcInstance object, opens the process instance on the specific CDO Message object. You must set the Message property and use the Open method before attempting to use any of the other routing object properties.
• Save method. This method saves any changes you make to the process instance. You must also call the CDO Update method on the process instance message to save your changes permanently.

The following code snippet, written in Visual Basic, shows you how to use some of these properties and methods. It assumes you already have a valid CDO Message object, named oMessage, that corresponds to the process instance you are interested in.

Map Object

The Map object represents the routing map that is evaluated and used by the engine when executing process instances. There must be a default map in every routing folder. This map is copied onto incoming messages when the messages do not already contain maps.

The Map object is a top-level object that can be created independently of other objects in the library, so you can create maps and edit maps without creating a ProcInstance object. The following are the major properties and methods for this object:

• ActivityCount property. This property returns a long value that represents the number of activities in a particular map. You can use this property to scroll through all the activities in a map to search for a specific activity or parameter.
• Message property. This property gets or sets the CDO Message object corresponding to the object you want to retrieve or save a map onto. You must set this property before you call the methods on the Map object. You can set this property to an individual message in a folder to retrieve the map stored in the message, or to the event binding message in the folder to retrieve the default map for the folder.
• CopyTo method. The CopyTo method copies the map from one message to another message. This method takes as its argument the CDO Message object, which corresponds to the process instance you want to copy the current Map object to.
• DeleteActivity method. This method takes an ActivityID as its argument and will delete the activity from the map. You must call the SaveMap method and the CDO Message object Update method to save your changes permanently.
• DeleteMap method. This method deletes the entire map from the current CDO Message object.
• GetRow method. This method retrieves a specific row from the map. It takes the row number as a long argument and returns a Row object that corresponds to that row.
• InsertActivity method. This method inserts a Row object into the current map. It takes a long value that indicates the row number preceding the row you will insert. This method also takes a Row object as an argument to indicate the source of the row to insert. The value _1 tells the library to insert your new row after the last row in the map.
• OpenMap method. This method opens the map on the CDO Message object you specify for the Message property. You can pass in a long argument, which takes the value 0 if you want to open the map as read-only, and nonzero if you want to open the map as read/write.
• SaveMap method. This method saves the current map on the CDO Message object specified in the Message property. Note that you must also change a property on the item and call the CDO Message Update method to permanently save the item. If you do not call the CDO Update method after calling the SaveMap method, your changes will be lost when you destroy the Map object.

The following code snippet shows you how to use some of these methods and properties in your own programs. It assumes you have a valid CDO Message object, named oMessage.

Row Object

The Row object represents a single row in your map. You can create a Row object independent of the other objects in the library. After creating a Row object, you should set its properties and add it to your map. If you are retrieving a row from an existing map, to store the row, you must pass in a variable that corresponds to your Row object. The following are the most important properties and methods for this object:

• Action property. This property takes a string value and can either set or retrieve the action for the current Row object. This action can be the name of an intrinsic action or of a script subroutine you create in VBScript.
• ActivityID property. This property is a Long value that contains the unique number that identifies the row in the map. Usually, you start ActivityIDs in a new map at 100 and increment according to your preference for numbering the subsequent rows.
• Flags property. This property is a Long value that contains a flag indicating whether the Action property is an intrinsic action or a VBScript-implemented action. The possible values for this property are 0 for an intrinsic action and 2 for a VBScript action.
• CopyTo method. This method takes a Row object as its argument, then copies the current row to the new Row object.
• GetArgs method. This method returns the parameters for a Row object. The parameters are returned in a string array along with a Long variable that indicates the number of parameters for an action. See the next code snippet to learn how to use this method.
• SetArgs method. SetArgs is the opposite of GetArgs. Instead of retrieving the parameters for the Row object, the SetArgs method sets the parameters for the Row object. You must pass in a Long value that is the number of parameters for the Row object as well as a string array of those parameters.

The following code snippet shows you how to use the Row object. Note that you must convert to the correct format any arguments you pass to the methods and properties. If a method is expecting a Long value, pass a Long value. This example assumes you already have a valid Map object set to oRTMap.

Log Object

The Log object allows you to log activities that execute in your map. This object stores its log differently from the way logs are stored in the Event Agent log. The only way you can retrieve the Log object is by using the Log property on the ProcInstance object. You cannot create a separate instance of this object. The following are the methods of the Log object:

• AddLogEntry method. This method adds a new log entry to the current log of the selected process instance. This method takes the application name as a string (referred to as the name ID), which you can use to identify custom activities or functions as a string, the date/time as a Long value, and the description you want to store as a string. You probably will use this method to store route-specific information for a particular process instance. This log is useful for storing audit trails and failures in a particular process.
• GetLogEntry method. This method retrieves a log entry from the current log of the process instance. It shares the same properties as the AddLogEntry method, but it returns them instead of adding them. The parameters for these two methods differ as well: the GetLogEntry method has an extra parameter, which is for the LogIndex.
• OpenLog method. This method opens the log so that you can retrieve or add items to it.
• SaveLog method. This method saves your changes to the current log.

The following code snippet shows you how to insert an item into the log. The code assumes that you have a valid ProcInstance object named oRTProcInstance.

Participant Object

The Participant object provides a way to refer to and manipulate addresses (which can be actual e-mail addresses or roles) in your routes and resolve roles to actual addresses. For example, you would use the Participant object to find out who the manager or expense approver for a certain user is by passing in the address of that user. This object would then return to you the address of the person who performs the role you specified. The three important methods of this object include the following:

• RoleName method. You pass the role name you want to resolve as a string to this method. For example, to resolve the Expense Approver role for a user, you would pass Expense Approver.
• MemberName method. You pass this method a string containing either the unique address or unique name of a person. This string should contain the information of the person for whom you want to find the role performer associated with the role name you specified in the RoleName method. For example, if you wanted to find the expense approver for Frank Lee, you would pass, as a string to this method, either the name Frank Lee or the e-mail address of Frank Lee.
• ResolveRole method. This method returns to you the address of the person who performs the role for the member you specified. You must set a variable to this method to retrieve the address. For example, if Tom Rizzo was the expense approver role performer for Frank Lee, the e-mail address of Tom Rizzo would be returned by ResolveRole.

The following sample code shows you how to use this object in the VBScript subroutines for your routes. It assumes that you already have a valid ProcInstance object named oRTProcInstance.

VoteTable Object

The VoteTable object allows server-based applications to create Outlook voting-button messages. The Exchange Server Routing Objects do not need to rely on the Outlook object model to do this; they include the functionality to create them. Being able to create voting buttons makes it easy for your Outlook users to select custom responses, such as Approve or Reject, for your routed items. The VoteTable object can also be used to consolidate voting button response messages in the original process instance. This consolidation saves time since you do not have to write this code yourself to consolidate the responses. Furthermore, this object updates the Tracking tab in Outlook without needing code from you.

The VoteTable object can be created as a separate object or retrieved by using the VoteTable property of a ProcInstance object. The VoteTable object is used in conjunction with the RecipientEntry object, which is discussed later in this chapter. The following list describes the properties and methods for the VoteTable object:

• Count property. This property returns the number of recipient entries in the VoteTable object.
• Item property. By passing in a number specifying an index, this property will return the corresponding, existing RecipientEntry object in the VoteTable.
• PIMessage property. When creating a stand-alone VoteTable object, this property must be set to the CDO Message object, which corresponds to the process instance for which you want to check recipients' votes.
• AddButtons method. This method adds voting buttons to your message. The two parameters you must pass to this method are the CDO Message object, which is the message you want to add the voting buttons to, and a string of the voting options, separated by commas, as in "approve, reject".
• ConsolidateResponse method. This method consolidates the responses for a voting button message received by the folder. This method takes two parameters, the first being a CDO Message object, which is the voting button response message. The second parameter is a Boolean specifying whether to automatically add a RecipientEntry object to the VoteTable for the user who responded to the voting button message, if one doesn't already exist for the user.
• Save method. This method saves your changes to the VoteTable object.

The following code example shows you how to create a voting button message. It assumes you already have a valid CDO Message object called oMessage.

The next code snippet shows you how to consolidate voting button responses received in a folder. This example assumes you have a valid CDO Message object in oMessage.

RecipientEntry Object

The RecipientEntry object is always used to track the response of a recipient in the route and the date that recipient responded. The RecipientEntry object is typically used in conjunction with the VoteTable object. The following properties are available for the RecipientEntry object:

• Date property. This property is the date the recipient sent a response for the process instance.
• Recipient property. This property is the name of the recipient who responded.
• Status property. This property contains the recipient's response, such as Approve or Reject.

The following code shows you how to create and fill in a RecipientEntry object. The code will also show you how to add this RecipientEntry object to the VoteTable object. This code assumes you have a valid oRTProcInstance object.

WorkItem Object

The WorkItem object can be retrieved only as a property of the RouteDetails object. The WorkItem object can represent a new item in the folder before a related process instance for the item is found, or a new item in the folder until that item is turned into a process instance. Most of the time, your applications will not call the methods and properties of the WorkItem object directly. Rather, the routing engine will call the methods. The only exceptions to this are the following:

• Item property. This property specifies the CDO Message object you want to assign to the WorkItem object. After assigning the CDO Message object, you can use the methods of the WorkItem object with that CDO Message object.
• ItemConsolidate method. This method merges the message content of one CDO Message object with another CDO Message object. To specify the target message, set the Item property for the WorkItem object to it. The ItemConsolidate method takes three parameters, the first being an array of MAPI property tags that you want to merge with the target message. These properties can be attachments, the message body, or your own custom properties. The second parameter is the CDO Message object, which is the source message you want to consolidate your specified properties with. The third argument, or parameter, is a Boolean value; you specify True if you want to append the content to the target message, or False if you want to overwrite any existing content in the target message's properties. The next code snippet shows you how to use the ItemConsolidate method.
• EmbedMsg method. This method makes it easier for you to embed the CDO Message object into the CDO Message object you specify in the Item property for the WorkItem object. The only parameter this message takes is the source CDO Message object that you use to embed in the WorkItem CDO Message object.

To illustrate how these methods and properties work, the following sample code sets a WorkItem object to a CDO Message object. It then embeds another message in the existing CDO Message. The code also consolidates all attachments from another message into the WorkItem CDO Message object. This sample assumes you have a RouteDetails object.