Logging and Exception Handling

Overview

The following sections describe message logging and exception handling for Adapter for Lotus Notes. A list of error codes and supporting information appears in Adapter for Lotus Notes Error Codes.

Adapter for Lotus Notes Logging Levels

Adapter for Lotus Notes uses the Integration Server logging mechanism to log messages. You can configure and view the Integration Server logs to monitor and troubleshoot the Adapter for Lotus Notes. For detailed information about logging in Integration Server, including instructions for configuring and viewing the different kinds of logs supported by the server, see the IBM webMethods Integration Server Administrator’s Guide for your release.

Configuring Adapter Logging Levels

About this task

Beginning with Integration Server 7.1, you can configure different logging levels for the Adapter for Lotus Notes.

Accessing the Adapter's Logging Information

About this task

To access the adapter's logging information

Procedure
  1. From the Integration Server Administrator screen, select Settings > Logging.

    The Logging Settings screen appears. The Loggers section has Adapters included in the Facility section.

  2. Expand the Adapters tree to see a list of all installed adapters with their code number and adapter description, along with the logging level.

Changing Logging Settings for the Adapter

About this task

To change logging settings for the adapter

Procedure
  1. Click Edit Logging Settings. Select the required Level of Logging for the Adapter for Lotus Notes.
  2. After making your changes, click Save Changes.
  3. For complete information about specifying the amount and type of information to include in the log, see the IBM webMethods Audit Logging Guide for your release.

Adapter for Lotus Notes Message Logging

Integration Server maintains several types of logs; however, Adapter for Lotus Notes only logs messages to the audit, error and server logs. Because Adapter for Lotus Notes works in conjunction with the WmART package, the adapter's messages and exceptions typically appear within log messages for the WmART package.

The logging levels are different depending on which version of Integration Server you are running the adapter on, as shown in the following table.

Integration Server Log Description
Integration Server 6.5 Audit Log You can monitor individual adapter services using the audit log as you would audit any service in Integration Server. The audit properties for an adapter service are available in each Adapter for Lotus Notes service template on the Audit tab.
Error Log Adapter for Lotus Notes automatically posts critical-level and error-level log messages to the server's error log. These log messages will appear as adapter run-time messages.
Server Log Adapter for Lotus Notes posts messages to the Server log, depending on how the server log is configured. Critical-level through debug-level log messages appear as adapter run-time log messages. V1-Verbose1 or V4-Verbose4 log messages appear as Adapter for Lotus Notes log messages.
Integration Server 7.1 and higher Audit Log You can monitor individual adapter services using the audit log as you would audit any service in Integration Server. The audit properties for an adapter service are available in each Adapter for Lotus Notes service template on the Audit tab.
Error Log Adapter for Lotus Notes automatically posts fatal-level and error-level log messages to the server's error log. These log messages will appear as adapter run-time messages.
Server Log Adapter for Lotus Notes posts messages to the server log, depending on how the server log is configured. Fatal-level through debug-level log messages appear as adapter run-time log messages. Trace-level log messages appear as Adapter for Lotus Notes log messages.

The Adapter for Lotus Notes's log messages appear in the format ADA.0720.nnnnc, where:

  • ADA is the facility code that indicates that the message is from an adapter.
  • 0720 (or 720) is the Adapter for Lotus Notes major code, which indicates that the error is generated by Adapter for Lotus Notes.
  • nnnn represents the error's minor code. For detailed descriptions of the Adapter for Lotus Notes's minor codes, see Adapter for Lotus Notes Error Codes.
  • c represents the message's severity level (optional).

To monitor the Adapter for Lotus Notes's log messages in the Server log, ensure that your server log's logging settings are configured to monitor the following facilities:

  • 0113 Adapter Runtime (Managed Object)
  • 0114 Adapter Runtime
  • 0115 Adapter Runtime (Listener)
  • 0117 Adapter Runtime (Adapter Service)
  • 0118 Adapter Runtime (Connection)
  • 0121 Adapter Runtime (SCC Transaction Manager)
  • 0126 Adapter Runtime (SCC Connection Manager)

Handling Lotus Notes Exceptions

If a Adapter for Lotus Notes object (for example, a connection or service) encounters an error with the Domino Server, it will throw an adapter error coupled with the Lotus Notes error, exactly as it was thrown by Lotus Notes. The Lotus Notes errors will be in an IData format.

For example, if a getDbdirectory service fails on the Domino Server at run time because its input fields contain invalid key values, you will receive an adapter error that indicates that the getDbdirectory service failed, and the adapter error will contain the specific error generated on the Domino Server indicating why the service failed. In this case, you would receive a Lotus Notes error specifying that the input key field values are invalid.

Adapter for Lotus Notes Error Codes

This section lists the Adapter for Lotus Notes's Critical- and Error-level minor codes, including the text of each error, information about the cause of the errors, and possible responses to the errors.

