10 Migrating and Configuring Error Handling Artifacts

This chapter describes how to migrate and configure Oracle AIA Error Handling artifacts.

You may need to migrate fault policies or error handling services developed using AIA 2.4 or 2.5. Since there is no utility to support migration of error handling artifacts, this task must be performed manually.

For information about error handling, see "Introduction to Oracle AIA Error Handling" in Oracle Fusion Middleware Infrastructure Components and Utilities User's Guide for Oracle Application Integration Architecture Foundation Pack.

This chapter includes the following sections:

10.1 How to Migrate Fault Policies

AIA Foundation Pack provides a default fault policy that is stored in MDS in the folder AIAMetaData/faultPolicies/V1. When default fault policies are used in a process, you must add the following elements to the composite.xml file:

<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>

If custom fault policies are used in AIA 2.4 and 2.5, then follow these steps to update them to AIA Foundation Pack 11g Release 1.

  1. Consider a sample custom fault policy file. Example 10-1 shows how to associate fault policies defined in this sample fault-policy file with a fault-policy binding.xml file. These two files should be placed in the composite process folder.

    Example 10-1 Sample QueryCustomerPartyPortalProvABCSImplFaultPolicy.xml with Fault Policies Defined

    <faultPolicies xmlns="http://schemas.oracle.com/bpel/faultpolicy">
   <faultPolicy version="2.4" id="SamplesQueryCustomerPartyPortalProvABCSImpl
    FaultPolicy" . . . . . . . . >
   </faultPolicy>
</faultPolicies>

    Within the Java action, change the name of the java class from BPELJavaAction to CompositeJavaAction. There is no change in the package structure.

    oracle.apps.aia.core.eh.CompositeJavaAction

    Similarly, if any aia-no-action is used to suppress notifications, then the corresponding name of the Java class should be changed from BPELJavaNoAction to CompositeJavaNoAction. Again, there is no change in the package structure.

    oracle.apps.aia.core.eh.CompositeJavaNoAction

  2. Associate the policies defined in the preceding fault policy file with the level of fault policy binding you are using. AIA recommends that you set this at the SOA composite level.

  3. To do this, modify the template fault-bindings.xml file.

  4. In the fault-bindings.xml file, perform the association as shown in Example 10-2.

    Example 10-2 fault-bindings.xml File

    <faultPolicyBindings version="2.4"xmlns=http://schemas.oracle.com/bpel/
 faultpolicyxmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <composite faultPolicy="SamplesQueryCustomerPartyPortal
    ProvABCSImplFaultPolicy"/>
</faultPolicyBindings>

For more information about the 11g fault-policies file and the schema for fault-bindings.xml, 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.

In 11g Mediator, fault policies are similar to BPEL fault policies and the corresponding Java class is also the same, for example, CompositeJavaAction.

For more information about Mediator fault policies, see "Fault Policies" in Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

For more information about the Mediator fault-policy schema file, see "Schema Definition File for Fault-policies.xml" in Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

10.2 How to Configure Transaction Configurations

For information, see "Enabling Transactions" in Oracle Fusion Middleware Developer's Guide for Oracle Application Integration Architecture Foundation Pack.

10.3 How to Configure AIAConfigurationProperties.xml for Error Handling

In AIA 2.4 and 2.5, and in AIA Foundation Pack 11g Release 1, the AIAConfigurationProperties.xml file contains settings related to AIA Error Handling. Table 10-1 provides a summary of the new settings introduced with AIA Foundation Pack 11g Release 1.

Table 10-1 AIA 11g Release 1 ConfigurationProperties.xml for Error Handling

Setting Values Meaning

EH.INVOKE.HWF

false | true

Enable/Disable creation of tasks in the worklist application.

EH.INVOKE.NOTIFY

false | true

Enable/Disable sending error notifications.

EH.AGGR.NOTIFY

false | true

Enable/Disable throttling.

FROM.EMAIL.ID

Email address. For example:

AIA_EH@oracle.com

Sender Email address for error notifications. Note that the email server may deny notifications if the sender email address is not accepted by the email server, for example, if the email domain does not match.

EH.DEFAULT.ACTOR.ROLE

User Name. For example:

