| Date tip published: | 11/08/2004 |
| Description: | A WebQuerySave agent is a server based background agent that runs when a user submits (saves) a document from a web browser. WebQuerySave agents can be used to pass an HTML message back to the browser after the user submits a new document or saves an existing document. Another use of Domino WebQuerySave agents is to process the user entered data from the submitted form. An example would be a user registration form. Once the user submits the form an agent can be used to create a person document in the Domino Directory and add the username to the appropriate groups. Then the agent could email the new user instructions on how to access the Domino server. This tip provides detailed instructions for creating a WebQuerySave agent. |
To learn more about Using LotusScript in Domino 6 web applications use the following links:
Developing Domino 6 Web Applications
Using LotusScript in Domino 6 Web Applications
Notes Domino 6 LotusScript Package
 Creating a WebQuerySave Agent
When Domino successfully processes a new Notes document that a browser user submitted, Domino returns a default message to the browser user. The following image shows the default "Form processed" message:
You can provide a custom return message using either of the following techniques:
- Add a field named $$Return and program it to display a customized message.
- Program a WebQuerySave agent that uses LotusScript Print statements to send HTML output to the browser.
A $$Return field can be very useful for simple messages and it uses the formula language. However, it is limited in the processing it can do. A more flexible approach is to use a WebQuerySave agent.
 Accessing the Current Document
In the Notes client, you would use the LotusScript front-end classes to access the current document, as illustrated in the image below:
The above example uses the NotesUIWorkspace and NotesUIDocument front-end classes. This code will not run in a WebQuerySave agent because the Domino HTTP task does not support front-end LotusScript classes and methods. You need another way to access the document that a user submits from a browser.
The DocumentContext property of the NotesSession class provides the solution. The code fragment below shows the proper way to access the current document when a browser user submits it.
Once you access the current document, you can use the GetItemValue or extended class syntax of the NotesDocument class to access field values.
Steps Required to Create the WebQuerySave Agent
Creating a WebQuerySave agent is a two-step process:
- Create the agent.
- Call the agent from a form's WebQuerySave event.
The rest of this tip provides detailed instructions for performing each of these steps.
 Step 1 - Create the Agent
Follow these steps to create an agent to use for documents submitted from a browser client:
- Open the desired database in Designer and create a new agent either by choosing Create | Agent from the Designer menu or by displaying the list of agents and clicking the [New Agent] action button.
- Assign a name to the new agent in the Properties dialog.
- Enable the "Shared Agent" option in the Properties dialog. This action allows the agent to run on the Domino server.
- Set the "Runtime" option to "Agent list selection". This setting causes Notes to omit the agent's name from the Actions menu, effectively hiding the agent from Notes users.
- Set the "Target" option to "None" (@Commands may be used with this option).
- In the Programmer's pane, set the "Run" option to "LotusScript."
- Enter your code in the agent's Initialize event. The example below takes the data from two fields (first and last) on the form (using the DocumentContext property) and displays them together with a message. The Print statement is used to send information back to the browser. Note that HTML tags are used to format the message in the browser. Domino will add the needed HTML <HEAD> and <BODY> tags.
- Save the agent.
 Use Vertical Bars Instead of Quotation Marks to Delimit HTML Strings
Because some HTML tags require the use of quotation marks, it is a good idea to use Vertical bar characters ( | ) as the delimiters for LotusScript Print strings. This was used in the final Print statement in the example above to create the link on the web page. |
Step 2 - Call the Agent from a Form's WebQuerySave Event
To use the agent, follow these steps:
- Open the desired form in Designer and click on the WebQuerySave event, as illustrated in the image below. This image shows where to find this event. Note that the WebQuerySave event is a Formula Language event with a default formula. The empty icon next to the WebQuerySave event in the Objects list indicates that the event is not yet coded to call an agent.
- Replace the "<Your agent goes here>" string with the name of your agent. Remember to enclose the agent name in parentheses. This next image demonstrates how to call the "(ProcessForm)" agent.
- Save the form.
| Remember the Parentheses around the Agent Name
When you create an agent that runs manually from the agent's list, Designer automatically surrounds the agent name with parentheses. The parentheses cause Notes and Domino to omit the agent's name from the Actions menu displayed to users in the Notes environment. Be sure to include the parentheses when you specify the agent name in a WebQuerySave formula. |
Resulting Output
When the user submits the following information in the browser ...
... the WebQuerySave Agent runs and displays the following output:
|