Code Description
106 Lotus Notes Adapter failed to load XMLDataFile.
Explanation: This message is thrown as a ServiceException wrapping the exception encountered while loading the XML data file.
Action: The exception wrapped will have details on the nature of the failure.
107 Lotus Notes Adapter cannot load class: class-name.
Explanation: This message is encountered mainly during development time. This message indicates that the adapter is unable to load a Java class as specified in the XML data file.
Action: Verify that the classpath and the name of the class are correct.
511 Lotus Notes Adapter will not attempt to execute method: method-name in class class-name using connection node: connection_name because no object reference was provided in the parameter-name parameter to execute such method on.
Explanation: The Lotus Domino Toolkit for Java/CORBA requires an object in order to execute Adapter for Lotus Notes. This error message indicates that an object was not provided.
Action: Check the flow or services to ensure that the object is properly mapped/provided.
513 Lotus Notes Adapter failed to execute method: method-name in class class-name. Reason: reason.
Explanation: This message is provided in the event that an exception other than a NotesException is thrown by a Domino object method invocation.
Action: Depending on the exception reported, make the necessary changes in input or on the Domino Server.
514 Lotus Notes Adapter failed to execute method method-name in class class-name. Reason: reason. Exception ID: id.
Explanation: Adapter for Lotus Notes caught a NotesException. Lotus Notes Adapter extracts the ID of the exception and the text provided with it.
Action: Consult the appropriate IBM documentation, and make the necessary changes to work around the exception. This is an application-level error; however, it may also be a system-level error which requires a fresh session. The adapter may handle these errors automatically. For more information about exception IDs and the Domino Objects for Java Reference Guide in the Lotus Domino Toolkit for Java/CORBA documentation.
516 Lotus Notes Adapter failed to execute method: method-name in class: class-name, because the indicated class can not be loaded.
Explanation: This message is encountered mainly during execution time. This message indicates that the adapter is unable to load a Java class as specified in the XML data file. It may be seen if the classpath was altered after a service has been properly generated.
Action: Verify that the classpath and the name of the class are correct.
517 Lotus Notes Adapter failed to find the class-name class definition in the XML data file. Aborting service_name execution.
Explanation: This exception is issued during run time. It indicates that a class has been removed from the XML data file after an adapter service has been created for it.
Action: Edit the XML data file to define the class and lists its methods. For instructions, see Editing the XML Data File.
518 Lotus Notes Adapter failed to find the method-name method definition in class class-name.
Explanation: A method in a class that is defined in the XML data file does not exist.
Action: Verify that the definition of the method is correct in the XML data file. Also check the spelling of the method, and ensure that the signature is accurate.
519 Lotus Notes Adapter encountered an IllegalAccessException while executing the method-name method in class class-name.
Explanation: This exception indicates that the adapter does not have the proper permissions to execute certain Java code. This is a rare exception because the proper permissions should already be in place to execute Java methods in the Lotus Domino Toolkit for Java/CORBA.
Action: Ensure that the environment for the adapter is set up to allow the adapter to properly load and access the classes defined in the XML data file.
520 Lotus Notes Adapter will not attempt to execute method: method-name in class: class-name because it encountered a NumberFormatException while trying to convert input parameter: parm-name with value: value to type: type.
Explanation: This message occurs when the adapter cannot properly convert a parameter to the desired target. Adapter services that have a signature in primitive mode and one of the parameters is of a format that requires conversion (for example byte, int, long, float, double or short), may encounter this error.
Action: Correct the specified value and rerun the service.
521 Lotus Notes Adapter failed to execute the built-in service service-name. Reason: reason. Exception ID: id
Explanation: Adapter for Lotus Notes caught a NotesException. Adapter for Lotus Notes extracts the ID of the exception and the text provided with it.
Action: Consult the appropriate IBM documentation, and make the necessary changes to work around the exception. This is an application-level error; however, it may also be a system-level error which requires a fresh session. The adapter may handle these errors automatically. For more information about exception IDs and the associated constants that are defined in NotesError for the lotus.domino classes, see the Domino Objects for Java Reference Guide in the Lotus Domino Toolkit for Java/CORBA documentation.
522 Lotus Notes Adapter failed to execute the built-in service service-name. Reason: reason.
Explanation: This message is provided in the event that an exception other than a NotesException is thrown by a Domino object method invocation.
Action: Depending on the exception reported, make the necessary changes in input or on the Domino Server.
523 Lotus Notes Adapter will not execute the wm.ln.authentication:logout service because there was no session object in the pipeline.
Explanation: The wm.ln.authentication:logout service requires that a session object be available in the pipeline under parameter name "session". If it is missing this message is encountered.
Action: Ensure that the session object is available in the pipeline.
600 Lotus Notes Adapter failed to initialize connection: connection_nameto host: Lotus-Domino-server with user: user-name. Reason: reason. Possible reason: reason. Exception ID: id. Exception message: message-text.
Explanation: This error message appears if the adapter encounters an error when trying to establish a connection to a Domino Server for the specified user.
Action: Consult the appropriate IBM documentation, and make the necessary changes based on the exception reported. For more information about exception IDs and the associated constants that are defined in NotesError for the lotus.domino classes, see the Domino Objects for Java Reference Guide in the Lotus Domino Toolkit for Java/CORBA documentation.