Lotus Domino Designer 8.5 Help - Triggering an agent on an event

APPLICATION DESIGN

Triggering an agent on an event
Once you have created an agent, you must choose whether to trigger the agent on an event or on a schedule. To trigger an agent on an event:

1. On the Basics tab of the Agent Properties box, click "On event."

2. Choose one of these events in the following table:

Event to trigger agent Use for

Action menu selection User-activated agents or for WebQuerySave or WebQueryOpen agents.

Agent list selection Agents that are only to be called by other agents and for agents that are still being developed or are run from Designer.

Before new mail arrives Processing mail before it is deposited in the mail databases; for example, to move incoming mail to a folder.
With this option, the agent runs before the message is listed in the database. Therefore, be careful what other options you choose. For example, do not use the "Mark Documents Read" simple action because documents will always be marked unread when they are listed in the database.
Note that this option is limited to one agent per database.

After new mail has arrived Processing incoming mail: to respond to it, forward it, or file it.
Note This agent will run when new mail is delivered to a database and when the agent cache is refreshed. In addition, this type of agent will run against all new and modified documents since it last ran which contain a DeliveredDate field. If you do not want the agent to run multiple times against the same document, use flags to indicate when a document has been processed.
Interactive functions and functions that read or modify data external to the current document are ignored when documents are mailed into the database. For example: @DbColumn, @DbCommand, @DbLookup, @MailSend, @Prompt, @Command, or @PostedCommand are all ignored.
Note that you can use this option multiple times within the same database.

After documents are created or modified Workflow tasks where a task is performed based on new or changed documents. This trigger is actually a scheduled agent handled by the Agent Manager and can execute either on the local Notes client or on a server.
When you select "After documents are created or modified," an "Edit settings" button appears. If you click the button, the Schedule dialog box appears. Here you can set a start and end date for the agent, tell the agent not to run on weekends, and either choose a server for the agent to run on or choose the local IBMR LotusR NotesR client. You can also specify that the server is chosen when the agent is enabled.
The delay time using this agent varies between 5 to 30 minutes, depending on the server load.

When documents are pasted Documents that are pasted into the database and need to be modified as they are being pasted. Note that this event requires action by the user and does not happen in the background.
Paste-activated agents cannot use @Command or @PostedCommand.

When server starts Agents that are only to be called when the server starts, and are not called at other times. If you want an agent to be called when the server starts, but also at other times while the server is running, use the agent list selection trigger, and create a separate agent triggered when server starts that calls that agent.

3. If you selected "Agent menu selection" or "Agent list selection," choose one of the following targets from the Target list. These are the documents on which the agent will run.

All documents in database
All new and modified documents
All unread documents in view
All documents in view
All selected documents
None - choose None for any agent that is not working with a specific set of documents. For example, choose None if you have an agent that displays a message to the user. None also lets you use @commands.

Note Beginning with IBMR LotusR Domino(TM) Designer 6, "Run Once" is no longer listed as an option on the Targets pull-down list. ("Run Once" was often used to set up Web agents.) Choose "None" instead.

See Also

Creating an agent

Triggering an agent on a schedule

Glossary

Feedback on Help or Product Usability?

Help on Help

All Help Contents

Glossary

Event to trigger agent	Use for
Action menu selection	User-activated agents or for WebQuerySave or WebQueryOpen agents.
Agent list selection	Agents that are only to be called by other agents and for agents that are still being developed or are run from Designer.
Before new mail arrives	Processing mail before it is deposited in the mail databases; for example, to move incoming mail to a folder. With this option, the agent runs before the message is listed in the database. Therefore, be careful what other options you choose. For example, do not use the "Mark Documents Read" simple action because documents will always be marked unread when they are listed in the database. Note that this option is limited to one agent per database.
After new mail has arrived	Processing incoming mail: to respond to it, forward it, or file it. Note This agent will run when new mail is delivered to a database and when the agent cache is refreshed. In addition, this type of agent will run against all new and modified documents since it last ran which contain a DeliveredDate field. If you do not want the agent to run multiple times against the same document, use flags to indicate when a document has been processed. Interactive functions and functions that read or modify data external to the current document are ignored when documents are mailed into the database. For example: @DbColumn, @DbCommand, @DbLookup, @MailSend, @Prompt, @Command, or @PostedCommand are all ignored. Note that you can use this option multiple times within the same database.
After documents are created or modified	Workflow tasks where a task is performed based on new or changed documents. This trigger is actually a scheduled agent handled by the Agent Manager and can execute either on the local Notes client or on a server. When you select "After documents are created or modified," an "Edit settings" button appears. If you click the button, the Schedule dialog box appears. Here you can set a start and end date for the agent, tell the agent not to run on weekends, and either choose a server for the agent to run on or choose the local IBMR LotusR NotesR client. You can also specify that the server is chosen when the agent is enabled. The delay time using this agent varies between 5 to 30 minutes, depending on the server load.
When documents are pasted	Documents that are pasted into the database and need to be modified as they are being pasted. Note that this event requires action by the user and does not happen in the background. Paste-activated agents cannot use @Command or @PostedCommand.
When server starts	Agents that are only to be called when the server starts, and are not called at other times. If you want an agent to be called when the server starts, but also at other times while the server is running, use the agent list selection trigger, and create a separate agent triggered when server starts that calls that agent.