27 Configuring Oracle AIA Processes for Error Handling and Trace Logging

This chapter provides an overview of Oracle BPEL and Mediator Process Error Handling and AIA Error Handler Framework and describes how to enable AIA Processes for Fault Handling, implement Error Handling for the Synchronous Message Exchange Pattern, implement Error Handling and Recovery for the Asynchronous Message Exchange Pattern to ensure guaranteed message delivery, configure AIA Services for notification, describe the FaultNotification Element, extend fault messages, extend error handling and how to configure Oracle AIA Processes for Trace Logging.

This chapter includes the following sections:

For more information about Oracle AIA B2B error handling, see Chapter 20, "Introduction to B2B Integration Using AIA."

27.1 Overview of Oracle BPEL and Mediator Process Error Handling

This section includes the following topics:

27.1.1 Understanding Oracle BPEL Error Handling

The Oracle Application Integration Architecture (AIA) Error Handling Framework groups BPEL process errors into two categories:

  • Run-time faults

  • Business faults

Run-time Faults

A run-time fault can occur in one of two scenarios:

  • The partner link invocation fails.

  • The partner link receives a named fault indicating that it is a run-time fault.

These faults are not user-defined and are issued by the system. Some situations in which a BPEL process can encounter a run-time fault include the following:

  • The process tries to use a value incorrectly.

  • A logic error occurs.

  • A SOAP fault occurs in a SOAP call.

  • An exception is issued by the server, and so forth.

AIA Services built as BPEL processes should be enabled and configured to catch and handle the run-time faults.

Business Faults

A business fault can occur in one of two scenarios:

  • A BPEL process runs a throw activity after evaluating a condition as a fault.

  • An Invoke activity receives a named fault indicating that it is a business fault.

Business faults are the application-specific faults that are generated when erroneous conditions take place when the message is being processed. These faults are specified by the BPEL process component and are defined in the WSDL.

AIA Services built as BPEL processes should be enabled and configured to catch and handle the run-time, and business faults.

27.1.2 Understanding Oracle Mediator Error Handling

A Mediator component can handle both run-time faults and business faults.

Run-time Faults

These are faults that occur because of some problem in the underlying system, such as the network not being available.

Business Faults

These are exceptions that are returned by called Web services. These are application-specific and are explicitly defined in the service's WSDL file.

AIA Services built as Mediator components should be configured to catch and handle the business faults.

However, fault policies are applicable to parallel routing rules only. For sequential routing rules, the fault goes back to the caller and it is the responsibility of the caller to handle the fault.

AIA recommends the usage of sequential routing rules only.

For more information about configuring the Mediator to handle business faults arising from synchronous invocations using sequential routing rules, see Section 27.4.3, "Guidelines for Configuring Mediator for Handling Business Faults."

27.2 Overview of AIA Error Handler Framework

For more information about the Error Handling Framework and its features, see "Setting Up Error Handling" in Oracle Fusion Middleware Infrastructure Components and Utilities User's Guide for Oracle Application Integration Architecture Foundation Pack.

27.3 Enabling AIA Processes for Fault Handling

This section includes the following topics:

27.3.1 What You Must Know About Fault Policy Files

A fault policy bindings file associates the policies defined in a fault policy file with the SOA composite application (or the service component or reference binding component). The fault policy bindings file must be named fault-bindings.xml. This conforms to the fault-bindings.xsd schema file.

Fault policy file names are not restricted to one specific name. However, AIA recommends a naming convention to be followed for the fault policy files. All fault policy files should be named using the convention <ServiceName>FaultPolicy.xml. They must conform to the fault-policy.xsd schema file.

For more information about naming conventions, see Chapter 32, "Oracle AIA Naming Standards for AIA Development."

AIA recommends that the fault policy bindings file should be defined to associate the policies defined in a fault policy file with the SOA composite application.

AIA Foundation Pack comes with a default fault policy, which is stored in Oracle Metadata Services (MDS), in the AIAMetaData/faultPolicies/V1 folder. When default fault policies are to be used, then the composite.xml file should have the elements shown in Example 27-1 added to it.

Example 27-1 Elements to be Added to composite.xml

<property name="oracle.composite.faultPolicyFile">[pointer to the fault policy 
 xml file in the MDS]</property>
<property name="oracle.composite.faultBindingFile">[pointer to the fault policy 
 bindings file fault-bindings.xml in the MDS]</property>

When Service Constructor is used to construct the AIA Services, and if the developer opts for using a default fault policy file, then Service Constructor automatically inserts the preceding elements in the composite.xml file.

For more information about Service Constructor, see Chapter 4, "Working with Service Constructor."

If a developer chooses to have a customized, service-specific fault policy file for her AIA Service, then, AIA recommends that the fault policy file and fault policy bindings file (fault-bindings.xml) be placed in the same directory as the composite.xml file of the SOA composite application.

When a developer is using Service Constructor to construct the AIA Services and opts for using a service-specific fault policy file and fault policy bindings file, then the tool creates a template file in the same directory as the composite.xml file of the SOA composite application. The developers must define the fault policies in those template files. In this case, the tool does not create the XML elements <property> in the composite.xml.

For more information, see "Schema Definition File for Fault-policies.xml" and "Schema Definition File for Fault-bindings.xml" in Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

27.3.1.1 Associating a Fault Policy File with Fault Policy Bindings File

The following example shows how to associate a fault policy defined in a sample fault-policy file with a fault-policy binding.xml file.

Consider a sample fault policy file, SamplesQueryCustomerPartyPortalProvABCSImplFaultPolicy.xml, with the fault policies defined as shown in Example 27-2.

Example 27-2 Sample Fault Policy File with Fault Policies Defined

<faultPolicies xmlns="http://schemas.oracle.com/bpel/faultpolicy">
   <faultPolicy version="2.0.1"
   id="SamplesQueryCustomerPartyPortalProvABCSImplFaultPolicy" . . . . . . .>
   </faultPolicy>
</faultPolicies>

Associate the policies defined in the preceding fault policy file with the level of fault policy binding that you are using-either a SOA composite application or a component (BPEL process or Oracle Mediator service component).

To do this, modify the template fault-bindings.xml file (created by the AIA Service Constructor when the developer chooses to have a service-specific fault policy instead of using a default fault policy).

In the fault-bindings.xml file, the association is done as shown in Example 27-3.

Example 27-3 Association in fault-bindings.xml

<faultPolicyBindings version="2.0.1"xmlns="http://schemas.oracle.com/bpel/ 
 faultpolicy" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <compositefaultPolicy="SamplesQueryCustomerPartyPortalProvABCSImpl
    FaultPolicy"/>
</faultPolicyBindings>

Note:

In this example, the association is made at the level of the SOA composite application.

AIA recommends that the fault policy binding level be a SOA composite application by default because this conforms with our recommendation that a composite must be built with a single component in it.

27.3.2 How to Implement Fault Handling in BPEL Processes

To implement fault handling in a BPEL process:

  1. Define an EBM HEADER variable in the BPEL process and populate it as the first step.

    The Error Handling Framework uses this variable to populate the fault message with contextual details from the Enterprise Business Message (EBM) header. If the BPEL process is an Application Business Connector Service (ABCS), then input is an Application Business Message (ABM), and the EBM HEADER variable should be populated as soon as the ABM is converted to an EBM. This way, if the error occurs on a partner link after this transformation step, the Error Handling Framework accesses and uses the EBM header details.

  2. Define a fault policy for the BPEL process and bind the process with this policy in fault-bindings.xml.

    When you are using a service-specific fault policy file, always use the CompositeJavaAction, oracle.apps.aia.core.eh.CompositeJavaAction, as specified in the default policy. Including this CompositeJavaAction accounts for error notifications and error logging.

    For more information about how to define a fault policy XML file to handle business faults, see Section 27.4.2.1, "Handling Business Faults."

    For more information about how to define a fault policy XML file to handle run-time faults in the synchronous message exchange pattern (MEP), see Section 27.4, "Implementing Error Handling for the Synchronous Message Exchange Pattern."

    For more information about how to define a fault policy XML file to handle run-time faults in the asynchronous MEP, see Section 27.5, "Implementing Error Handling and Recovery for the Asynchronous Message Exchange Pattern to Ensure Guaranteed Message Delivery."

  3. Define the catch blocks.

    The default behavior of the fault policy after the CompositeJavaAction is to do a rethrow. This returns the execution control to the catch or catch-all block specified in the BPEL process.

    In a way, interception of faults using a fault policy is transparent to you because the CompositeJavaAction rethrows the same fault that has been intercepted by it. So in BPEL, you must catch the fault, such as a binding or remote fault, which is expected out of the invoke activity.

    Hence, define a catch block for each business fault and run-time fault that can be expected at design time.

  4. Define a catch-all block.

    This assists in catching any unexpected errors that may occur while you are running the process.

For more information about defining BPEL catch and catch-all blocks for the synchronous request-response MEP, see Section 27.4.2, "Guidelines for BPEL Catch and Catch-All Blocks in Synchronous Request-Response."

For more information about defining BPEL catch and catch-all blocks for the asynchronous MEP, see Section 27.5.4, "Guidelines for BPEL Catch and Catch-All Blocks."

27.4 Implementing Error Handling for the Synchronous Message Exchange Pattern

This section includes the following topics:

27.4.1 Guidelines for Defining Fault Policies

This section includes the following topics:

27.4.1.1 Defining a Fault Policy XML File for Handling Run-time Faults

Define faults in the fault policy XML file per guidelines illustrated in the following code snippet. In the fault policy, define a section under Conditions as shown in Example 27-4.

Example 27-4 Fault Definition in the Fault Policy XML File

<faultName xmlns:bpelx="http://schemas.oracle.com/bpel/extension"name="bpelx:
 remoteFault">
   <condition>
      <action ref="aia-ora-java"/>
   </condition>
</faultName>
<faultName xmlns:bpelx="http://schemas.oracle.com/bpel/extension" name="bpelx:
 bindingFault">
   <condition>
      <action ref="aia-ora-java"/>
   </condition>
</faultName>

Though AIA recommends that by default, remote and binding faults should be defined, as shown previously, other run-time faults can be handled in the same way if required per the functionality of the service.

For example, if you are required to handle the subLanguageExecutionFault fault, then define the section as shown in Example 27-5.

Example 27-5 subLanguageExecutionFault Fault Handling

<faultName xmlns:bpelx="http://schemas.oracle.com/bpel/extension"name="bpelx:
 subLanguageExecutionFault">
   <condition>
      <action ref="aia-ora-java"/>
   </condition>
</faultName>

However, all the run-time faults that are defined in the fault policy file must be caught in the BPEL process in a catch block, which is specific to the fault.

For more information about defining BPEL catch and catch-all blocks for the synchronous request-response MEP, see Section 27.4.2, "Guidelines for BPEL Catch and Catch-All Blocks in Synchronous Request-Response."

27.4.1.2 Defining a Fault Policy XML File for Handling Business Faults

The Fault Management Framework is used to handle the business faults that are for an invoke activity. In other words, only business faults thrown by external services and applications when invoked using the invoke activity are intercepted by the Oracle Fusion Middleware Fault Management Framework, according to the definitions specified in the fault policy file.

The business faults that are internal to the BPEL, business faults thrown by a throw activity, for example, are not intercepted by the Fault Management Framework.

To define a fault policy to intercept Oracle AIA faults:

  1. Examine your partner link WSDL and check to determine whether it is throwing any Oracle AIA faults.

  2. If it is throwing Oracle AIA faults, look for the partner link namespace and name of the fault in the partner link WSDL.

  3. In the fault policy, define a section under Conditions as shown in Example 27-6.

    Example 27-6 Conditions Element in the Fault Policy

    <Conditions>
       <faultName xmlns:corecustomerpartyebs="http://xmlns.oracle.com/Enterprise
        Services/Core/CustomerParty/V2" name="corecustomerpartyebs:fault">
          <condition>
             <test>[ XPath expression to be evaluated for the fault variable
              available in the fault]</test>
             <action ref="aia-ora-java"/>
          </condition>
       </faultName>
    </Conditions>
    

    Note:

    To avoid unnecessary processing, ensure that you specify retry options only when explicitly required.

  4. Configure the default condition to call the aia-ora-java action, as shown in Example 27-7.

    Example 27-7 Default Condition Configuration Used to Call the aia-ora-java action

    <Conditions>
       <faultName xmlns:corecustomerpartyebs="http://xmlns.oracle.com/Enterprise
        Services/Core/CustomerParty/V2" name="corecustomerpartyebs:fault">
          <condition>
             <test>[XPath expression to be evaluated for the fault variable
              available in the fault]</test>
             <action ref="aia-ora-java"/>
          </condition>
       </faultName>
       <faultName>
          <condition>
             <action ref="aia-ora-java"/>
          </condition>
       </faultName>
    </Conditions>
    
  5. All business faults defined in the fault policy file must be caught in the BPEL process in a catch-block that is specific to the business fault.

    For more information, see Section 27.4.2, "Guidelines for BPEL Catch and Catch-All Blocks in Synchronous Request-Response."

27.4.2 Guidelines for BPEL Catch and Catch-All Blocks in Synchronous Request-Response

Each BPEL process should have explicit catch blocks for remote faults, binding faults, business faults (Oracle AIA faults), and any other fault expected on a partner link at design time. Use these guidelines for defining these catch blocks.

27.4.2.1 Handling Business Faults

To handle an internal business fault:

  1. In the case of a BPEL process carrying out a throw activity, construct a business fault message (Oracle AIA fault message) and populate the AIA Fault message with the ECID, as shown in Example 27-8.

    Example 27-8 Business Fault Message

    <sequence name="SequenceBusinessFault">
       <assign name="AssignBusinessFault">
          <copy>
             <from expression="ora:processXSLT('xsl/EBM_to_Fault.xsl',bpws:
              getVariableData('EBM_HEADER'))"/>
             <to variable="AIAFaultMessage" part="AIAFault" query="/corecom:Fault"/>
          </copy>
          <copy>
             <from expression="'invalid account id'"/>
             <to variable="AIAFaultMessage" part="AIAFault" query="/corecom:Fault/
              corecom:FaultNotification/corecom:FaultMessage/corecom:Text"/>
          </copy>
          <copy>
             <from expression="'invalid account id'"/>
             <to variable="AIAFaultMessage" part="AIAFault" query="/corecom:Fault/
              corecom:FaultNotification/corecom:FaultMessage/corecom:Stack"/>
          </copy>
          <copy>
             <from expression="ora:getCompositeInstanceId()"/>
             <to variable="AIAFaultMessage" part="AIAFault" query="/corecom:
              Fault/corecom:FaultNotification/corecom:FaultingService/corecom:
              InstanceID"/>
          </copy>
          <copy>
             <from expression="'BPEL'"/>
             <to variable="AIAFaultMessage" part="AIAFault" query="/corecom:Fault/
              corecom:FaultNotification/corecom:FaultingService/corecom:
              ImplementationCode"/>
          </copy>
          <copy>
             <from expression="ora:getCompositeName()"/>
             <to variable="AIAFaultMessage" part="AIAFault" query="/corecom:
              Fault/corecom:FaultNotification/corecom:FaultingService/corecom:ID"/>
          </copy>
          <copy>
             <from expression="ora:getECID()"/>
             <to variable="AIAFaultMessage" part="AIAFault" query="/corecom:Fault/
              corecom:FaultNotification/corecom:FaultingService/corecom:
              ExecutionContextID"/>
       </assign>
       <throw name="Throw_custom_business_fault" faultName="client:fault"
        faultVariable="AIAFaultMessage"/>
    </sequence>
    

    Note:

    Ensure that in EBM_to_Fault.xsl, the <corecom:ExecutionContextID/> element is injected under the <corecom:FaultingService> element.

  2. Catch the preceding fault message in the catch block. In the catch block:

    • Send the AIA Fault Message as a reply.

      Invoke the AIAAsyncErrorHandlingBPELProcess with this Oracle AIA fault message as input.

    • Throw the AIA Fault Message that has been caught. This rethrow enables the process to appear as faulted in the Enterprise Manager Console.

To handle an external business fault:

In the case of an Invoke activity in the BPEL receiving an AIA fault message as a response, catch the AIA fault message in the catch block. In the catch block:

  • Send the AIA Fault Message as reply.

  • Throw the AIA Fault Message that has been caught. This rethrow enables the process to appear as faulted in the Oracle Enterprise Manager Console.

Note:

In this case, AIA does not invoke the AIAAsyncErrorHandlingBPELProcess because the business fault is handled by the Oracle Fusion Middleware Fault Management Framework, according to the fault polices defined in the associated fault policy file.

27.4.2.2 Handling Run-time Faults Defined in the Fault Policy File

For each of the run-time faults that has been defined in the fault policy xml file, have a catch block in the BPEL.

To handle run-time faults defined in the fault policy file:

  1. In the catch block, construct an Oracle AIA fault message.

  2. Send this Oracle AIA fault message as the reply.

  3. Rethrow the fault that has been caught. This enables the process to appear as faulted in the Oracle BPEL Console.

27.4.2.3 Handling Run-time Faults Not Defined in the Fault Policy File

Each BPEL process should also have a catch-all block to process run-time faults that are not caught in catch-blocks and not defined in the fault policy file.

To define the catch-all block:

  1. Construct an Oracle AIA fault message. Populate the AIA Fault message with ECID as shown in Example 27-9.

    Example 27-9 Catch-All Block Construction

    <sequence name="SequenceCatchAll">
       <assign name="AssignFault">
          <copy>
             <from expression="ora:processXSLT('xsl/EBM_to_Fault.xsl',bpws:
              getVariableData('EBM_HEADER'))"/>
             <to variable="AIAFaultMessage" part="AIAFault" query="/corecom:Fault"/>
          </copy>
          <copy>
             <from expression="ora:getFaultAsString()"/>
             <to variable="AIAFaultMessage" part="AIAFault" query="/corecom:Fault/
              corecom:FaultNotification/corecom:FaultMessage/corecom:Text"/>
          </copy>
          <copy>
             <from expression="ora:getFaultAsString()"/>
             <to variable="AIAFaultMessage" part="AIAFault" query="/corecom:Fault/
              corecom:FaultNotification/corecom:FaultMessage/corecom:Stack"/>
          </copy>
          <copy>
             <from expression="ora:getCompositeInstanceId()"/>
             <to variable="AIAFaultMessage" part="AIAFault" query="/corecom:Fault/
              corecom:FaultNotification/corecom:FaultingService/corecom:
              InstanceID"/>
          </copy>
          <copy>
             <from expression="'BPEL'"/>
             <to variable="AIAFaultMessage" part="AIAFault" query="/corecom:Fault/
              corecom:FaultNotification/corecom:FaultingService/corecom:
              ImplementationCode"/>
          </copy>
          <copy>
             <from expression="ora:getCompositeName()"/>
             <to variable="AIAFaultMessage" part="AIAFault" query="/corecom:Fault/
              corecom:FaultNotification/corecom:FaultingService/corecom:ID"/>
          </copy>
          <copy>
             <from expression="ora:getECID()"/>
             <to variable="AIAFaultMessage" part="AIAFault" query="/corecom:Fault/
              corecom:FaultNotification/corecom:FaultingService/corecom:
              ExecutionContextID"/>
       </assign>
    </sequence>
    

    Note:

    Ensure that in EBM_to_Fault.xsl, the <corecom:ExecutionContextID/> element is injected under the <corecom:FaultingService> element.

  2. Invoke the AIAAsyncErrorHandlingBPELProcess with this Oracle AIA fault message as input.

  3. Send this Oracle AIA fault message as the reply.

  4. Throw AIA fault message. This enables the process to appear as faulted in the Oracle Enterprise Manager Console.

  5. Unless otherwise required, these catch and catch-all blocks can be defined at the top-level scope and are not required to be defined at the scope for each partner link.

For more information about the Fault Management Framework, see "Using the Fault Management Framework" in Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

27.4.3 Guidelines for Configuring Mediator for Handling Business Faults

Oracle Mediator provides fault policy-based error handling for business faults. However, fault policies are applicable to parallel routing rules only. For sequential routing rules, the fault goes back to the caller (that has invoked the mediator) and it is the responsibility of the caller to handle the fault.

AIA recommends using only sequential routing rules.

When a service invoked by the mediator throws a business fault, this fault must be propagated up to the service that has invoked the mediator.

This section discusses how to configure the mediator to handle business exceptions returned by the services invoked by the mediator.

Here are some points to consider:

  • When the mediator invokes a service, the invoked service can throw any of the business faults that are defined in its WSDL.

  • The fault that is thrown by the invoked service is propagated back to the mediator.

To configure the mediator to handle business exceptions returned by the services invoked by the mediator:

  1. Open the mediator in design-mode using Oracle JDeveloper.

  2. Using the Static Routing panel, assign the inbound fault reaching the mediator to the outbound fault, which is now propagated by the mediator to the service that invoked it, as shown in Figure 27-1.

    Figure 27-1 Assignment of the Faults in the Mediator

    This image is described in surrounding text
  3. As shown in the preceding diagram, assign the inbound fault from the target service's WSDL operation to the outbound fault that is propagated by the mediator to its invoker service.

    For more information about how to assign faults, see "How to Handle Faults" in Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

27.5 Implementing Error Handling and Recovery for the Asynchronous Message Exchange Pattern to Ensure Guaranteed Message Delivery

This section includes the following topics:

27.5.1 Overview

In the context of AIA, guaranteed message delivery for the asynchronous MEP means that the message initiated from a sender is persisted until it is successfully delivered to and acknowledged by the receiver, if acknowledgment is expected.

The sender and receiver are not necessarily the participating applications. Rather, they are logical milestones in an Oracle AIA integration flow. Multiple milestones could be in an Oracle AIA integration scenario.

Temporary unavailability of any hardware or software service in an asynchronous message flow does not result in a lost message or a delivery failure. The Error Handling framework provides a way for the message to be persisted until the hardware or software service becomes available.

After an integration administrator has been notified of the unavailable resource by the Error Console, she can address the resource issue. The integration administrator can then use the Message Resubmission Utility to resubmit the persisted message into the integration scenario from the appropriate transaction milestone point, enabling its delivery to the next component or milestone.

For more information about running the Message Resubmission Utility, see "Using the Message Resubmission Utility" in Oracle Fusion Middleware Infrastructure Components and Utilities User's Guide for Oracle Application Integration Architecture Foundation Pack.

These points summarize primary aspects of an implementation of the guaranteed message delivery programming model for the asynchronous MEP.

  • Message persistence milestones

    Messages are picked from a persistence store (source), processed, and pushed to the next persistence store (target). The message is not removed from the source until it has been successfully processed and delivered to the target. The source and target may be applications. Each persistence store represents a milestone and may be a database, file system, JMS queue, or JMS topic.

    For more information about configuring milestones, see Section 27.5.2, "Configuring Milestones."

  • Global transaction

    These tasks must be accomplished as a part of the global transaction:

    • Picking up the message from the source.

    • Processing the message by one or more services.

    • Delivering the message to the target.

    • The initiation of a service from the source with an input message initiates a transaction. All the services invoked downstream participate in this global transaction. This global transaction ends or is committed when the message is successfully delivered to the target and removed from the source.

      In the case of an error, an exception is raised and the transaction initiated is rolled back with the message safe in the source. The message is either in the source or target and is not lost.

      For more information about configuring the global transaction, see Section 27.5.3, "Configuring Services Between Milestones."

  • Error handling and recovery

    Any exceptions due to system or business errors must generate a rollback of all preceding services and trigger a single error notification to the Integration Administrator. This requires marking the message in the source as faulted, preventing it from being processed until the error condition is removed.

    For more information about configuring error rollback, see Section 27.5.6, "Configuring Fault Policies to Not Issue Rollback Messages."

