OUTLOOK HELP DESK 3.1 – Service Provider edition

 

 Installing the Event Sink for Exchange 2000, 2003 and 2007

 

Crow Canyon Systems, Inc.

www.crowcanyon.com

support@crowcanyon.com

 

Installation of the Event Sink involves simply running the CCSEventSinkSetup.exe on the Exchange Server. Click here to get started.

 

For Troubleshooting the Event Sink after installation, see Appendix A

 

OVERVIEW

Exchange 2000 and above use Event Sinks to convert emails into new tickets. Event Sinks react to events in the Exchange public folders, such as the addition or deletion of a message. Event Sinks are compiled DLLs installed as a COM+ Components on the Exchange Server. They are faster and more efficient than the folder Agents and scripts that were used with the Microsoft Exchange Event Service in Exchange 5.5. We provide “OHD310SP.DLL” to convert emails to Help Desk tickets as part of the Outlook Help Desk program.

Using Email to create new Help Desk Tickets

Users can simply send an email to the Help Desk folder and the Event Sink will convert the email into a new Help Desk Ticket.

Accepting emails from inside the organization

For internal users, you can show the Help Desk in the Global Address List. Users either select it from the address list or just type “Help Desk” in the To: line. To allow your users to do this, you must show the Help Desk folder in the Address Book.

Accepting emails from outside the organization

Customers or clients can send to an SMTP address you set up for the Help Desk folder. To allow the folder to accept emails from external senders, give Anonymous at least Contributor permissions to the Help Desk folder. To set up an email address, open Exchange System Manager, find the Help Desk folder under Folders/Public Folders, go to Properties and check the E-mail Addresses tab for the SMTP address.

Using a Web form to generate emails

Outlook Help Desk comes with a full-fledged web application that offers users a way to enter and view tickets without using Outlook client. It runs on an OWA server and users must login with a Windows account.

Another way to use the Web is to create a simple Web form that users can fill out without logging in. When the form is submitted, a script creates an email out of the web form and sends it to the Help Desk folder. The Event Sink will treat this email like any other email and convert it into a new Help Desk ticket.

The advantage to this is that users do not need a Windows accounts. Anyone who can access your Web server can fill out a ticket. The web form can run on any web server. This is a good way to service outside customers by providing a “Send email to support” link on your web site. You can set up an Intranet link this way also.

 

INSTALLATION WITH SETUP.EXE PROGRAM

The trial package comes with “CCSEventSinkSetup.exe” in the EventSink folder that is in the Zipped package. Extract this EXE and copy to the Exchange Server.

 

In order to run the EXE, you need to be logged into the Exchange with an account that has a mailbox that is Owner of the Help Desk folder. That permission is set in Outlook by right-clicking the Help Desk folder and going to Properties/Permissions. The “Permissions” tab only shows up for Owners of the folder.

 

Once logged in to the Exchange Server with an account with that is Owner of the Help Desk folder, double-click the Setup file. The following screens appear:

 

WELCOME

 

 

LICENSE

 

 

The “User Accounts and Permissions” screen needs to be filled in correctly to install the Event Sink successfully:

1) User Name and Password – this is the account that the Event Sink will run under. It may be the same account you are logged in to the Exchange Server when running this Setup, but it does not have to be. (Note: This account will show up on the COM+ Application in Component Services, and can be changed there, as described in the Appendix of this manual.)

 

2) Email Domain is pre-filled, but most likely you will need to change this to the domain that is used in your SMTP address, usually something like “yourcompany.com”

 

3) The Public Folder path can be selected using the button at the right of the box, or manually entered. It is not case-sensitive, but all the spelling and spacing have to be correct.

 

 

 

CONFIRMATION

 

After running the Setup.exe, the Event Sink should be installed. You can test this by sending in emails to the Help Desk folder and seeing if they are converted to Help Desk tickets.

 

If you wish to review the Event Sink setup, there are two parts to check:

 

1) First is the Administrative Tools/Component Services. The Event Sink should be listed as a COM+ Application as follows:

 

 

2) The other place to check is the Event Registration on the Help Desk folder. For this, the “enum.bat” that is in the EventSink folder in the Trial package can be used. You will need to Edit the BAT file to put in the correct email domain and folder path. The file comes with this syntax:

 

