Fault and Business Exception Handling in Oracle BPM Suite 11g

A few months back I had blogged about some advanced Fault Handling concepts that can be implemented in Oracle SOA Suite 11g by leveraging the in build policy based fault framework, using custom JAVA Action to implement a fault condition and the use of SOA Suite API’s to retry them.

The full blog post can be read here

Unfortunately the same policy based fault management cannot be used for components in a composite application that are based on BPMN. The same policy based fault management will be available in some future versions of Oracle BPM Suite.

This article will try to explain how we can have a fault and exception handling defined for a BPM process in our composite application.

Consider a very basic BPMN process to approve the credit application for an individual. The process is exposed as a web service with an asynchronous callback. It takes the applicant’s Social Security Number and processes the credit approval process for him.

The business process take the applicant’s SSN and retrieves his credit history from a web service interface. The details of his credit history are presented to a credit approval clerk who can either approve or reject it. Upon rejection the process throws a custom business exception and is terminated. If the credit approval clerk approves the application the process is ended gracefully. Quite simple. So let us get started.

The following visio diagram explains the simple use case et all.

image

The above process needs to have a runnable implementation. We can design and deploy the same process in Oracle JDeveloper. The process inside JDeveloper looks like this.

image

Use the XML Schema below to create a Business Object called PersonalInformation inside the BPM Business Catalog. The business process is instantiated with a message start event. Use this business object as the input argument for the Start event.

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.soatechnologies.blog/pi" targetNamespace="http://www.soatechnologies.blog/pi" elementFormDefault="qualified">
<xsd:element name="ApplicantInformation">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="firstName" type="xsd:string"/>
<xsd:element name="lastName" type="xsd:string"/>
<xsd:element name="ssn" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="CreditApprovalResponse">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="creditRating" type="xsd:string"/>
<xsd:element name="isDefaulter" type="xsd:boolean"/>
<xsd:element name="noOfDefaults" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>

Add a variable called applicationInformation of type Process Data Object and assign the value of the input argument to it.

image

The complete JDeveloper project can be downloaded from the link here. Import it and see how the rest of the process has been created.

The Get Credit History service task in the project has a boundary event attached to it.

Boundary events can be of Error, Timer or Message type and are triggered if the activity to which they are attached is not yet completed. They are very useful for Exception and Interruption Handling.

Our process in this example uses an Error Boundary Event that catches Remote Fault for the service task i.e for instance faults arising out of remote endpoint being unavailable.

You can even attach a Timer Boundary Event to any activity or SubProcess. If the activity or the Subprocess doesn’t complete within the Time defined in the timer event, the process triggers in the direction to which the boundary event is wired.

image

The wire from this Error Boundary Event is drawn to the Handle Service Remote Fault Subprocess that introduces a wait and loops it back to the Service Task. Doing this ensures that if an error occurs due to service unavailability the process retries by itself before terminating.

The number of retries can be controlled by defining a counter for the Service task and adding an exclusive gateway in the Remote fault Handling Subprocess.

image

Once the activity has been retried for the maximum number of allowed time the process is terminated.

image

Another thing that every BPM process needs to have is define and handle Business Faults.

Business Exceptions can be defined in the Business Catalogue component inside a BPM project.

imagen

Business Exceptions created thus can now be thrown from the process if in case any business scenario fails to meet. In the present example let us throw an ApprovalException if the approval clerk rejects the credit application request.

This can be achieved by throwing and catching Intermediate Events inside the process flow. Drag an Error Event of type Error from the BPM Component Palette in the process canvass.

The Check Manual Response gateway evaluates the response of the approval clerk and forks the process into two paths. Connect the sequence that evaluates to a “REJECT” outcome to this error event.

image

Now that we have thrown a custom business exception we need to define a way in our process to catch and handle it.

In Oracle BPM 11g we can create Event Subprocesses that are invoked when an Event that they are listening to are thrown.

You can drag an Event Subprocess from the Activities pane of the BPM Component Palette. The event trigger for start event of the Event sub process is changed to “Error” which means it would Catch an Error event to initialize its flow. From the list of Exceptions select the custom business exception that was just created.

image

The Event Subprocess is in itself a mini process having its own Start, End and intermediate activities. Depending upon preference we can choose to either create a Manual Task to allow user to take a look at the Custom Exception and may be handle it offline.

Service Activities to log the exception record to File/DB or JMS can also be used or we can simple choose the FYI Task to notify users.

image

Similarly create another Event Subprocess that catches all other exceptions inside the process (something like a Catch All branch)

image

The basic process design and fault handling is complete now. Deploy this composite application now on a running SOA Server where we will run a few scenarios to validate whether the process behaves as expected.

Scenario 1 : Application is Rejected by Approval Clerk

The CreditApproval business process has a message start event. It can be invoked as a webservice. To test it as a webservice we can login to the EM console, locate the composite application in the partition where we deployed it and test it.

image

The composite instance lands up in the Running state as it is waiting in the inbox of the approval clerk. Login to the custom worklist application and reject the instance.

As we have designed the process to throw and catch a custom business exception in case an application is rejected the process instance during runtime does exactly that.

image

The business exception is caught and thrown by the Event Sub process. See the process instance flow to see how the instance completes its execution.

image

Scenario 2 : The Get Credit History web service is Unavailable

If you recall we had added a Boundary event to the Service Task. The boundary event will catch Remote Fault (if any) occurring in the service task activity and call the subprocess to decide whether a retry is needed or not. The maximum retry limit is set to a constant value of 3 here. Depending upon the number of times the Service Task has been invoked the subprocess either loops the instance back to the service task activity or terminates it (in case Retries are exhausted)

image

If the end point doesn’t come up within the defined retries the process terminates.

image

On the contrary if the Web Service endpoint become available the process instance is completed.

image

This article demonstrates a basic fault handling approach that can be employed while designing business processes in Oracle BPM Suite 11g.

All the artifacts used in this article can be downloaded from here.

.

