Error and Non-Error Logging

As described in the following sections, logging is essential for ensuring correct operation of the integration. You can specify the following two types of logging for Service Manager integration:

System-level logging using a summary logs table and a log details table. See System-Level Logging.
Configurable logging for conversion scripts. See Configurable Logging for Conversion Scripts.

System-Level Logging

System-level logging is the only way to administer the integration on an ongoing basis. We recommend creating a portlet or a report to regularly query and display the logging tables and help you identify potential problems.

You can configure ALM to log only errors for integration exceptions and a summary, or to also log entries for non-error events related to the processing of changes. For information about setting the server.conf parameter that controls the level of logging (MAC_LOG_SEVERITY), see Configure the server.conf parameter in OpenText PPM.

Setting the MAC_LOG_SEVERITY parameter to 0 causes the summary logs table (SDI_SUMMARY_LOGS) to include only a summary of errors. Setting this parameter to 1 causes the summary logs table to also include information about tickets as they are being processed.

The summary logs table maintains only one row for each unique combination of the TICKET_ID and ADAPTER_NAME columns. See Summary Logs Table. Each row is updated on an ongoing basis as status changes.

The log details table (SDI_LOG_DETAILS) includes details about the errors that have a value of Y in the MESSAGES column of the summary logs table. See Log Details Table. (The setting of the MAC_LOG_SEVERITY parameter in the server.conf file does not affect the contents of the log details table.)

Summary Logs Table

The columns in the summary logs table (SDI_SUMMARY_LOGS) that contain useful information are described in the table below.

Table 4-7. Summary logs table (SDI_SUMMARY_LOGS)
Column	Description
LOG_ID	Primary key for this table.
TICKET_ID	Ticket ID imported using the connector. In some cases such as connection errors or authentication failures, the value is SUMMARY.
STATUS	Current state of the ticket. Possible values are as follows: Retrieved/Not processed. The ticket was retrieved and has not been processed. preFilter Passed. The ticket passed the `preFilter` function and was sent to the `convert` function. Rejected in preFilter. The ticket did not pass `preFilter` criteria. Ticket converted. The ticket passed the `convert` function and was sent to the `postFilter` function. postFilter Passed. The ticket passed the `postFilter` function and was sent to the `sender` function. Rejected in postFilter. The ticket did not pass the `postFilter` function. Error occurred in JavaScript. An exception occurred in the `preFilter, convert,` or `postFilter` function when processing the JavaScript conversion file. Ticket processed. The ticket was created in the target system. Errors occurred when sending the ticket. An exception occurred and the ticket could not be sent to the `sender.`
LAST_UPDATE_DATE	Last time the ticket was updated in OpenText PPM.
COMPONENT	Component that logged the message—the connector, converter, or sender.
ADAPTER_NAME	Service desk name in the adapter settings file.
MESSAGES	If the value is Y, further details for this log entry are provided in the log details table (`SDI_LOG_DETAILS`). If the value is N, no further details are provided.
IN_PROCESS	If the value is Y, processing of this ticket is complete. If the value is N, processing of this ticket is not yet complete.

Log Details Table

The log details table (SDI_LOG_DETAILS) includes the details described in the following table for the errors that have a value of Y in the MESSAGES column of the summary logs table.

Table 4-8. Log details table (SDI_LOG_DETAILS)
Column	Description
LOG_DETAIL_ID	Primary key for this table
LOG_ID	Foreign key to the entry in the `SDI_SUMMARY_LOGS` table
DETAILS	Detailed error message captured when the error occurred

Configurable Logging for Conversion Scripts

Configurable logging is useful for debugging your integration mapping. During testing, you can specify log messages that appear at key points in the conversion script to indicate correct or incorrect conversion. Before deploying the integration to production, you would typically want to comment out the messages for correct operation so they do not quickly accumulate in the logs.

If you want to view log messages describing the activity that occurs during the request conversion process, you can include logging objects in your conversion scripts. During the conversion process, you can view the log messages in the conversion script log files, located in the <PPM_Home>/script-logs directory. Each adapter logs messages in a separate log file. The names of the log files are based on the names of the adapters for which the files log errors.

Within any of the script functions, a logging object with the following syntax should be included:

logger.<type of message>("<log message>");

The following message types can be used:

info. Records all processing activity that is performed.
warn. Records warning messages.
error. Records error messages.

Note: Logging is also controlled by the severity specified in the OpenText PPMlogging.conf file.

For example, you can include a logging object such as the following:

logger.info("Processing ticket " + serviceManagerRFC.get("header.changeNumber"));

If you want the conversion script log files to display a list of all Service Manager fields, you can include the following logging object in your conversion script:

logger.info(BeanUtils.describe(ticket));

If you use this logging object, make sure the following line is included at the beginning of the conversion script:

importPackage(Packages.org.apache.commons.beanutils);