In case of system errors, after the exception condition has been removed, the faulted messages in the source must be reset. This enables them to be resubmitted. The Message Resubmission Utility can be used to resubmit the messages for reprocessing by the correct source.

In case of business errors, the faulted messages in the source must be removed and sent to fallout management for further action. Fallout management is a custom implementation in which the messages encountering business errors are segregated and processed separately.

For example, suppose that orders submitted for processing encounter a business error. As a part of an Order Fallout Management implementation, the Order message and error message are routed to an application that introspects the error messages and raises a trouble ticket that provides an explanation of the error and the suggested remedial action. After the remedial action is taken, the order is reprocessed.

Error handling and recovery for the asynchronous MEP are implemented as follows to ensure guaranteed message delivery:

  1. Ensure that each message has a unique message identifier.

  2. Populate the EBM header with the source milestone identifier.

  3. Ensure that the fault notification contains the message identifier and source milestone identifier of the faulted message.

  4. Use the Message Resubmission Utility to recover and resubmit a faulted message.

For more information about how to implement these configurations, see Section 27.5.2, "Configuring Milestones" and Section 27.5.3, "Configuring Services Between Milestones."

For more information about using the Message Resubmission Utility, see "Using the Message Resubmission Utility" in Oracle Fusion Middleware Infrastructure Components and Utilities User's Guide for Oracle Application Integration Architecture Foundation Pack.

For more information about the Message Resubmission Utility API, see Section 27.5.7, "Using the Message Resubmission Utility API."

27.5.2 Configuring Milestones

As a part of implementing error handling and recovery for the asynchronous MEP to ensure guaranteed message delivery, messages must be persisted at milestones. The movement of messages between milestones must be guaranteed.

A milestone can be a JMS queue or a JMS topic.

Figure 27-2 and Figure 27-3 illustrate a few possible milestone locations across an integration flow.

Figure 27-2 Integration Flow in Which the Receiver Target Milestone is the Target Participating Application

This image is described in surrounding text

Figure 27-3 Integration Flow in Which the Receiver Target Milestone is Within the Global Transaction Space

This image is described in surrounding text

27.5.3 Configuring Services Between Milestones

This section includes the following topics:

Completing these activities ensures that the services between milestones are configured to provide error handling and recovery for the asynchronous MEP to ensure guaranteed message delivery.

27.5.3.1 Populating Message Resubmission Values

These parameters in the EBM header must be populated in the JMS consumer service transformation:

  • SenderResourceTypeCode

    Indicates the type of resource or system in which the rolled-back message is stored, whether Queue or Topic.

  • SenderResourceID

    Identification of the resource/system of type SenderResourceTypeCode.

  • SenderMessageID

    Identification of the message persisted in the resource/system associated with type SenderResourceTypeCode.

Scenario 1

When an ABM in the JMS Queue or Topic is triggering the JMS Consumer Service, then the preceding information must be passed to the requester ABCS as a part of the ABM header.

For more information, see Section 27.5.3.1.1, "Populating the ABM with Message Resubmission Values in JMSConsumerAdapter."

In the JMS Consumer Service, this information must be configured to be sent to the ABM header. In the requester ABCS, this information is extracted from the ABM header and sent to the EBM header in the transformation.

For more information, see Section 27.5.3.1.2, "Populating the EBM Header with Resubmission Values in the Requester ABCS."

Scenario 2

When an EBM in the JMS Queue or Topic is triggering the JMS consumer service, use an EBM-to-EBM transformation and populate (overwrite) the resubmission values in the EBM message. The following values in the EBM header fields of the inbound message should be overwritten with the new values for the ResourceType, Resource Name, and JMS Message ID pertaining to the current milestone.

  • <corecom:SenderResourceTypeCode>

  • <corecom:SenderResourceID>

  • <corecom:SenderMessageID>

Example 27-10 provides sample code snippet from the EBM-to-EBM XSL.

Example 27-10 EBM-to-EBM XSL Code Example

<corecom:IntermediateMessageHop>
   <corecom:SenderResourceTypeCode>
      <xsl:value-of select="/custebo:CreateCustomerPartyListEBM/corecom:
       EBMHeader/corecom:FaultNotification/corecom:FaultMessage/corecom:
       IntermediateMessageHop/corecom:SenderResourceTypeCode"/>
   </corecom:SenderResourceTypeCode>
   <corecom:SenderResourceID>
      <xsl:value-of select="/custebo:CreateCustomerPartyListEBM/corecom:
       EBMHeader/corecom:FaultNotification/corecom:FaultMessage/corecom:
       IntermediateMessageHop/corecom:SenderResourceID"/>
   </corecom:SenderResourceID>
   <corecom:SenderMessageID>
      <xsl:value-of select='mhdr:getProperty("in.property.jca.jms.
       JMSMessageID")'/>
   </corecom:SenderMessageID>
</corecom:IntermediateMessageHop>
27.5.3.1.1 Populating the ABM with Message Resubmission Values in JMSConsumerAdapter

Ensure that the ABM is enriched with the following content:

  • The unique Message ID. The JMSMessageID in the JMS header is used as the value.

  • The resource name. This is the JMS Queue/Topic name. This is the same as the <svcdoc: ResourceName> value in the JMSConsumerAdapter's composite.xml.

  • The type of the resource. The possible values are Queue or Topic.

Use specifically designated fields in the ABM for this purpose. These fields are identified at the time of design.

Within the mediator-based JMSConsumerAdapter:

  • Use the transformation step in the mediator routing rule.

  • In the XSL used by the transformation, assign the values of the JMS Message ID, Resource Name, and Resource Type to the specifically designated fields of the ABM.

Example 27-11 illustrates how to assign the JMS Message ID to the ABM.

Example 27-11 Example of How to Assign the JMS Message ID to the ABM

<xsl:attribute name="MessageId">
   <xsl:value-of select='mhdr:getProperty("in.property.jca.jms.JMSMessageID")'/>
</xsl:attribute>

In this example, the assumption is that the ABM has a specific attribute, MessageId, to which the JMS Message ID is assigned.

In some cases, only one designated field may be available in the ABM. In such scenarios, concatenate the values of the JMS Message ID, Resource Name, and Resource Type and assign the value to the specific designated field of the ABM. While concatenating these values, AIA recommends using :: as the separator.

For example, consider a Siebel Customer ABM, ListOfCmuAccsyncAccountIo. In this ABM, assume that the MessageId attribute of the ListOfCmuAccsyncAccountIo element is designated to hold the information about JMS Message ID, Resource Name, and Resource Type at design time. Example 27-12 illustrates how to concatenate the data and assign it to the ABM.

Example 27-12 Example of How to Concatenate Data and Assign it to the ABM

<xsl:attribute name="MessageId">
   <xsl:value-of select='concat(mhdr:getProperty("in.property.jca.jms.
    JMSMessageID"),":: SampleQueue","::Queue")'/>
</xsl:attribute>
27.5.3.1.2 Populating the EBM Header with Resubmission Values in the Requester ABCS

When the ABM arrives at the requester ABCS, it contains the JMS Message ID, Resource Name, and Resource Type values because these values were made available in the designated fields of the ABM.

Tip:

Ensure that the <corecom: FaultNotification/> element is inserted into the EBM header when transforming the ABM to the EBM.

Extract these values from the ABM and enter the following elements in the EBM header within the <corecom:IntermediateMessageHop> element:

  • <corecom:SenderResourceTypeCode>: Populate it with the Resource Type value

  • <corecom:SenderResourceID>: Populate it with the Resource Name value

  • <corecom:SenderMessageID>: Populate it with the JMS Message ID value

The XSL that performs the ABM-to-EBM transformation should accomplish this task. The task is straightforward when three different ABM fields are designated for holding the three resubmission values, as shown in Example 27-13.

Example 27-13 Example Illustrating Three ABM Fields Used to Hold Three Resubmission Values

<corecom:IntermediateMessageHop>
   <corecom:SenderResourceTypeCode>
      <xsl:value-of select="[xpath to the ABM field holding the ResourceType]"/>
   </corecom:SenderResourceTypeCode>
   <corecom:SenderResourceID>
      <xsl:value-of select="[xpath to the ABM field holding the 
       Resource Name]"/>
   </corecom:SenderResourceID>
   <corecom:SenderMessageID>
      <xsl:value-of select="[xpath to the ABM field holding the Message Id]"/>
   </corecom:SenderMessageID>
</corecom:IntermediateMessageHop>

The following content discusses how resubmission values are extracted from the ABM and assigned to the EBM header when all three resubmission values are concatenated and assigned to a single designated field in the ABM.

For example, consider a Siebel Customer ABM, ListOfCmuAccsyncAccountIo. In this ABM, assume that the MessageId attribute of the ListOfCmuAccsyncAccountIo element has been designated to hold the information about the JMS Message ID, Resource Name, and Resource Type, concatenated using :: as a separator. See the previous section for more information.

Example 27-14 provides a code snippet that extracts the resubmission values and assign them to EBM header elements.

Example 27-14 Code Used to Extract Resubmission Values and Assign Them to EBM Header Element

<xsl:variable name="MsgId">
   <xsl:value-of select="substring-after(/seblcustabo:ListOfCmuAccsyncAccountIo/
    @MessageId,'::')"/>
</xsl:variable>
<corecom:IntermediateMessageHop>
   <corecom:SenderResourceTypeCode>
      <xsl:value-of select="substring-after($MsgId,'::')"/>
   </corecom:SenderResourceTypeCode>
   <corecom:SenderResourceID>
      <xsl:value-of select="substring-before($MsgId,':: ')"/>
   </corecom:SenderResourceID>
   <corecom:SenderMessageID>
      <xsl:value-of select="substring-before(/seblcustabo:ListOfCmuAccsync
       AccountIo/@MessageId,'::')"/>
   </corecom:SenderMessageID>
</corecom:IntermediateMessageHop>

The XSL that performs the ABM-to-EBM transformation should accomplish this task.

For more information about resubmitting messages, see "Using the Message Resubmission Utility" in Oracle Fusion Middleware Infrastructure Components and Utilities User's Guide for Oracle Application Integration Architecture Foundation Pack.

27.5.3.2 Configuring All Services to Participate in a Single Global Transaction

Configure a single global transaction as follows:

  • Ensure that no commit points are between two milestones.

  • Ensure that the work done between two milestones is one logical unit of work.

For more information about configuring the global transaction, see Chapter 14, "Designing and Developing Enterprise Business Services," Chapter 15, "Designing Application Business Connector Services," Chapter 16, "Constructing the ABCS," and Chapter 19, "Designing and Constructing Enterprise Business Flows."

27.5.4 Guidelines for BPEL Catch and Catch-All Blocks

This section includes the following topics:

27.5.4.1 Handling Run-time Faults Defined in the Fault Policy File

For each of the run-time faults that has been defined in the fault policy xml file, have a catch block in the BPEL. In the catch block, rethrow the fault that has been caught. This enables the process to appear as faulted in the Oracle Enterprise Manager Console.

27.5.4.2 Handling Run-time Faults Not Defined in the Fault Policy File

Each BPEL process should also have a catch-all block to process run-time faults that are not caught in catch-blocks and not defined in the fault policy file.

To define the catch-all block:

  1. Construct an Oracle AIA fault message. Populate the AIA Fault message with ECID as shown in Example 27-15.

    Example 27-15 AIA Fault Message with an ECID Defined

    <copy>
       <from expression="ora:getECID()"/>
       <to variable="AIAFaultMessage" part="AIAFault" query="/corecom:Fault/corecom:
        FaultNotification/corecom:FaultingService/corecom:ExecutionContextID"/>
    </copy>
    
  2. Invoke the AIAAsyncErrorHandlingBPELProcess with this Oracle AIA fault message as input.

  3. Throw the AIA fault message. This enables the process to appear as faulted in the Oracle Enterprise Manager Console.

  4. Unless otherwise required, these catch and catch-all blocks can be defined at the top-level scope and are not required to be defined at the scope for each partner link.

For more information, see Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

27.5.5 Guidelines for Defining Fault Policies

For more information, see Section 27.4.1.1, "Defining a Fault Policy XML File for Handling Run-time Faults."

27.5.6 Configuring Fault Policies to Not Issue Rollback Messages

According to the guaranteed message delivery programming model, when a message cannot be delivered to a service or component in the flow of a global transaction, the message is rolled back to the appropriate source milestone. This source milestone corresponds to an Oracle Advanced Queue, JMS Topic, or Mediator Resequencer Store. The message is persisted here until it can be resubmitted for delivery to the service or component.

The BPEL processes along the transaction rollback path issue fault messages and should be configured to not issue rollback messages as well. The configuration deciphers a rollback transaction so that services in the rollback path do not issue unnecessary notifications.

Without this configuration to suppress rollback messages, these processes issue unnecessary notifications. For example, in the transaction rollback flow illustrated in Figure 27-4, redundant rollback notifications would be sent out by the Requester ABCS, in addition to the one sent out by the Provider ABCS, which is the only one that should be issued.

Figure 27-4 Transaction Rollback Flow

This image is described in surrounding text

To suppress unnecessary notifications for a rollback transaction:

  • Use bpelx:rollback instead of throw in the catch blocks: <throw name="ThrowEBSFault" faultName="bpelx:rollback"/>

  • Use a Java snippet to invoke the Oracle AIA Error Handler, as shown in Example 27-16.

    Example 27-16 Java Snippet to Invoke the Oracle AIA Error Handler

    <bpelx:exec name="Java_Embedding_1" language="java" version="1.5">
       <![CDATA[ oracle.apps.aia.core.eh.InvokeBusinessErrorHandler.process
        ((oracle.xml.parser.v2.XMLElement)getVariableData("inputVariable",
        "FaultMessage","/ns1:Fault"));]]>
    </bpelx:exec>
    
  • Add an empty no-op action to the fault policies of Mediator and BPEL processes along the transaction rollback flow. This empty no-op action is aia-no-action.

When a Mediator or BPEL process receives a rollback message, the control is directed to the class oracle.apps.aia.core.eh.CompositeJavaNoAction, which is implemented against the aia-no-action action.

The oracle.apps.aia.core.eh.CompositeJavaNoAction class is an empty operation, meaning that it does nothing, and thus suppresses further notifications in the rollback flow.

These sample BPEL and Mediator fault policies illustrate the way in which these conditions should be defined in impacted fault policy files.

The aia-no-action fault policy contains a filter expression to perform no action in the case of the rollback fault ORABPEL-02180. An example is illustrated in Example 27-17.

Example 27-17 Sample Fault Policy Using the aia-no-action No-op Action