cscript RegEvent.vbs enum "file://./backofficestorage/exchangetest.com/public folders/help desk" all

 

Explanation of parts in bold:

exchangetest.com = domain needs to be your email domain. This is often also your Active Directory domain, but not always.

help desk = you must put in the correct path to the “Help Desk” folder. The above example assumes Help Desk is right under the All Public Folders. If not, you must put in each folder level, such as “file://./backofficestorage/domain/public folders/IT Support/help desk”.

 

Replace as needed, then run the BAT file (or just this command directly) from the Command Prompt. Change the Command Prompt directory to be the folder with the enum.bat in it.

 

Here is an example with a domain of singleflower.com, and the Help Desk right under All Public Folders (all on one line):

>Cscript RegEvent.vbs enum “file://./backofficestorage/singleflower.com/public folders/help desk” all

 

INSTALLATION WITHOUT SETUP.EXE PROGRAM

Only use this procedure if the Setup.exe program is not successful or if you are not able to use the Setup.exe program for some reason.

Before we automated the install process with a Setup.exe, the following procedure was required to install the Event Sink. This is included here for troubleshooting and if for some reason the Event Sink needs to be added manually or reconfigured.

A.      Choose or set up User Account for running Event Sinks

B.      Install and register the DLL

C.      Create a COM+ Application

D.      Add Components to the COM+ Application

E.      Add an Event Registration to the Help Desk folder

 

A. Set up User Account and Permissions for running Event Sinks

Exchange Event Sinks run out-of-process and therefore some form of authentication is required before the code in the DLL can execute. For the Event Sink to run correctly, you must specify a user account under whose security context the code will execute. This account is specified when setting up the Component in Step C below.

The code will always run with the permissions of this user account, regardless of who wrote the DLL or who installed it. Anything the account can do, the code can do, and conversely, anything the account is denied from doing, the code will be denied from doing. The account needs:

To explain:

  1. EDITOR: When an email is sent to the Help Desk folder, the DLL “edits” the email to create a ticket.
  2. DOMAIN ADMINS: When the email is converted to a ticket, a notification message is sent to the names in the Automatic Notification list in the Five Utilities form in the Utilities folder. The DLL takes the FROM address of the email and puts it into the FROM of the notification message. The notification message will be seen as from the person who sent in the email. (However, the sent messages will be in the Sent Items of the user account that you use for the Event Sink.) The user account for the Event Sink therefore needs the Send As permission for any mailbox in the Exchange organization. This is granted by default to members of the Domain Admins group.

 

B. Install and Register the DLL on the Exchange Server

Place the DLL in a directory on the Exchange Server. We recommend the “\Program Files/Exchsrvr/Bin” directory on your system drive so that the DLL is with other Exchange-related DLLs. Once the DLL is copied to the server, it needs to be registered using Regsvr32. This utility comes with Windows 2000 and 2003 Server and should already be in the System32 directory.

To use Regsvr32, go to Start, Run, then type regsvr32 “YourPath\OHD310SP.DLL” in the box (substituting in the full path to the DLL for “YourPath”). Regsvr32 returns a success message if the DLL is registered successfully.

 

C. Creating a COM+ Application on the Exchange Server

  1. Go to Start/Programs/Administrative Tools/Component Services. Expand Component Services and then expand COM+ Applications. A screen similar to this comes up:

 

  1. Right-click the COM+  Applications folder and click New. On the shortcut menu, click Application. This welcome screen comes up. Click Next:

 

  1. On the “Install or Create a New Application” page, click “Create an empty application”.

 

  1. On the “Create Empty Application” page, enter “Outlook Help Desk Event Sink” for the name and select Server Application for the type. Click Next.

 

 

5.       On the “Set Application Identity” page, select “This user:” and Browse for the appropriate account for running Event Sinks, along with the password.

ON EXCHANGE 2000

 

ON EXCHANGE 2003/2007:

 

6.       ON EXCHANGE 2003/2007:

Press Next on the next screen, since the CreaterOwner role is the only one needed.

 

7.       ON EXCHANGE 2003/2007:

Press Next on the next screen, since the account is already in the CreatorOwner role.

 

 

8.       On Exchange 2000, 2003 or 2007: Select “Finish” on the last Thank you screen.

 

 

D. Add Components to the COM+ Application

