Caveats with If "New Mail Has Arrived" agents
 | Shared Simple Action | Shared Formula | Personal Simple Action | Personal Formula |
| If New Mail Has Arrived | |
| |
|
| If Documents Have Been Modified/Updated | | | | |
Except for "SELECT @All," a SELECT statement must be the first statement in the formula to be effective.
If New Mail Has Arrived
Use for processing incoming mail to respond to it, forward it, or file it.
Interactive functions and functions that impede the progress of the mail router are ignored when documents are mailed into the database. For example:
- @DbColumn
- @DbCommand
- @DbLookup
- @MailSend
- @Prompt
- @Command
- @PostedCommand
Most other rules about background agents from R4.1 and R4.5 continue to apply with R4.6. All agents are
signed by the designer of the agent or the person who enabled the agent, whichever is the most recent. The
signature on the agent must be able to authenticate with the server's ID, when the agent is running on the
server. If the agent is running on a workstation, the authentication is done with the current user ID. Agents
of the type "Simple Action" or "LotusScript" run under the signer's name. Agents of the type "formula" will
run under the current server's name.
The database ACL and the workstation ECL continue to limit what an agent can perform. As noted
previously background agents that use formulas run under the server's ID. The Agent Manager section of
the server document continues to control the agent manager task. R4.6 adds the name "Lotus Notes
Template Development/Lotus Notes" to the field titled "run restricted LotusScript/Java agents" as some
template agents now contain the wildcard machinename and are signed by this ID.
Technote Document Details
What Determines if New Mail Agents Run on a Server in Notes Release 4?
Problem:
What determines if New Mail agents run on a server in Notes Release 4?
Solution:
Agents that have the "When should this agent run?" option set to "If New Mail Has Arrived" do not have
the option to choose Schedule, and select a specific server. However, a server name is automatically
populated next to the agent. For example, the agent may say "When should this agent run on
Server1/Acme". The server listed on this line is never used and has no effect on whether the agent will run
or not. Since the server name displayed in the agent is not used, the agent does not display the server name
in this context in Release 4.5. Remember this is specific to New Mail agents.
Knowing that the server name displayed with the agent is never used, how does the server know whether to
run the agent or not? The server determines this by taking the name of the last person to save the agent,
performing a person lookup into the Name and Address Book and retrieving the Mail Server from that
user's person document. If the Mail Server in the person document is different than the current server, the
agent will not run. If the person is not found in the N&A book, the agent will not run. This person lookup is
performed every time the agent loads to run. Remember, if the User ID is hierarchical, the user name in the
person document must also be hierarchical. This is stored in the field "FullName" in the person document.
In essence, this means the New Mail agent will not run unless it is on the User's Mail Server.
Caveats with New Mail Triggered Agents on Notes 4.x Servers
Problem:
What are some of the caveats to be aware of regarding the New Mail Triggered agents in Notes 4.x?
Solution:
In order for "New Mail" triggered agents to run on Notes 4.x servers, the following must be true:
1. The signer of the agent (the last person to save or enable the agent) must have their mail file located on
the same server as where the agent will run. The server determines this by taking the name of the last person
to save the agent, performing a person lookup into the Name & Address Book (NAB) and retrieving the
Mail Server from that user's Person document. If the Mail Server in the Person document is different than
the current server, the agent will not run. If the person is not found in the NAB, the agent will not run. This
person lookup is performed every time the agent loads to run. Remember, if the User ID is hierarchical, the
user name in the Person document must also be hierarchical. This is stored in the field "FullName" in the
Person document.
2. If the agent is a Formula agent (as opposed to a Simple Action or Script agent) there is an additional
requirement that the agent be saved as a R4 type agent, rather than a R3/R4 Compatible agent (which is the
default). An agent will save as a R4 agent when a feature which is exclusive to R4 is used within the agent.
Workarounds for the Mail Server Lookup Caveat in #1 Above:
In Notes 4.1x:
Rather than using the New Mail trigger, use the trigger "If documents have been created or
modified". A flag would need to be used as a check so that modified documents were not acted on a
second time.
Additional Option for Notes 4.5x, 4.6x:
You can add a parameter to the NOTES.INI which disables this mail lookup check. The
NOTES.INI parameter must be set on the server where the agent is to be run. The parameter is:
AMgr_DisableMailLookup=1
Note: In 4.5x releases prior to 4.5.3 and in release 4.6, if the above INI parameter is set to 0
it still acts as if it is set to 1. So, in those Notes releases if you want to re-enable the mail
lookup, the INI parameter must be removed entirely. Refer to the following document for
more information:
"Mail-in Agent Triggers Although Signer Doesn't Have Mail File on
Server and Amgr_DisableMailLookup=0" (#158768 )
Supporting Information:
Note: The fact that the default R3/R4 agent format does not trigger for New Mail agents is currently under
investigation by Lotus Quality Engineering.
Related Documents:
What Determines if New Mail Agents Run on a Server in Notes Release 4?
Document #: 143102
Title: Caveats with Notes R4 New Mail Triggered Agents
Product Release: Notes 4.x
Topic: Workstation/Desktop \\ Application Development \\
Macro/Agent/LotusScript
Document #: 138594 Last Update: 04 16 9819980416
Problem:
What are some of the caveats users should be aware of regarding the Notes R4
New Mail Triggered agents?
Solution:
I. New Mail triggered (" If New Mail Has Arrived ") agents created by the
Notes R4 client that are shared agents (as opposed to private agents) and
use Notes formulas (as opposed to using simple actions or LotusScript) will
not be executed in the background by the Agent Manager. Lotus Quality
Engineering is aware of this issue. There are two ways to work around this:
1. Write the agent in LotusScript; or
2. Use more than one "Simple Action" that contains the formulas.
II. New Mail triggered agents for mail-in databases are subject to the
limitation mentioned above. In addition, New Mail Triggered agents will run
only if the Mail-In Database resides on the same server as the Mail Server
listed in the Person Document belonging the user who last saved the agent.
As of Release 4.5, this person document lookup can be suppressed using the
server Notes.ini parameter AMgr_DisableMailLookup=1. For more detail on
this, see the document "What Determines if New Mail Agents Run on a Server
in Notes Release 4?" (#143102).
Note: The Amgr_DisableMailLookup does not work as expected when set to zero.
For more details on this, see the document "Mail-in Agent Triggers Although
Signer Doesn't Have Mail File on Server and Amgr_DisableMailLookup=0"
(#158768).
1. Verify the mail-in database is on the same server of the mail file for
the particular user who creates and saves the agent; or
2. If running 4.5 on the server, add the line AMgr_DisableMailLookup=1 to
the Notes.ini on the server.
Note: The Amgr_DisableMailLookup=0 ini setting will still disable the lookup
although the documentation indicates it should not. This has been fixed in
Notes 4.5.3. The issue exists in Notes 4.6 as well. The workaround is to
totally remove the line if you want the lookups to execute.
3. Save the agent with the Server ID. If the agent is last saved with the
Server ID, the agent will trigger and run on that same server.
4. For Notes releases prior to R4.5, use a Document Update ("If Documents
Have Been Created or Modified") triggered agent instead of a New Mail
triggered agent. Unlike a New Mail triggered agent, a Document Update
triggered agent allows you to specify the server to run the agent on via the
Schedule button (this button is grayed out for a New Mail triggered agent).
This is the best solution for servers running a release prior to 4.5. You
can have Document Update Agents function exactly like New Mail Agents by
adding an extra parameter to check for a DeliveredDate field. You can also
set a flag field to prevent the Agent from processing it again if the
document is modified afterwards.
5. Use a Document Update ("If Documents Have Been Created or Modified")
triggered agent instead of a New Mail triggered agent. Unlike a New Mail
triggered agent, a Document Update triggered agent allows you to specify the
server to run the agent on via the Schedule button (this button is grayed
out for a New Mail triggered agent). This is the best solution of the thrssee.
You can have Document Update Agents function exactly like New Mail Agents by
adding an extra parameter to check for a DeliveredDate field. You can also
set a flag field to prevent the Agent from processing it again if the
document is modified afterwards.
For Example, a New Mail Agent with the following Simple Action will run only
once on documents that are mailed in and will not run on them again if
someone modifies the document afterwards:
Modify field 'Subject': Set to 'Testing Agents'
If this Agent is changed to a Document Update Agent, to ensure it only runs
on documents that have been mailed in, and to ensure it only runs on them
once, you would write the agent with the following formula:
Select @IsAvailable( DeliveredDate ) & Flag != "Processed";
@SetField( "Subject" ; "Testing Agents" );
@SetField( "Flag" ; "Processed")
Note: All existing R3 Mail-In databases' New Mail agents will continue to
run under Notes R4. The problem described above affects only New Mail agents
created by Notes R4 clients.
6. If the error "Unable to determine the execution access privileges for the
agent (Agent Name). Agent may not run" has occurred, the $MachineName field
on the agent refers to a server other than the server containing the
database with the New Mail agent. If the $MachineName is not the current
server then the error will occur each time the agent executes. Saving the
agent at the server console with the server's ID will not change the
$MachineName field value.
One solution for such an agent would be to change the agent trigger to
something that doesn't use a $MachineName field, (for example, "Manually
from Actions menu"). Saving the agent with this trigger will remove the
$MachineName field. At this point the agent can be resaved at the server
console with the server's ID and its trigger changed back to "If New Mail
has Arrived".
Supporting Information:
This information is outlined under the "Server Caveats" section of Part 4
"Troubleshooting and Known Problems" on pg. 53 of the Notes 4.0 Release
Notes.
Related Documents:
What Determines if New Mail Agents Run on a Server in Notes Release 4?
Document #: 143102
Mail-in Agent Triggers Although Signer Doesn't Have Mail File on Server and
Amgr_DisableMailLookup=0
Document #: 158768