CCS HELPDESK 4.0

Manual Installation of the Event Sink for Exchange 2000/2003/2007

 

Crow Canyon Systems, Inc.

www.crowcanyon.com

support@crowcanyon.com

 

OVERVIEW

NOTE: For Exchange Servers that run on Windows 2003 and above, there is an EventSink Setup file that can be run. The instructions below are for Manual Installation of the Event Sink on Windows 2000 Server. The procedure can also be used on Windows 2003 and later servers, in case the EventSink Setup EXE does not run for some reason.

Exchange 2000, 2003, and 2007 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 “CCSHD40.DLL” to convert emails to Help Desk tickets as part of the CCS HelpDesk program.

There are five steps to installing the Event Sink:

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

 

For Troubleshooting the Event Sink after installation, see Appendix A

 

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

External users can send to an SMTP address you set up for the Help Desk folder. To allow the folder to accept emails from external users, give Anonymous at least Contributor permissions to the 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

CCS HelpDesk 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

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

Exchange Server 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 Server and should already be in the System32 directory.

To use Regsvr32, go to Start, Run, then type regsvr32 “YourPath\CCSHD40.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 “CCS HelpDesk 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:

 

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.       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 “CCS HelpDesk Event Sink”. Click the “Components” folder under CCS HelpDesk 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 CCSHD40.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 2000/2003 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 CCS HelpDesk 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 CCSHD40.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 CCSHD40.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. Leave this at the defaults as shown below:

 

V. Select “COM Event Sink”

 

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

 

 

VII. Finally, there is the Finish screen. If there are any errors, it will tell you after you press Finish.

 

 

 

 

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. 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 “CCSHD40.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 number in the component under Components of the COM+ Application:

 

Right-click 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.

 

Event Sink Error Handling

The Event Sink 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: