Writing Agents by Using Scripts

The first step in writing scripts that run as part of the Exchange Event Service is to create an agent that acts as the event handler for certain folder events. To reach this interface, however, you are required to run certain versions of Outlook. To be a script writer for the Event Service, you must be running Outlook 97 version 8.03 or higher. The interface for creating new agents in Outlook is the Agents tab in the Properties dialog box, which was shown in Figure 12-5. To create a new agent, follow these steps:

1. Start Outlook 8.03 or a later version.
2. Right-click on a folder you own where you want to create an agent, and select Properties.
3. Click on the Agents tab, which should be visible if you have the correct permissions for the folder and the Server Scripting add-in is installed. At the bottom of the Agents tab is a drop-down menu from which you select the Exchange Server where you want to run your agents. Make sure that the correct server is selected in the drop-down list. Only servers with the Event Service installed will appear in this list. Note that all agents in the folder will run on that Event Service computer. You cannot run agents that are in the same folder on different Event Service computers. Your agents do not have to run on the same server as the folders they monitor.
4. To create a new agent, click the New button. The New Agent dialog box appears, as shown in Figure 12-6.



Figure 12-6 The New Agent dialog box. This dialog box allows you to pick the events that your agent will fire on.

5. Type in a name for your agent.
6. Select the events that your agent will handle. To create a timer-based agent, select the first option, named A Scheduled Event Occurs, and click the Schedule button. The Scheduled Event dialog box appears, as shown in Figure 12-7.



Figure 12-7 The Scheduled Event dialog box allows you to configure scheduled events for your agents.

7. In the Scheduled Event dialog box, you can specify that the event should fire hourly, daily, or weekly, as well as limit the hours when the event fires. Limiting the hours when your agent runs is useful if you want to make the agent run when the server is least taxed, usually late at night or early in the morning.
8. After specifying which events the agent should handle, select which action will occur for those events. To do this, select either the Script option or the Other option in the bottom half of the New Agent dialog box. The Other option enables the drop-down list of custom event handlers installed on the server. For example, if you have the custom event handler Exchange Routing Objects installed, the Microsoft Routing Engine Agent will appear in the list.
9. To create a new script, select the Script option, and click the Edit Script button. Notepad will automatically display an .asp file that contains the event procedures to handle the four events supported in the Event Service, as shown in Figure 12-8.

Figure 12-8 A new script shown in Notepad. Notice how the new agent automatically contains four event procedures to handle the four events supported by the Event Service.

Supported Event Types

As mentioned earlier, the Event Service supports four different event types: message create, change, delete, and timer-based. To write a script that implements your functionality for these events, you must modify these four default stub subroutines:

• Folder_OnMessageCreated
• Message_OnChanged
• Folder_OnMessageDeleted
• Folder_OnTimer

When you write an Event Scripting Agent, you can also use JavaScript. In JavaScript, these would be the four functions:

• Folder::OnMessageCreated
• Message::OnChanged
• Folder::OnMessageDeleted
• Folder::OnTimer

Intrinsic Objects for Scripts

Collaboration Data Objects (CDO), which you learned about in Chapter 11, represent the intrinsic object model for your scripts. When you are writing agents, the Event Service passes you some objects and variables that you can use to quickly figure out what item triggered the event and in what folder the item is located. To help you access these items quickly as well as access other Exchange Server items, the Event Service also passes you a pre-logged-on CDO session so that you do not have to log on to the Exchange Server yourself. The intrinsic objects passed to your script by the Event Service are discussed in the following sections.

EventDetails.Session

The EventDetails.Session object represents the pre-logged-on CDO session for your script. The Event Service decides which identity to use for logging on to your script by using the identity of the author who most recently saved the script. This is important to consider for two reasons. First, the functionality of your application might depend on access to specific items in the Exchange Server Information Store. If the identity of the most recent author does not have access to this information, your script will not work.

Second, any mail you send from your script will use the name of the pre-logged-on CDO session because the Event Service is logging in as this user. The sent messages will also be saved in the Sent Items folder of that user. For these reasons, consider creating unique identities for your agents, and log on as these users to save your script. For example, if you are creating an expense report application, you might want to create a user named Expense Report Administrator and log on to your Exchange Server as that user. Then create and save your script using that identity. Any of the e-mail sent by the agent will appear to be from the Expense Report Administrator rather than from your personal account.

Since the CDO Session object is pre-logged-on, you can start accessing CDO objects directly from the EventDetails.Session object. It is a good idea in your script to assign the EventDetails.Session object to another variable for use throughout your script.

EventDetails.FolderID

The EventDetails.FolderID variable contains the entry identifier of the folder that the event took place in. By using this variable with the CDO GetFolder method, you can quickly retrieve the correct folder for the event. Again, it is a good idea to assign this variable to another variable in your script.

EventDetails.MessageID

The EventDetails.MessageID variable contains the entry identifier of the message that triggered the event. By using this variable with the CDO GetMessage method, you can quickly retrieve the exact message that the event corresponds to. Be aware, however, that timer events do not pass an EventDetails.MessageID variable because no message triggers the event; rather, an elapsed amount of time triggers the event. Keep this in mind when creating scripts, because an error related to EventDetails.MessageID for a timer event can be hard to track down when debugging.

Instantiating Other COM Objects from Your Scripts

In addition to using the CDO object library in your scripts, you can call other COM components by using the CreateObject method in VBScript. These components can include server-based object libraries such as ADO for database access and ADSI for directory access. You can even instantiate your own COM components developed using Visual Basic or Visual C++. There are two primary requirements for custom COM components to be used with the Event Service:

• The components must not have any user interface elements. Because the Event Service is running on the Exchange Server without an interactive user at the keyboard, the component can't, for example, display dialog boxes or error messages.
• The component must be programmed as an apartment-threaded component.

By remembering these two requirements, you can offload much of the work in your scripts to your COM components and include only the necessary script to instantiate your components.

To send errors from your component to the event script, use the Error.Raise method in your component. For debugging purposes, use the arguments of the Raise method to pass back the correct error number as well as the source and description of the error.

If your components instantiate other remote COM components, make sure to configure Distributed Component Object Model (DCOM) correctly so that the Windows NT account the Event Service is running under can correctly instantiate them. You can modify the permissions for DCOM using the DCOM Configuration program (dcomcnfg.exe).

In your objects, you can also create custom COM components that use the features of Microsoft Transaction Server (MTS) to make the components more scalable and robust. For example, components created with MTS can handle process isolation, security identity, resource pooling, and distributed transaction coordination. Your script can instantiate MTS objects using CreateObject in the same way it instantiates other types of objects.