With the new COM+ application created, you can now add components to it.

  1. Go once again to the Component Services console, expand “Component Services”, then “COM+ Applications”, then “Outlook Help Desk Event Sink”. Click the “Components” folder under Outlook Help Desk Event Sink to open it.

 

 

  1. Right-click “Components”, then choose “New”. On the Welcome screen, click Next.

 

  1. On the “Import or Install a Component”, choose “Install new component(s)”

 

  1. On the “Install new components” page, use Add to find the OHD310SP.DLL.

 

 

  1.  The wizard analyzes the DLL and lists the Components found. Click Next.

 

  1. Click Finish on the final “Thank you” page.

 

  1. The DLL components should now be listed in the Components folder.

 

 

E. Creating an Event Registration Item in the Public Folder

There are a variety of methods to create an Event Registration in a public folder. We offer two methods here. One is using the regevent.vbs on the command line. The other is using a utility in the Exchange Server SDK. You can either of these two methods.

 

Notes: This must be done directly on the Exchange Server and not through Terminal Services. Also, you must be log in with an account that has an associated mailbox that is Owner of the Help Desk folder.

 

See Event Registration Errors at the end of this section if you run into any errors.

 

1. USING REGEVENT.VBS

You can use RegEvent.vbs to register Event Sinks in the Help Desk folder. For the nitty-gritty details on using RegEvent.vbs see this link. You need to have RegEvent.vbs, which is included in the Outlook Help Desk package (it is also in the Exchange Server SP1, the Exchange SDK and other places).

To use RegEvent.vbs, run Cscript on the command line. The syntax to add an Event Registration to the Help Desk folder is as follows (all on one line):

Cscript “path\RegEvent.vbs” Add OnSave OHD310SP.AsyncEvents “file://./backofficestorage/domain/public folders/help desk/regevent.eml”

 

Explanation of parts in bold:

            “path\RegEvent.vbs” = the full path to the RegEvent.vbs   

domain = domain needs to be your email domain. This is often also your Active Directory domain, but not always.

help desk = you must put in the correct path to the “Help Desk” folder. The above example assumes Help Desk is right under the All Public Folders. If not, you must put in each folder level, such as “file://./backofficestorage/domain/public folders/IT Support/help desk/regevent.eml”.

 

Here is an example with RegEvent in the root of C drive, a domain of singleflower.com, and the Help Desk right under All Public Folders (all on one line):

Cscript “C:\RegEvent.vbs” Add OnSave OHD310SP.AsyncEvents “file://./backofficestorage/singleflower.com/public folders/help desk/regevent.eml”

 

To see what Event Registrations are on the Folder, use “Enum” instead of “Add” as follows (all on one line):

Cscript “C:\RegEvent.vbs” Enum “file://./backofficestorage/singleflower.com/public folders/help desk”

 

To delete all Event Registrations on the folder, use this (all on one line):

Cscript “C:\RegEvent.vbs” Delete “file://./backofficestorage/singleflower.com/public folders/help desk”

 

 

2. USING THE EXCHANGE SDK

A.      One of the Exchange SDK tools is “Exchange Explorer”. Start this utility and log in.

B.      In the Exchange Explorer screen, choose the Help Desk folder.

C.      From the File menu, choose “Add Event Registration”

D.      The “Exchange Store Event Sink Registration” wizard starts:

I. The name you give the sink is not critical and is used only for later reference.

 

 

 

II. The default kind of event is “Asynchronous”, which is what you want.

 

III. Check “OnSave”

 

IV. Choose “Exact” for the Scope and leave “Firing criteria” blank.

 

 

 

 

V. Select “COM Event Sink”

 

 

VI. The “class” is “OHD310SP.AsyncEvents”

 

VII. Finally, there is the Finish screen

 

 

 

To Check on Event Registration

In the Details view of Exchange Explorer, the folder Items can be listed. The event registration shows up like other messages, except that it is hidden, has a different icon and its DAV:contentclass is "urn:content-class:storeeventreg". You can right-click the event registration item to modify it. It also can be deleted from this screen.

 

 

Event Registration Errors

 

“Error Opening Connection”

