21 Oracle Application Server ProcessConnect Error Handling

This chapter describes how to detect and handle system and domain errors in Oracle Application Server ProcessConnect runtime components.

This chapter contains these topics:

• Domain and System Error Handling

• Where Do I Find Runtime Error Details?

• Typical Adapter Framework and Integration Manager Errors

• Alert E-Mail Message Format

• Chapter Summary

  
  

  See Also: The following sections for additional details on viewing Oracle Application Server ProcessConnect errors: Chapter 18, " System Management with Oracle Enterprise Manager 10g" for instructions on viewing log files and alerts through Oracle Enterprise Manager 10g "Design-Time Troubleshooting of Modeling Metadata Dependencies" "Error Status Report" for instructions on creating error reports for analysis

  
  

21.1 Domain and System Error Handling

This section describes administrator types and errors, provides domain error modeling examples, and describes the implications of role and event instances being in an error state.

This section contains these topics:

• Administrator Types

• Types of Errors

• Error Handling with Step Return Code Ports

• Implications of Role Instances and Event Instances Being in an Error State

21.1.1 Administrator Types

This section describes tasks typically performed by the following administrators:

• System Administrator

• Business Administrator

21.1.1.1 System Administrator

The system administrator manages Oracle Application Server ProcessConnect components and monitors and diagnoses the Oracle Application Server ProcessConnect runtime behavior.

The system administrator must ensure the following:

• An active runtime configuration exists and the adapter framework instance is deployed

• The Oracle Application Server ProcessConnect integration manager and adapter framework components start up and shut down correctly

21.1.1.2 Business Administrator

The business administrator monitors and diagnoses the semantic correctness of an integration.

The business administrator must ensure the following:

• A configuration is deployed

• The profile data is correct

• All adapters within the integration are started

21.1.2 Types of Errors

Oracle Application Server ProcessConnect distinguishes between two types of errors:

• Domain errors

  These errors occur because of incorrect metadata or profile data. For example:

  • A translation step fails because the translator was unable to convert a native event to an application event

  • A transformation step fails because the transformation map was unable to be applied to a given event

  • The adapter framework did not execute an inbound interaction because a native role was not identified

  • The content of the event does not match the designed event type

• System errors

  These errors occur because of system failures. For example:

  • The end system or application is not available for execution of an inbound or outbound interaction

  • A repository is down or out of resources (full tablespace, not enough temporary space, not enough undo space, and so on)

  • Delivery of an event to a party for which no adapter framework has yet been started

The fundamental difference between domain errors and system errors is that you can design domain errors as part of normal business process modeling. This is achieved by providing special error ports on steps where domain errors occur. These ports are then populated with either success or failure values. You can then design the error case.

Note that in fixing a domain error, you as the modeler must typically modify metadata information (or the business administrator must modify the profile data), which requires redeployment of the business process.

In contrast, a system error correction typically does not involve redeployment of the business process.

21.1.3 Error Handling with Step Return Code Ports

The Oracle Application Server ProcessConnect user interface tool enables you to automatically create a step return code port that captures domain error details in the following role steps:

• Translation step

• Transformation step

• Condition step

The step return code port is automatically created as an outbound step port when you create a condition, translation, or transformation step. This port connects only to other step ports because it has a datatype, and never to role ports because role ports require event types. Figure 21-1 shows a step return code port in a transformation step of a transformation binding role and all other required steps. While the example shown in Figure 21-1 includes a transformation step, the step return code port in a translation step requires you to create similar functionality.

Figure 21-1 Step Return Code Port in a Transformation Step of a Transformation Binding Role

Description of the illustration ipusr060.gif

Note: Ensure that the step return code port error handling you create is simple so that it does not result in domain errors. For example, avoid using domain value maps without defaults in Transformation Step 2 in Figure 21-1.

Table 21-1 describes the step return code port and step activity shown in Figure 21-1. The step return code port is automatically created when you create a transformation, translation, or condition step. You must manually create all other steps, step ports, and data flows shown in Figure 21-1 and described in Table 21-1.

Table 21-1 Step Return Code Port in a Transformation Step of a Transformation Binding Role

Step or Port	Description
Split step 1	Delivers the same inbound event to two transformation steps
Transformation step 1	Transforms the event to a business event
Return code port of transformation step 1	Captures the status of the event transformation (either success or failure)
Split step 2	Receives the transformation status (either success or failure) from the return code port and passes it onto the condition step.
Condition step	Receives the transformation status (either success or failure) from the return code port and processes one of the two outgoing control flows: If the transformation succeeded, the event success control flow is processed, which results in the subsequent execution of the pass-through step If the transformation failed, the event failure control flow is processed, which results in the subsequent execution of transformation step 2 The condition step includes a preseeded condition expression named isReturnCodeSuccess that tests for event success or failure.
Pass-through step	Receives the event from transformation step 1, but this step is processed only if the event success control flow was taken, indicating that transformation succeeded. In this case, the event is passed to the business role for additional processing.
Transformation step 2	Receives the event from the split step, but this step is processed only if the event failure control flow was taken, indicating that transformation failed. In this case, transformation step 2 creates and passes an application event to the application role, translation binding role, native role, and onto, for example, an E-Mail adapter for delivery to the business administrator.

21.1.3.1 Creating a Step Return Code Port

Table 21-2 describes the tasks to create the steps, step ports, and data flows shown in Figure 21-1. References are provided to the procedures for performing these tasks. If you create a step return code port in a translation step, you must perform similar tasks.

Table 21-2 Step Return Code Port Tasks

Task	See Also...
Create transformation step 1. Create the remaining steps shown in Figure 21-1: Split step 1 and split step 2 Transformation step 2 Condition step Pass-through step Note: The step return code port is automatically created as an outbound port to another step on the condition step and on both transformation and translation steps.	Chapter 9, " Creating Metadata with the Modeling Wizards" to automatically create the initial transformation step as part of a spoke "Creating a Step" to manually create all steps Note: The modeling wizards only create an initial transformation or translation step in a role. Manually create the second step.
Create step ports, control flows, and data flows as needed for all steps.	"Creating a Step Port" "Creating a Step Data Flow " "Creating a Step Control Flow" Note: The modeling wizards only create an initial transformation step’s data flow or step port. Manually create all remaining step ports, control flows, and data flows.

See Also: "Creating an Alert E-Mail Message Native Format" for additional tasks to perform if you want to include error details in an e-mail message, including creating all remaining roles of a spoke for an integration, creating the E-Mail adapter interaction, specifying token substituted text as the native format, and creating an application agreement

21.1.3.2 Additional Domain Error Modeling Examples

Figure 21-2 shows an additional example of how domain error modeling appears in the Process Diagram for a translation binding role. Note that the End step at the bottom is not shown due to space constraints.

Figure 21-2 Modeling Domain Errors in a Translation Binding Role

Description of the illustration alert_tl1.gif

Figure 21-3 shows an additional example of how domain error modeling appears in the Process Diagram for a transformation binding role. Note that the End step at the bottom is not shown due to space constraints.

Figure 21-3 Modeling Domain Errors in a Transformation Binding Role

Description of the illustration alert_tbr1.gif

See Also: "Error Handling with Step Return Code Ports " for an example of how steps such as these can be designed Chapter 12, " Managing Business Processes and Roles " for details about creating steps, ports, control flows, and data flows

21.1.4 Implications of Role Instances and Event Instances Being in an Error State

As described in Chapter 3, "Oracle Application Server ProcessConnect Concepts" and Chapter 12, " Managing Business Processes and Roles ", a coordination represents the execution of the business transaction represented by the modeled business process. A coordination consists of the full set of role instances and event instances that are bound to a specific business process. A native event instance is created from the wire message received by the adapter framework. As the event is processed by various roles in Oracle Application Server ProcessConnect, the appropriate role instances are created. The event can be translated into an application event instance and transformed into a business event instance before executing the business process. The various event instances and role instances and their states are described in Chapter 3, "Oracle Application Server ProcessConnect Concepts".

An event instance is set to an error state in the following scenarios:

• A native event instance (that is correlated to another native event) is raised by the adapter but the adapter framework cannot determine a port to send this native event to because:

  • The correlated native event was received earlier and therefore there is not another port for this native event being raised. For example, assume an acknowledgment (ack) for a purchase order is sent; this error occurs if the ack is sent for the second time.

  • The coordination corresponding to the correlated native event is in an aborted or closed state

• A native event instance (that is not correlated to another native event; meaning this is an initiating native event) is being raised by the adapter, but the adapter framework cannot determine a native role to process this native event. This is because there is no valid effective agreement for the native role responsible for accepting this native event.

  • For example, assume a purchase order is sent. The native role that has an initiating port of the purchase order type is ProcessPONativeRole. However, assume ProcessPONativeRole is part of an agreement with effective agreement dates of 04/01/2003 to 04/30/2003. Based on the current date, this agreement is not effective or valid. Therefore, a native role cannot be instantiated.

• A translation step in one of the binding roles that encounters a domain error. The corresponding input event is then put into an error state.

• A transformation step in one of the roles that encounters a domain error. The corresponding input events are then put into an error state.

• Another event in the same coordination (may be or may not be in the same role instance) causes the coordination to be put into an aborted state.

When the native event is set to an error state while being raised by the adapter, there is no corresponding role instance associated with it. Therefore, there is no impact on states of any role instances or coordinations. However, when an event is set to an error state because of a domain error in one of the steps you designed, the subsequent processing depends on the designed behavior, which can be one of the following:

• You have designed the domain error modeling in anticipation of this error by:

  • Creating a data flow between the return code port of this step and an input port of a condition step that uses the preseeded condition expression (isReturnCodeSuccess) to determine if the current step succeeded or not. The condition step itself is connected to two different steps for the two possible outcomes.

    In this case, the input event into the current step is set to an error state and the execution of the steps continues along the false path out of the condition step. There is no impact on the state of the current role instance or the current coordination

• You have not designed the domain error modeling (that is, the return code port of this step is not connected to any other port).

  • In this case, the current role instance and the current coordination are set to the aborted state. All subsequent processing in all roles in this coordination halts.

    For example, say a createPO event (POID: 123) runs into a transformation error. A subsequent updatePO (POID: 123) event that is correlated to the createPO event cannot then be raised after the createPO (ID: 123) event runs into the transformation error because this results in the corresponding role instance and the coordination being put into an aborted state.

    Assuming that updatePO (POID: 123) was raised before the transformation error, the native event is raised successfully. However, the native, application, and business events corresponding to the updatePO event are subsequently set to an error state depending on when the transformation error occurs and which role is processing updatePO at that time.

For system errors such as a database going down due to insufficient memory or tablespace problems, Oracle Application Server ProcessConnect retries periodically until it succeeds. You do not need to design for these errors.

21.2 Where Do I Find Runtime Error Details?

This section describes the various methods for detecting and handling errors that can occur during the execution of the business process.

Oracle Application Server ProcessConnect captures various runtime error details. Table 21-3 describes where to look for this information.

Table 21-3 Runtime Errors

Area	Description	See Also
Oracle Application Server ProcessConnect user interface tool error reports	Error reports are useful for diagnosing errors directly related to event processing in roles and steps, such as: A translator failed to translate a native event to an application event A transformation step failed because of a type mismatch in the event body data A condition step failed evaluating the condition expression A SetParty step failed because of an attempt to set a nonexisting party name	"Error Status Report" to create a report "Monitoring Current Errors in an Integration" for an error report example
Oracle Application Server ProcessConnect user interface tool event status and details reports	Event status reports can be generated using the event state as a filter. This enables you to create a report for events in an error state. In the details section of the report, you can navigate through the errored event predecessor events to identify the origin and context of the errored event (role step and port information, and so on).	"Event Status Report" to create a report "Monitoring iProcurement Process Status" for event status report examples
Oracle Application Server ProcessConnect user interface tool coordination status and details reports	Coordination status reports can be quickly generated to identify erroneous business transactions. The details section of the report lists all the roles and event instances involved in a coordination.	"Coordination Status Report" to create a report "Monitoring Coordination Details" for a coordination status report example
Oracle Application Server ProcessConnect system metrics through Oracle Enterprise Manager 10g Grid Control Console or the Oracle Enterprise Manager 10g Application Server Control Console	You can use the Oracle Enterprise Manager 10g monitoring functions to check for errors. For example, you can check the following: The status of the Oracle Application Server ProcessConnect integration manager and adapter framework components (either up or down) The number of errored events for each adapter	"Oracle Application Server ProcessConnect Monitoring and Administration Tasks" to access the Oracle Enterprise Manager 10g Application Server Control Console and "Oracle Application Server ProcessConnect Monitoring Tasks" to access the Oracle Enterprise Manager 10g Grid Control Console, from which you can view Oracle Application Server ProcessConnect status and adapter framework metrics
Oracle Application Server ProcessConnect log and system exception files through the Oracle Enterprise Manager 10g Application Server Control Console and Oracle Enterprise Manager 10g Grid Control Console, respectively	Errors occurring during operation of the integration manager and adapter framework are logged to component specific log files and as system exceptions in the runtime repository. In contrast to the preceding errors, these errors are not directly related to event processing: A SQL error occurred while accessing the Oracle Application Server ProcessConnect repository An adapter failed to establish a connection with the EIS	"Oracle Application Server ProcessConnect Monitoring Tasks" to access the Oracle Enterprise Manager 10g Grid Control Console, from which you can view the system exception runtime repository "Oracle Application Server ProcessConnect Monitoring and Administration Tasks" to access the Oracle Enterprise Manager 10g Application Server Control Console from which you can view log files
Oracle Application Server ProcessConnect log files through the Oracle Enterprise Manager 10g Application Server Control Console	Fatal JVM errors preventing the integration manager and adapter framework from continuing are logged to OC4J log files in the $ORACLE_HOME/opmn/logs directory. The naming conventions for these files are as follows: ProcessConnect~IntegrationManager~instance_name for the integration manager ProcessConnect~AdapterFramework~instance_name for the adapter framework	"Oracle Application Server ProcessConnect Monitoring and Administration Tasks" to access the Oracle Enterprise Manager 10g Application Server Control Console, from which you can view OC4J log files

See Also: Chapter 18, " System Management with Oracle Enterprise Manager 10g" Chapter 23, " Creating Reports"

21.3 Typical Adapter Framework and Integration Manager Errors

Table 21-4 describes typical adapter framework errors.

Table 21-4 Common Adapter Framework Errors

Error	Reason	Where To Look	Action
Oracle Application Server ProcessConnect adapter framework component is not starting	There are several possible reasons, including: An environment issue (a missing jar file) The repository is down The adapter framework instance name is not in the design-time repository	Use the Oracle Enterprise Manager 10g Application Server Control Console to check the Oracle Process Management Notification (OPMN) log for errors	Fix and restart the adapter framework
Oracle Application Server ProcessConnect adapter framework component terminates unexpectedly	A Oracle Application Server ProcessConnect component is terminated (for example, the adapter framework or integration manager) in the case of fatal JVM errors (for example, if a jar file was not found or there was an internal VM error)	Use the Oracle Enterprise Manager 10g Application Server Control Console to check the OC4J log	Fix and restart the adapter framework
No adapter is started by the adapter framework	The adapter framework does not start adapters in the following cases: The adapter framework active runtime configuration does not exist The adapter framework instance is not yet deployed No effective agreement is found for the adapter	Use the Deployment tab to check for an active configuration or use the Oracle Enterprise Manager 10g Application Server Control Console to check for errors in the adapter framework log file	Deploy a configuration and monitor if the adapters start after deployment If the adapters exist, but there is no agreement, create an agreement and redeploy the configuration
There is no effective agreement between the native role and the party	The current date is not within the time interval specified with the Effective From Date and Effective To Date fields of the agreement	Adapter framework log files, which are viewable from the Oracle Enterprise Manager 10g Application Server Control Console	Create a new agreement and redeploy the configuration

See Also: Chapter 18, " System Management with Oracle Enterprise Manager 10g" Chapter 23, " Creating Reports"

Table 21-5 describes typical integration manager errors.

Table 21-5 Common Integration Manager Errors

Error	Reason	Where To Look	Action
Oracle Application Server ProcessConnect integration manager component is not starting	There are several possible reasons, including an environment issue (a missing jar file) a repository being down, and so on.	Use the Oracle Enterprise Manager 10g Grid Control Console and check the OC4J log for errors.	Fix and restart the integration manager
Oracle Application Server ProcessConnect integration manager component terminates unexpectedly	A Oracle Application Server ProcessConnect component is terminated (for example, the adapter framework or integration manager) in the case of fatal JVM errors (for example, if a jar file was not found or there was an internal VM error).	Use the Oracle Enterprise Manager 10g Grid Control Console and check the OC4J log.	Fix and restart the integration manager
A translation step failed in the translation binding role	The translator was unable to convert the native event data to the designed application event.	The Oracle Application Server ProcessConnect user interface tool error report or event status report or the Oracle Enterprise Manager 10g Grid Control Console	Check the translator error message and take appropriate actions
A transformation step failed in the transformation binding role	A transformation map was unable to be applied due to a type mismatch	Oracle Application Server ProcessConnect user interface tool error report or event status report or the Oracle Enterprise Manager 10g Grid Control Console	Check the error message in the error report and take appropriate actions
A condition step failed in the binding role	The condition expression was unable to be evaluated	Oracle Application Server ProcessConnect user interface tool error report or event status report or the Oracle Enterprise Manager 10g Grid Control Console	Check the error message in the error report and take appropriate actions

See Also: Chapter 18, " System Management with Oracle Enterprise Manager 10g" Chapter 23, " Creating Reports"

21.4 Alert E-Mail Message Format

You can send an alert e-mail through the E-Mail adapter. This e-mail typically contains the following details:

• Business process name

• Step name

• Error code

• Source event identifier (that is, the purchase order identifier)

Alert e-mails consist of a subject and message body. Example 21-1 shows an alert e-mail example:

Example 21-1 Alert E-Mail Example

FROM: [e-mail]
SUBJECT: my_po_bp.transform_po transformation failure

Transformation step transform_po failed in business process my_po_bp for 
purchase order #12345 with error:
Error -:  AIP-10422:  Transformation step callout failed during 
execution: 
oracle.tip.ts.transformation.api.exception.DomainResourceException: 
Error -:  AIP-14004:  Error in invoking domain value function 
lookupBusinessViewDomain.

Where...	Is...
Business process name	my_po_bp
Step name	transform_po
Error code	Error -: AIP-10422: Transformation step callout failed during execution: oracle.tip.ts.transformation.api.exception.DomainResourceException: Error -: AIP-14004: Error in invoking domain value function lookupBusinessViewDomain.
Source event identifier	#12345

To produce the alert e-mail, you must create a transformation to produce the appropriate event type for delivery through the E-Mail adapter. In most cases, the transformation occurs in a context event such as a purchase order so that the message is customized with contextual information.

Alert e-mails consist of subject and message bodies. The token substituted text native format supports the specification of alert e-mail subject and message bodies. Token substituted text is free-form text interspersed with tokens representing values that can be completed at runtime. The token substituted text converter creates an application datatype with members for each of the tokens. You define a transformation to populate these values. The token substituted text translator substitutes the values into the text for outbound messages and parses the message for the token values for inbound messages.

See Also: "Token Substituted Text" for examples of how to define token values in subject and message bodies of alert e-mails

21.4.1 Creating an Alert E-Mail Message Native Format

Table 21-6 describes the tasks to perform to create an alert e-mail message native format. References are provided to procedures for performing these tasks.

Table 21-6 Tasks for the Alert E-Mail Message Native Format

Task	See Also...
Add an E-Mail adapter outbound interaction by selecting Send E-mail(E-MailRecord) and providing answers to specific questions when prompted.	"Adding an E-Mail Adapter Interaction"
Select token substituted text as the native format when prompted.	"Review the Adapter Interaction Details"
Specify a token substituted text namespace when prompted.	"Providing Token Substituted Text Details"
Create the remaining roles of a spoke for your integration (native roles, binding roles, application roles, business roles, and business process)	Either of the following chapters: Chapter 9, " Creating Metadata with the Modeling Wizards" to automatically create roles and a business process Chapter 12, " Managing Business Processes and Roles " to manually create roles and a business process
Create an application and application agreement that uses the E-Mail adapter.	Chapter 15, " Managing Applications and Application Agreements"
Create an event transformation map for the return code. The map is for populating the application event type created for the E-Mail adapter interaction. Values can be constant, come from the return code, or come from the initial instance. Do not rely on initial instance values, as they may have caused the system error in the first place.	"Managing Transformation Statements"

Note: You can also use the Oracle Database adapter to log errors to a database table. To do this, you must create an application agreement and adapter interaction that includes the Oracle Database adapter.

21.5 Chapter Summary

This chapter describes the following details:

• Two types of errors: domain errors (errors due to incorrect metadata or profile data) and system errors (errors due to system failures)

• How to design a step return code port in a condition, transformation, or translation step that captures domain error details

• Role and event instance error state implications

• Where to look for runtime error details

• Typical adapter framework and integration manager errors and corrective actions

• Creating e-mail messages containing error alerts using the E-Mail adapter