Exoledb Script Host Event Sink Debugging and Troubleshooting

Introduction - updated 05/2004

I've had a few questions on how to debug event sink scripts lately so I thought I'd write a small article on the techniques I've used to do this and what you can do about the general error messages you may receive sometimes.

Troubleshooting Script Registration problem

If you have tried to register one of the scripts from any of my articles and received the following error

Error Commiting Transaction : 2141913024 Event Registration failure: The %1 specified does not contain a valid ProgID or CLSID

This errors usually means (as long as you have no typos) that the Exchange script event handler is not registered properly (or at all). To fix this have a look at this Qbase article and or my other article.

If you have followed the above steps and received an error message such as

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

This error points to a problem with the Com+ application security for the Exoledb scripthandler. For this you need to have a look at the identity tab of the Com+ application as shown below

This should be set to a user that has access to the mailboxes that you want to run your scripts on. But before you dash into using the Domain admin account remember. By default all the administrator accounts don’t have access to mailboxes other then their own. A quick way to tell if its going to work is try opening the mailbox where you are trying to register the eventsink via the M: drive (if you get access denied there's your problem). Have a look at http://support.microsoft.com/support/kb/articles/Q262/0/54.ASP for more info.  The other thing you need to think about with security is that the account you are registering the script under as well as the account you are using in the identity tab both need to have write access to the mailbox you wish to register the sink on. eg if you see an error such as this you know you have a permission problem  Error open record: -2147025891, Access is denied.

Your Event sink just doesn't fire even though its registered okay

There could be a few possibilities here the first thing to check is the security of the Com+ application as detailed above. Because the actually script code is stored as an object in the mailbox if the COM+ app doesn't have rights to view this object the code will never run.  The other things to check is make sure you have no compile errors in your code (see below on testing your code manually)  and also remember that events will not trigger on the Sent Items and outbox folders see this Qbase article for more details.

One other thing to watch out for here is that some antivirus programs quarantine the script code so you end up with a registered event with nothing inside it. You can try the following code snipit to check what's inside your event registration (which if you have used the -file switch will be your script code).

set msgobj = createobject("CDO.Message")
msgobj.datasource.open
"file://./backofficestorage/mydomain.com/mbx/TestAccount/inbox/yoursink"
set stm = CreateObject("ADODB.Stream")
Set stm = msgobj.GetStream
stm.savetofile "c:\dumpmsg.txt"

Testing you Event sink code before implementation

One of the hardest problems when it comes to troubleshooting and debugging event sink code is because its designed to run when an event happens eg an email is delivered any problems that do occur in your code (even down to simple compile errors) you may not see because they are happening at run time. There is however a very simple way to test what your code is going to do. First of all compose an email you want to fire the eventsink and then send it to the event sink mailbox. Go to the M: drive on your mail server look at the inbox of your event sink mailbox and look at the  filename of the email that you just sent . If you now take this name and apply it to the Exoledb path of the event sink mailbox eg(file//./backofficestorage/yourdomain/mbx/mailboxalias/inbox) you will the have a path that can be used to open the email in your script (or the DAV:Href is you a familiar with Exoledb). Now if you modify your code so instead of relying on the eventsink information to work out which email it should open you can specify that actual email path. This will then allow you to double click on your script to run it manually and see what happens eg if you get any errors, you can put some msgboxes in to see what's happening to certain variables etc.

Logging/Debugging

Okay first thing of the top of the bat there is no debugging or logging that's built into the scripteventsink by default so to do any troubleshooting your going to have to write your own logging/debug code. A method I use is to use the file scripting object to create a text file and then write out any of the script variables I think there might be a problem with for example.

Set fso = CreateObject("Scripting.FileSystemObject")
Set wFile = fso.OpenTextFile("c:\temp\OnSave_Log.txt", 8, True)
wfile.WriteLine ("Event Sink Fired at " & Now)
wfile.WriteLine ("Script fired by " & bstrURLItem)

Once you have opened the object up you can then write the properties of this object out such as

Wfile.writeline ("Mail from :" & msgobj.From)
wfile.writeline ("Mail subject:" & ADODBRec.Fields("urn:schemas:mailheader:subject").Value )

Using Error Checking in your Code

This is one of the most important parts of your code and one of the most overlooked. I'm certainly no Guru when it comes to error checking most of the code I have posted lacks even the basic parts of error checking but before you put anything into production some sort of error checking code is a must.

To start with you must enable error handling in your code to do this place on error resume next at the top of your script, this will mean when an error is encountered in your code instead of displaying a message box with the error to the user it will continue on executing the code. You then need to place some code further on to deal with any errors that occur. For example you may just want to write the error out to your logging file with a line such as

if err.number <> 0 then
        wfile.writeline(err.description)
        err.clear ' Clear error for next run
end if

The one thing you need to remember is if you are using error handling in your code and you are also doing some sort of loop that if an error does occur in your code before the section of the code that may be there to set your loop exit variable your code could get stuck in an endless loop

OnTimer Event Sinks

Updated 05/2004

Someone recently pointed out a inaccuracy in this article regarding my comments on the On-timer event sink registration so here's a correction

If your using OnTimer event sink with the Exoledb Script host you need to be careful of the following, If you are using the "-file" command line parameter to reference your event sink script in the registration make sure that you don't register your event sink with the extension .eml . (just use no extension the sample in the regevent.vbs file will work fine) if you do use a .eml extension the sink will register by not fire.

What happens when you use the -file reference to do an event sink registration is it copies the code from your event sink script into the eventsink object itself and then it sets the scripturl property of the eventsink registration object to reference itself.

 An alternate method of registering an ontimer eventsink is use the -url command line parameter to reference your VBS script. This means that you need to upload your script into the mailbox somewhere before you can register the event sink to point to the script url. One method I've used is the below code fragment which will create an object in your mail store and upload the code form the d:\scripts\yourscript.vbs script file to that object

Const adDefaultStream = -1
Set stm = CreateObject("ADODB.Stream")
set Rec = CreateObject("ADODB.Record")
set Rec1 = CreateObject("ADODB.Record")
Set Conn = CreateObject("ADODB.Connection")
mailboxurl = "file://./backofficestorage/yourdomain.com.au/MBX/yourmailbox/inbox/yourscript.eml"
Conn.Provider = "ExOLEDB.DataSource"
Rec.Open mailboxurl, ,3,0
Set Stm = Rec.Fields(adDefaultStream).Value
stm.charset = "us-ascii"
stm.loadfromfile "d:\scripts\yourscript.vbs"
stm.flush

The other thing to remember about OnTimer event sink registrations is that the start time and end time are in UTC format so you need to make adjustment for GMT when you registering them. If you having problems try pushing the start time back a few weeks into the past and so if this makes a difference.