This means the URL (the part that starts with file://) is wrong. This is usually the domain portion. Try another domain. It should be the email domain of your Exchange server, not the Active Directory domain. See also Q286336 if you have subdomains.

 

“Error Opening Connection : -2147217895 Object or data matching the name,

or selection criteria was not found within the scope of this operation.”

This is usually because you are attempting the Event Registration while logged in with an account that does not have an associated mailbox with Owner permissions on the Help Desk folder.

 

“Error Committing Transaction : -2147024891 Access is denied.”

This is usually because you are attempting the Event Registration while logged in with an account that does not have an associated mailbox with Owner permissions on the Help Desk folder.

 

“Error Committing Transaction : -2141913011 Event Registration failure: The specified event sink (ProgID: % 1) is not allowed to run in-proc.”

This usually means the COM+ component was not added as a Server application. It needs to be a server application, not a library application. Right-click the component in Component Services, go to Properties and set it to a server application on the Application tab.

APPENDIX A

 

Troubleshooting the Event Sink

After installing the Event Sink, you should be able to send an email to the Help Desk folder and it should get converted to a new Help Desk ticket. This usually only takes a few seconds. If this does not work, here are some troubleshooting tips:

The email conversion is a two-step process. First, the email has to arrive at the folder. After arriving, it gets converted into a ticket.

 

Emails do NOT arrive at the folder

If emails do not arrive in the folder, then the error is in the configuration of the Help Desk folder, not in the Event Sink. The folder must be Mail-enabled in the Exchange System Manager. If you want the folder to receive mails from outside customers, then the Anonymous permission on the Help Desk folder must be set to Contributor.

The email address of the Help Desk folder can be set in Exchange System Manager. This address could be used by people inside or outside your company. For people inside your company, you can set the folder to show in the Global Address List. If it is listed in there, then your users can find it easily when sending an email.

Another consideration is if there are multiple Exchange servers with replicas of the Help Desk folder. If that is the case, the email could be arriving at another server different than the one with the Event Sink installed. In that case, put the Event Sink on both servers or reduce it to one replica.

 

Emails arrive at the folder but are converted into regular Tasks

The most common reason for this is that you are using the wrong DLL (such as the demo one instead of the full release one). Make sure you have the correct DLL, that is, the one that matches the version of the program that you are using, and put it in place of the existing DLL that you have there now.

 

Emails arrive at the folder but are not converted

If the emails do arrive in the Help Desk folder, but are not converted into tickets, then that could be an issue with the Event Sink configuration.

Check COM+ Application Account

The account that the COM+ Application runs under needs to be mail-enabled, and its Exchange mailbox must be Owner of the Help Desk folder. This can be confusing, The COM+ Application account is a Windows account, and the Help Desk permissions are given to mailboxes. The two permissions have to be coordinated -- the Windows account on the COM+ Application needs to have its mailbox be Owner of the Help Desk folder.

Make sure registered DLL matches DLL in Component Services

Another crucial part is that the DLL is installed and registered on the server. It is very likely that it is, otherwise you could not add it under the Components folder in the COM+ Application. However, there are times when it gets registered twice. Therefore, you can check the Class ID in the registry against the Class ID in the Component, as follows:

 

Go to Regedit on the Exchange Server, then HKEY_Classes_Root. Find the DLL in the list (this will be the same listing as under the Components folder in the COM+ Application, something like “OHD310SP.AsyncEvents”). Under it is a Clsid folder. See what the number is there and compare it to the number found on the Component Service. These long GUID numbers should match.

 

 

 

 

Compare to CLSID number in the OHD310SP.AsyncEvents component under Components of the COM+ Application:

 

Right-click the component and go to Properties:

 

Check if there is more than one Event Registration on the Help Desk folder

There should only be one Event Registration for this Event Sink on the Help Desk folder. You can see this in Exchange Explorer. Check the full list of Items in the Help Desk and make sure there is only one with the icon of the hammer lying across a piece of paper.

The only reason there might be two Registrations is if they are for different Event Sinks. You can look in the Property of the Event Registrations for the SinkClass and make sure a) that it is correct; and b) that there is only one Registration for that SinkClass.

 

 (Note: The SinkClass is “OHD310SP.AsyncEvents” in the Service Provider edition.)

 

Event Sink Error Handling

The Event Sink (starting with May 10, 2006) contains Error Handling code that writes errors out to the Event Viewer on the Exchange Server where it is running. The errors have a source of “VBRuntime” and Event ID of 1.

 

The error details screen gives important information in the description: