Table of Contents
As a Domino Administrator, you may consider agents are for developers to write and handle. However; there are a number of things every Domino Administrator should know relating to agents. This article provides the list of these agent-related topics including how can an agent trigger, how to determine which agnets are schedule to run on the server, full text searches and agents, performance impact on agents,
and how to write an agent.
Agents can be triggered in a number of ways and can also run under a number of server tasks including agent manager, server and http. When an agent is created, the developer can choose how that agent can run. An agent can be triggered on an event such as being called from a menu, a mail message being delivered or a document being created. It is important to understand which task an agent will be running under in order to be able to recognize the impact of an agent. If you see a sudden increase in CPU usage on your server, you may want to be able to easily identify or eliminate an agent as the potential cause. The list of triggers is as follows:
- On Schedule: This type of agent will run on the server and on schedule that was defined by the developer. The agent may run multiple times per day, weekly or monthly.
- Action menu selection: For this type of agent to run, a user must selects the agent from the Actions menu in the Lotus Notes client. When an agent runs in this manner, the code will run either on the client or in the server task depending on how the agent was coded. Domino administrator does not get a log or see a list of agents triggered in this way.
- Agent list selection: This type of agent trigger is reserved for agents that will be called by another agent or only ran from the designer client. These agents will run in the designer client or within the server task that called the agent.
- Before new mail arrives: This type of agent is triggered by the router task immediately prior to the message being written to the Inbox of a mail or application database. This type of agent will run under the router task.
- After new mail has arrived: This type of agent is triggered by a new mail message being written to the Inbox of a mail or application database. Once the message is delivered, the agent is scheduled to run in 2 minutes. This type of agent is controlled by the agent manager task; this ensures that if multiple mail messages are written into the database within a short period of time, the server will be able to process those new mail messages during one execution rather than running multiple times within seconds.
- After documents are created or modified: When a new document is created or a document is updated, this type of agent will run. The agent will be set to run as a scheduled agent under the agent manager task once a document has been created or modified, but not more than every 30 minutes.
Determining Which Agents Are Scheduled to Run on the Server
The Domino Administrator client provides an easy way to determine which agents are scheduled to run on the server. In figure 1 you can see that there are 5 agents scheduled to run. For illustration purposes, the agents are named with their trigger type. As you can see, only the agents that will be run by the agent manager task are listed. The next scheduled run time can be easily seen under the Next
column. If you place your cursor over the schedule, the server will then display information on the schedule for that agent. "A Scheduled Agent on a Server" is set to run every 60 minutes. If you were to hover over "An After documents are created" or "An After New Mail Arrives" agent, you will see a listing of "Agent will not run" to indicate to you that the agent will be scheduled based on another trigger.
Agent Manager Settings That Affect Agent Execution
There are several settings that determine how many agents can run on your server at any time and how long they may run. You find these settings in the server document, Server Tasks... Agent Manager
tab as shown below in figure 2. For example, by default, only 1 agent may run at a time during the day and 2 agents may run concurrently during the night. Depending on the number of agents that need to be processed in you environment, you can raise this number.
Why would you need to increase the number of agents to run concurrently? In the section above, you saw how to determine which agents are scheduled to run. If you saw many of those agents scheduled to run in the past, and they are not agents triggered by a document update or mail message, then the agent manager task is not keeping up and you may want to consider increasing the Max concurrent agents parameter for daytime, nighttime or both. Another parameter to consider is the Max LotusScript/Java execution time. If you have agents that take over 10 minutes to process, you must change this parameter or the agent will be stopped by the agent manager task before it is finished. This setting is a safety precaution against infinite loops and to ensure one agent does not prevent all other agents from running.
Full Text Searches and Agents
An agent may often times need to search for information and then take action. Full text searches are resource-intensive operations when a full text index is not maintained. For more information, refer to 3.8 Managing Domino Indexing
. To determine if any agent is performing full text searches on an application without a full text index, you can search your server logs for the following message:
Warning: Agent is performing full text operations on database 'application/application1.nsf' which is not full text indexed. This is extremely inefficient.
You can easily do this using the log analysis tool. To access the log analysis tool, go to the Domino Administration client, Server... → Analysis
tab. In the right panel select Tools → Analyze → Log...
as shown in figure 3.
At this point, you should be presented with a Log Analysis window. From here, you can click on the Words
tab to enter a string to search. In this case, the word inefficient
is enough as shown in figure 4. You can then click OK
to begin the search.
Once the search as finished, you can review the Log Analysis Results
. Below in figure 5 is the desired result of the search No matching entries found
Performance Impact of New Agents and Applications
It is a good idea to have a performance baseline before adding a new application or agent to your environment. This helps you to determine the impact of that application or agent in your environment. For more information on this, refer to 4.3 Establishing a Performance Baseline.
The Design task and Server Scheduled Agents
In Domino version 8, DESIGN_AGENT_UPDATE became available to address the issue of the design task updating and disabling server side scheduled agents. The default setting for this value is 0. Here is a summary of this ini setting and the behavior you should see.
DESIGN_AGENT_UPDATE=0: In this case the design task will update the agent if the agent in the template is newer than the agent in the database. After the update is complete the design task will re-enable the agent adding the previous signer to the "run on behalf of" setting in the agent security properties.
DESIGN_AGENT_UPDATE=1: The design task will not keep the agent enabled. The agent will be overwritten if the agent in the template is newer than the agent in the existing database.
DESIGN_AGENT_UPDATE=2: The design task will update the agent any time a design refresh or replace in ran against the database. In this case the design task will not compare the date before the update and the agent will be disabled when it is replaced.
Be aware - there is a bug where the DESIGN_AGENT_UPDATE setting does not work properly if only some of the design elements are inherited from the template. For details refer to SPR PALT842M2U. If this is a concern to you, it is recommended you open a PMR to log a customer report for this issue.
Troubleshooting Problems with the Agent Manager Task
For troubleshooting, see technote 7002851 - Troubleshooting Script for Notes Scheduled Agents (and Agent Manager).
Writing an Agent
After you become more comfortable with Domino administration, you may want to move into automating processes or writing an application. To get started with LotusScript, you can refer to the Domino Designer help which includes a Lotus Script tutorial
or LotusScript Self-Help Training Modules
Additional resources can be found in the Lotus Notes and Domino Application development wiki