Agents

Domino agents are self-contained programs that perform tasks on one or more databases. Here are some examples of the power and flexibility that agents provide:

• 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 using simple actions, formulas, LotusScript, or Java. This enables you to select the best language for a particular task.

• Agents are not tied to a specified design element, so 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 ability to run an agent depends on a user or server's access level.

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

• 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.

Setting Agent Properties

To set the properties for an agent, follow these steps:

1.	In the Designer, open the database that contains the agent.
2.	Click Shared Code, Agents in the Design Pane to view the list of agents.
3.	Double-click an agent to open the Agent properties box shown in Figure 9.14. Figure 9.14. The Agent properties box.
4.	Make the necessary changes.
5.	Save the agent.

Scheduling Agents

Domino has long had the capability to schedule agents. To schedule an agent, follow these steps:

1.	In the Designer, open the database that contains the agent you want to modify.
2.	Click Shared Code, Agents in the Design Pane to view the list of agents.
3.	Double-click an agent to open the Agent properties box.
4.	Enable the On Schedule option in the Trigger section.
5.	Choose Schedule from the list. The options are outlined in Table 9.6. Keep in mind that scheduled agents are not supported on the Web. Table 9.6. On-schedule Trigger Options Option Description More ThanOnce 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 per 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 monthly 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 being called by another agent.
6.	For scheduled agents, set the scheduling parameters by clicking the Schedule button. 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. The options in this list will vary depending on the trigger type. Target options are defined in Table 9.7. Table 9.7. 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.
8.	Save the agent.

Hiding Agents

Sometimes the need arises to hide agents so that users cannot run them directly. To hide an agent, follow these steps:

1.	In the Designer, open the database that contains the agent you want to hide.
2.	Click Shared Code, Agents in the Design Pane to view the list of agents.
3.	Right-click an agent and choose Design Properties to open the Design properties box.
4.	Click the third tab to view the agent Hide options.
5.	(Optional) Enable the Do Not Show This Design Element in Menus of Notes R4 or Later Clients option to remove the agent from recent Notes client menus.
6.	(Optional) Enable the Hide Design Element from Web Browser option to hide the agent from Web clients.
7.	(Optional) Enable the Hide Design Element from Notes 4.6 or Later Clients option to hide the agent from Notes clients.

Agent Activation

Domino 6 now enables developers to specify that agents can be enabled by any user with Editor access or higher in the ACL. To configure user based agent activation, follow these steps:

1.	In the Designer, open the database that contains the agent.
2.	Click Shared Code, Agents in the Design Pane to view the list of agents.
3.	Open the agent.
4.	Right-click and choose Agent Properties to open the Design properties box.
5.	Click the second tab to view the agent security options.
6.	(Optional) Enable the Allow User Activiation check box.

Restricting Agent Operations

Domino 6 now allows developers who have unrestricted agent rights (defined in the Security tab of the Server document in the Public Directory) to specify restrictions for each agent on a case-by-case basis. The following list defines the agent restrictions that are available:

• Do Not Allow Restricted Operations— This is the default value and the most secure choice. It specifies that the agent is not allowed to perform restricted operations.

  Unrestricted agents can perform low-level operations such as the following: File I/O Network I/O Calling external programs Changing the system date and time

  
  

• Allow Restricted Operations— Allows the agent to perform restricted operations.

• Allow Restricted Operations with Full Administration Rights— This is the least secure option because it allows the agent to perform restricted operations with full administration rights. Be very careful with this level of access.

To set agent restrictions, simply follow these steps:

1.	In the Designer, open the database that contains the agent you want to modify.
2.	Click Shared Code, Agents in the Design Pane to view the list of agents.
3.	Double-click to open the Agent properties box.
4.	Click the second tab to view the agent Security options.
5.	In the Set Runtime Security field, choose one of the options explained previously.
6.	Close the Agent properties box.
7.	Save the agent.

Setting the Effective User of an Agent

Domino allows developers to determine the authority under which an agent runs. By default, the agent will run with the authority of the developer who last saved the agent because the developer's digital signature is associated with the agent.

However, for Web-based applications, you can specify that the agent run with the authority of the Web user who invokes it. Additionally, new to Domino 6 is the capability to specify that an agent run on behalf of someone else.

To change the effective user for an agent, follow these steps:

1.	In the Designer, open the database that contains the agent you want to modify.
2.	Click Shared Code, Agents in the Design Pane to view the list of agents.
3.	Double-click to open the Agent properties box.
4.	Click the second tab to view the agent Security options.
5.	(Optional) Enable the Run as Web User option to make the agent run with the authority of the Web user running it.
6.	(Optional) Specify a user in the Run on Behalf Of field to make the agent run with the authority of the named user.
7.	Close the Agent properties box.
8.	Save the agent.