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 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:
Figure 11.2. The Agents folder of the Mail Template displays all agent types.
In addition, the following is true for specific agents:
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
|Schedule Status||Icon representation of whether a scheduled agent is enabled or disabled. A check mark indicates enabled, X indicates disabled, and no icon indicates that the agent is not a scheduled agent.|
|Name /Comment||The name of the agent and any comment.|
|Alias||The alias of the view name, if one is defined.|
|Trigger||The value from When Should This Agent Run in the agent's properties box.|
|Private||If the agent is a private view, a check mark appears in the column.|
|Last Modified||Date the agent was last modified and by whom.|
|Last Modified By||Person who last saved the agent.|
|No Refresh||If checked, the agent will not be refreshed when a design refresh or design replace is invoked.|
|Notes||If checked, the agent runs in Notes.|
|Web||If checked, the agent runs on the Web.|
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
|To Create||Access Needed|
|(Note: Web users cannot create agents.)|
|Private agents||Reader access or higher. Create Private Agents must be enabled in the ACL.|
|Private agents using||Reader access or higher.|
|LotusScript and Java||Create Private Agents and Create LotusScript/Java Agents must be enabled in the ACL.|
|Shared agents using simple actions and formulas||Designer access or higher.|
|Shared agents using LotusScript or Java agents||Designer access or higher. Create LotusScript/Java Agents must be enabled in the ACL.|
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.
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.
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.
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
Agents can be triggered in several specific ways:
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:
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.
Part I. Introduction to Release 6
Whats New in Release 6?
The Release 6 Object Store
The Integrated Development Environment
Part II. Foundations of Application Design
Advanced Form Design
Using Shared Resources in Domino Applications
Using the Page Designer
Adding Framesets to Domino Applications
Automating Your Application with Agents
Part III. Programming Domino Applications
Using the Formula Language
Real-World Examples Using the Formula Language
Writing LotusScript for Domino Applications
Real-World LotusScript Examples
Writing Java for Domino Applications
Real-World Java Examples
Enhancing Domino Applications for the Web
Part IV. Advanced Design Topics
Accessing Data with XML
Accessing Data with DECS and DCRs
Security and Domino Applications
Creating Workflow Applications
Analyzing Domino Applications
Part V. Appendices
Appendix A. HTML Reference
Appendix B. Domino URL Reference