22
Oracle Application Server ProcessConnect Troubleshooting

This chapter describes Oracle Application Server ProcessConnect troubleshooting methodologies.

This chapter contains these topics:

• Runtime Troubleshooting Methods

• Performing Runtime Troubleshooting

• Design-Time Troubleshooting of Modeling Metadata Dependencies

• Additional Troubleshooting Documentation

• Chapter Summary

Runtime Troubleshooting Methods

Oracle Application Server ProcessConnect provides several methods for troubleshooting errors:

• Log Files

• Business Intelligence Logging Levels

• Reports

Log Files

Oracle Application Server ProcessConnect generates adapter framework and integration manager log files describing all types of events, including startup and shutdown details, errors, warning messages, access details on HTTP requests, and so on. You can view the log files in either of two ways:

• With Oracle Enterprise Manager (strongly recommended)

• With a command line editor
  • The adapter framework log file is located in the $ORACLE_HOME/ip/log/af/log.xml file.

  • The integration manager log file is located in the $ORACLE_HOME/ip/log/im/log.xml file.

After installation, the adapter framework and integration manager are automatically started with error as the logging level. To view errors in, for example, translation or transformation, the logging must be set to debug. This can be done in the Oracle Enterprise Manager Application Server Control as follows:

1. Select the Oracle Application Server ProcessConnect middle-tier instance.

2. Select the Server Properties link.

3. Change the settings of parameters with oracle.tip.DiagnosticLevel in their name from error to debug.

   See Also: "Oracle Application Server ProcessConnect Log Files" for instructions on accessing log files through Oracle Enterprise Manager "Oracle Application Server ProcessConnect Middle-Tier Instance Configuration Parameters" for instructions on changing logging levels to debug

Business Intelligence Logging Levels

When you prepare to deploy a configuration, you can select a business intelligence logging level. The level that you set impacts the detail of the reports you can later create when your configuration is deployed. The available settings and the details that they create are as follows:

• High creates instance data for all roles, ports, steps, transition instances, and event instances, but can have an impact on runtime performance.

• Medium creates data for role, step, and port instance data, and has less of an impact on runtime performance.

• Low creates data for roles with only one step (typically, a pass-through step), but provides better runtime performance.

  See Also: "Deploying a Validated Configuration" for the following details: Specific descriptions of each logging level Instructions on setting a business intelligence logging level

Reports

Oracle Application Server ProcessConnect provides a series of report creation wizards that enable you to track the movement of events and business processes and identify errors.

• Process monitoring reports

  Show the current status of events, coordinations showing how far events have progressed in an integration, domain and system errors and associated events, collaborations, and business messages in an integration. They are best used to either monitor the status of events or business processes or debug the progress of a specific deployed integration.

• Process optimization reports

  Monitor business process efficiency

• Activity monitoring reports

  Analyze specific business activities across integration objects

  See Also: Chapter 23, "Creating Reports"

Performing Runtime Troubleshooting

This section provides an overview of how to troubleshoot an error in Oracle Application Server ProcessConnect.

This section contains these topics:

• Creating an Error Status Report

• Creating a Coordination Status Report

• Creating an Event Status Report

• Using the IP.tip_rtlog table

• Troubleshooting Use Case

Creating an Error Status Report

Error status reports contain any domain or system errors and the associated events.

1. Create an error status report.
   1. Select Reports > Process Monitoring.

   2. Select Error Status.

   3. Optionally click the calendar icon for the Start Date field to select a date at which to begin gathering report data.

   4. Click Finish.

2. The Summary Report of the Error Status Report page displays the number of errors occurring in the past week.

3. Click Details. The Details Report of the Error Status Report page appears.

   The Event Timestamp column indicates when the error first occurred. The Last Occurred Timestamp column indicates the last time the error occurred. The Retry Count column indicates the number of retries that were attempted to recover from the error.

4. Click Details in the Details column.

   The Error Details page displays specific details about the error, including error class, code, and message.

