Daniel Nashed's Blog

Passing a document to an agent without saving it first

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


Introduction

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 Agent.run 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

Java	public Document AgentContext.getDocumentContext()
LotusScript	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

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

• Comments [3]