55 thoughts on “Fault and Business Exception Handling in Oracle BPM Suite 11g

  1. The complete JDeveloper project can be downloaded from the link here. It is a different project use of complex gateway. The project is not related to the example specified here. Try to upload the example fault handling project explained above. Is is very useful for me, if you uploaded above example project please….

    Like

  2. The complete JDeveloper project can be downloaded from the link here. The link specified here is different different project, use of complex gateway. The project is not related to the example specified here. Try to upload the example fault handling project explained above. Is is very useful for me, if you uploaded above example project please….

    Like

  3. I need a help here in the example. In business exception handler (script task), how can we design the manual user task or fly user task, so that the exception can be directly shown to the user when the process is running. Otherwise the process will terminate when the exception occurred. If you tell with the screen shots or any example if you upload. It is very useful for me.

    Like

    • Hi Narsimhulu,

      I am afraid i didnt fully understand your exact requirement. However let me try to explain.

      If you have unhandled or unchecked exceptions in your process flow it will eventually terminate.

      However you can catch defined and undefined exceptions using Event Subprocesses or Subprocesses as shown in this post.

      Subprocesses are mini processes in themselves that have their own start and end events. You can create a Manual Task inside
      a subprocess that gets invoked due to an error where the error context can be viewed by a process user.

      However in the current version of BPM Suite 11g the user cannot route the task to a previos activity. So there is little that you can
      acheive here.

      Let me know if this helps or probably put in your exact requirement so that i can comment.

      Like

      • Hi arun,

        Thanks for replying . My requirement is, Suppose user submitted the form by filling the relevant details and next step, data is stored in the database (DB Service) or stored using webservice. While storing something goes wrong in the BPM_SOA_server (either database connectivity problem, service object is not assigned ,…..etc), how can i catch the exception and notifying the exception to the corresponding user, using user task form (handling the exception), so that the process cannot be terminated when the exception occurs. How can i validate the user task form fields .( ex: suppose user has to enter the value between 1 to 1000, if he/she enter other than this values, i should not allow the form to continue even though, he/she submits and showing as an error, has to enter the data between 1 to 1000).

        Like

        • Depending upon preference we can choose to either create a Manual Task to allow user to take a look at the Custom Exception and may be handle it offline.

          Service Activities to log the exception record to File/DB or JMS can also be used or we can simple choose the FYI Task to notify users. How can i will do this, explained in the

          post.

          Like

        • Hi,
          Oracle BPM Suite 11g doesn’t have an OOTB error handling that allows you to retry from the point of failure. I am sure this feature will be there shortly. For now even if you create a Manual Task in case of errors, it can notify a set of users about the type and nature of fault and also allow him to act on it.

          In the blog post i have show how you can handle Remote faults automatically. These are exceptions that generally arise when there are connectivity problems, network downtime, endpoints not available etc. If you are using JCA Adapters you can even configure your adapters to retry by using the jca.retry property.

          Coming to your second question about validation of form fields. Oracle BPM Suite 11g allows you to create auto generated UI components based on ADF for a human task. You can write your own form validation logic in the ADF UI project if you have to. However the ADF UI is generated based on the in and out payload (XML or native) for a human task. So for example if the input to a human task is an xml element defined with a schema type then your task form at runtime will make those fields mandatory that are defined with minOccurs=”1″ in your schema.

          Like

            • What i meant is like this.
              Supposedly you create a Task based on a task payload defined by an xml schema. And imagine the schema has an element defined as under

              This means that when a UI component is generated in ADF for this task the input field for Order Id will be mandatory.

              For custom validations you can open the ADF project of your UI and add them there.

              Like

  4. Great post, congratulation.

    But supposing that we have one human task and during its execution, one error (unanticipated) occurs on UI screen. Can I retrieve this process instance anyway?

    Regards,

    Diovani

    Like

  5. Hi Diovani,

    Oracle BPM Suite 11g is not stateless. It stores all instance data in the SOA_INFRA schema which is also referred to as
    the dehydration store.

    Whenever the process hits a checkpoint activity like wait,manual task,event etc the process instance is hydrated in the database and
    its last successful state is stored.

    So if you have a bpm process that has a manual task and something goes wrong on the UI screen the instance will still remain in the
    user’s worklist.

    Like

  6. Is there any possible way to send the notification email to the next user accessing the role tasks. he should not enter any email address,it has to go automatically to next user (“my task is over to continue you task in the bpm process.”). Like wise, can able to send next users in the complete process based on role assigned.

    Like

  7. I am unable to get the some of the types (binary, component) in the Project Data Objects. I dont know how to set the new project data object as component. I saw in the above example project, defined project data objects. Component types in the project data objects are shown in red mark colour. How can i will do ?

    Like

  8. In the em console, each process under SOA (Soa_Infra) composite , test option is disabled. Is there any way to enable it. SOA version is 11.1.1.4.0.

    Like

  9. For a human task flow details form, comments and attachments are added for the parent process (first human workflow page form), and they are propagated to the next human task pages. But other human task forms comments and attachments are not able to attach directly. Using process tracking we can able to add comments and attachments to the parent page. Is there any way to add comments and attachments in every page directly, which can be propagated to the next pages (so that next users can able to get the comments and attachments).

    Like

  10. Exception message has to be shown in the user task form as an alert message in the process or in the human task before going to next process. Just tell me the solution with sample screen shots as shown in the blog or just show the screen shots of complete User task ( Parameters to alert the exception message, data associations which contain exception message). If you provide this information, very helpful for me to handle any type of exceptions using human task (FLY User or manual user task) inside the event sub process.

    Like

    • Do the following to achieve what you are looking for.

      Create a Custom Fault Schema that may contain fault information, instance metadata information and business data.
      Create a Business Object of type Business Exception in the Business Catalog of your project and assign the above schema as its type.
      Now you can catch faults by either using boundary events or catch error events. Draw a wire from either the boundary event or the catch error event to a Throw Event that throws the custom Business Exception you created.

      Also remember fault information is available through custom XPath functions like ora:getFaultName and ora:getFaultAsString

      You can then have an event sub process to that has a Catch Exception start node to catch the business exception and have a Manual Task Activity. The input to the manual Task service can be your exception data. When you create a UI for the User Task it would present the fault data to the user who can then act on it.

      Like

  11. Hi arun, i created two business objects. Each business object contain one arraylist component as attribute. In a human taskflow form, created a dropdown using payload for the first business object. similarly created a one more dropdown list for the second business object using payload. When i will select the first dropdown one of the value, the second drop down automatically refresh based on selection and has to show only the corresonding values. I did the following for getting page refresh. The first dropdown made the autosubmit = “true”, second dropdown add partialtrigger = id of first dropdown. After deploying the application, when i will select the first drop downlist value. I am getting the following error on the form

    Error: Cannot create an object of type:oracle.jbo.RowIterator from type:java.lang.String with value

    I am unable to solve this, will you provide solution for this.

    Like

    • The above error is solved, but while select the first dropdown (project list) of any project, it will refresh automatically the second dropdown (project activity list) based on partial trigger and point to the first activity of corresponding project. Eventhough it points to the corresponding activity, it will have other project activities in the second dropdown list, according to my requirement it should not be there. When i will select a project in the first dropdown, it has to show corresponding activities in the second dropdown. I used select one choice to display the dropdown. The following way, i did dropdown for displaying in the .jspx page of human taskflow page

      Just suggest me to how can will get the required one.

      Like

  12. Hi Arun,

    I have a catch all event sub process to call all other process exception. how do i capture the error details from this catch all so i can display it to the user. when i create a custome business exception, i get an error details i needed.

    Like

  13. Hi Arun,

    I have a catch all event sub process to call all other process exception. how do i capture the error details from this catch all so i can display it to the user. when i create a custome business exception, i get an error details i needed. So i need a similar error details when i select catch all sytstem abd business errors.

    Like

    • Hi Rebecca,

      You can use get the fault details i.e the fault name, code and details from the fault context using XPath expresseions. The two expressions that can be used are ora:getFaultName() and ora:getFaultAsString().
      These can now be displayed to the user by assigning them to the task payload elements.

      Like

      • Hi Arun,

        I tried that, it doesnt work. ora:getFaultName() and ora:getFaultAsString() comes up with error when i include it in a scrit task to get the process error details. Im talking about in your exaple, thats catches all process error, you select catch all business exceptions or all system exceptions. getting the details of what ever that process fault caught is the problem, the two ora functions above dont work. maybe you can show me an example code of the bpm code looks like or you can update your example process to show me how you captured error data under the catch all exceptions

        Like

          • Arun, i understnad what you saying but my problem is that it does not work.
            From your example you have a event subprocess to deat with catch all Exceptions. inside the subprocess, the start event is an implemenrtation type of Error (catch all business exceptionsand catch all system exception selected). Under the use association of this event, by using association to assign the ora:getFaultAsString to an object, it does not do any assignment, the object happens to be empty despite the assignent or any other assignent of text int or whatever. (is it a known error that it does not do any assignment?) It does not come up as eror but still no assignment is reflected. However if we do the assignent under a scriptask right after the error catch event start, any assignment works apart from the ora:getFautlAsString or ora:getFaultName, both comes up with error and the bpm fails. I need you to do an example by extending your above example further asg show me if you manages to capture the details (ora:) to a variable successfully.

            I hope i explain myself better this time. Im awaiting your response. Thank you so much Arun.

            Like

      • Hi Arun
        In the example you create two Event Subprocess . One catch a specific exception and the other catch all business exceptions. My question is when this happens the specific exception is not captured by the two Event Subprocess. In the example specifically in scenario 1 exception should be captured by the two.
        Ths a lot

        Like

  14. Hi Arun
    In the example you create two Event Subprocess . One catch a specific exception and the other catch all business exceptions. My question is when this happens the specific exception is not captured by the two Event Subprocess. In the example specifically in scenario 1 exception should be captured by the two.
    Ths a lot

    Like

If you have any comments, suggestions or feedback about the post, please feel free to type it here and I will do my best to address them asap

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s