Working in the Agent Builder Design Window
Each of the sections of the Agent Builder controls different aspects of the agent. The design window contains a three-pane interface, as shown in Figure 11.6.
Figure 11.6. Agents are created in the Agent Builder. The Out of Office agent used in the mail database operates on new documents.
Naming Agents
Naming an agent is similar to naming a form or view. If an agent appears on the Actions menu, it can be cascaded into submenus, as illustrated in Figure 11.7. If many agents are run manually from the Actions menu, consider collecting them into a submenu by cascading them by using a common title, a slash (), and the actual agent's name , as in MyMailAgentsMy_Agent1. Agents are sorted alphabetically , just as forms and views are. You can include an accelerator key by prepending an underscore to a character. This causes the letter to be underlined in the menu. Users can then type the letter when they are in the Actions menu and have the agent execute.
Figure 11.7. Agent names can be cascaded just as form and view names can.
As you can see in the Agent's Design view in Figure 11.8, the agent names are cascaded by using a slash and correspond to the cascaded agent names shown on the drop-down Agent menu in the Notes client in Figure 11.7. The comment window is fairly small and is not expandable, although it is scrollable. It is a good idea to keep the comment succinct so that as much of the comment as possible will fit into the visible area. The comment can briefly describe the purpose of the agent.
Figure 11.8. Cascaded agent names in the Agent Design view.
Agent options can be found on the Basics tab of the Agent InfoBox. The first check box relates to search agents. Search agents are agents that can be stored and used from the Search bar of a database that is full-text “indexed. Store Highlights in Document and Run in Background Client Thread are both new to Domino 6. The Store Highlights option makes sure that the search keywords are highlighted in the documents returned by the query. To run an agent without having to wait until it completes, check Run in Background Client Thread. Note that you should check this option only if the agent (or the top-level agent that calls this agent) is triggered by an On Event, Action menu selection. To make full use of this feature, the database should reside on a server and the agent must be invoked via the client. Caveat: If this box is checked and the agent refers to any front-end classes, the user will receive a runtime error.
Determining When the Agent Should Run
The Runtime section on the Basics tab of the Agent InfoBox is used to choose which event triggers the agent. The On Schedule and On Event radio button choices indicate whether the agent is run on a schedule or is triggered by an event. Table 11.3 shows the various On Event triggers, and Table 11.4 shows the On Schedule triggers.
Table 11.3. Agent On Event Triggers
| On Event Trigger | When to Use |
|---|---|
| Action menu selection | With user-activated agents, WebQuerySave, and WebQueryOpen agents. |
| Agent list selection | With agents that are called by other agents and for agents that do not belong on the Agent menu in the Notes client. Agent names are also automatically encapsulated by opening and closing parentheses, as in (MyAgent1). |
| Before New Mail Arrives | To process mail before it is deposited into the mail .nsf database, for example to move incoming mail to a particular folder. The agent runs before the message is posted to the database. As a note of caution, do not use the Mark Documents Read simple action because documents that are acted upon by the agent are always marked unread as new when they are posted to a database. Marking them read implies that they are not new. This option is limited to one agent of this type per database. |
| After New Mail Has Arrived | To process incoming mail by responding to it, forwarding it, or filing it. @DbColumn , @DbCommand , @DbLookup , @MailSend , @Prompt , @Command , and @PostedCommand commands are all ignored. This option can be used multiple times within the same database. |
| After Documents Are Created |
To perform a task based on new or changed documents. This trigger or Modifiedevent is essentially a scheduled agent that is handled by the Agent Manager and can execute either on a local Notes client or on a server.When After Documents Are Created or Modified is selected, an Edit Settings button appears. If button is clicked, the Schedule dialog box appears. Here you can set the agent to start and end on a particular date, determine whether the agent can run on weekends, and set the name of a server or local Notes client for the agent to run on. You can also specify that the server name can be chosen when the agent is actually enabled. IBM reports that the delay time using this agent varies between 5 to 30 minutes, depending on server load. |
| When Documents Are Pasted | With documents that need to be modified as they are being pasted into the database. Note that this event requires action by the user and does not function running in the background. Paste-activated agents cannot use @Command or @PostedCommand . |
NOTE
Agents set to run on-schedule are not supported on the Web; however, an agent invoked on the Web can be triggered in other ways, such as through Tools/Macros, with @Functions, or from a URL.
Table 11.4. Agent On Schedule Triggers
| On Schedule Trigger | How to Use |
|---|---|
| More Than Once a Day | Set for high-priority databases, such as mission-critical applications and databases that replicate several times a day, such as routing or workflow applications. IBM warns that if agents are scheduled to run on a very frequent interval (such as every five minutes), the server's performance could be compromised. |
| Daily | Set for activities that are important but that will not cause a delay if they are generated only once a day. |
| Weekly | Used for routine tasks , such as generating reports and sending reminders. |
| Monthly | Set for low-priority maintenance tasks, such as archiving or distributing documents. |
| Never | Used for agents that you do not want to run in any particular circumstance. For example, use this run option for agents that do run on the Web or for agents that are called by other agents. |
Figure 11.9 shows the Agent Schedule properties that allow the agent to be run at various times.
Figure 11.9. The Agent Schedule window enables you to set the agent schedule. This is accessed by selecting the Schedule button on the Agent InfoBox Basics tab.
CAUTION
A caveat of running New Mail agents is that the server on which the agent is run must be the home server for the signer of the agent. There is a workaround for this in R4.5 or higher. A modification to Notes.INI to include the parameter AMgr_DisableMailLookup=1 disables the lookup of the signer's mail file location in the directory.
Figure 11.10 shows the agent trigger settings and properties that allow the agent to be run under various states and circumstances.
Figure 11.10. The All New or Modified Documents Schedule window enables you to set the server on which the agent should run. This is accessed by selecting the Edit Settings button on the Agent InfoBox Basics tab.
The Edit Settings button appears on the Agent InfoBox for only certain trigger events, whereas the Schedule button appears only when an agent is set to run on a schedule.
Scheduling Agents
Figure 11.11 shows the Schedule window for On Schedule More Than Once a Day. Three portions exist in the Schedule window. The top two sections deal with when; the bottom section deals with where. The daily, weekly, and monthly Schedule windows are essentially the same as this box.
Figure 11.11. The On Schedule More Than Once a Day agent dialog box.
TIP
If you schedule an agent to run on a server and that agent will modify documents, be sure to specify which server the agent should run on. If you run the agent on multiple replicas of the database, you will encounter replication conflicts.
An agent scheduled more than once daily allows for an agent to run as often as every five minutes. The minimum repeat time for an agent is five minutes. The hour and minute selections for Run Agent Every option has 12 choices for hours (0 through 11 hours) and 12 choices for minutes (0 through 55 incremented by fives). If you select an hour or minute for Run Agent Every, you can specify a range of time during which the agent will run. This is useful because some agents can take up significant server resources and stagnating them will help balance agent run loads.
TIP
If you choose to have an hourly agent notify users when documents are added to a database, there is no sense in having it run when there are no users present. Select an hour and/or minute to choose a range of time when users are at work ”say, from 8:00 a.m. to 5:00 p.m. Check Don't Agent Run on Weekends if you are lucky enough to work somewhere where people actually don't work on the weekends.
Each of the other scheduled agents has a similar section. The Weekly Schedule box allows you to choose the day of the week and time of day. The monthly schedule lets you choose the day number (1 “31) and the time of day.
The middle portion of the Schedule box, Restrict Dates When Agent Runs, has three options: Start Running Agent on This Date, Stop Running Agent on This Date, and Don't Run Agent on Weekends.
The bottom part of the window, the where part, is also common to all variations of the Schedule box. The Run On drop-down menu lists all available servers as well as local ones. Developers can either choose the server on which the agent runs when the agent is designed or click Run On to select a server in which to run the agent.
To allow an agent to run on a specific server, select a server name from the drop-down choices in the Run On field.
On Schedule, Never is included for backward compatibility with previous releases of Notes that have Never as the schedule option. An agent called by other agents can also use this trigger.
Selecting Documents
After you determine when an agent should run, it is time to determine which documents it should act upon. Document selection is available for all events except those listed in Table 11.5.
Table 11.5. Triggers with Automatic Document Selection
| Trigger | Selected Documents |
|---|---|
| If New Mail Has Arrived | Newly received mail documents |
| Before New Mail Arrives | Each incoming mail document |
| If Documents Have Been Created or Modified | Newly modified documents |
| If Documents Have Been Pasted | Pasted documents |
The documents upon which the agent will act are found by selecting Agent List Selection and Action Menu Selection in the runtime properties. The document selection criteria are as follows :
- All documents in database
- All new and modified documents
- All unread documents in view
- All documents in view
- Selected documents
- None
The On Schedule events have only the first two options available, but all the options are available for the two manual events, which makes them far more flexible.
When you write new agents, it is a good idea to test them against a small subset of documents in the database. One way to test an agent ”even one that will be scheduled to run in the background ”is to choose Selected Documents and Manually from Actions Menu. Select a few documents and run the agent. When the agent is running properly, switch to the appropriate schedule.
Creating an agent to run against selected documents is useful for allowing users to change fields in multiple documents.