AIAIntegrationAdmin

Actor user name. Note that this is a user name and no longer a role, as in AIA 2.4 and 2.5.

EH.DEFAULT.FYI.ROLE

User Name. For example:

AIAIntegrationAdmin

For your information (FYI) user name. Note that this is a user name and no longer a role, as in AIA 2.4 and 2.5.

10.4 How to Migrate the Error Notification Setup

To migrate the Error Notification Setup from an AIA 2.4 or 2.5 environment to a new AIA Foundation Pack 11g Release 1 environment, you must review all custom notification records and manually duplicate these entries in the new AIA Foundation Pack 11g Release 1 environment. The Error Notification page can be accessed by clicking the Go button in the Setup area of the AIA Home Page.

There is no functional difference for the record attributes that existed in AIA 2.4 and 2.5. The new attributes relate to error notification throttling and default when entering new records. There is no need to change these values if the throttling feature is not required.

For more information about error notification throttling, see "Using Error Notifications" in Oracle Fusion Middleware Infrastructure Components and Utilities User's Guide for Oracle Application Integration Architecture Foundation Pack.

10.5 How to Configure the Oracle User Messaging Service for Email Notifications

To enable and configure email messaging:

  1. In Oracle Enterprise Manager, select the SOA infrastructure and open the context menu SOA Administration and Workflow Notification Properties. Set Notification Mode to Email, click Apply, and then click Go to the Messaging Driver page.

  2. On the Messaging Driver page, click the Configure Driver button for the User Messaging Email Driver. Provide a valid value for the OutgoingMailServer property, such as mail.oracle.com, and enter any other settings that are relevant for your environment.

  3. Restart the SOA server for the changes to take effect.

For more information about configuring the Oracle User Messaging Service, see "Configuring Oracle User Messaging Service" in Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite.

10.6 How to Configure User Email Addresses

To configure user email addresses:

  1. Open the User Messaging Preferences UI located at http://<server>:<port>/sdpmessaging/userprefs-ui.

  2. Log in as the user who is supposed to receive error notifications, such as AIAIntegrationAdmin.

  3. Create a new default messaging channel of type EMAIL, and assign the email address to which notifications will be sent.

10.7 How to Migrate Custom Error Handlers

Similar to AIA 2.4 and 2.5 Error Handling, AIA Foundation Pack 11g Release 1 Error Handling allows you to implement a custom error handler to extend the default capabilities of the AIA Error Handler. For example, it allows you to add further details to the fault payload.

Note a few key changes made to the custom error handler:

  • Implements handleCompositeSystemError as opposed to handleBPELSystemError in AIA 2.4 and 2.5.

  • Handles errors for BPEL and Mediator components within composites.

  • Distinguishes component types (BPEL and Mediator) and responds accordingly.

  • Code changed to provide access to runtime variables. Specifically, see the reference to getVariableData in Example 10-3.

For your reference, Example 10-3 provides a code sample from the AIA Foundation Pack Demo available on Oracle Technology Network at http://oracle.com/technetwork.

Note the highlighted area to understand the differences between AIA Foundation Pack 11g Release 1 and 2.4 and 2.5 implementations, and make modifications accordingly to your subscriber code.

Example 10-3 Sample Code from the AIA Foundation Pack Demo Implementation

package oracle.apps.aia.demo;
import oracle.integration.platform.faultpolicy.IFaultRecoveryContext;
 
import com.collaxa.cube.engine.fp.BPELFaultRecoveryContextImpl;
import com.collaxa.cube.engine.types.bpel.CXMessageVariable;
import oracle.apps.aia.core.eh.IAIAErrorHandlerExtension;
import oracle.apps.aia.core.eh.logging.AIALogger;
 
public class AIADemoErrorHandlerExtImpl implements IAIAErrorHandlerExtension
{
  public AIADemoErrorHandlerExtImpl()
  {
  }
 
