Agent design elements
Table of contents
Agents are the workhorse of Lotus Notes. They can be run in the foreground or backround, Notes client, Web client, or server.
When working with agents, consider the following.
- For long running agents, consider running on the server on a scheduled basis. If it is an absolute requirement to run on a Notes Client, run them in the background so the user is not locked out.
- For the Web, use agents sparingly, for the following reasons:
- Agents on the Web are run using the HTTP task. Too many agents or long running agents cause a performance hit and may delay response time to Web browsers.
- A separate thread is required for each agent, which uses up server resources.
- An agent context must be created and destroyed each time an agent is run, further using up server resources.
A WebQueryOpen event runs an agent via the @CommandToolsMacro command. The timing is such that the agent is called and run prior to Domino rendering the document to HTML and sending it to the Web browser.
WebQueryOpen agents only run when the user opens a form or document and are not run when the user saves a document. Be aware that any changes the WebQueryOpen agent makes to such fields are not saved when the user submits the document. You can either recalculate them in the WebQuerySave agent or set the form property "Generate HTML for all fields" to ensure you get the results you expect.
Domino ignores any output produced by an agent run by the WebQueryOpen event.
A WebQuerySave event runs an agent via the @CommandToolsMacro command. The timing is such that the agent is called after field input validation formulas are run and before the document is actually saved to disk. The document is automatically saved after the agent runs whether you explicitly save the document or not. We recommend that you do not
explicitly save the document in the agent, because this can cause replication or save conflicts.
If you want the form to not be saved automatically, use the SaveOptions field. Create the field on the form first, and set it to 0 (false). The agent can change the value of the field if you want. Be aware that if you rely on the agent to entirely create the field, it does not work as expected.
A WebQuerySave agent can produce output to be sent back to the user via the LotusScript print statement. This statement can send a string that consists of an entire HTML page if you wish. For large strings with consistent and static HTML, such as a header, navigation or footer, you can store the such HTML in fields in your form, and then reference them while building your output string.
If the form has a $$Return field, it is ignored by Domino and the only output is from the query save agent.