Search This Blog

Thursday, May 29, 2014

NotesAgent.Runwithdocumentcontext() - cool thing

Hi guys

I would like to pull your attention to method Runwithdocumentcontext() of NotesAgent class.

I personally missed this method somehow and found out about it just recently though it was released with IBM Lotus Notes 8.5.2.

It finally allows developers to pass a non-saved NotesDocument to a NotesAgent. Let me explain.

I believe all of you had a task where you needed to pass many constants/parameters/fields to a NotesAgent to let the agent to do some work. Earlier (prior LN 8.5.2) we had only two methods for that:

  • NotesAgent.Run(noteid)
  • NotesAgent.RunOnServer(noteid).

Notice, since these two methods work with NoteId it is required to save document to be able to pass it to NoteasAgent.

I usually created a temporary document, put required parameters there, saved document and then passed its NoteId to one of the methods mentioned above depends of what I need to rich.


However, the problem of this way was that later I had to clean up after myself - I had to remove that temporary document that I didn't need any more. It wasn't so easy task though. The NotesAgent.Run() method works with a current user's privileges and document deletion can be restricted. The same about NotesAgent.RunOnServer(noteid) in a local replica. Besides that if agent fails then temporary documents can stay in database as garbage. So, to be sure for 100% that I cleaned up everything I had to create a scheduled agent for that that is not the best option also - I personally do not like if database contains many scheduled agents, especially if you use some common template for tens of similar applications. Plus all these things about Server Security - sometimes (if you work for big companies with complex internal policies) it is a tricky thing to get permission to create any scheduled agents, you know :-)

But now, with this nice method NotesAgent.Runwithdocumentcontext(documentcontext as notesdocument, optional byval noteid as string) you can pass any number of parameters to a NotesAgent through a temporary document without need to save it and later delete.


  1. Hi, I'm posting this msg because I need an help.

    We have written a java agent and calling it in postopen of db through Agent.runonserver(noteid) method.

    Functionality of agent : It checks some groups on web for user id and if user doesn't exist it gives them access denied msg.
    But somehow it's working on server but not local. Even we tried with just Agent.Run method also but still won't.
    The strange thing here is it's working for my colleague on local with the same access as me. Not sure what is going wrong. Do we need to do any settings from LN side or any idea ? Absolutely nothing wrong with the code since it's working on server.

    1. Hi
      It's hard to say anything definite without looking at agent but you may check these points
      1) IBM\Lotus\Notes\jvm\lib\security\java.policy, try to grant all permissions
      2) Check Notes ECL configuration regarding java (I mean ECL -not ACL)
      3) Check database ACL and agent signer
      4) Try to Clean database and build it again
      5) Try to create a simple Java-agent printing something to console only and check if it works (with Java-console enabled)
      6) May be your agent uses some custom jar-files which should be copied to jvm/lib/ext and specified in JavaUserClasses setting in Notes.ini
      7) "Check Runtime Security Level" of agent - there are three levels of access you can provide for agent.