In Action: Adapter Rejection Handlers in Oracle BPEL

In Oracle BPEL you can use several types (e.g. file, JMS or Oracle AQ) of technology adapters to activate a bpel process. This is done by using a BPEL receive task on a adapter partner link that is that actually is polling a file directory for specific files or is listening on a JMS or Oracle AQ queue for inbound messages. In most cases the inbound message or file contains XML structured data or data that needs to be translated to a custom native XML structure. In both cases the data must cohere to a defined structure otherwise the data cannot be translated to the XML type of the variable that the bpel process will use the store the message for later use. But what if the data doesn't cohere to the structure?

The adapter will reject malformed messaged and will log a message and will store the rejected message in a default folder. In the BPM console you don't see any indication that a message has been rejected by the inbound adapter. So this is not very convenient for a production environment. The use of rejection handlers makes it possible to handle rejected messages in a proper way. A rejection handler must defined in bpel.xml with a adapter activation agent and only works for inbound bpel receive operations. Rejection handlers come in for different flavors:

• File based


• Oracle AQ based


• BPEL process rejection handler


• WSIF based

In this posting I will only discuss the BPEL process rejection handler. Please look here here for more information about the other three flavors.
To use a bpel process rejection handler you have to define a bpel process that takes an input message of type RejectedMessage. Like:

<message name="RejectionMessage">

<part name="message" element="err:RejectedMessage">

</part>
</message>

The schema for this type is in the rejectionmessage.wsdl file in the xmllib directory. In the wsdl file of your BPEL process you can just import this wsdl file and the appropriate partnerlink. E.g.

<definitions xmlns="http://schemas.xmlsoap.org/wsdl/" bpws="http://schemas.xmlsoap.org/ws/2003/03/business-process/" plnk="http://schemas.xmlsoap.org/ws/2003/05/partner-link/" tns="http://xmlns.oracle.com/pcbpel/rejectionHandler" xsd="http://www.w3.org/2001/XMLSchema" name="RejectionMessage" targetnamespace="http://xmlns.oracle.com/pcbpel/rejectionHandler">
  <import location="http://genomw01:7777/Artifacts/RejectionMessage.wsdl" namespace="http://xmlns.oracle.com/pcbpel/rejectionHandler">
  <plnk:partnerlinktype name="RejectionHandlerPortType_PL">
      <plnk:role name="RejectionHandlerPortType_Role">
          <plnk:porttype name="tns:RejectionHandlerPortType">
      </plnk:porttype>
  </plnk:role>
</plnk:partnerlinktype>

In this example BPEL wsdl definition file you can see that the wsdl is imported (a project copy is used here) and that RejectionHandlerPortType is referenced here.

In the RejectionHandler process you have now access to the rejection reason, payload of the reject message and many more useful attributes to show a proper error message to an administrator. For example, you can use your custom Error Hospital for further processing.

The final things you have to do to make things work is adding an rejection handler property to the adapter activation agent in the bpel.xml file. E.g:

<activationagents>
    <activationagent classname="oracle.tip.adapter.fw.agent.jca.JCAActivationAgent" partnerlink="DEQUEUE_DCS731_B2B_IP_IN_QUEUE">
      <property name="portType">Dequeue_ptt</property>
      <property name="rejectedMessageHandlers">bpel://default|JCARejectionHandler|handleRejection|message</property>
    </activationagent>
</activationagents>

Just applying some small steps you are able to add more robustness to you inbound adapters so that malformed rejected message will eventually reach the system administrator that can decide how to deal with them. This sounds more convenient than scanning log files for possible rejected messages :)