In this 3rd and final part of the Exception Handling tutorial series, both Technical and Systems faults will be covered.

 

Solution:

Technical and System Exceptions Project:

exceptionhandling_technical__system

 

---

3.1: Technical Faults

 

Examples of technical faults include SOAP faults, completionConditionFailure and conflictingReceive.

A Web service will be used to demonstrate this functionality. It has been written in such away that the entity invoking the service can cause the service to respond with a custom exception SOAP fault by sending it a particular parameter. 

---

Setting up the test Web service

 

To trigger the Technical Exceptions we will be using a simple Web service called AddException as a test object. This Web service adds two integers together and expects three parameters: a (type int), b (type int) and throwException (type boolean). Once it receives these parameters, if throwException is set to false, the service will return the result of a+b in the response message (type int). On the other hand, if throwException equals true, a custom SOAP fault is triggered and the repsonse will be a custom exception fault called customMessage (string).

 

The Web service which has been saved as an Apache service file and its WSDL can be found in the zip file below:

 

addexception

 

To use the AddException Web service you will need to upload (deploy) it into Axis 2 (SOAP stack used by Intalio|BPMS to communicate with Web services).

 

1. Enter the following URL into your browser: http://localhost:8080/axis2

 

2. Username: admin Password: axis2

 

3. Click on Upload service under Tools and upload AddException.aar.

 

 

4. Click on Available Services to see AddException listed.

 

5. Click on the AddException link to see the WSDL. You will see that this is exactly the same as the wsdl provided in the zip file attached). In fact if you prefer you can save this WSDL and use it instead.

 

---

 

How to create the example process

 

Below is an image of the Diagram that needs to be created:

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

1. Create a new Intalio Business Process Project called ExceptionHandlingWithAWebService.

 

2. Create a Business Process Diagram with the same name.

3. Copy AddException.wsdl into this project at root level.

 

4. In the diagram create 3 pools: Client, InvokeAServiceProcess and AService.

 

5. The Client and AService pools needs to be set  to NonExecutable. To do this, right click on the pool and from the contextual menu select 'Set pool non executable'.

 

6. We need to model the fact that the client will start the process by sending it a message. Create a Task called Send in the Client pool which is the only activity needed in this pool.

 

7. Create a Sub-process in the InvokeAServiceProcess pool to behave as a compound activity.

 

8. The first thing to occur in the sub-process will be the receipt of a message. This event will actually start the process.

Add a Message Start Event called ReceiveMessage in the subprocess.

 

9. The process will invoke the AddService Web service. To model this connect ReceiveMessage to a task called Invoke. Connect Invoke to a Message End event called Send Result to model the fact that the process will respond with a result.

 

10. We need to integrate the Web service (AddService) into our process so that our process can communicate with it. If you have not implemented service orchestration in an Intalio process before you can learn more about it here:

http://bpms.intalio.com/bpms-screencasts/intalio-bpms-5.2-services-and-people-orchestration.html

 

Dnd the Add operation from the AddException.wsdl into the Aservice pool. Select the first option from the pop up menu: Provide operation 'Add ' bound to port.... Connect up the message links between the Invoke and Add tasks.

 

11. We need to add in the functionality related to catching and handling the error which can be generated. When Error Intemediate Events are attached to the boundary of activities, they catch error triggers, interrupt the activity and create exception flow. 

 

Add an Error Intermediate Event on the bottom boundary of the Sub-process. (call it Catch Exception). Using the exception sequence flow, connect this event to a new sub-process which acts as an Exception Handler (call it Exception Handler).

 

To do this click on the Error Intermediate Event and move your mouse curser towards to right hand side of the object. You should see the sequence flow connector arrow appear (bold black arrow). If you click on this arrow, holding down your mouse button you can drag it out, then release your mouse button and you will be given a list of possible objects to connect to. Choose a sub-process.

 

12. The catch properties of the Error Intemediate Event need to be set so that the process knows exactly which error fault to catch (there can be more than one).

 