Creating a Coordination Status Report

Coordination status reports show how far an event has progressed.

1. Create a coordination status report to determine if any errors occurred:
   1. Select Reports > Process Monitoring.

   2. Select Coordination Status.

   3. Optionally click the calendar icon for the Start Date field to select a date at which to begin gathering report data.

   4. Click Finish. The Summary Report page displays the number of coordinations for the business processes in the configuration.

   5. Click Details for more information. The Details Report page appears, and displays the following coordination state information:

      State	Description
      aborted	Coordination processing has been aborted. For example, a transformation failed.
      closed	Coordination processing has completed.
      open	Coordination processing is occurring. This state can remain open for a while if you are waiting for an acknowledgment.

   6. Click the Details page of any coordinations that display as aborted.

      The Coordination Details page displays only the roles to which the event progressed. For example, it may stop at the translation binding role.

   7. Click Expand All to display the last action the event attempted to do, but failed. For example, if the last role to which the event progressed was a translation binding role, then the last step that the event made it to may be the translation step. This can indicate that a translation error occurred.

Creating an Event Status Report

1. Create an event status report to determine if the event made it to the integration manager:
   1. Select Reports > Process Monitoring.

   2. Click Specify Event.

   3. Optionally click the calendar icon for the Start Date field to select a date at which to begin gathering report data.

   4. Select the event type classification and event name to track.

   5. Click Finish.

      If the adapter framework created the native event successfully, there is at least one event that made it to the integration manager.

   6. Click Details for more information.

2. If the event did not make it to the integration manager:
   1. Check the adapter framework log file from the Oracle Enterprise Manager Application Server Control by following the instructions in "Managing and Monitoring a Middle-Tier Instance from Oracle Enterprise Manager Application Server Control".

   2. Search for AIP (the prefix for error message codes).

3. If the event made it to the integration manager:
   1. Follow the event through the reports created in Step 1 to identify the problem.

   2. Check the integration manager log.

   3. Search for AIP. If the event is not in the integration manager log, it may be a system error.

4. Resolve the problem based on your findings in Step 2 or 3.

Using the IP.tip_rtlog table

When the oracle.tip.DiagnosticLevel is set to debug, Oracle Application Server ProcessConnect records activities occurring in the Oracle Application Server Metadata Repository in the IP.tip_rtlog table. The $ORACLE_HOME/ip/admin/iprtcln.sql script can be run to place the contents of the table in a log file and delete the selected entries from the table. The script must be run as the ip Oracle Application Server ProcessConnect schema user.

This script requires three parameters:

• The name of the log file with the absolute path. By default, this creates an im_db.log file in the current directory.

• The date up to which the entries in the table must be selected

• An option to delete the selected entries

Enter the following syntax at the command prompt:

sqlplus ip/ip_password@net_service_name @$ORACLE_HOME/ip/admin/iprtcln.sql

where ip_password is the password for the Oracle Application Server ProcessConnect schema in the Oracle Application Server Metadata Repository and net_service_name is the Oracle net service name for connecting to the Oracle Application Server Metadata Repository.

For example:

sqplus ip/ip@iasdb @$ORACLE_HOME/ip/admin/iprtcln.sql

After the contents are placed in a log file, search for ORA- (the prefix for errors occurring in the metadata repository). If you see entries with ORA-, contact Oracle Support Services.

Troubleshooting Use Case

Chapter 7, "Tutorial of an Integration within an Enterprise" describes how to create an integration within an enterprise. Included in this chapter is "Task 6: Troubleshooting Any Errors with Log Files and Reports", which provides specific details on how to troubleshoot problems that can occur. Oracle recommends that you read this section.

Design-Time Troubleshooting of Modeling Metadata Dependencies

This section describes modeling metadata dependencies to understand as you design and troubleshoot an integration. Note the following modeling metadata dependencies:

• Modeling metadata can reference other metadata.

• Modeling metadata must be created before it can be used as a reference by other modeling metadata.

