Adapter Logging and Exception Handling
Overview
The following sections describe message logging and Adapter for Remedy exception handling. A list of error codes and supporting information appears at the end of this chapter.
Adapter Logging Levels
Adapter for Remedy uses IBM webMethods Integration Server logging mechanism to log messages. You can configure and view Integration Server logs to monitor and troubleshoot Adapter for Remedy. 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 Audit Logging Guide for your release.
Configuring Adapter Logging Levels
About this task
Beginning with Integration Server 7.1.1, you can configure different logging levels for Adapter for Remedy. 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.
Accessing the Adapter's Logging Information
About this task
To access the adapter's logging information
Procedure
Changing Logging Settings for the Adapter
About this task
To change logging settings for the adapter
Procedure
- Click Edit Logging Settings. Select the required Level of Logging for Adapter for Remedy.
- After making your changes, click Save Changes.
Adapter Message Logging
Integration Server maintains several types of logs; however, Adapter for Remedy logs messages only to the audit, error, and server logs. Because Adapter for Remedy works in conjunction with the WmART package, the adapter's messages and exceptions typically appear within log messages for the WmART package.
The following table lists the logging levels when you are running Adapter for Remedy on Integration Server 7.1.1 or higher:
| Integration Server | Log | Description |
|---|---|---|
| Integration Server 7.1.1 or 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 Adapter for Remedy service template on the Audit tab. |
| Error Log | Adapter for Remedy automatically posts fatal-level and error-level log messages to the error log. These log messages appear as adapter run-time messages. | |
| Server Log | Adapter for Remedy 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 Remedy log messages. |
The Adapter for Remedy's log messages appear in the format ADA.0760.nnnnc, where:
- ADA is the facility code that indicates the message is from an adapter.
- 0760 (or 760) is the Adapter for Remedy major error code, which indicates that the message is generated by Adapter for Remedy.
- nnnn represents the error's minor code. For detailed descriptions of the Adapter for Remedy's minor codes, see Adapter Error Codes.
- c represents the critical level
of the error. For Adapter for Remedy this
will be either V2-Verbose2 or V4-Verbose4. Beginning with Integration Server 7.1.1, all verbose
logging levels appear as Trace logging level. Important: Adapter for Remedy logs all messages at Trace logging level.
To monitor the Adapter for Remedy'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
- 0117 Adapter Runtime (Adapter Service)
- 0118 Adapter Runtime (Connection)
- 0121 Adapter Runtime (SCC Transaction Manager)
- 0126 Adapter Runtime (SCC Connection Manager)
Adapter Exception Handling
Adapter for Remedy throws the following exception classes that you should be aware of as you build integrations using the adapter:
- AdapterException is thrown when an ARException is thrown in the AR System. For more information, see AdapterException.
- AdapterConnectionException is thrown when a fatal error occurs and the AR System becomes unavailable. For more information, see AdapterConnectionException.
In all cases, the adapter passes the underlying exception to the adapter runtime, which wraps it in a container exception that it then passes to Integration Server. Integration Server then serializes the exception and returns it to the client service. Typically, that client (for example, a flow or Java service that calls an adapter service) will include logic that traps these exceptions and branches accordingly. For information about how to trap the exception in a flow, see the IBM webMethods Service Development Help for your release.
AdapterException
When an ARException occurs in the AR System, the exception is wrapped in an AdapterException. An AdapterException is for a non-fatal errors where the AR System is still available. For example, an AdapterException would be thrown when an error occurs while trying to create an entry in the AR System. The AR System's error message is logged in the server.log file. The logged error message includes the Remedy message and the reference to the field ID and the field name.
When an AdapterException is thrown, the connection is not dropped. Adapter for Remedy only drops connections for fatal errors that result in an AdapterConnectionException. If you determine that there are AR System API call errors for which you want the connection dropped, you can configure Adapter for Remedy to identify additional error codes that should be considered fatal. For more information about AdapterConnectionExceptions, see AdapterConnectionException below. For more information about configuring error codes that should be considered fatal, see Configuring Additional Fatal Error Codes.
AdapterConnectionException
An AdapterConnectionException is thrown when a fatal error occurs and the AR System becomes unavailable, for example due to a network problem or when the AR System Server is shut down.
Adapter for Remedy recognizes a fatal error based on the AR System API call error code. An example of an error that Adapter for Remedy considers fatal is error code 90, which indicates that the AR System catalog could not be opened.
When an AdapterConnectionException is thrown, WmART drops the connection from the connection pool and tries to create a new connection. WmART then wraps the exception in com.wm.pkg.art.error.DetailedSystemException and throws it to the Integration Server.
In addition to the API call error codes that Adapter for Remedy considers fatal, you can configure additional error codes that you want Adapter for Remedy to treat as fatal; that is, additional error codes for which you want Adapter for Remedy to drop the connection and throw an AdapterConnectionException. For more information, see Configuring Additional Fatal Error Codes below.
Configuring Additional Fatal Error Codes
About this task
Adapter for Remedy recognizes a set of AR System API call error codes as fatal. These error codes indicate that the AR System has become unavailable. In response to a fatal error code, Adapter for Remedy throws an AdapterConnectionException, drops the connection from the connection pool, and tries to create a new connection.
You can configure Adapter for Remedy to add to the list of error codes that it considers fatal. As a result, when Adapter for Remedy receives one of the fatal error codes you configure, it behaves in the same manner; that is, throws an AdapterConnectionException, drops the connection from the connection pool, and tries to create a new connection.
To identify additional fatal error codes, use the Integration Server Administrator to configure the watt.adapter.Remedy.fatalErrors server configuration parameter in the Extended Settings. You use this configuration parameter to list the AR System API call error codes that should be considered fatal.
When an AR System API call results in an error and an ARException is thrown, Adapter for Remedy catches the exception. Adapter for Remedy examines the error code and if it matches a code listed on the watt.adapter.Remedy.fatalErrors configuration parameter, an AdapterConnectionException is thrown rather than a AdapterException.
To configure additional fatal error codes
Procedure
Adapter Error Codes
This section lists the Adapter for Remedy's minor codes and provides information on the message, reason, and possible action for each error.
Adapter for Remedy categorizes its minor code numbers as follows:
| Error Number Range | Descriptions |
|---|---|
| 0001-0099 | Adapter-specific informational logging messages. |
| 0100-0999 | Adapter-specific warning messages. For more information, see Warning Messages. |
| 1000-1999 | Adapter-specific error messages. For more information, see Error Messages. |
Warning Messages
| Warning Code | Description |
|---|---|
| 0100 | Login Status for userName - message. |
| Explanation: The AR System user configured in the Adapter for Remedy connection does not exist on the AR System Server. However, the logon succeeded and the connection was enabled with a guest user on the AR System. Note that this happens only when the AR System is configured to allow guest users logon. | |
| Action: Check the user account you have defined in the adapter connection. If you do not want to allow guest user logon, configure the AR System to deny logon to guest users. | |
| 0200 | Adapter for Remedy cannot retrieve the list of available form names. Check the log for details. |
| Explanation: When creating an adapter service, Designer displays appropriate adapter service settings in the Flow Service Editor. Designer accesses logic in Adapter for Remedy to obtain the appropriate settings for the adapter service. Adapter for Remedy was unable to obtain all the form names from the AR System. As a result, the Form Name field in the adapter settings will not list all available forms. | |
| Reason: Adapter for Remedy is unable to obtain all form names might be that the user does not have the privilege to access one or forms, or there might be a problem with one or more forms. | |
| Action: If the Form Name field contains the form you want to use, proceed. Otherwise, use have an AR System administrator check the form and its accessibility, and make corrections as necessary. | |
| 0300 | Remedy field type [Field Type Identifier] could not be mapped to a data type supported by the Adapter for Remedy; data type java.lang.Object will be used. |
| Explanation: Adapter for Remedy is retrieving a value from an AR System field. However, the data type of the AR System field is not supported by Adapter for Remedy. Adapter for Remedy will use the data type java.lang.Object for the field. For more information about data type mappings, see AR System Data Type to Adapter Data Type Mapping. | |
| Action: To avoid the error, you can update the Input Fields tab of the adapter service to unselect the Use Field check box. |
Error Messages
| Error Code | Description |
|---|---|
| 1001 | Problem connecting to AR system - user: userName. |
| Explanation: Adapter for Remedy failed to establish a connection to an AR System Server. Adapter for Remedy attempted to establish the connection using the specified user. Previous messages display information about the AR System Server to which Adapter for Remedy is attempting to make a connection. An AdapterConnectionException is thrown. | |
| Action: Ensure that the AR System Server is running. If the AR System Server is running, ensure that you have your environment set up correctly. For information about the required AR System jar and dll files, see Installing the Adapter. | |
| 1002 | Problem clearing AR system's userInfo object. |
| Explanation: AR System uses a userInfo object to maintain the session state of each of its clients. After Adapter for Remedy destroys a connection, it attempts to clear the userInfo object using the userInfo.clear() API. If the userInfo.clear() API results in an ARException being thrown, the exception is wrapped into an AdapterException, and Adapter for Remedy issues this message. | |
| Action: From the Integration Server Administrator, reload the WmRemedyAdapter package. Then from the Adapter for Remedy administrative screens, re-enable the adapter connection. For instructions, see Enabling Adapter Connections. | |
| 1003 | Invalid value specified for input parameter parameterName. The input cannot be empty or null. |
| Explanation: When running a Adapter for Remedy service, one of the input values specified for paramerName was invalid. | |
| Action: Check the service parameterName and provide a valid value. Rerun the service. | |
| 1005 | Empty or null values specified for input. |
| Explanation: The values provided for one or more of the parameters of a Adapter for Remedy service were invalid. | |
| Action: Check the service signature and provide valid values. Rerun the service. | |
| 1010 | Adapter Service Operation Name service execution failed on Form: formName. Error: Message. |
| Explanation: Internal error occurred while executing the specified operation/adapter service. | |
| Action: Check the error message for a possible correction. If there is none, contact IBM support. | |
| 1018 | ResourceDomainLookup failed. |
| Explanation: Adapter for Remedy encountered a problem while attempting to generate adapter service templates. | |
| Action: From the Integration Server Administrator, reload the WmRemedyAdapter package. Then in Designer, refresh the Integration Server host. If the problem persists, restart Integration Server. | |
| 1021 | Missing required input(s) for ARS Server Operation: Operation Name. |
| Explanation: There are missing input parameters for the specified Operation Name in the ARS Server Operation adapter service. | |
| Action: Fill in the required input parameters for the service and then rerun the service. | |
| 1022 | ARS Server Operation Operation Name execution failed. |
| Explanation: An exception occurred when running the specified Operation Name in the ARS Server Operation adapter service. | |
| Action: Ensure that a connection to the ARS server is available. Ensure that all dependent jars and dll are located in the Integration Server_directory\packages\WmRemedyAdapter\code\jars and the Integration Server_directory\lib directory respectively. | |
| 1023 | Invalid migration package Package Name. |
| Explanation: The Adapter for Remedy migrate_60_To_71 service failed, because the specified target package was invalid. | |
| Action: Specify a valid package in the packageName parameter of the migrate_60_To_71 service and rerun the service. | |
| 1100 | ARException occurred while trying to create entry on Form: formName. ARException Message. |
| Explanation: A Create adapter service was executed to create an entry in the AR System. However, the Create adapter service failed after the field values for the new entry were set. | |
| Action: Review the input signature of the Create adapter service and ensure that valid values were supplied as input and that the input variables have the correct data types. | |
| 1200 | ARException occurred while trying to delete entry <<entryID>> on Form: formName. ARException Message. |
| Explanation: A Delete adapter service was executed to delete an entry in the AR System. However, the Delete adapter service failed to delete the entry. | |
| Action: Check the input and output signatures of the adapter service and ensure valid values were supplied as input and that the input variables have the correct data types. | |
| 1300 | ARException occurred while trying to get entries from Form: formName. ARException Message. |
| Explanation: A Get or Batch Get adapter service was executed to retrieve detail information about one or more entries in the AR System. However, the Get or Batch Get adapter service failed after reading the fields in the entry or entries. | |
| Action: Check the input and output signatures of the adapter service. Ensure the output fields have the correct data types. | |
| 1400 | ARException occurred while trying to update the entry [entryID] on Form: formName.ARException Message. |
| Explanation: An Update adapter service was executed to update information for an entry in the AR System. However, the Update adapter service failed after setting the fields in the entry. | |
| Action: Review the input signature of the Update adapter service and ensure valid values were supplied as input and that the input variables have the correct data types. | |
| 1500 | ARException occurred while trying to find entries from Form: formName, using the query [query]. ARException Message. |
| Explanation: A Find adapter service was executed to retrieve details from the AR System. However, the adapter service encountered an error while getting the list entries for the specified query. | |
| Action: Check the query and output signature of the Find adapter service. |