Working with Agents

Agents are the workhorses of a Domino database. They are similar to programs in other application design systems, but agents in Domino have some significant differences. First, agents are event-driven. A number of different events can trigger the execution of an agent, such as the following:

• Agents can be scheduled to run at any time of the day or night.
• Agents can be executed based on the addition or modification of a document.
• Agents can be invoked by a user .
• Agents can be triggered by a mail message being delivered.

Agents are used throughout Domino to do many tasks. In fact, most times, it is not apparent that agents are being used to perform many tasks in the Notes client. Specifically , all the actions that appear in the Actions menu are effectually agents. For example, in the mail database, the mail calendar tools on the Actions menu are agents. To see this for yourself, open your mail database in Designer 6 and click the Agents folder in the View Navigator pane. Actually, more agents are listed in the Agents folder in Domino Designer (as shown in Figure 11.2) than what appears in the Actions menu. This is because you can select which actions appear on the Actions menu and which agents run hidden in the background. Here's a brief synopsis of what agents can do:

• Be run by users in the background as scheduled agents
• Run in the foreground or automatically
• Be associated many different design elements
• Run on a specific server, on several servers, on client workstations, or on the Web
• Call other agents
• Be constructed using simple actions, formulas, LotusScript, imported Java, and Java programs
• Be distributed easily because they can be replicated and are now considered to be a shared code element new to Domino 6
• Be designated as shared or private

Figure 11.2. The Agents folder of the Mail Template displays all agent types.

In addition, the following is true for specific agents:

• A shared agent is created by one user but can be run by other users.
• A private agent can be created and run by the user who creates it.
• A private agent is not visible on the Actions menu in the Notes client.
• Anyone with Designer-level access or higher can see and run a private agent using Domino Designer, which is new to Domino 6.

Working in the Agent View Pane

When you select agents from the Design menu, the list of agents for the database is displayed in a view, as shown in Figure 11.2. The columns displayed in this view describe the properties shown in Table 11.1.

Table 11.1. Agent View Column Properties

Agents have a multitude of possible uses. When you understand how agents function, their uses will become more apparent. Some agents merely automate routine tasks. Others can be highly complex and sophisticated, performing multiple actions that would not otherwise be possible by any other means.

Examples of the simple agents are those that move documents into archive databases, such as the Archive agent in the mail database. Agents can also search a database for documents that meet certain criteria and then move or copy them into a folder. For example, the Page Minder agent in the Notes Personal Web Navigator checks for updates to Web pages that you select and refreshes them on a schedule. This agent can save a lot of time because it can be set to execute during the night, without human intervention. Another example is the Web Ahead agent in the same database that automatically retrieves Web pages to the depth that you specify. The combination of these two agents makes for a very powerful research tool.

In a typical application, such as a workflow application, an agent might send notifications to reviewers when the allotted time for the review has expired . Other agents might add or modify information in newly created or modified documents. For a mail-in database, an agent could be created to modify the Form field of a document mailed in to the database. That way, the new document could be displayed using a form appropriate to the database. For example, a rejected change request mailed to a document library database could be displayed with a special Rejected form. The agent would change the Form field, and the document would then be displayed using the Rejected form.

Discussion databases often have newsletter agents that email participants in a particular discussion group when documents have been modified or added to the database. Agents can be scheduled to run on the server at varying intervals more than once a day, daily, weekly, or hourly.

More complex agents might handle the movement of data from external databases into a Domino database. An agent such as this might use LotusScript and ODBC, and might be scheduled to execute during off-peak times. Or, this agent might execute when a user accesses a Domino Web site and queries a SQL database. Agents can also call other agents to accomplish complex multistep processes.

What's more, agents can be designed to specifically run in the Notes client only, in a Web application only, or on a mobile device. They can also be written in Java to extend the capabilities of the agent to the Web browser, Notes client, and mobile device.

As you can see, agents are very versatile and are extremely valuable , powerful tools for a user as well as a developer.

Comparing Private (Personal) and Shared Agents

Two general categories of agents exist: shared and private. A private agent can be run only by the person who created the agent or by anyone with Designer access to the database (new to Domino 6). When an agent is created and saved, the signature of the active user ID is saved with the agent. This is what is used to determine whether a private agent is one that can be run by any given user. Anyone with Reader access can create a private agent stored in a shared database if that person has been given access when the ACL option Create Private Agents is checked. This means that someone can create an agent using simple actions or the Formula language. For someone with reader access to create an agent with LotusScript, Create Private Agents and Create LotusScript/Java Agents must both be checked, as indicated in Figure 11.3.