• All modeling metadata can be created without the need to reference any other metadata at creation time.

• Deleting modeling metadata requires that all references to it are removed first.

Note the following special cases:

• Some modeling metadata also deletes the metadata it references (for example, when an application event type is deleted, its datatypes are also deleted).

• Some objects can be deleted even if they are referenced by other modeling metadata or profile data (for example, deleting a native role also removes its reference from any agreements with which it is associated).

This section provides specific information on these type of dependencies:

• Modeling Metadata Dependency Graphical View

• Application Event Dependency Example

• Modeling Metadata Dependency Cases

• Common Modeling Metadata Dependency Error Examples

Modeling Metadata Dependency Graphical View

Figure 22-1 shows this modeling metadata dependency. For example, to delete an event type, you must first remove any references in the event map, correlation, role port, step port, condition expression, and event transformation map. If you attempt to delete the event type before removing these associations, you receive an error.

Figure 22-1 Metadata Dependencies

Text description of the illustration ipusr094.gif

Application Event Dependency Example

This section provides an example of dependencies between modeling metadata.

An application event is created by the translator when defining the native event. Note the following modeling metadata dependencies between the native event and the application event:

• You cannot directly delete an application event.

• You must delete the native event to delete the application event (that is, there is a one-to-one relationship between the native event and application event).

• Deleting a native event (and its application event) is only possible when both are not used elsewhere. Examples of places in which the native event and application event can be used include the following:
  • Role ports

  • Step ports

  • Event transformation maps

  • Condition expressions

• Deleting an application event also deletes application event datatypes (this is a special case)

• Deleting an application event is impossible when application event datatypes are used in step ports, datatype transformation maps, or condition expressions.

• Updating a native event, native event datatype, application event, or application event datatype is not possible. You can only update by first deleting and then recreating.

• Deleting an interaction requires that no native event refers to it

• Deleting a role is allowable (that is, if it only uses other modeling metadata, but is never used by modeling metadata)

Modeling Metadata Dependency Cases

The same methodology (that is, some modeling metadata cannot be deleted before their references have been removed) must be applied to rest of the modeling metadata and some profile data. In addition, there are special cases where these dependencies are slightly different. Table 22-1 describes these dependencies and special cases.

Table 22-1 Dependency Cases

Modeling Metadata	Dependency
Event transformation maps	Before deleting an event transformation map, remove all references to it from the transformation steps and event header rules transformation map.
Datatype transformation maps	Before deleting a datatype transformation map, all references to it must be removed from the event transformation maps and transformation steps.
Condition expressions	Before deleting a condition expression, all references to it must be removed from the condition steps, event transformation maps, and datatype transformation maps.
Control flow	Can always be deleted from the step details page
Data flow	Can always be deleted from the data port details page or the step port details page
Data flow group	Can always be deleted from the business process details page or role details page
Native event correlation	Can always be deleted from the native event types details page
Role port	Special case: can always be deleted, but also deletes all data flows related to it
Step port	Special case: can always be deleted, but also deletes all data flows related to it
Event map	Can always be deleted from the native event types details page
Interaction	Before deleting an interaction, the event map referencing its record type must be deleted from the native event type details page.
Business process and role types	Can always be deleted. Special case 1: Deleting a business process or any of the role types also deletes all the referenced data flow groups, role ports, steps, control flows, step ports, and data flows Special case 2: Deleting a native role removes the reference to it from any agreement.
Application	Before deleting an application, the application agreement and SetParty steps referencing that application must be updated.
Application Agreement	Can always be deleted
Events	Before deleting any event type, the following modeling metadata must not reference it: event map, native event correlation, role port, step port, condition expression and, event transformation map. See "Native Event Type" for additional details about native event type dependencies.

Native Event Type

Before deleting the native event type, perform the following tasks:

• The event map specified in the native event type details must be deleted.

• The native event correlation referencing the native event type must be deleted (it is not possible to update it and change the native event type).

• All role ports referencing the native event type must be updated.

• All step ports referencing the native event type must be updated.

Special Case 1

Deleting the native event type also deletes the corresponding application event type (also note that application event types cannot be deleted directly). This means that before deleting the native event type:

• All role ports referencing the application event type must be updated.

• All step ports referencing the application event type must be updated.

• All event transformation maps referencing the application event type must be updated.

• All condition expressions referencing the application event type must be updated.

Special Case 2

Deleting the native event type and application event type also deletes its body elements and associated native datatypes and application datatypes. This means that before deleting the native event type:

• All datatype transformation maps referencing the associated application datatypes must be updated.

• All event transformation maps referencing the associated application datatypes must be updated.

• All step ports referencing the native datatypes and associated application datatypes must be updated.

Common Modeling Metadata Dependency Error Examples

This section provides examples of the types of errors you can receive when attempting to delete modeling metadata that is associated with other modeling metadata.

Example 22-1 Deleting a Native Event

Error

An error occurred when deleting the native event type.

Error-: AIP-16015: Delete of Application Event Type failed with error: Cannot 
delete Event Body Element which is referenced by Event Body Item

Error-: AIP-16011: Cannot delete Event Body Element which is referenced by Event 
Body Item

Solution

You cannot delete the native event because it is referenced in an event map. First delete the event map for the native event. This same error can also refer to a condition expression or transformation map reference.

Example 22-2 Deleting an Interaction

Error

An error occurred when deleting the interaction.

Error-: AIP-16015: Delete of Interaction failed with error: Cannot delete 
Interaction Usage which is referenced by Port

Error-: AIP-16011: Cannot delete Interaction Usage which is referenced by Port

Solution

You cannot delete the interaction, because another native role and native event are using it. First delete any modeling metadata referencing the native roles and native events. Then delete the native roles and native events. After that, you can delete the interaction.

Example 22-3 Deleting an Event Transformation Map

Error

An error occurred when deleting the transformation map {0}.

Error-: AIP-16015: Delete of Event Transformation Map failed with error: Cannot 
delete Event Map Parameter which is referenced by Event Header Rule

Error-: AIP-16011: Cannot delete Event Map Parameter which is referenced by 
Event Header Rule

Solution

You cannot delete the event transformation map, because it is associated with an event header rule. You must first remove the event header rule association, and then delete the event transformation map.

Example 22-4 Deleting an Application

There are two objects that can reference an application: an agreement (the application agreement) and a step (the SetParty Step). The following example describes the errors for both cases:

Problem

The following error occurs when you attempt to delete an application that is being referenced in a SetParty Step:

Error -: AIP-16015: Delete of Application failed with error: Cannot delete 
Application which is referenced by Set Party Step 

Error -: AIP-16011: Cannot delete Application which is referenced by Set Party 
Step 

The application is referenced in a SetParty step in either the business process or one of the roles.

Solution

Remove all references to the application:

1. Locate the SetParty step that is referencing the application you tried to delete.

2. Update the SetParty step and change the party to a different party; for example, select Unspecified.

3. Delete the application.

Problem

The other object that can reference an application is an application agreement. The following error occurs when you attempt to delete an application that is being referenced in an application agreement:

Error -: AIP-16015: Delete of Application failed with error: Cannot delete 
Application which is referenced by Application Participant 

Error -: AIP-16011: Cannot delete Application which is referenced by Application 
Participant 

The application is a participant in an application agreement.

Solution

1. Locate the application agreement referencing the application you attempted to delete.

2. Update the application agreement and change the application participant; for example, select Unspecified.

3. Delete the application.

Additional Troubleshooting Documentation

Oracle Application Server ProcessConnect provides references to error resolution, error handling, and good design practices information in this User Guide and the Application Adapter Guides.

Troubleshooting Details in the User Guide

Table 22-2 describes troubleshooting details in the User Guide.

Table 22-2  Troubleshooting and Error Handling Details

