Creating, Modifying, and Troubleshooting Agents

An agent is a self-contained program that can perform tasks on one or more databases. Some examples of the power and flexibility that agents provide include the following:

• Agents can run in any Domino environment: on a specific server, on several servers, on workstations, or when launched by Web clients accessing a Domino server.

• Agents can be programmed through the use of simple actions, formulas, LotusScript, or Java, enabling you to select the best language for a particular task.

• Agents are not tied to a specified design element, so that you can write modular, reusable code.

• A user can explicitly call agents from the menu, an action, a hot spot, or a URL.

• Agents can be scheduled to run automatically or when a specific event occurs.

• Agents can run other agents.

• Agents are easily distributed and maintained through replication.

• The capability to run an agent depends on several factors, including a user or server's access level in the database, the agent permissions defined in the Security tab of the server document, and whether the agent runs as the current user or the designer who signed it.

• Agents can be run under the authority of the user running it, or the last person or server to sign the agent, or on behalf of another user (new in Domino 6).

  The new security options for running an agent (see previous bulleted list) are likely to show up on the exam.

  
  

• Agents cannot make modifications to data that the user/server who signed the agent, or is running the agent (depending on how the agent has been configured), is not allowed to make.

• Agents can be configured to log their actions and errors to text files, agent logs, mail memos, or Notes databases, making it easy to ensure that they run properly.

Creating Agents

Table 4.3 contains the various options you can specify for the On Event trigger of an agent.

Table 4.3. On Event Trigger Options

Option	Description
Action Menu Selection	Use this setting for user-activated agents or when running agents on the Web using WebQuerySave or WebQueryOpen events.
Agent List Selection	Use this setting for agents that are called by actions, buttons, URLs, or other agents, because agents with this setting do not appear in the Actions menu.
Before New Mail Arrives	Use this setting to process mail documents before they are shown in a mail database.
After New Mail Has Arrived	Use this setting for processing mail after it is shown in the mail database. The following functions (which create user interface “side-effects”) cannot be used in agents of this type: @DbColumn @DbCommand @DbLookup @MailSend @Prompt @Command @PostedCommand
After documents have been created or modified	Use this setting for agents in which documents that are new or modified since the last run of the agent should be processed.
When documents are pasted	Use this setting for agents in which documents that have been pasted into the database should be processed. Keep in mind that @Command or @PostedCommand functions cannot be used in these agents.

The On Schedule trigger option enables you to specify the frequency with which an agent should run, as well as the schedule.

The On Schedule Trigger option offers a number of choices for scheduling the agent, as shown in Table 4.4.

Table 4.4. On Schedule Trigger Options

More Than Once a Day	Use this setting to run the agent on a schedule several times a day. Remember that scheduling frequent runs affects your server's performance. Click the Schedule button to specify the schedule.
Daily	Use this setting to run the agent on a schedule once a day. Click the Schedule button to specify the daily schedule.
Weekly	Use this setting to run the agent on a weekly basis. Click the Schedule button to specify the weekly schedule.
Monthly	Use this setting to run the agent on a monthly schedule. Click the Schedule button to specify the weekly schedule.
Never	Use this setting if you want to save an agent but do not want it to run except under special circumstances, such as when it is called by another agent.

When you choose to have the agent triggered by a specific event, you also must choose a value for the target, which specifies the documents that it will process. Target options for an agent are defined in Table 4.5.

Table 4.5. Target Options When Trigger Is On Event

Option	Description
All documents in database	The agent builds a collection of and runs against all documents in the database.
All new and modified documents	The agent builds a collection of and runs against all documents that have been created or edited since the agent was last run.
All unread documents in view	The agent builds a collection of and runs against all documents considered unread in the current view.
All documents in view	The agent builds a collection of and runs against all documents in the current view.
All Selected documents	The agent builds a collection of and runs against selected documents in the current view.
None	The agent does not attempt to process a collection of documents. @Commands may be used with Run Once agents. Run Once agents can be called from the Web using the WebQueryOpen and WebQuerySave events, as well as by direct reference in a URL if you use the ?OpenAgent command.

If your agent is triggered on a specific schedule, you also must choose target options. Target options for scheduled agents are described in Table 4.6.

Table 4.6. Target Options When Trigger Is On Schedule

Option	Description
All documents in database	The agent builds a collection of and runs against all documents in the database.
All new and modified documents	The agent builds a collection of and runs against all documents that have been created and saved since the agent was last run.

