Creating an agent

About this task


Before you begin, plan your agent carefully. For example, decide what type of agent you want (simple action, formula, LotusScript®, imported Java, or Java), what it will act upon, where it will run, how it will be invoked, whether it will perform restricted or unrestricted operations, and under whose ID it should run (run on behalf of).


  1. In the Applications Navigator, double-click Agents under Code. Click New Agent. Alternatively you can choose Create - Design - Agent.
  2. In the New Agent dialog box, enter a name for the agent and optionally the name of the application.

    Note that names and aliases should be unique within an application. (Agents that call other agents look for the first instance of a name and will attempt to run that agent. If more than one agent has the same name, you may run into problems.)

  3. Choose one of the following to define the agent's automated components:
  4. Click OK. The Agent property dialog box appears.

  5. Optional: Optionally, enter a comment in the Comment field. The comment appears when you view the list of agents.
  6. Click Shared if this agent will be used by other users. A shared agent is one that other users have access to. Note that ownership of a shared agent can be reassigned to another user who saves or re-signs the agent.

    Click Private if you want the agent to be an agent that only you can run. In Notes®, private agent are not available on the Actions menu. In Domino® Designer, anyone with Designer level access or higher can see and run a private agent.

    Beginning with Domino® Designer 6, you have the option of converting a private agent to a shared agent or a shared agent to a private agent.

  7. If the agent searches for text in documents, you can specify the following settings in the Options section:
    • Check "Store search in search bar menu" to display your search query in the search bar.
    • Check "Store highlights in document" so that your search matches are highlighted in the searched documents.
  8. To run an agent without having to wait until it completes, check "Run in background client thread."

    Note that you should check this option only if the agent (or the top-level agent that calls this agent) is triggered by "On event - Action menu selection."

    To get the full benefit of this feature, the database should reside on a server and the agent must be invoked via the client.

    If you check this box and the agent references front end classes, the user receives a run-time error.

  9. 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.
  10. Click the Security tab of the Agent Properties box to set up security for the agent.
  11. Close the Agent Properties box after you have filled in the necessary fields.
  12. If you want to create a search, select the Object tab and then the "Document Selection" event in the Programmer's pane. Then use the "Add Condition" button to invoke the Add Condition dialog box.

    Note that this way of creating a search replaces the Search button found in earlier versions of Designer.

  13. Save the agent.

    Note that the agent is being saved and signed with your current ID.


Scheduled agents are enabled by default when first created and existing scheduled agents that are edited are saved with their current state of enabled or disabled.

For additional information on using the Enable, Disable, and Sign buttons, see Useful agent procedures.

For additional information on agent security, see Security for agents on servers and the Web.

For troubleshooting information, see Troubleshooting agents.