Open Mic
Domino Agents
Presenters :
Sudhakar Kunam
1
OPEN MIC LOTUS TEAM
Sudhakar Kunam– Tech Support Engineer
●
Presenter
●
Ranjit Rai - Lotus Technical Advisor
●
Focussing on Notes/Domino, LotusLive
●
Hansraj Mali - Lotus Technical Advisor
●
Focussing on Notes/Domino, LotusLive
●
Soumitra Limaye – Lotus Support
●
Facilitator for Open Mics
●
2
Agenda
 Introduction
 Uses for Agents
 How Agents are triggered
 Kinds of Agents
 Creating Agents
 Testing Agents
 Managing Agents
 Agent Security
 Troubleshooting Agents
 Q&A
3
Introduction
●
●
●
●
Agents are predefined formulas that act on a predetermined set of
documents.
Agents are similar to macros, automate many commonly performed
database tasks.
Agents work in a database to manage documents, send messages,
and change field values.
Agents are stored in the database for which they are created.
4
Uses for Agents
●
Agents help you work more efficiently and distribute information
quickly and easily. You can use agents to:
●
Manage documents in folders
●
Archive documents
●
Send messages, documents, newsletter summaries
●
Run other agents
●
Change information in documents.
5
How Agents are triggered
●
Agents are designed to be triggered by either a predetermined time
or an event. (Scheduled or Event based)
Scheduled :
●
Agent can be set to run More than once a day, daily, weekly, or
monthly
6
How Agents are triggered
7
How Agents are triggered
●
●
Agents are designed to be triggered by either a predetermined time
or an event. (Scheduled or Event based)
Event:
➔
Action menu selection
➔
Agent list selection
➔
Before new mail arrives
➔
After new mail has arrived
➔
After documents are created or modified
➔
When documents are pasted
➔
When server starts
8
How Agents are triggered
9
●
Kinds of Agents
Notes provides two kinds of Agents
➔
Personal Agents – Created by a user for personal use
➔
Share Agents – Created by designers and are used by many people.
10
Creating Agents
●
Open the application and then click Create > Agent
1. Name the Agent, comments and select the type of
Agent
11
Creating Agents
2. Select Shared or Private
12
Creating Agents
3. In the Runtime section of the properties box, choose one of the
following triggers for the agent. Different options appear depending on
the trigger you choose.
Select On event, and then select the event which triggers the
agent.
➔
➔
●
Select On schedule, and then schedule the time the agent triggers.
Note: Depending on the trigger you choose, you may need to select
which documents the agent runs on in the Target field.
13
Creating Agents
On Event :
14
Creating Agents
On Event :
15
On Schedule :
Creating Agents
16
Creating Agents
On Schedule :
17
Creating Agents
On Schedule :
18
Creating Agents
4. Click on Action and 'Add action' button to add the action to the agent.
Select the desired function from the drop down menu.
19
Testing Agents
●
●
●
For agents that do not call other agents, use Menu command.
For agents that use LotusScript, use the LotusScript debugger.
For more complicated agents, create a test copy of the database you
can work with before you work with the original database.
20
Testing Agents
➔
To use the Test menu command
♦
Select the agent and choose Design – Test or Right click on
agent and click on 'Test'
Read the Agent Log and check:
How many documents would be processed .
What action would be taken if the agent were actually run
If necessary, make corrections and run the test again.
21
Testing Agents
➔
➔
To use the LotusScript debugger
Choose Tools - Debug LotusScript.
♦
Run the agent and the LotusScript debugger
appears. You can then review each step as the
agent runs.
♦
Use message boxes and print statements
22
Managing Agents
●
You can edit ,delete ,move and copy agents within an application
and from one application to another.
To edit an agent :
➢
➢
Open the agents list and double-click the agent you want to
edit.
Make edits in the Agent properties box or the Programmer's
pane.
➢
Press Esc.
➢
Click Yes to save the changes you have made to the agent.
23
Managing Agents
To copy an agent:
➢
Open the agents list and select the agent.
➢
From the menu, click Edit > Copy.
➢
➢
If you are copying the agent to another application, open
that application and click View > Agents.
Click Edit > Paste.
To delete an agent:
Open the agents list and select the agent.
➢
Click Edit > Cut.
➢
24
Agent Security
●
You can set up basic security for an agent by using the
Security tab of the Agent Properties box.
25
Agent Security
Run as Web user: - Checking this option specifies the current Web user to
be the agent's effective user.
●
The effective user is the user under whose authority the agent runs.
Run on behalf of : - Lets you specify the agent's effective user.
●
●
●
●
Allow restricted operations : - Lets users who have unrestricted rights
specify whether the agent should run in restricted, unrestricted, or
unrestricted with full administrator rights mode. The default setting is
restricted mode, the safest setting.
Allow user activation : - Checking this box allows users with editor access
to enable this agent without affecting its signature.
Default access for viewing and running this agent : - The default level for
viewing and running the agent is "All readers and above." You can
deselect this option and choose who you want to have default access for
viewing and running the agent.
26
Agent Security
●
Who can create agents?
To control who can create agents that run on servers, use database
ACLs.
Web users cannot create agents.
Private agents
Reader access or higher and must
have "Create private agents" enabled
in the ACL
Private agents using LotusScript and
Java
Reader access or higher and must
have "Create private agents" and
"Create
LotusScript/Java
agents"
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 and must
have
"Create
LotusScript/Java
agents" enabled in the ACL
27
Agent Security
When are restrictions checked?
Domino checks the security restrictions differently depending on
whether the agent is running:
●
●
Locally or on the server
●
In the foreground or background
Locally on Notes :
●
An agent runs locally when:
- It runs within a Notes client database.
- You choose "Local" from the "Run on" list for a scheduled agent.
- A user starts the agent from the Actions menu in the Notes client
●
When an agent runs locally, Notes does not check security
restrictions, unless you have set the Enforce ACL option.
28
Agent Security
When are restrictions checked?
●
On the Server :
●
●
An agent runs on the server when it is running in a
database stored on a server and it is started by one
of the following:
●
Before new mail arrives
●
After new mail arrives
●
If documents have been created or updated
●
On schedule more than once a day
●
On schedule daily
●
On schedule weekly
●
On schedule monthly
If the agent is running on a server, Domino checks all
security restrictions.
29
Agent Security
When are restrictions checked?
●
Foreground or background:
●
➔
●
➔
An agent runs in the foreground when a user starts it
from the Notes Actions menu, selects it from the Designer
Agents list, or clicks an Action button.
When agents run in the foreground, security restrictions
are not checked.
An agent runs in the background when it is scheduled or it
is triggered by an event (for example, when documents
are modified)
When agents run in the background, Domino checks
security restrictions.
30
Agent Security
●
Controlling agents that run on a server
1.From the Domino Administrator, click Configuration, and open the
Server document.
2.Click the Security tab.
3.In the Programmability Restrictions section, complete one or more of
these fields, and then save the document.
31
Agent Security
Sign or run unrestricted methods and
operations
Enter the names of users and groups who are
allowed to run.
Sign agents to run on behalf of someone else
Enter the names of users and groups who are
allowed to sign agents that will be executed on
anyone else's behalf. The default is blank,
which means that no one can sign agents in
this manner.
Run restricted LotusScript/Java agents
Enter the names of users and groups allowed
to run LotusScript and Java agents.
Leave the field blank to deny access to all
users and groups
Run simple and formula agents
Enter the names of users and groups allowed
to run to run simple and formula agents.
Leave the field blank to allow all users and
groups to run simple and formula agents.
32
Troubleshooting Agents
●
You can experience problems running agents at several points during
agent development, deployment, and implementation.
Try the following to help diagnose any problems.
➔
❖
❖
❖
❖
Review the Agent Log (for all types of agents).
Every time an agent runs, it writes a log report with the following
information:
❖
When it ran
❖
The number of documents it processed
❖
The actions it took on the documents
Each time an agent runs, it writes over the previous log report.
If you are running agents built with LotusScript or Java and the
agents run in the background, you can add the NotesLog class to
your agent code to record run-time information in the Agent Log.
33
Troubleshooting Scheduled Agents
Agent does not run during certain times
➔
If a scheduled agent runs, but you notice that there are times
when the agent is not running, check the following settings:
Server's light sleep time
●
Check the Agent Manager section of the Server document to
verify the times when Agent Manager is enabled to run. If the
Start times and End times for Daytime and Nighttime
parameters do not account for a portion of the day, the Amgr
task will not run during that period. For example, assume the
following parameters: Daytime parameters are 08:00 AM and
05:00 PM, and the Nighttime parameters are 08:00 PM and
08:00 AM. In this case, no agents will be executed by Agent
Manager between 5:00 PM and 8:00 PM.
34
Troubleshooting Scheduled Agents
Agent does not run during certain times
35
Troubleshooting Scheduled Agents
Agent runs, but not to completion
●
Does the agent run to completion if run manually?
Certain pieces of code are not intended to run as a
background process, for example:
@Commands, and
LotusScript UI (user interface) methods.
➔
Check for any errors that may have been generated:
Check agent log and Server log
➔
Is it a LotusScript agent?
There is a Max LotusScript Execution Time parameter in the
Agent Manager section of the Server document that defines
how much time a LotusScript agent has to complete
execution. If the maximum allocated time is exceeded, the
agent will not finish, and report so in the agent log. If this is
the case, verify the LotusScript code to make sure it
functions correctly, and is not in an infinite loop, for
example. If the code is correct, consider increasing the
execution time limit, but be aware that it may have an
impact on system performance, as the Agent Manager
executive process will run for a longer time for this script.
36
Troubleshooting Scheduled Agents
Agent is not running
Are any scheduled agents running on the server?
●
➔
➔
➔
Check if other scheduled agents are running on the server. If
no scheduled agents are executing when they should be,
verify the following.
Perform a 'Show Task' at the server console. This will give
information on currently-running Notes tasks. Verify that
AMgr is running.
Perform 'Tell Amgr Status' at the server console.
provide information such as :
This will
Length of Time Agent Manager has been running,number of
Agents in Eligible Queue,number of Agents in Schedule
Queue,number of New Mail Triggered Agents, etc.
➔
Perform a 'Tell Amgr Schedule' at the server console. This
command shows the Agent Manager schedule of all the agents
scheduled to run for the current day. This is useful for
debugging purposes, because you can see if your agent is
waiting in one of the Agent Manager queues.
37
Troubleshooting Scheduled Agents
Agent is not running
●
If other agents are running on the server, check the following:
Check the errors in both the server log and agent log.
Depending on the errors found, revise the agent, ACL, or
permissions in the Domino Directory.
Try editing the settings and re-saving them.
Pull a new replica of the database, if one exists, from
another server.
What type of agent is this? (for example, New mail,
New/Modified docs, Hourly/Daily/Weekly, etc.)
Did the proper event take place to trigger the agent (for
example, has new mail arrived)?
If some scheduled agents are running, but none in this
database, is the "Disable background agents for this
database" option selected in the Database Properties? Select
File, Database, Properties to look at this setting.
38
Troubleshooting Scheduled Agents
Debugging
●
There are 2 notes.ini parameters that can give a high level of detail to the
Amgr task running.
1) debug_amgr=<value> 2) log_agentmanager=<value>
●
Below are the different flags you can set the values to.
Syntax: Debug_AMgr=value
c - to output agent control parameters
e - to output information about Agent Manager events
l - to output agent loading reports
m - to output agent memory warnings
p - to output agent performance statistics
r - to output agent execution reports
s - to output information about Agent Manager scheduling
v - verbose mode, to output agent loading, scheduling, and queues
* - to output all of the above flags
Syntax: Log_AgentManager=value
●
Description: Specifies whether or not the start of agent execution is recorded
in the log file and shown on the server console:
0 - Do not log agent execution events
1 - Log agent execution events (partially and completely successful)
2 - Log agent execution events 39
(completely successful only)
Troubleshooting Scheduled Agents
Output of Debug parameter on server console.
26-09-2011 07:57:15 AM AMgr: Start executing agent 'test' in 'debug.nsf'
26-09-2011 07:57:15 AM AMgr: 'Domain851 Admin/ORG851' is the agent signer of ag
ent 'test' in 'debug.nsf'
26-09-2011 07:57:15 AM AMgr: 'Agent 'test' in 'debug.nsf' will run on behalf of
'Domain851 Admin/ORG851'
26-09-2011 07:57:15 AM Agent Manager: Error validating execution rights for age
nt 'test' in database 'debug.nsf'. Agent signer 'Domain851 Admin/ORG851', effect
ive user 'Domain851 Admin/ORG851'. Examine 'Programmability Restrictions' field
in the Server Record.
26-09-2011 07:48:37 AM AMgr: Agent 'test' in 'debug.nsf' does not have proper
execution access, cannot be run
40
References
●
●
Title:
Troubleshooting Script for Notes Scheduled Agents (and Agent
Manager)
Doc #: 7002851
URL:
http://www.ibm.com/support/docview.wss?uid=swg27002851
Agents and the Domino Administrator wiki article
http://www10.lotus.com/ldd/dominowiki.nsf/dx/1.5_Agents_and_the_Domino_Administrator
●
Notes Help Database
●
Useful agents for IBM Lotus Notes and Domino administrators
http://www10.lotus.com/ldd/dominowiki.nsf/dx/10022009124512AMWEB7LC.htm
41
Q&A
42