NotesUI API - Execute agents with UI access

Integration of existing LotusScript code into XPages applications in the Notes Client that has access to the UI, e.g. to display a dialog box.

ShowTable of Contents

HideTable of Contents

1 Sample application
2 Download link

This is the second article to demonstrate the features of the NotesUI API.

Sample application

The sample application in this article shows how you can execute a LotusScript agent from XPages. This is useful if you have existing LotusScript code that you would like to leverage in an XPages application.

Note that using the standard Notes APIs, it's already possible to call a background agent from SSJS code (using Agent.run) which also works on the web, but unfortunately this agent does not have any access to the Notes Client UI. So for example, it's not possible to open dialog boxes, picklists or simply let the user answer a simple yes/no question from the LotusScript agent.

By using the XPages2Eclipse agent execution function, you can do anything you like in the Client UI and in addition, it's possible to pass data back and forth between XPages and classic LotusScript code.

Our sample contains a simple XPage with a multiline textbox. By clicking a button, an agent gets executed that opens the same text in a classic dialog box. When you are done editing the text, the changes get transferred back to the underlying XPage:

Execute LotusScript agent that displays a dialog box and pass data back and forth

Here is the code that is calling the UI agent:

var oldTxt=getComponent("xContent").getValue();

var conn=X2E.createConnection();
var notesTools=com.x2e.NotesUIAPI.getTools(conn);
var ws=notesTools.getNotesUIWorkspace();

//prepare the result document in which we expect the agent result
var retDbPath=notesTools.getTempDbPath();
var retDb=session.getDatabase("", retDbPath);
var retDoc=retDb.createDocument();
retDoc.save(true,false);
var retDocUnid=retDoc.getUniversalID();
retDoc.recycle();

//pass text and filepath/unid of result document to the agent
var agentParamsMap=new java.util.HashMap();
agentParamsMap.put("content", oldTxt);
agentParamsMap.put("retdbpath", retDbPath);
agentParamsMap.put("retdocunid", retDocUnid);

//execute the agent and wait for the result   
ws.runAgent(database.getServer(), database.getFilePath(),
   "lsDialogAgent", agentParamsMap, false, true);

//reload the result document to pull out the new text
retDoc=retDb.getDocumentByUNID(retDocUnid);
if (retDoc.hasItem("content")) {
    var newTxt=retDoc.getItemValueString("content");
    getComponent("xContent").setValue(newTxt);   
}
//cleanup the temporary result document
retDoc.removePermanently(true);

The agent does not have to be located in the same database as the XPages application. So you can for example leave all LotusScript code in one database together with the application data and develop the new XPages based UI in a separate one.

We are using a Java Map to pass three string values to the agent: one with the current textbox content and two other values with the location of a temporary document in which we expect the agent's result.

When the agent execution is done, we reload the result document (retDoc), grab the new content for the textbox and update the XPages UI.

The agent parameters are passed to the agent via the DocumentContext document. The agent displays the Form "dialogBox" as a dialog box by using the method NotesUIWorkspace.Dialogbox and writes the edited text back into the result document.

Option Public
Option Declare

Sub Initialize

    On Error GoTo errHandler
    
    Dim session As New NotesSession
    Dim db As NotesDatabase
    Dim ctxDoc As NotesDocument
    Dim ws As New NotesUIWorkspace
    Dim result As Variant
    Dim retdbpath As String
    Dim retdocunid As String
    Dim retdb As NotesDatabase
    Dim retdoc As NotesDocument
    
    Set db=session.Currentdatabase
    'the DocumentContext document contains parameters passed to the agent
    Set ctxDoc=session.DocumentContext
    
    'the path of the local temporary database and the unid of
    'the document that should receive the new value are passed
    'into this agent via the documentcontext doc:
    retdbpath=ctxDoc.retdbpath(0)
    retdocunid=ctxDoc.retdocunid(0)
    

    'Display the dialog
    result=ws.Dialogbox("dialogBox", true, true, false, false, false, false, "Dialog box",
        ctxDoc, true, false, false)
    If result=True Then
        'write new text into the result document
        Set retdb=session.Getdatabase("", retdbpath)
        Set retdoc=retdb.Getdocumentbyunid(retdocunid)
        retdoc.content=ctxdoc.content(0)
        retdoc.save True, False
    End If
    Exit sub
errHandler:
    MsgBox "lsDialogAgent: "+Error()+" in line "+CStr(Erl())
    Exit sub
End Sub