Web agents

Agents cannot run in a browser. They can be activated from a browser but run on the Domino server containing the agent.

Setting up a Web agent

Using the Agent Properties box, do the following:

  • Check the Shared option when you create the agent.
  • Set the agent trigger to On event and either Agent list selection or Action menu selection.
  • Set the agent target to either:
    • None for agents that work on the current document such as those launched from WebQueryOpen or WebQueryClose, or a form action or hotspot that works on fields in the current document.
    • All documents in database for agents that work on existing documents such as those launched from the OpenAgent URL or a view action. The actual documents processed depend on the agent code, for example, the SELECT statement in a formula or the UnprocessedDocuments property in LotusScript.
  • Check Run as web user on the Security tab to run the agent using the browser login name. Otherwise the agent runs with the rights of the agent signer.

Activating a Web agent

You can activate agents from a browser in two ways:

  • OpenAgent URL command . Entering the name of an agent wherever URLs are allowed launches the agent.
  • RunAgent @command or ToolsRunMacro @command. You can use these @commands, which are equivalent, in an action, a hotspot action, a hotspot button, the WebQueryOpen event, or the WebQuerySave event.

The name of a hidden agent (for example, if the trigger is Agent list selection) must include the parentheses when RunAgent or ToolsRunMacro launches the agent. The parentheses are optional when the OpenAgent URL command launches the agent. The OpenAgent URL requires conversion of special characters for Web use; for example, a space must be specified as + (plus sign) or %20.

Two form events work for Web processing:

  • WebQueryOpen occurs before Lotus Domino converts the document being opened to HTML and sends it to the browser. You can change initial field values and do other pre-processing.
  • WebQuerySave occurs before a Web document is saved. You can change final field values and do other post-processing.

To prevent the document from being saved, the document must contain a text field named SaveOptions with 0 as its value.

Note: The SaveOptions field must be an existing field, the value of which the Web agent changes to 0. If the Web agent creates this field, the document will be saved regardless of the value.

LotusScript and Java in Web agents

A Web agent can be written in LotusScript or Java, as well as formula or simple actions.

An agent is the only context in which a Web application can use LotusScript. Anything that runs in the browser, such as an action, hotspot action, hotspot button, or event, cannot contain LotusScript. LotusScript agents activated from the Web cannot use any of the classes NotesTimer, NotesUIDatabase, NotesUIDocument, NotesUIView, or NotesUIWorkspace.

You can write HTML to the browser by putting it in print statements. Domino accumulates print statements and creates a page with their contents after the agent runs.

To display a new page after an agent runs, put one print statement at the end of the code containing the page's URL in brackets. You can start the URL with a slash and the name of the database to designate an element in the current database.

In Java, you must get a PrintWriter object with AgentBase.getAgentOutput and use this object to write to the browser.

The available context depends on how the agent is started:

  • If the RunAgent or ToolsRunMacro @command starts the agent, DocumentContext or getDocumentContext gets an object representing the current document.
  • If the OpenAgent URL command starts an agent, there is no current document, but DocumentContext and getDocumentContext return a special NotesDocument or Document object containing the values of the CGI variables supported by Lotus Domino. In the case of RunAgent or ToolsRunMacro, CGI values are available but not automatically. The form backing up the current document must contain a field named after each desired CGI variable.

The OpenAgent URL command passes arguments at the end of the URL string delineated by ampersands. For example:

http://host/database/view/OpenView&Start=1&Count=20

In LotusScript and Java agents, you can get the arguments by parsing the Query_String item in the document returned by DocumentContext or getDocumentContext. Query_String contains the entire URL command that started the agent.