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

Passing a document to an agent without saving it first

Daniel Nashed  6 April 2014 13: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


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.



  • [IBM Lotus Domino]
  • [Domino on Linux]
  • [Nash!Com]
  • [Daniel Nashed]