<?xml version="1.0" encoding="UTF-8"?>
<faultPolicy version="2.0.1" id="SamplesCreateCustomerPartyPortal
 ProvABCSImplFaultPolicy" xmlns:env="http://schemas.xmlsoap.org/soap/
 envelope/" xmlns:xs="http://www.w3.org/2001/XMLSchema"xmlns="http://schemas.
 oracle.com/bpel/faultpolicy"xmlns:xsi="http://www.w3.org/2001/XMLSchema-
 instance">
   <Conditions>
      <faultNamexmlns:plmfault="http://xmlns.oracle.com/EnterpriseServices
       /Core/CustomerParty/V2" name="plmfault:fault">
         <condition>
            <test>$fault.summary/summary[contains(., "ORABPEL-02180")]</test>
            <action ref="aia-do-nothing"/>
         </condition>
      <condition>
            <action ref="aia-ora-java"/>
         </condition>
      </faultName>
      <faultName>
         <condition>
            <test>$fault.summary/summary[contains(., "ORABPEL-02180")]</test>
            <action ref="aia-do-nothing"/>
         </condition>
         <condition>
            <action ref="aia-ora-java"/>
         </condition>
      </faultName>
   </Conditions>
   <Actions>
      <!--  This action will attempt 8 retries at increasing intervals of 
       2, 4, 8, 16, 32, 64, 128, and 256 seconds. -->
      <Action id="aia-ora-retry">
         <retry>
            <retryCount>1</retryCount>
            <retryInterval>2</retryInterval>
            <exponentialBackoff/>
            <retryFailureAction ref="aia-ora-java"/>
            <retrySuccessAction ref="aia-ora-java"/>
         </retry>
      </Action>
      <!--  This is an action will cause a replay scope fault -->
      <Action id="ora-replay-scope">
            <replayScope/>
      </Action>
      <!-- This is an action will bubble up the fault  -->
      <Action id="ora-rethrow-fault">
            <rethrowFault/>
      </Action>
      <!-- This is an action will mark the work item to be "pending recovery
       from console" -->
      <Action id="ora-human-intervention">
         <humanIntervention/>
      </Action>
      <!--  This action will cause the instance to terminate  -->
      <Action id="ora-terminate">
         <abort/>
      </Action>
      <Action id="aia-do-nothing">
         <javaAction className="oracle.apps.aia.core.eh.CompositeJavaNo
          Action" defaultAction="ora-rethrow-fault">
            <returnValue value="REPLAY" ref="ora-terminate"/>
            <returnValue value="RETRHOW" ref="ora-rethrow-fault"/>
            <returnValue value="ABORT" ref="ora-terminate"/>
            <returnValue value="RETRY" ref="aia-ora-retry"/>
            <returnValue value="MANUAL" ref="ora-human-intervention"/>
         </javaAction>
      </Action>
      <Action id="aia-ora-java">
         <javaAction className="oracle.apps.aia.core.eh.CompositeJava
          Action" defaultAction="ora-rethrow-fault">
            <returnValue value="REPLAY" ref="ora-terminate"/>
            <returnValue value="RETRHOW" ref="ora-rethrow-fault"/>
            <returnValue value="ABORT" ref="ora-terminate"/>
            <returnValue value="RETRY" ref="aia-ora-retry"/>
            <returnValue value="MANUAL" ref="ora-human-intervention"/>
         </javaAction>
      </Action>
   </Actions>
</faultPolicy>

27.5.7 Using the Message Resubmission Utility API

The Message Resubmission Utility API enables external programs to use the functionality of enabling a message that is in error state to be ready again to be consumed for a transaction. This utility would typically be run after the associated problem that caused the message to end in error is fixed.

For more information about the Resubmission Utility, see "Using the Message Resubmission Utility" in Oracle Fusion Middleware Infrastructure Components and Utilities User's Guide for Oracle Application Integration Architecture Foundation Pack.

27.6 How to Configure AIA Services for Notification

This section discusses the standard configuration steps that must be performed when you are handling a BPEL fault.

This section includes the following topics:

For more information about how to define notification roles, see "Setting Up Error Handling" in Oracle Fusion Middleware Infrastructure Components and Utilities User's Guide for Oracle Application Integration Architecture Foundation Pack.

27.6.1 Defining Corrective Action Codes

For custom or business faults (business faults thrown by a throw activity), define corrective action codes by adding it to AIAMessages.properties file located under <MW_HOME>/soa/modules/oracle.soa.ext_11.1.1/classes folder and restart the server. Ensure that the translated string in the language-appropriate properties file for that language is located in the same directory.

This custom XPath function is available to get details from this resource bundle in a localized format: Signature: aia:getCorrectiveAction (String key, String locale, String delimiter)

Parameter details include:

  • Key

    The corrective action code.

  • Locale

    A concatenated string of language code, country code, and variant. For example, en-US.

  • Delimiter

    The delimiter used in Locale parameter, such as -.

27.6.2 Defining Error Message Codes

For custom or business faults (business faults thrown by a throw activity), define corrective action codes by adding it to AIAMessages.properties file located under <MW_HOME>/soa/modules/oracle.soa.ext_11.1.1/classes folder and restart the server. Ensure that the translated string in the language-appropriate properties file for that language is located in the same directory.

This custom XPath function is available to get details from this resource bundle in a localized format: Signature: aia:getErrorMessage (String key, String locale, String delimiter)

Parameter details include:

  • Key

    The corrective action code.

  • Locale

    A concatenated string of language code, country code, and variant, for example, en-US.

  • Delimiter

    The delimiter used in Locale parameter, such as -.

27.7 Describing the Oracle AIA Fault Message Schema

This section includes the following topics:

The top-level element of this schema is Fault. It has three elements: EBMReference, B2BMReference, and FaultNotification, as shown in Figure 27-5 and Figure 27-6. Fault elements are described in Table 27-1.

Figure 27-5 Fault Element and Its Child Elements (1 of 2)

This image is described in surrounding text

Figure 27-6 Fault Element and Its Child Elements (2 of 2)

This image is described in surrounding text

Table 27-1 Fault Elements

Name Purpose Details

EBMReference

Provides contextual information about the fault instance. All values are taken from the EBM header of the EBM in a faulted service instance.

For more information, see Section 27.7.1, "Describing the EBMReference Element."

B2BMReference

Provides business-to-business (B2B)-specific details when an error is in a B2B flow from Oracle AIA.

For more information, see Section 27.7.2, "Describing the B2BMReference Element."

FaultNotification

Provides actual details of the fault.

For more information, see Section 27.7.3, "Describing the FaultNotification Element."


27.7.1 Describing the EBMReference Element

This section provides details about the EBMReference element in the Oracle AIA fault message schema, as shown in Figure 27-7. EBM Reference elements are discussed in Table 27-2.

Figure 27-7 EBMReference Element and Its Child Elements

This image is described in surrounding text

Table 27-2 EBMReference Elements

Name Purpose

EBMID

Provides the EBMID in the message.

EBMName

Provides the EBMName in the message.

EBOName

Provides the EBOName in the message.

VerbCode

Provides the VerbCode in the message.

BusinessScopeReference

Provides the BusinessScopeReference in the message.

Provides details about the end-to-end scenario in which the faulted service instance was participating.

This is the instance of the BusinessScopeReference in which BusinessScopeTypeCode equals BusinessProcess.

SenderReference

Provides the SenderReference in the message.


For more information about these elements, see Section 26.6, "Introducing EBM Header Concepts."

27.7.2 Describing the B2BMReference Element

This section provides details about the B2BMReference element in the Oracle AIA fault message schema, as shown in Figure 27-8. B2BM reference elements are discussed in Table 27-3.

Figure 27-8 B2BMReference Element and Its Child Elements

This image is described in surrounding text

Table 27-3 B2BMReference Elements

Name Purpose Details

B2BMID

Provides the message ID used to identify the transaction in Oracle B2B.

A user can use this message ID to query for a failed business message in Oracle B2B and retry the failed transaction.

For more information, see Chapter 20, "Introduction to B2B Integration Using AIA."

CollaborationID

Provides the collaboration ID that is common across multiple request-and-response messages related to the same business transaction.

For more information, see Chapter 20, "Introduction to B2B Integration Using AIA."

ReplyToMessageID

Provides the ID of the reply-to message.

For more information, see Chapter 20, "Introduction to B2B Integration Using AIA."

