Sample: An Agent that Searches Your Database for Documents with a Particular Subject

Objective
The objective of this sample is to create an agent that searches the documents in a Domino database.

Time Required
Allow half an hour to create and run this agent.

Before You Begin
To build and run this sample you need to have Notes 4.6 or higher installed.

To prepare for the sample, follow the steps in the Domino Samples Overview.

Set up your Lotus Notes and VisualAge for Java environments to support the Domino AgentRunner by following the steps in Setting up for the AgentRunner and return to this sample.

Description
This sample agent runs against a database retrieving all documents which have the same subject as the document you invoke the agent against. The agent will send you a mail message containing a list of links to all documents related to a common subject. For example, if you select a document with the subject Hello World and then invoke the agent, a list of all the documents that contain the string 'Hello World' in the subject field will be returned in a mail message, with a link to each document.

Export the .class File
To export the .class file from the com.ibm.ivj.examples.simpleagent package in VisualAge for Java to the file system so it can be read by Notes:

  1. Open the IBM Domino Examples project in the Workbench and expand the com.ibm.ivj.examples.domino.simpleagent package. 
  2. Click the SimpleAgent class with mouse button 2.
  3. Select Export.  The Export SmartGuide will open.
  4. Select the Directory radio button as your export destination.  Click Next.
  5. In the Directory text field, enter a location in the file system where you want to export the .class file.
  6. Select the .class checkbox and click Details
  7. Select the IBM Domino Examples and the SimpleAgent::com.ibm.ivj.examples.domino.simpleagent checkboxes.  Click OK.
  8. Deselect the .java and resource checkboxes if they are selected.
  9. Click Finish.

When you export files to the file system, the directory path of the file is maintained.   For example, if you entered X:\VAJexport as your export destination, the SimpleAgent.class file will be in X:\VAJexport\com\ibm\ivj\examples\domino\simpleagent.

Create the Agent in Notes
For the AgentRunner to work in the IDE you have to provide it with a context for running your agent.  In this samples you run the agent in your Notes mail database but you could create the agent in any database.  To create an AgentContext document:

  1. Open your mail database.
  2. Select Agent from the Create menu.
  3. Enter a name for the agent, such as CheckMail
  4. Select  Manually from Actions Menu from the drop-down list When should this agent run.
  5. Select All documents in database from the Which documents should it act on pull-down menu.
  6. Select the java radio button for what should this agent run.
  7. Click the import class files button.
  8. Locate the SimpleAgent class file, click the Add button.
  9. Click OK.
  10. Press the Esc key to close the Create Agent window. You will be asked if you want to save your changes.
  11. Click Yes.

Running the Agent in Notes
Open the Java Console in Notes by selecting File - Tools - Show Java Debug Console so you can monitor your agent.  Select a document that has as its subject the text string you want your agent to search for.  From the Actions menu of the Domino database, select SimpleAgent.  The agent will run but the session will return Null. An AgentContext document will be created in the AgentRunner.nsf

Using the AgentRunner
Now you are ready to run the agent in the AgentRunner.

To run your agent from the Workbench:

  1. Open the Console window by selecting Window - Console.  This window will show the status of your agent.
  2. Select the SimpleAgent class with mouse button 2.
  3. Select Tools - Domino AgentRunner - Run.

The Domino AgentRunner will run your agent using the AgentContext document that you created in Notes. 

Update your AgentContext (optional)

If you want to change which documents you want the agent to run against:

  1. Select the SimpleAgent class with mouse button 2.
  2. Select Tools - Domino AgentRunner - Properties.  The Properties window will open.
  3. Click the Update Agent Context button.
  4. Select which documents you want the agent to run against like you would in Notes.
  5. Add a description so you can identify your context.
  6. Click Update Agent Context Document.
  7. Close the window.
  8. Select your new agent context.
  9. Click the Run Agent button from the AgentRunner window.

The Domino AgentRunner will run your agent with your updated agent context.

Create the Production Agent
When your agent runs without errors, you can create the production agent by taking it out of 'Debug' mode.

Open your SimpleAgent class file in the Workbench.  In the Source window, change what the class extends from lotus.notes.DebugAgentBase to lotus.notes.AgentBase. Click your SimpleAgent class in the All Projects window.  You will be asked if you want to save your changes.  Click Yes.

Export the .class File
Your agent is now in it's completed state and can be run in Notes.  Export the .class file to the file system using the Export SmartGuide.  Open your agent in Notes and reimport the SimpleAgent.class file.

Run the Agent in Notes
To run the agent, select a mail document with a common subject. Select your agent from the Actions menu. The agent will run and send you a mail message that contains all the documents in the database that contain the subject of the document you ran the agent against. Open the mail message and select the links to the related documents.