Overlooking the world of SBS2003 and Office Systems 2003

When the Agent Tab appears, you then have access to the Agent Script Editor and the Agent Log.  The Agent Tab opens with a control listing the Agents that are defined for this folder.  It is empty, of course, the first time you open it. You click the Add button and give the agent a name and specify which event it will use. The script Editor then appears and you are presented with stubs of the four events that can be used to give life to the Agent.  You could then start building your script.  Usually, and certainly for the first time, you will want to install a script that you have downloaded from Microsoft or CDOLive.  The instructions with these scripts is to replace all the initial code in the Script Agent Editor with the downloaded code.  This guarantees that you will get the event to fire and see the entries in the log before you start introducing the errors with your own code.  These starter Agent Scripts progress through a bunch of nested ifs, with each if statement testing the success of each step in the process of answering the Event, getting the CDO Session object, logging on, getting the Item from the ID that comes with the Event Context object, and on, until the function is finally performed.  I recommend starting with the Change Message Class Agent script as the final step is just two lines of code and you can't really miss it. 

Debugging your own script is a real tedious process.  The Agent scripts and the Agents log are implemented as hidden messages in the folder.  You can only see them by invoking them from the Agents tab.  The only other source of information about the processing of the script is to be found in the Application Event log.  Usually, the logging information there is set to minimum, which doesn't tell you much.  You may want to change that to maximum, to get more information out of every run.

The embedded if statements really comprise a structured approach to programming.  Each step adds some logging info to a global string, and it all gets added to the Agent's Log when the Agent completes.  The consequence of this structure is that, if you have an error in your code that kills script processing, you won't get any material in your log, nor any change in your objects in the folder, and will be left wondering if the event is firing the script at all.  There should be an error event in the Server's Event log, perhaps not the most convenient place to find it.  If you decide to send you own messages directly to the log, you will discover that only the last one gets out--not very satisfactory if you have put in a whole bunch of different messages to determine how the pachinko balls fall through the bumpers.  I found that the best approach was to use the default method of adding your progress message and moving a Exit Sub command progressively through the code to determine which line is the Death Star.  

Agent 007: The complete code of Agent 007 is included in the download package.  Several features are discussed here, because they are gotcha's that you want to know ahead of time.

1) The Crippled Appointment Item  When you use the Event context object to acquire the Appointment object causing the event, 

' Get current message
Set oCurrentMsg = oSession.GetMessage(EventDetails.MessageID,Null)

you don't get a real Appointment object.  By design, the Message Class of the returned object is not the number for a real appointment object.  Consequently, most of the Appointment properties cannot be accessed.  The usual code dies leaving you a message that the object does not support that property.  But, you do get a subject property and an ItemID, so you can search the folder for the Event causing item, and get the real appointment item.

Set omyMsgsCol = omyFolder.Messages

On Error Resume Next

myMsgsColCount = omyMsgsCol.Count
LoopFlag = 1
For Ndex = 1 to myMsgsColCount
Set omyMsg = omyMsgsCol.Item(Ndex)
If omyMsg.Subject = oCurrentMsg.Subject Then
'If oSession.CompareIDs(omyMsg.ID, oCurrentMsg.ID) = True Then
LoopFlag = 0
Call DebugAppend("Ndex = " & Ndex, False)
Exit For
End if
If Ndex = myMsgsColCount then Exit For
Next

The above code searches the folder for a matching subject, which is OK if you expect to have unique subject fields.  Us old Outlook programmers expect that the correct item can be found by matching the ItemID properties.  In CDO, you have to use the CompareIDs method from the Session object, as shown in the commented-out if statement.  This line, however, causes the script to say it failed, but actually puts the correct answer in the outgoing buffer.  Changing the code back to a match on the subject field causes the next event to flush the suspended output and generates its own output.  I could not get anyone to respond to the problem in the various Exchange newsgroups, so it is an unresolved issue for me.  But I did notice that the last 6 or 7 digits of the ItemID property map to the index of the item in the folder, so they can be used to confirm a match on the subject field.

Send mail to Hollis@outlookbythesound.com with questions or comments about this web site.
Last modified: October 31, 2003