Click on the Catch Business Exception Intermediate Event. In the properties select the field next to Catch and notice how many different faults which can be caught. The list includes a large set of Standard faults. We want to be able to catch the custom exception fault that is returned from the AddService Web service so select invoke fault: ex:AddServicePortType/Add/fault/CustomExceptionFault.. Set the property as displayed below.

 

Catch: thrown fault: this: Throw Exception 

 

 

12. In the Exception Handling sub-process add a Message End Event (call it Fault). In our case we have not defined any complex exception handling in the Exception Handler although it is possible to define one or more activities in this sub-process.

 

13. Using message links connect the task Send to the start event (request message) and to the end event (response message)

 

14. Connect a message connector from the Message End Event (Fault) to the Send task located in the Client pool.

 

---

Data Management

 

1. Copy the RequestResponse.xsd schema which was created in Part 2 into your project.

2. In this schema add an element called exceptionThrown of type boolean to the Input complexType. Also create an element called errorMessage of type string.

 

 

3. Using the RequestResponse.xsd, Dnd the Request element onto the request message link and dnd the Response element onto the response message link. The response message from the Fault end event can be left as a simple string (default context).

 

4. Click on the Message End Event (Fault) and select the properties tab. Click on the Response fault name property and type "ExternalFault".

 

5. Click on the Send Result message end event. Complete a direct mapping between the return element of the $exAddResponseMsg.partResponse message variable to the thisReceiveMessageResponse.body$ message variable.

 

6. Click on the Fault message end event. Complete a direct mapping between the customMessage element of the $exCustomExceptionFaultVar.partException message variable and the thisExternalFaultMsg.body$ message variable.

 

---

Process Deployment and Execution

 

Deploy the process in the same fashion as described in Part 2.

 

Run the process with the following parameters.

 

Scenario 1:

a = 1

b = 2

exceptionThrown: false

 

Result: 3

 

Scenario 2:

a=1

b=2

exceptionThrown: true

 

Result: Error as seen below

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Note: Currently the Intalio console will not display the contents (body) of the fault message. It will only show the type. To see the whole message displayed including the body, you can either access it through the data tab in the console as hown below or run the process via SOAPUI (http://www.soapui.org/)

 

---

 

---

---

3.2 System Faults

 

Examples of system faults include Read Timeouts (Activity Failure Fault).

 

With the example below we can easily test the ability to catch a system fault by deactivating the Web service we deloyed above (AddService). This can be done in the Axis2 administration console through the deactivate service command (as shown below). When the process tries to invoke the service it will not be able to. The result will be a Timeout (Activity Failure Fault).

 

 

---

 

How to create the example process

 

We will build on the example process that was built in 3.1 so that it can catch system faults as well as technical faults.

 

 

1. If a system error occurs, like an activity failure, we want to ensure that the over all process does not fail. Instead the process should be configured to trigger a fault on failure which can be caught and handled. There are three properties to edit as shown below.

 

You can set a Retry For property to specify how many times you want the process to attempt to do what it was requested to before it triggers the fault e.g. how many times it should invoke a Web service if the attempt failed the first time.

It is also possible to set the Retry Delay which relates to how long the process should wait between attempts.

 

Click on the main Sub-process in the InvokeAServiceProcess pool. Select the Properties Tab and set

 

Fault on failure: true

Retry Delay: 30

Retry for: 3

 

Next a change needs to be made to the properties of the Catch Exception intermediate event so that is catches all faults, not just the one returned from the AddService Web service. This is controlled by the catch property.

 

2. Click on the Catch Exception Intermediate Event. In the properties select the field next to Catch select (none: for catchAll). This will set the catch property as shown below: Catch invoke fault: null

 

 

---

Process Deployment and Execution

 

1. Deploy the process in the same fashion as described in Part 2.

 

2. Ensure the AddService is deactivated through AXIS2 as described above.

 

3. Run the process with any value for the parameters for example:

 

Scenario:

a = 1

b = 2

exceptionThrown: false

 

Result:You will see the same ExternalFault message is displayed. 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

---

Further Reading and Material

 

In the Intalio process library you can find a process which has been designed as an extention of the two processes above to catch all three types of exception fault.

 

Library location: To be added shortly.