B2BDocumentType/TypeCode

Provides the document type of the failed transaction in Oracle B2B.

This information from the fault can be used to define document-type-specific error processing. For example, you could assign errors resulting from different document types to different users for resolution.

For more information, see Chapter 20, "Introduction to B2B Integration Using AIA."

B2BDocumentType/Version

Provides the document type version of the failed transaction in Oracle B2B.

For more information, see Chapter 20, "Introduction to B2B Integration Using AIA."

SenderTradingPartner/TradingPartnerID

Provides the name of the sending trading partner in the B2B flow.

For more information, see Chapter 20, "Introduction to B2B Integration Using AIA."

ReceiverTradingPartner/TradingPartnerID

Provides the name of the receiving trading partner in the B2B flow.

For more information, see Chapter 20, "Introduction to B2B Integration Using AIA."

GatewayID

Provides the name of the B2B software used to initiate the flow, for example, Oracle B2B.

For more information, see Chapter 20, "Introduction to B2B Integration Using AIA."


27.7.3 Describing the FaultNotification Element

This section includes the following topics:

This section provides details about the FaultNotification element in the Oracle AIA fault message schema, as shown in Figure 27-9. Fault notification elements are discussed in Table 27-4.

Figure 27-9 FaultNotification Element and Its Child Elements

This image is described in surrounding text

Table 27-4 FaultNotification Elements

Name Purpose Details

BusinessComponentID

Unique key for the application.

Provides an agnostic representation of the object instance.

ReportingDateTime

Provides the date and time at which the service faulted.

The date and time at which the service faulted.

CorrectiveAction

Provides the possible corrective action for the fault.

The corrective action for the fault.

FaultMessage

Provides details of the actual fault message.

For more information see Section 27.7.3.1, "FaultMessage Element."

FaultingService

Provides details of the faulting service.

For more information see Section 27.7.3.1, "FaultMessage Element."


27.7.3.1 FaultMessage Element

Table 27-5 discusses fault message elements.

Table 27-5 FaultMessage Elements

Name Purpose Details

Code

Provides the error code.

This is the fault code that was received.

Text

Provides error details.

This describes the details of the fault.

Severity

Provides the severity of the error.

This is the severity of the fault expressed as an integer.

Stack

Provides the error stack.

This is the complete fault stack.

ApplicationFaultData

Enables the fault message to be extended to accept any kind of XML input.

Enables a fault message to be extended to include any kind of XML input, as decided by the implementation scenario.

For more information about extending fault messages, see Section 27.8, "Extending Fault Messages."

IntermediateMessageHop

Captures properties specific to a message in a multi-hop transaction.

Properties that are captured here can be used to support use cases implementing guaranteed message delivery and message recovery.

For more information about implementing guaranteed message delivery and message recovery, see Section 27.5, "Implementing Error Handling and Recovery for the Asynchronous Message Exchange Pattern to Ensure Guaranteed Message Delivery."


27.7.3.2 IntermediateMessageHop Elements

Figure 27-10 illustrates IntermediateMessageHop elements. Intermediate message hop elements are discussed in Table 27-6.

Figure 27-10 IntermediateMessageHop Elements

This image is described in surrounding text

Table 27-6 IntermediateMessageHop Elements

Name Purpose Details

SenderResourceTypeCode

Used for storing the type of resource or system that is the sender of this message in the multi-hopping messaging layer.

Example values of this element are Queue, Topic, or Resequence Store.

SenderResourceID

Provides identification of the resource or system associated with the SenderResourceTypeCode.

Identification of the resource or system associated with the SenderResourceTypeCode.

SenderMessageID

Provides message identification in the context of the resource or system associated with the SenderResourceTypeCode.

Message identification in the context of the resource or system associated with the SenderResourceTypeCode.


27.7.3.3 FaultingService Element

Table 27-7 discusses the FaultingService element.

Table 27-7 FaultingService Element

Name Purpose Details

ID

Provides the date and time at which the service faulted.

This is the name of the faulting service.

ImplementationCode

Provides the possible corrective action for the fault.

This is a string describing the type of service that faulted. Possible values are BPEL, JAVA, and OTHER.

InstanceID

Provides the details of the actual fault message.

This is the instance ID of the faulted service. If the service is a BPEL process, this is the BPEL instance ID.

ExecutionContextID

Provides the value for the ECID.

This is an ID generated for a group of service invocations/executions.


27.8 Extending Fault Messages

This section includes the following topics:

27.8.1 Introduction to Extending Fault Messages

When an error occurs within an integration flow, within a Mediator service or BPEL process, the Error Handling framework captures the error within a fault message. The fault message is made available in the error details within the Oracle BPM Worklist.

For information about using the Oracle BPM Worklist with Oracle AIA error handling, see "Using the Oracle BPM Worklist" in Oracle Fusion Middleware Infrastructure Components and Utilities User's Guide for Oracle Application Integration Architecture Foundation Pack.

Fault message content is defined by the FaultType message schema definition in Meta.xsd, which is located in \EnterpriseObjectLibrary\Infrastructure\V1\Meta.xsd. If your fault message requirements are not met by the default elements of the schema, you can use the ApplicationFaultMessage element included in the schema to extend the scope of the fault details captured in the message.

For more information about the fault message schema, see Section 27.7, "Describing the Oracle AIA Fault Message Schema."

Extending fault details can add functionally rich information to the fault message to help the integration flow consumer better understand the context of the fault, leading to more effective error resolution. These additional fault details can be used to enable extended error handling functionality as well.

For more information about extending error handling, see Section 27.9, "Extending Error Handling."

For example, you can enrich the fault message with Order Number and Fulfillment System values, which are required to perform extended error handling tasks that update Order tables and create new service requests in an Order Fallout Management application.

27.8.2 Extending a Fault Message

Extending a fault message uses the ApplicationFaultData element, highlighted in Figure 27-11, of type xsd:anyType in the FaultType message schema definition in Meta.xsd.

Figure 27-11 ApplicationFaultData Element Highlighted in Meta.xsd

This image is described in surrounding text

The ApplicationFaultData element is populated by a fault extension handler that you will configure to be invoked by the Error Handling Framework at runtime in the case of BPEL faults.

The input to the fault extension handler is the default fault message. The fault extension handler enriches the fault message with additional content defined by the ApplicationFaultData element. Control of the enriched fault message is passed from the fault extension handler to the Error Handling Framework, which then passes the fault message on to the Oracle AIA common error handler for further processing.

