Configuration tasks required for Event Listener
The Event Listener component is an event sink that is installed as a COM+ component
to Exchange Server. You must perform the following configuration
tasks on the machine running Exchange Server:
- Create a user account for running event sinks and assign it
the appropriate permissions. See Setting up a user account and permissions for event sinks. Under
normal circumstances, this will also create the connector's
user account.
- Register the Event Listener executable (BIA_Exchange.dll) on
the Exchange Server machine. See Registering Event Listener.
- Create a COM+ application for Exchange Server and add the Event
Listener component to it. See Creating a COM+ application.
- Modify the Event Listener configuration file. See Modifying the configuration file.
- Enable the Windows Event Viewer to display Event Listener messages.
See Configuring the Windows Event Viewer for use with Event Listener.
Setting up a user account and permissions for event sinks
Exchange 2003 event sinks such as Event Listener run out-of-process
and so must have some form of authentication before they can execute.
Therefore you must create a user account with permissions to execute the event sink.
This document refers to this account by the general name Exchange_User.
In most circumstances this account will also serve as the connector's
user account.
- Create a user account using Windows system administration tools.
If the user is going to be part of a domain (usually the case),
the user account must be added using Microsoft Active Directory.
Otherwise, the user account must be created using the computer's
Local Users and Groups program.
- Open the Exchange System Manager. You use this to set the new
accounts permissions.
- Navigate through the server tree until you reach your server.
For example, you might need to click through an administrative
group and a server group.
- Right click on your server. A pop-up menu appears.
- Click Properties
- Click the Security tab.
- In the Name dialog box, click Add and
then select a user from the list that appears.
- Select Full Control for the permission
level.
- Click Okay.
Refer to the Microsoft Knowledge
Base article 262054 (XADM: How to Get Service Account Access to All Mailboxes in Exchange 2003)
for more information.
Note:
It may take a few hours for the change to take
effect. If you wish the change to take place immediately, you may
reboot your Exchange Server.
Registering Event Listener
The Event Listener component must be registered on the
Exchange Server machine with the Regsvr32 utility, as
follows:
- Click Start --> Run.
The Windows Run dialog box is displayed.
- In the Open field, type the following:
regsvr32 installation_directory\BIA_Exchange.dll
where installation_directory specifies
the location in which you installed the BIA_Exchange.dll file (for example,
C:\Program Files\Exchsrvr\bin).
Windows displays a dialog box to confirm the successful registration
of the Event Listener file.
Creating a COM+ application
Perform the following steps to create a COM+ application
on your Exchange Server machine. This COM+ application is needed
to run the Event Listener event sink.
- Click Start --> Programs --> Administrative Tools --> Component Services.
The Component Services dialog box is displayed.
- Expand the Component Services tree by clicking the plus sign
(+) next to it.
- Right-click the COM+ Applications folder under Component Services,
and then click New --> Application.
The COM Application Installation Wizard launches.
- Click Next on the Welcome dialog box.
The Install or Create a New Application dialog box is displayed.
- Click Create an empty application. The
Create Empty Application dialog box is displayed.
- Type BIA_Exchange in the Enter a name for the new application field.
- In the Activation type box, click Server application,
and then click Next. The Set Application Identity dialog
box is displayed.
- In the Account box, click This user, and
then click Browse. The Select User or Group
dialog box is displayed.
- Select the name of the Exchange user you set up in Setting up a user account and permissions for event sinks, and then click OK. The user
name is inserted in the User field.
- In the Password field, type the password
for the Exchange_User.
- Retype the password in the Confirm password field,
and then click Next.
- Click Finish to create the application
and exit the wizard. The COM+ Applications folder now contains a BIA_Exchange
application folder, with corresponding Components and Roles subdirectories
underneath.
Adding Event Listener to the COM+ application
After you have created the new COM+ application, you must
add the Event Listener component to it, as follows:
- Navigate to the BIA_Exchange application folder in the Component
Services dialog box.
- Right-click the Components folder, and then click New.
The COM Application Installation Wizard launches.
- Click Next on the Welcome dialog box.
The Install or Create a New Application dialog box is displayed.
- Click Install new component(s), and then
click Next. The Install new components dialog
box opens.
- In the Files to install window, click Add.
- Browse for the BIA_Exchange.dll file you installed on the machine,
and then click OK. The wizard analyzes the
file and lists the Events component in the Components found window.
- Click Next, and then click Finish to
exit the wizard. The BIA_Exchange.Events.1 component is placed in the
BIA_Exchange application's Components folder.
Modifying the configuration file
Event Listener requires a configuration file called BIA_Exchange.ini.
This file contains configuration properties used by Event Listener; Table 5 describes the properties you
need to edit or set. Usernames are specified here so that Event
Listener can filter out events caused by itself, thereby avoiding
the "ping-pong" effect.
Table 5. Event Listener configuration properties
Property |
Description |
Default value |
CwEventID |
Identifies the last event ID used. |
zero (0) |
CWEventUser |
Specifies the User logon name for the Exchange_User
account. The Event Listener sends its notifications to this account's
mailbox. |
CwEvent |
CwAgentUsername |
Specifies the full name of the connector's account. In most cases this will be the same as Exchange_User, but it is possible to have two separate accounts, as long as permissions on both accounts have been set to have access to all mailboxes. |
CwAgent |
CwAgentUserGUID |
Specifies the GUID of the connector's
account. In most cases this account will be the same as Exchange_User. |
N/A |
CwEventUsername |
Specifies the full name of the Exchange_User
account. |
CwEvent |
EventsTraceLevel |
Specifies the level of trace messages for the
Event Listener. |
0 (no tracing) |
Make the following modifications to the file:
- Modify the CwEventUser entry to specify the name of the Exchange_User
account you set up in Setting up a user account and permissions for event sinks. When
Event Listener receives notification of an event, it sends an email
message with event information to this user account.
- Set the CwAgentUserGUID entry to specify the GUID of the user
account associated with the connector.
Note:
A convenient way of obtaining this value is to
trigger the Event Listener and then examine its event log entries.
For example:
- Set the EventsTraceLevel to 5.
- Create an event registration in the Tasks folder (SeeRegistering for events. )
- Create a new task using Outlook. This will trigger the Event
Listener.
- Using the Event Viewer, examine the entry in the Application
Log corresponding to this trigger and locate the value of CwAgentUserGUID.
- If additional filtering is
desired, modify the CwEventUsername and CWAgentUserName entries
to specify the display name of the Exchange user accounts to be
filtered out.
Configuring the Windows Event Viewer for use with Event Listener
The Event Listener logs its error and trace messages to
the Windows Event Viewer. You must manually edit the Windows Registry
to enable the Windows Event Viewer to find and properly display
Event Listener messages.
Caution
Incorrectly editing the Windows Registry can cause problems with
your machine. Use caution when editing the Registry. If you are
unfamiliar with the Registry, seek assistance from a Windows system
administrator.
Perform the following steps to update
the Windows Registry:
- If the Windows Event Viewer is open, close it now.
- Click Start --> Run,
and type regedit in the Run dialog box. The Windows Registry opens.
- Navigate to and highlight the key HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\ Services\Eventlog\Application.
- Right-click to bring up the context menu, and then click New --> Key.
A new key is added to the Registry under the Application key.
- Name the key BIA_Exchange.
- Right-click in the right pane of the Windows Registry to bring
up the context menu. Click New --> String Value.
A new entry is added.
- Name the new entry EventMessageFile.
- Double-click the EventMessageFile entry to open the Edit String
dialog box.
- In the Value data field, specify the full
path name for the BIA_Exchange.dll file (for example, ProductDir \connectors\Exchange\dependencies\eventListener\BIA_Exchange.dll),
and then click OK.
- Right-click in the right pane of the Windows Registry to bring
up the context menu. Click New --> DWORD Value.
A new entry is added to the key.
- Name the new entry TypesSupported.
- Double-click the TypesSupported entry to open the Edit DWORD
Value dialog box.
- Type 7 in the Value data field, and leave the default base (Hexadecimal)
selected. Click OK.
- Click Registry --> Exit to
close the Windows Registry.
