Triggering an agent on an event

About this task

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 Notes® 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 Domino® 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.