1. What will you learn
You will learn how to call a Notes agent from xPages and hand over the
document for processing.
2. Task Description
Use your scrapbook database. Create one form with 3 fields: color, shape
(editable, text), statement (text, computed when composed, formula ->
empty string), create a view to show those documents. Put both onto a single
xpage and make an agent process the document when saved in xPages.
3. Detailed Steps
1. Create a notes form “AgentDemo” with 3
fields: color, shape (editable, text), statement (computed when composed,
formula -> empty string)
2. Create a view “AgentDemos” with 3 columns
to show color, shape, statement. Use this view selection formula: SELECT
(Form = “AgentDemo”)
3. Create a new xPage “AgentSample” and add
entry fields for color and shape, below add a button to save the form and
below that add a view to see the existing document. (Don't forget the data
binding!) It should look about this (feel free to make it pretty):
4. In the button select a simple action to save
all data sources and to load the same page again:
Test your page. It will create new entries with an empty statement column
(not that this example makes any business sense, that's why it is in your
5. Locate the data events of the xPage (near
the root) and expand the events linked to the document:
6. Add the following code:
ag = database.getAgent("agFromXpage");
noteid = agSampleDoc.getDocument().getNoteID();
7. Create a new LotusScript agent (the good
old fashioned way), call it “agFromXpage”
8. Add the following code (again not too useful):
Dim db As NotesDatabase
Dim doc As NotesDocument
Dim s As New NotesSession
Dim ag As NotesAgent
Dim noteid As String
Set db = s.CurrentDatabase
Set ag = s.CurrentAgent
noteid = ag.ParameterDocID
Dim statement As String
Set doc = db.GetDocumentByID(noteid)
If doc Is Nothing Then
Print "Document not found"
If doc.color(0) ="" Or doc.shape(0) = "" Then
Statement = "Half baken data entry, too bad!"
Statement = "You choose " + doc.color(0)
+ " and "+ doc.shape(0)
Important remark here:
In a “classic” WebQuerySave agent a handle to the current document is
obtained using NotesSession.DocumentContext. That handle returns the NotesDocument
after it has been processed by the server BEFORE it hits the disk. You
can use NotesDocument.SaveOptions = “0” to prevent a save.
In xPages currently you hand over a NodeID (not a universal-ID!) to the
agent and the agent code needs to use NotesSession.currentAgent.ParameterDocID
to get the ID of the document and retrieve it. The document will be in
it's saved state (so if you call an agent other than from the PostSave
event you will have an OLD copy of the data to work on (which can be useful
In a WebQuerySave agent “Print” statements are sent back to the browser.
Currently the xPages implementation doesn't support this, so you might
need to write return information into a field in the document, so xPages
can pick them up from there.
4. The Result
5. Things To Explore
an auxiliary document to transport values to/from an agent.
the difference between run and runOnServer
your agent call a web service