Topic	Section
Tutorial troubleshooting methods Note: The troubleshooting methods described in the tutorial can be used in all situations	"Task 6: Troubleshooting Any Errors with Log Files and Reports"
Technology adapter diagnostics and troubleshooting details:
Advanced Queuing adapter	"Advanced Queuing Adapter Diagnostics and Troubleshooting"
E-Mail adapter	"E-Mail Adapter Diagnostics and Troubleshooting"
File/FTP adapter	"File/FTP Adapter Diagnostics and Troubleshooting"
HTTP adapter	"HTTP Adapter Diagnostics and Troubleshooting"
JMS adapter	"JMS Adapter Diagnostics and Troubleshooting"
Oracle Database adapter	"Oracle Database Adapter Diagnostics and Troubleshooting"
Web Service adapter	"Web Service Adapter Diagnostics and Troubleshooting"
Common errors when using the modeling wizards	"Common Modeling Wizard Errors"
Common role design errors	"Designing Roles to Ensure Proper Validation"
Common transformation design errors and transformation design limitations	Chapter 14, "Advanced Transformations Design"
Deployment topics:
Reasons for the unsuccessful creation of a configuration	"Unsuccessful Configuration Creation and Validation"
Setting business intelligence reporting levels in a configuration	"Deploying a Validated Configuration"
Oracle Enterprise Manager topics:
Accessing log files	"Oracle Application Server ProcessConnect Log Files"
Changing logging configuration parameter settings	"Oracle Application Server ProcessConnect Middle-Tier Instance Configuration Parameters"
Error handling topics, including:
Types of errors	"Types of Errors"
Creating a step return code port that captures domain error details	"Error Handling with Step Return Code Ports"
Role and event instance error state implications	"Implications of Role Instances and Event Instances Being in an Error State"
Where to look for runtime error details	"Where Do I Find Runtime Error Details?"
Typical adapter framework and integration manager errors and corrective actions	"Typical Adapter Framework and Integration Manager Errors"
Creating alert e-mail messages	"Alert E-Mail Message Format"
Error, business process, and event reports, including use case examples	Chapter 23, "Creating Reports"

Troubleshooting Details in the Application Adapter Guides

Troubleshooting details are also included in the documentation set for the application adapters. Table 22-3 references the documentation in which to look for each adapter.

Table 22-3  Third Party Application Adapter Troubleshooting Documentation

Adapter	Documentation
PeopleSoft 8 adapter	Oracle Application Server Integration Adapter for PeopleSoft 8 User's Guide
SAP R/3 adapter	Oracle Application Server Integration Adapter for SAP R/3 User's Guide
Siebel 2000 adapter	Oracle Application Server Integration Adapter for Siebel 2000 User's Guide
J.D. Edwards OneWorld XE adapter	Oracle Application Server Integration Adapter for J.D. Edwards OneWorld XE User's Guide
VSAM adapter	Oracle Application Server Integration Adapter for VSAM Installation and User's Guide
CICS adapter	Oracle Application Server Integration Adapter for CICS Installation and User's Guide
IMS/TM adapter	Oracle Application Server Integration Adapter for IMS/TM Installation and User's Guide
IMS/DB adapter	Oracle Application Server Integration Adapter for IMS/DB Installation and User's Guide
Tuxedo adapter	Oracle Application Server Integration Adapter for Tuxedo Installation and User's Guide

Chapter Summary

This chapter describes the various methods for troubleshooting errors (viewing log files, setting business intelligence log levels, and creating reports). A use case that describes how to use these methods to troubleshoot an error is also provided.

Modeling metadata in an integration must be deleted in a specific order in Oracle Application Server ProcessConnect. A graphical view shows the dependencies between modeling metadata. A table describing the order in which to delete modeling metadata and profile data and error messages of how not to delete modeling metadata are also provided.

References to troubleshooting details provided throughout this User Guide and the Application Adapters Guides are also provided.