  public String handleBusinessError(String faultMessageConstructed)
  {
    return faultMessageConstructed;
  }
 
public String handleCompositeSystemError(
IFaultRecoveryContext iFaultRecoveryContext,
        String faultMessageConstructed,
        String componentType )
{
    String enrichedFaultMessageConstructed = faultMessageConstructed;
    
    if ( componentType.equals("bpel") )
    {
      try
      {
        BPELFaultRecoveryContextImpl bpelCtx =
          (BPELFaultRecoveryContextImpl) iFaultRecoveryContext;
        CXMessageVariable bpelVar =
          (CXMessageVariable) bpelCtx.getVariableData("AIADemoProcess
           CreditChargeAuthorizationReqMsg");
        if (bpelVar != null)
        {
          String ebmPayload = bpelVar.toXML();
          enrichedFaultMessageConstructed =
              faultMessageConstructed.replaceFirst("<IntermediateMessageHop>",
                                                   (new StringBuilder()).
append("<InputPayLoad>").append(ebmPayload).append("</InputPayLoad><Intermediate
MessageHop>").toString());
        }
      }
      catch (Exception ex)
      {
        ex.printStackTrace();
        AIALogger.logErrorMessage(null, ex.getLocalizedMessage());
      }
    }
    else if( componentType.equals("mediator") )
    {
      //do your mediator custom error handling..
      //This block gets triggered only in case parallel routing rules 
are enabled.
    }
 
    return enrichedFaultMessageConstructed;
  }
}

Detailed Steps

  1. Compile your code by including the following jar files in your project or from ant task.

    <AIA_HOME>/lib/aia.jar
${mw.home}/jdeveloper/soa/modules/oracle.soa.bpel_11.1.1/orabpel.jar
${mw.home}/wlserver_10.3/server/lib/weblogic.jar

  2. Once you have your jar file constructed, compile the custom classes, for example AIADemoErrorHandler.jar.

    Extract the contents to ${mw.home}/Oracle_SOA1/soa/modules/oracle.soa.ext_11.1.1/classes folder.

  3. Restart the SOA managed server for the extension to work.

    Make sure that your AIA Error notification rules have the custom listener stamp setup which is the same as that in 10g.

    Note that the table name changed from BSR_ERROR_NOTIFICATIONS to AIA_ERROR_NOTIFICATIONS.

10.8 How to Migrate Custom Subscribers

The migration of custom subscribers to the AIA_ERROR_TOPIC that was implemented to pick up fault messages for further processing depends on how the subscriber was implemented in AIA 2.4 and 2.5/Oracle SOA Suite 10g.

Assuming that the subscriber was implemented as either a BPEL- or ESB-based process leveraging a JMS adapter, the usual technical migration applies as for any other AIA service.

It is essential to ensure that the JMS adapter configuration located in the JCA file is adjusted to point to the correct JNDI name of the AIA error topic and the connection factory in AIA Foundation Pack 11g Release 1. Note that these names have changed since AIA 2.4 and 2.5. See Example 10-4, which is a sample JCA file from the AIA Demo, to understand the relevant properties in bold and their correct settings.

Example 10-4 Sample JCA file from the AIA Demo

<adapter-config name="AIADemoErrorJMSListener" adapter="Jms Adapter" 
 xmlns="http://platform.integration.oracle/blocks/adapter/fw/metadata">
   <connection-factory location="eis/jms/aiaErrorTopicCF" UIConnectionName=
    "dev_soa_server" UIJmsProvider="WLSJMS" adapterRef=""/>
   <endpoint-activation portType="Consume_Message_ptt" operation="Consume_
    Message">
      <activation-spec className="oracle.tip.adapter.jms.inbound.
       JmsConsumeActivationSpec">
         <property name="DestinationName" value="jms/aia/aiaErrorTopic"/>
         <property name="UseMessageListener" value="false"/>
         <property name="MessageSelector" value="JMSCorrelationID = 
          'AIADEMO_CREDITCARD_FAILURE'"/>
         <property name="PayloadType" value="TextMessage"/>
      </activation-spec>
   </endpoint-activation>
</adapter-config>

In 11g, AIA Error Topic JMS infrastructure is moved from AQ implementation to that of WebLogic JMS (default behavior). WLS JMS can be configured to use any foreign JMS server or use database as persistent point for the JMS resource configured. As delivered, Foundation Pack configures it as file based artifact.

The custom listener stamping logic and enrichment extension handler in 10g is applicable for 11g with the changes mentioned above.