To extend a fault message:

  1. Create a fault extension handler that will be invoked to enrich the fault message.

  2. In the Error Extension Handler field on the Error Notifications page, enter the name of the error extension handler that will be invoked to extend the fault message. For example, enter ORDERFOEH_EXT for an Order Fallout error extension handler.

    Based on the combination of error code, system code, service name, and process name parameters, the Error Handling framework checks to determine whether the error extension handler has a nondefault parameter defined.

    If so, the framework locates the full classpath for the parameter in the AIAConfigurationProperties.xml file and makes a call out to that handler with the base fault message as input.

    Within this error extension handler, the fault message will be enriched to accommodate custom content. It will then be sent back to the Error Handling framework for further processing.

    For more information about the Error Notifications page, see "How to Set Up AIA Error Handling Configuration Details" in Oracle Fusion Middleware Infrastructure Components and Utilities User's Guide for Oracle Application Integration Architecture Foundation Pack.

  3. Access the AIAConfigurationProperties.xml file in $AIA_HOME/aia_instances/$INSTANCE_NAME/AIAMetaData/config. Define a property name that matches the error extension handler name that you defined in step 2, as shown in Figure 27-12. The value for this property is the fully qualified class path of the handler.

    Figure 27-12 Example Error Extension Handler Property and Value in AIAConfigurationProperties.xml

    This image is described in surrounding text

    It is through this class that the extension; Order Number and Fulfillment System values, for example; are added to the fault message using xsd:anyType in the ApplicationFaultData element in Meta.xsd.

  4. Implement the IAIAErrorHandlerExtension interface in your error extension handler class registered in AIAConfigurationProperties.xml. Implement these methods:

    • handleCompositeSystemError for BPEL system errors

    • handleBusinessError for BPEL custom errors

    Example 27-18 and Example 27-19 illustrate the interface structure.

    Example 27-18 IAIAErrorHandler Interface Class

    public interface IAIAErrorHandler
    {
      /**
        *
        * @param ebmHeader
        * @param faultMessage
        */
      public void logErrorMessage(Element ebmHeader, String faultMessage);
    
      /**
        *
        * @param XMLELfaultMessage
        */
      public void logErrorMessage(XMLElement XMLELfaultMessage);
    
      /**
        *
        * @param ebmHeader
        * @param faultMessage
        */
      public void logErrorMessage(Node ebmHeader, String faultMessage);
    
      /**
        * @since FP 2.3
        * @param faultMessage
        * @param jmsCorrelationID
        */
      public void sendNotification(String faultMessage, String jmsCorrelationID,
                                                 HashMap compositeDetailsHM);
    }
    

    Example 27-19 IAIAErrorHandlerExtension Interface Class

    package oracle.apps.aia.core.eh;
    public interface IAIAErrorHandlerExtension
    {
      /**
       *
       * @param iFaultRecoveryContext
       * @param faultMessageConstructed
       * @param componentType
       * @return
       */
      public String handleCompositeSystemError(IFaultRecoveryContext iFaultRecoveryContext,
                                               String faultMessageConstructed,
                                               String componentType);
    
    
      /**
       *
       * @param faultMessageConstructed
       * @return
       */
      public String handleBusinessError(String faultMessageConstructed);
    }
    

    You can view extended field values in the error logs accessed in Oracle Enterprise Manager.

    For more information about viewing error logs in Oracle Enterprise Manager, see "Using Trace and Error Logs" in Oracle Fusion Middleware Infrastructure Components and Utilities User's Guide for Oracle Application Integration Architecture Foundation Pack.

    You should also be able to view them in email notifications if they have been configured appropriately.

    For more information about customizing error notifications, see "Customizing Error Notification Emails" in Oracle Fusion Middleware Infrastructure Components and Utilities User's Guide for Oracle Application Integration Architecture Foundation Pack.

27.9 Extending Error Handling

This section includes the following topics:

This section provides an overview of error handling extension and discusses how to implement an error handling extension.

27.9.1 Introduction to Extending Error Handling

The default error handling behavior for BPEL and Mediator errors is to route fault messages to the Oracle AIA common error handler, which logs the error and delivers the fault messages to the Oracle AIA error topic. The default Oracle AIA error listener subscribes to this Oracle AIA error topic, picks up the fault message, and calls the error notification process, which issues a notification to the Oracle BPM Worklist if configured to do so.

For information about using the Oracle BPM Worklist with Oracle AIA error handling, see "Using the Oracle BPM Worklist" in Oracle Fusion Middleware Infrastructure Components and Utilities User's Guide for Oracle Application Integration Architecture Foundation Pack.

You can extend the Error Handling Framework to perform actions beyond these default behaviors.

For example, you may want a particular error to trigger default error-handling behavior, in addition to extended error handling behavior, such as updating a table and creating a new request in an application.

To implement an error-handling extension, extend fault messages to provide additional values.

For more information about extending fault messages, see Section 27.8, "Extending Fault Messages."

27.9.2 Implementing an Error Handling Extension

To implement an error handling extension:

  1. On the Error Notifications page, enter an Error Type field value for an error code, system code, process name, and service name value combination.

    For more information about the Error Notifications page, see "How to Set Up AIA Error Handling Configuration Details" in Oracle Fusion Middleware Infrastructure Components and Utilities User's Guide for Oracle Application Integration Architecture Foundation Pack.

    The Error Handling Framework uses the Error Type value to stamp the JMSCorrelationID JMS header. The JMSCorrelationID is used by the custom error listener to identify fault messages that require its custom error handling.

  2. Implement an error extension listener to subscribe to the Oracle AIA error topic.

    Configure an error extension listener to filter fault messages based on the JMS Header - JMSCorrelationID value defined by the error type you created in step 1.

For example, you can create an Order Fallout error extension listener that picks up fault messages with the JMSCorrelationID value of ORDER_FO. For this example the Error Type field value defined on the Error Notifications page in step 1 should be ORDER_FO.

The Order Fallout error extension listener can then extract values from the fault message, extended to include Order Number and Fulfillment System values, for example. The error extension listener can then pass those values to an Order Fallout Management application, for example, which can use those values to update Order tables and create new service requests.

The extended error handling flow is illustrated in Figure 27-13.

Figure 27-13 Sample Extended Error Handling Flow Alongside a Default Error Handling Flow

This image is described in surrounding text

27.10 Configuring Oracle AIA Processes for Trace Logging

This section includes the following topics:

These custom XPath trace logging functions are available to BPEL and Mediator services operating in an Oracle AIA ecosystem.

  • aia:isTraceLoggingEnabled(String logLevel, String processName)

    Determines whether trace logging is enabled for the service or at the overall system level.

  • aia:logTraceMessage(String level, Element ebmHeader, String message)

    Generates the actual trace log.

When developing a BPEL or Mediator process, always call the aia:isTraceLoggingEnabled() function first. If it returns a true result, then have the process call the aia:logTraceMessage() function.

These log files are stored in the <aia.home>/logs/ directory.

In addition to these custom XPath functions, a Java API is also available so that any application developer can use it to log trace messages.

For more information about using trace logs, see "Using Trace and Error Logs" in Oracle Fusion Middleware Infrastructure Components and Utilities User's Guide for Oracle Application Integration Architecture Foundation Pack.

27.10.1 Describing Details of the isTraceLoggingEnabled Custom XPath Function

The isLoggingEnabled custom XPath function is a utility function that returns a Boolean result. The function signature is: aia:isTraceLoggingEnabled (String logLevel, String processName)

These are the parameter details:

  • logLevel

    Possible values include:

    • Severe

    • Warning

    • Info

    • Config

    • Fine

    • Finer

    • Finest

  • processName

    Name of the Oracle AIA service using this function.

27.10.2 Describing Details of the logTraceMessage Custom XPath Function

The logTraceMessage custom XPath function generates a trace message, which contains the details of the message to be included in the trace log.

This function accepts the EBM header and the verbose logging message as parameters. Various elements from the EBM header are used to populate supplemental attributes to the log message. If the EBM header is not passed, these supplemental attributes are set as empty strings.

The function signature is aia:logTraceMessage (String level, Element ebmHeader, String message). These are the parameter details:

  • level

    Possible values include:

    • Severe

    • Warning

    • Info

    • Config

    • Fine

    • Finer

    • Finest

  • ebmHeader

    EBM header.

  • message

    Verbose text message to be logged.

27.10.3 Describing the Trace Logging Java API

In addition to the isTraceLoggingEnabled and logTraceMessage custom XPath functions, a trace Logging Java API is also available so that any application developer can log trace messages. These functions are available through the trace logging Java API.

One of the function signatures is AIALogger.isTraceLoggingEnabled (String logLevel, String processName). This function determines whether trace logging is enabled for the service or at the overall system level. These are the parameter details:

  • logLevel

    Possible values include:

    • Severe

    • Warning

    • Info

    • Config

    • Fine

    • Finer

    • Finest

  • processName

    Name of the Oracle AIA service using this function.

Another function signature is AIALogger.logTraceMessage (String level, Element ebmHeader, String message). This function generates the actual trace log. These are the parameter details:

  • level

    Possible values include:

    • Severe

    • Warning

    • Info

    • Config

    • Fine

    • Finer

    • Finest

  • ebmHeader

    EBM header.

  • message

    Verbose text message to be logged.