Domino on Linux/Unix, Troubleshooting, Best Practices, Tips and more ...


Daniel Nashed

Passing a document to an agent without saving it first

Daniel Nashed – 6 April 2014 11:43:43
How cool is that new functionality introduced in 8.5.2.  Simple but important addition.
Looks like this has been implemented for XPages but you can also use it in normal Java and LotusScript.
Before you had to save a document before passing the document context to an agent.
Now you can just pass a new in-memory document and you don't need to save it at all.

This is really useful when passing parameters to and from agents that you invoke.
For example if you want output for a Java agent that you need to call -- like in my case right now.

Thanks to Michael Gollmick who pointed me to this documentionation! This really made my day. I wasn't aware of this new functionality!

-- Daniel


Release 8.5.2 introduces a new API for Agents to allow them run with a Document context that can be set by the caller, either an outer Agent or an XPage.

The Agent.runWithDocumentContext() API runs an agent and passes a saved or unsaved in-memory document to the DocumentContext property of the called agent:

New APIs

The new APIs are :

JavaScript (XPages) Agent.runWithDocumentContext(doc:NotesDocument) : void
Agent.runWithDocumentContext(doc:NotesDocument, noteID:string) : void
Java public void Agent.runWithDocumentContext(Document doc)
public void Agent.runWithDocumentContext(Document doc, String noteID)
LotusScript NotesAgent.RunWithDocumentContext(doc As NotesDocument, noteID As String) As Integer

Getting the In-Memory Document

The called agent can access the in-memory document via the existing API for accessing an in-memory document context. For example

public Document AgentContext.getDocumentContext()
Dim doc As NotesDocument
Set doc = NotesSession.DocumentContext

The document can be updated within the agent and when control returns to the XPage the updated values can be read from the document.

Run as Web user

Domino Server-based Agent code must run in an Agent with "Run as Web user" selected on the Security tab under Properties.


1Stefan Schneider  09.04.2014 13:11:03  Passing a document to an agent without saving it first

As far as I know it also runs with normal html pages

2Adam  03.11.2014 13:01:17  Passing a document to an agent without saving it first

on open question is: this new method RunWithDocumentContext runs locally or on the server? put another way: RunWithDocumentContext behaves like: or agent.runoneserver?

3Ashish Kansal  18.02.2015 18:37:36  Passing a document to an agent without saving it first

Is there any way to call agents from xpages which print on browser and pass in-memory document to the agent through xpage. I cannot modify the agents as they are 200 in number and used across 100 DB as suggested in the { Link } blog.

Any help will be of great help



    • [HCL Domino]
    • [Domino on Linux]
    • [Nash!Com]
    • [Daniel Nashed]