To create an agent, follow these steps:

1.	In the Designer, open the database in which you want to create the agent.
2.	Click Agents in the Design pane.
3.	Choose Create, Design, Agent, or click the New Agent button. Figure 4.3 shows an agent built with Java. Figure 4.3. The Agent designer interface in the Designer IDE. [View full size image]
4.	Enter a name for the agent in the Name field. Optionally enter a comment.
5.	If the agent is to be used by multiple users/servers, select Shared Agent. Otherwise, the agent is saved as a personal agent that can be run only by its creator. An improvement that developers have long clamored for has been added to Domino 6. You can now change an agent from Shared to Personal—or vice versa—after the agent has been saved.
6.	Choose a trigger: On Event or On Schedule in the Runtime section. These options are explained as follows: The On Event trigger list enables you to specify to which event the agent should respond. Choose from the options shown in Table 4.3. The On Schedule trigger list enables you to specify the frequency and schedule by which an agent should run. Choose from the options shown in Table 4.4. Keep in mind that scheduled agents are not supported on the Web. For scheduled agents, set the scheduling parameters. You must also select where the agent should run from the Run On list. Remember that selecting a server or server(s) is especially important when agents modify documents in databases that are replicated among multiple servers.
7.	Choose a value for Target from the options described in Tables 4.5 or 4.6, depending on the trigger type.
8.	If you want to further specify the choice of documents, click Document selection in the Objects tab and add criteria to filter the documents included in the collection against which the agent will run.
9.	Choose the type of agent to create from the Run pull-down list in the Programming pane. These options are Simple Action(s)— Select any of a number of simple actions (pre-built applets that can perform very simple tasks). Remember that simple actions are not customizable and are not supported in Web applications. Formula— Use the Notes Formula language to code an agent. @Commands may be used with Run Once agents. LotusScript— Use LotusScript (based on Microsoft Visual Basic) to program agents. Java— Code agents using Java. Imported Java— Import Java files into agents.
10.	Save the agent.
11.	Test the agent. Choose Agents, Test to conduct a test run of the agent and receive feedback from the system.
12.	Modify as necessary and save.

Modifying Agents

To modify an agent, follow these steps:

1.	In the Design pane, select Agents, which displays all the agents in the database in the View pane.
2.	Select the agent you want to modify and double-click it.
3.	If necessary, change the options that control when and how the agent is run. These options were described previously in the “Creating Agents” section.
4.	Save the agent.
5.	Test the agent. Choose Actions, Test to conduct a test run of the agent and receive feedback from the system.
6.	Modify as necessary and save.

Troubleshooting Agents

Because agents provide such a wide array of capabilities, it is important to consider a number of things when troubleshooting agents. This section focuses on the most effective tools and techniques for debugging agents. These tools include the following:

• Agent log— You can access an Agent's Agent Log to determine key information, such as the last time and date the agent was started, how many documents were processed, the type of code run (LotusScript, for example), and the last time and date it completed. To view the Agent Log, select the agent and choose Agent, Log from the menu.

• LotusScript debugger— You can use the LotusScript debugger to debug agents written in LotusScript. The debugger enables you to track the progress of the agent as well as the value of variables and objects within the scope of the agent. To use the LotusScript debugger, choose File, Tools, Debug LotusScript from the menu and run the agent. Remember that this works only on agents launched from within Notes. Agents launched by a Web browser cannot be debugged by this method.

• LotusScript Remote debugger— You can use the LotusScript Remote debugger to debug server-side agents written in LotusScript. This is new in Domino 6.

• Perform a test run of the agent— After you have completed an agent, you can do a simulated run to see whether it performs as expected before running it on production data (with possibly disastrous results!). As part of the test run, security and schedule settings are also checked. To perform a test run, select the agent to test and choose Agents, Test from the Menu. When the agent is complete, the Agent log appears with the results.

• Server console debugging— The Domino Server console provides three commands: Tell Amgr Schedule, Tell Amgr Status, and Tell Amgr Debug, which display information about scheduling, agent queue status, and the status of agent debugging settings that are in effect.

• NotesLog class— The NotesLog class is a convenient and powerful option that enables you to track the progress and report errors that occur in agents written with LotusScript or Java.

• Printing debug information as agent runs— If you are using LotusScript or Java agents, you can write messages in the Notes Log database.

• Using prompts at run time— If you are using the Formula language, you can use the @Prompt command to report on progress and variable values. In LotusScript you can use the MsgBox function to achieve the same results.