Figure 11.3. Whether a user can create an agent in a database depends on the ACL options set for that user.

Domino 6 contains several new rules for agent security; the fields controlling new security functionality are located in the server record of the name and address book. To be able to run a private agent stored on the server, you must be listed in the Run Private Agents field of the Agent Manager section of the Server document, or you must be in a group listed in that field. If you are not listed in this field, you cannot run a private agent in a shared database, no matter what the setting in the ACL is. Table 11.2 provides you with the Create Agent rules for Domino 6.

Table 11.2. The Domino 6 Create Agent Rules

Domino 6 now supports two modes for enabling agents. One mode enables an agent to run and updates the signature when activated (the same as in R5); the second mode only enables an agent to run without changing the signature when activated. The user activation mode of the agent is controlled by the Allow User Activation setting on the second tab of the Agent Builder InfoBox. This setting allows the agent to be enabled (activated) by an Editor-level user when checked.

A shared agent can be used by anyone who has Reader access to the database. To create a shared agent, you must have at least Designer access in the ACL of a database. This enables you to create an agent using simple actions and formulas. To create a LotusScript or Java agent as a Designer, you must also check the Create LotusScript/Java Agents selection in the ACL. By default, it is unchecked.

Two other fields that control the execution of agents on a server are Run Restricted LotusScript/Java Agents and Run Unrestricted LotusScript/Java Agents. Granting access to unrestricted LotusScript and Java agents is potentially dangerous because these agents can manipulate files, operating system commands, and the system time on a server. Most administrators limit access to unrestricted agents.

NOTE

You must be explicitly listed in or be a member of a group that is listed in the Run Restricted LotusScript/Java Agents field in the server document for the Out of Office agent to run in the mail database.

Restricting Agents

An administrator can place several run restrictions on an agent. You should review the restrictions that are set on your server before attempting to schedule an agent. These restrictions can be found in the Agent Manager tab of the Server Tasks tab in the directory of the Server document, as displayed in Figure 11.4.

Figure 11.4. The Agent Manager Security tab section of the Server document provides settings for who can execute agents on the server.

NOTE

One setting that an administrator can set for limiting agents is the length of time that an agent can run. By default, this variable is set to 10 minutes during the day and 15 minutes at night. Certain agents may require a longer period of time to run. Therefore, if a scheduled agent is set to run at night and requires at least an hour to complete, using the 15-minute period by default would force the agent to quit before completing. The rule of thumb here is to always time your agents during testing to ensure that they have enough time complete their runs.

The Agent Owner

In all versions of Domino, the person who last compiled (saved) the agent was, by default, the agent's owner. This presents problems with mail automation agents and the like ”the mail would be stamped as being from the agent owner, the name of the person who last compiled the agent. This is not always the intended case. In fact, most times developers will set the agent's owner name manually, using a script, to various robot or system names such as AutoMailer, Process Manager, or MailRobot.

For agents that run as scheduled or in Web applications, Domino 6 has a new feature on the Security tab of the Agent InfoBox: Run as Web User and Run on Behalf Of. This allows the developer to control who the agent signer is. To use, check Run as Web User on the Security tab on the Agent InfoBox to run the agent using the browser login name. To set a name, use the name picker button to select a name, or enter your own in the field provided. If no name is entered, the agent runs with the current name and rights of the agent signer.

To set a From name manually within an automail generator agent that creates email documents on the fly, use the doc.principal variable using LotusScript in your agent to set the owner's name in your agent, where doc. refers to the declared mail document in your script, as shown in this code fragment:

Dim MailDoc As NotesDocument Set Maildoc = New NotesDocument(Currentdb) ... maildoc.principal=""

To get the current value of agent.onbehalfof in your agent using LotusScript, use the following script agent method:

doc.from = agent.OnBehalfOf

Triggering Agents

Agents can be triggered in several specific ways:

• Scheduled on either a server or a client
• Run manually from a hotspot, form or view action, the Action menu, or the Agent list
• Run from any object event, such as PostOpen , WebQuery Open , WebQuerySave , and so on
• Executed based on an action, such as a new document being created, modified, mailed into the database, and so on

These triggers determine whether the agent is run without user intervention and what kicks off the agent.

Each of these triggers can take action on all documents or a subset of documents. Three basic questions must be answered when writing an agent:

• When should the agent run? This is the trigger.
• Which documents should it run on? This is the set of documents the agent will act on.
• What actions should it take? This is the code that you will write.

Each of these questions can be answered using the Agent Builder window. The section "Working in the Agent Builder Design Window" describes this window in detail. The Agent Builder window is where agents are written or coded. Let's take a look at some possible uses for agents.