A Comfortable Couch

Tuesday, October 26, 2004

Agent Boost Alpha

Here is the first cut at AgentBoost. This is version, oh I dunno know, lets say 0.2. There is no documentation, the code isn't well commented or organized and I've only done minimal testing. But it's already pretty powerful.

To install it, place nAgentBoost.dll in your notes program directory, aboost.nsf into your data directory and the line extmgr_addins=nAgentBoost.dll into you Notes.ini file. To see a lot of debug messages put AgentBoostDebugMsg=1 in your notes.ini.

So far with Agent Boost you can have agents run on the following events: document open, document save/update, document delete and mail send. It can be installed on a client or a server. Currently it is only for Windows. I have only tested it on Windows XP and Domino 6.51, but it should run on R5 and later and any Win32 OS. Also, be careful what you use it for, the global events can royally screw things up if your agents aren't written carefully. Don't run it on a production server.

I don't have any documentation, mostly because I'm lazy, but also because anything about this project is subject to change before a version 1.0. So instead I have really simple instructions to set up a test agent.

The following instructions show you how to set up Agent Boost to not allow the sending mail messages by a particular user:

  1. On the Domino where Agent Boost is installed, create database called mailcatcher.nsf.
  2. From aboost.nsf, copy the AgentBoost library to the clipboard and paste into the new database.
  3. In the database, create an agent named CatchEmails.
    In the agent properties, give the agent a target of None (I think its called "Run once" in R5).
    Put this code in the agent (Replace "CN=Damien Katz/O=Corp" with a test user name in canonical format):
    Use "AgentBoost"

    Sub Initialize
      Dim s As New notessession
      Dim doc As NotesDocument

      Set doc = s.documentcontext

      If doc.From(0) = "CN=Damien Katz/O=Corp" Then
        Print "Aborting the send of a mail message"
      End If

    End Sub
  4. Open aboost.nsf. Create a new Agent Boost document. Save it with the following settings:
    Database File Name: mailcatcher.nsf
    Agent Name: CatchEmails
    Event: Mail Arrival
    When: Run before the event occurs
  5. You are done!
To test it out, switch over to the test user account and send a message mail. You should see on the server console "Agent printing: Aborting the send of a mail message". The user will not see an error message, the mail will appear to be sent, but the agent intercepted it and aborted the event.

Please send me any questions, feedback, ideas or bugs. There is still a lot more it could do, and many more events Agent Boost can used for, like when someone adds a document to a folder or when a replication conflict occurs. I can also create a setting where only one instance of an agent is run at any time so that race conditions don't occur (for example, if you want to generate a sequential number whenever a document is saved).

If anyone wants to help me out with this project, let me know. There are lots of things I'd like help with, development, testing, documentation, pretty UI, etc.

And again, any feedback on any portion of Agent Boost is welcomed.

Download AgentBoostAlpha.zip


Julian Robichaux said...

So, does this count as the "published app" that you have to produce to satisfy the terms of your Microsoft Empower thingie?

I think there would be some small amount of irony there, fulfilling your MS obligations by writing a Notes app.

- Julian

10:24 PMlink  
Damien said...

LOL! I think this might. I was planning on building Couch for Windows anyway, but now I can change my mind and not worry about it.

12:59 AMlink  
Anonymous said...

Hi Damien,

you should keep your code from initializing itself every time a process starts on the server (ExtMgr addins get called per process, not per server). Currently you re-cache over and over again every time a task loads...
For an addtl. feature, it would be great to add support for SMTPMessageAcceptEMCallback, SMTPDisconnectEMCallback, SMTPConnectEMCallback and SMTPCommandEMCallback, to allow custom handling of incoming SMTP messages. The current mail.box event handles incoming email somewhat, but with the addtl. EMs one could reject/disconnect the email/session instead of just silently accepting/discarding the email, etc.

Thomas Gumz

1:38 AMlink  
Anonymous said...

Another thing would be to re-cache on NoteUpdates to the agentboostnsf itself, so everytime you make a config change you re-read the configuration, instead of doing it periodically....

Thomas Gumz

1:44 AMlink  
Anonymous said...

I received the Red Box when I tried to open AgentBoost.nsf on Local.

"Sorry, uncorrectable error has occurred. LookupHandle: handle out of range"

8:47 AMlink  
Anonymous said...

I checked the error again. I must correct my previous statement.
I have custom icon in my toolbar with "@Command([DesignForms])" to open the databases in design. And when I use that icon I get the error message that I posed before. I know that it is my 'extra' tool but just wanted to let you know. It is a first time I got error using the icon.

Thank you for your work and good luck with your project(s).


9:01 AMlink  
Damien said...


Actually it must hold a cache for each server process since each process has its own memory space. The cache loading is super quick and lightweight however (its only reading a view summary data), so it's really not much of problem.

I considered an approach like you suggest for updating the cache, but only the nserver process would "catch" updates to aboost.nsf, so it would have to signal to the other server processes that the cache is out of date. Instead each process uses the call NSFDbOpenExtended with a time/date stamp, which is a efficient way to conditionally open a database if its been modified since a certain time. By default each process will check no more than once every ten seconds for changes, and will reload the config data if the cache is out of date. This can be configured so that its instantaneous but I think there is *some* cost in the NSFDbOpenExtended call and under load it would call that hundreds of times a seconds, so it only tries at most every ten seconds.

Good idea about the SMTP callbacks. I didn't even see those.

9:46 AMlink  
Damien said...

Voytek, I'm not sure why you see that crash. Could you mail me what version of Notes you are using, where you installed Agent Boost (server or client) and the exact steps to follow to get the crash? Plus an NSD or Rip file would be really helpful.


9:55 AMlink  
Anonymous said...


looks great! Any plans to compile & test it under Linux? We have no Domino on Windows and want to keep it that way...

6:41 AMlink  

Post a Comment

<< Home