Examples of agents to run before Web users open or save documents

To perform error checking, field validation, and other processing before Web users open or save documents, create a shared agent that runs manually. Then write a formula that uses @Command([RunAgent]) or @Command([ToolsRunMacro]) to run the agent and attach it to the WebQueryOpen or WebQuerySave form events. This simulates the LotusScript® QueryOpen and QuerySave form events that aren't supported on the Web.

WebQueryOpen events

A WebQueryOpen event runs the agent before Domino® converts a document to HTML and sends it to the browser. Domino ignores any output produced by the agent in this context.

Examples for using this agent include performing large computations that aren't possible with @commands or collecting statistics about who opened documents and when they did so.

Note: WebQueryOpen agents run when the user opens a form or document, but do not run when the user saves a document. This means that computed fields set by a WebQueryOpen agent are not saved when the user submits a document. To make sure computed fields are saved, you can either recalculate them in the WebQuerySave agent or set the form property "Generate HTML for all fields."

WebQuerySave events

A WebQuerySave event runs the agent after field input validation formulas are run and before the document is actually saved to disk or mailed. The agent can modify the document or use the document data to perform other operations. The document is automatically saved after the agent runs. Do NOT have the agent explicitly save the document (for example, by calling NotesDocument.Save) because an explicit save could cause incorrect results.

A WebQuerySave agent can produce output to be sent back to the user. For example in a LotusScript agent, you can use the Print command to return raw HTML. If the agent produces output, then the form should not have a $$Return field because Domino will return only the agent output and ignore the field.

Examples for using this agent include:

  • Performing complex field validation. If the document does not pass validation, you can prevent Domino from saving the document by changing the value of the SaveOptions field to "0" on the form.
  • Simulating CGI programs that run on user-supplied data by programming a WebQuerySave event and changing the value of the SaveOptions field to "0" on the form. When the agent runs, you can collect field values from the filled-out form without generating a new Notes® document.
  • Collecting statistics based on data submitted by browsers, such as CGI variables, by writing a program that uses CGI variables and attaching it to a WebQuerySave event.
Note: The SaveOptions field must be an existing field on the form, which the WebQuerySave agent changes the value of. If the agent creates the SaveOptions field, the form will be saved regardless of the value in that field.