Category list

Troubleshooting Agents

This section provides techniques that can be used to troubleshoot agents. As you know, agents can be written to utilize "Simple Actions," Formula Language, LotusScript, and a variety of other languages. Given this variety, numerous tools and approaches can be used to debug problems. The tools used to debug the agent will, in part, depend on the design and implementation of the agent. The following outlines approaches that will be covered:

1.	Review the agent log
2.	Use the Debugger for LotusScript agents
3.	Incorporate message prompts
4.	Monitor the Domino Server Log (requires special access)
5.	Monitor the Domino Server Console (requires special access)

A.21.2

As with most application development, you'll find there's no substitute for experience, and as you gain experience, you'll find one technique to be preferred over others. You'll also find there is no easy method to troubleshoot agents that utilize "Simple Actions" or Formula Language.

A.21.3

Working with the Agent Log

The Domino Designer client includes a feature to test the agent. When utilized, the client performs a trial run of the agent and displays the Agent Log. The Agent Log is usually a good place to start when looking to test or troubleshoot an agent. The Agent Log contains information pertaining to the agent execution and can often help to diagnose common agent problems.

The Agent Log is produced by testing the agent. This is accomplished by selecting the agent in the Domino Designer client and choosing the Agent > Test menu options. The software subsequently returns the expected results along with potential errors in a dialog. Figure 21.7 illustrates a sample Agent Log.

Figure 21.7. Sample of the Test Run Agent Log

In this example, statement 2 indicates that this is a scheduled agent that has been signed by "Mark Elliott". Statement 4 shows the agent name "Archive" and a timestamp when the trial run started. This is followed by the total number of documents as well as the number of documents affected by the agent. The log ends with a completion time for the agent test.

Note

The Agent Log can only be displayed for specific types of agents. For instance, agents that are developed to parse or utilize the user interface cannot utilize the "Agent Test" function. In this scenario, the Designer client will display an error message as illustrated in Figure 21.8. If you encounter this message, consider running the LotusScript Debugger and tracing the agent as it is executed in the database from the Lotus Notes client.

Figure 21.8. Some agents can only be run from the Lotus Notes client

Working with the Debugger

For agents that utilize LotusScript, the debugger can be used to trace the code and review object values as the agent executes. As described earlier in the chapter, the debugger can step through the agent execution, halt execution, and display detailed information pertaining to all LotusScript objects. Unfortunately, this feature only applies to LotusScript. There is no comparable function that can be used to trace agents that are written in "Simple Actions" or Formula Language.

Working with Message Prompts

Message prompts can be used to display data values or status points in the execution of the agent from the user interface. This approach can be used for manually triggered agents. Using Formula Language commands (such as @Prompt ) or LotusScript commands (like Print , Messagebox , and Prompt ), you can periodically display information in the Lotus Notes client. The resulting information can sometimes identify problems with the agent.

Other avenues include the LotusScript NotesLog class, which can be incorporated into agents that utilize LotusScript. This class offers methods to log actions, events, and errors and determine agent properties including the number of errors, program name, total actions, and parent object name. Refer to the Domino Designer help for additional information pertaining to this class.

Working with the Domino Server Log

The Domino server log contains a running history of events and informational text messages associated with the server's operation. This database resides on the server and is updated as events occur. It also tracks messages issued by the LotusScript print statement for all agents run by the server. It's important to understand that this a restricted database. Based on the default ACL settings, you probably will not have access to this database. Consult your Domino server administrator to request "Read" access to the database.

After you have appropriate access, select the File > Database > Open menu options to open the server. Specify the Domino server name in the Server field and locate the database. The database will most likely be named " Server Log" (where "Server" represents the actual name of the Domino server). The log database contains a wide variety of information associated with the Domino server's operation. For debugging purposes, select the Miscellaneous Events view. The most current document containing server log information will be located at the bottom of the view (see Figure 21.9). Open this document and review the statements for potential clues to help diagnose the problem.

Figure 21.9. Domino Server Log

Working with the Domino Server Console

The Domino Server Console displays information pertaining to the operation of the server. This can include informational messages during agent execution, similar to those appended to the server's log file. Additionally, you can issue a variety of the commands to retrieve status information for a given agent. However, to run these commands, you must have access to the server's console window or the authority to establish a remote console connection using the Domino Administrator client. For many, these options will not be feasible . A summary of server commands has been included for those who manage both database development and server administration.

Tell amgr schedule Displays the current list of scheduled agents. The console information includes the agent work queue, trigger type, target run time, agent name, and affected database name.
Tell amgr status Displays the current status of the various agent work queues and run-time control parameters. This command is helpful to determine the control parameters as well as to obtain a general snapshot of the agent status.
Load amgr -? Displays help information for the agent manager command.
Show agents DatabaseName Displays all agents for the specified Notes database (where DatabaseName represents a valid Lotus Notes database).
Tell amgr cancel DatabaseName AgentName Terminates a scheduled agent that is currently running (where DatabaseName represents a valid Lotus Notes database and AgentName represents a valid agent). The command only applies to scheduled agents. Be sure to specify a valid database name and agent name when issuing this command.
Tell amgr run DatabaseName AgentName This command starts a specified agent for a given database (where DatabaseName represents a valid Lotus Notes database and AgentName represents a valid agent). Be sure to specify a valid database name and agent name when issuing this command.