« From Notes.net: Answer to "What is Lotus Notes/Domino?" | Main| How would you load test a mass email agent without getting blacklisted? »

SuperNTF: Cool (and Sneaky) Agent Tricks


Secret Notes AgentSo Mr./Ms. Developer, you've just filled out all the forms and gotten all the approvals for your detailed rollout plan for that shiny new application. Considering that the bureaucratic process took longer than the actual development, it's sure a good thing all those scheduled agents were set to run at the right time.

Sorry, what's that you say? The client has changed their mind and wants the Sales Report Agent to run twice a day instead of just in the morning? Oh, and that *monthly* archive agent timed out after exceeding your server's agent runtime limit, so you'd like to run it weekly instead? "No problem" you say, I don't need to fill out another change request because thanks to SuperNTF I can just edit a couple documents and then get back to building my next nsf masterpiece.

Yes, I know, you're shaking your head because these sorts of "code changes that aren't really code changes" normally require you to beg your admins to "slip it in on last week's change control" or, failing that, go through the whole tedious change control process again. Or maybe you ARE that admin and you're sick of handling such trivial requests because you'd rather focus on planning your upgrade to Notes/Domino 8? "How DOES SuperNTF save me from this" you ask?

In short, SuperNTF lets you give even users with only Author access the ability to edit a document that in turn causes the actual agent's schedule to be updated, and still signed by the server.

There are essentially three parts to this trick:

1 - THE USER INTERFACE. The front end configuration interface is just a form with fields corresponding to key agent attributes such as Interval Type (daily, weekly, more than once a day, etc.), run time and maybe run day (for monthly), and what server to run on. The idea is that user with the [Admin] role (you didn't think I would let ANYONE fool with this stuff did you?) can select an agent, have it's current settings populate the various fields on the form, change whatever they want, and save. That's it for the user.

2 - THE "AGENT SCHEDULER". The Agent Scheduler is itself an agent that is triggered by the user via a "RunOnServer" call that happens when the UI form is saved. Because it is run by the server, it runs with the server's rights, which are typically Manager (but not always so keep that in mind). This agent takes the information entered by the user and then updates the target agent with the new settings.

3 - THE "MAGIC". The truly "hard" part of this trick is actually changing the agent settings, or at least the ones we actually want to change. Yes, there is the NotesAgent Lotusscript class, which allows for enabling/disabling and gives access to a few other settings.  And yes you can access the agent "note" as a NotesDocument and manipulate specific NotesItems that control settings (Andre Guirard had a good writeup on this recently). The problem though is that all the key settings that related to when and how often the agent runs are stored in a very non-human-readable way in a field on the agent called $AssistInfo. This is where the Notes C API comes to the rescue, and we can thank Rob Goudvis for providing code that I adapted for this part.

Disclaimer #1: The above trick currently only works on Windows-based servers because in addition to the C API (which can be converted to multi-platform) there are also a few Windows-specific API bits. If you are either a) a multi-platform API god, or probably even better b) a DXL god, and want to help, assistance is welcome. I am actually very optimistic that the DXL approach will work, as the DXL does express the schedule settings in human-readable form.

Disclaimer #2: This approach doesn't (yet) allow for the target agent to be signed by a specific "Agent Runner" Notes id, only the server id. I actually recommend the special id approach in most cases, but obviously that would not work here. If you know how to pull this off let me know as I haven't looked into it yet.

Disclaimer #3: There are limits to the amount of scheduling flexibility you might want to give to non-Notes Admin application "owners." Care should be exercised when designing the application and it's security policy to minimize the chances that an agent is (re)scheduled in a way that adversely impacts server performance.

As to the question "where can I get it?", the answer is "in the upcoming release of SuperNTF." For those keeping track, yes the release is overdue considering my desire to get it out shortly after the VIEW conference in Boston. One reason is that when inspiration for cool new features strikes, you just have to go with it. That is what happened this past weekend, and it produced the coolness you see here. My rationalization is that when SuperNTF.Next comes out, it will have been worth the wait. I hope you'll agree .


1 - I already wrote this to you in a private email, but it might be interesting for other readers of this blog too:
You wrote "I am actually very optimistic that the DXL approach will work, as the DXL does express the schedule settings in human-readable form"
I've looked into this and although the DXL option seems nice for changing the agent schedule it runs into a huge problem which is described on this IBM website: { Link }
in short, the problem is that after you've imported a Notes agent it has a signer problem and the LotusScript NotesDocument.sign method does not work here. You need to use the C API to fix this.

2 - Well, I've actually succeeded in getting the DXL approach working, and the notesdocument.sign method worked just fine. Look for a sample database and SnTT post soon. Emoticon

3 - Hi Kevin,

Did the CAPIAgentScheduleManager ever make it into a SuperNTF release?

I have Version 0.9.7d (beta)and cannot find anything in the database design regarding "Agent Scheduler".



Post A Comment


Your Host

Kevin Pettitt View Kevin Pettitt's profile on LinkedIn

Tools I Use

Idea Jam

Subscribe to This Blog

 Full Posts  Comments

netvibes Add to Netvibes


Hosted by



This site is in no way affiliated, endorsed, sanctioned, supported, nor blessed by Lotus Software nor IBM Corporation, nor any of my past or future clients (although they are welcome to do so). The opinions, theories, facts, etc. presented here are my own and in no way represent any official pronouncement by me on behalf of any other entity.

© 2005-2019 Kevin Pettitt - all rights reserved as listed below.

Creative Commons License
Unless otherwise labeled by its originating author, the content found on this site is made available under the terms of an Attribution / NonCommercial / ShareAlike