soa service logging and exception handling standards · soa version: 1.4 service logging and...

SOA

Service Logging and Exception Handling Standards

SOA Version: 1.4

Service Logging and Exception Handling Standards Date: 2013-07-29

eHealth Ontario Confidential ii

Contents

1 Purpose ........................................................................................................................... 5

2 Scope .............................................................................................................................. 5

3 eHO SOA Service Logging Standards ........................................................................... 6

3.1 eHO SOA Service Troubleshooting Standards ............................................................................. 6

3.1.1 Minimum Data Set for eHO SOA Troubleshooting ......................................................... 7

3.2 eHO SOA Service Monitoring Standards ..................................................................................... 8

3.2.1 Minimum Data Set for eHO SOA Service Monitoring ..................................................... 8

3.3 eHO SOA Service Auditing Standards ........................................................................................ 10

3.3.1 Minimum Data Set for eHO SOA Service Auditing ........................................................ 10

4 SOA Service Exception Handling (EH) Standards ...................................................... 12

4.1 Minimum Data Set for eHO SOA Service Exception Handling .................................................. 13

4.2 SOAP Fault ................................................................................................................................. 14

4.2.1 SOAP v1.1 Fault Element ............................................................................................... 14

4.2.2 SOAP v1.2 Fault Element ............................................................................................... 15

4.2.3 Modeled WSDL Faults ................................................................................................... 16

4.2.4 Un-modeled WSDL Faults ............................................................................................. 16

5 ESB Exception Handling Standards ............................................................................. 17

5.1 Minimum Data Set for eHO ESB Exception Handling ................................................................ 17

5.2 Mediation Modules ................................................................................................................... 19

5.3 Components of the Mediation Modules ................................................................................... 19

5.4 Mediation Primitives ................................................................................................................. 20

5.5 Error handling in the Mediation Flow Component ................................................................... 20

5.5.1 Mediation Flow Modeled Faults ................................................................................... 20

5.5.2 Mediation Flow Unmodeled Faults ............................................................................... 21

5.5.3 Mediation Component Error Flow ................................................................................ 22

5.6 Common Patterns for ESB Exception Handling ......................................................................... 22

5.6.1 Synchronous Invocation ................................................................................................ 22

5.6.2 Asynchronous Invocation .............................................................................................. 23

SOA Version: 1.4


eHealth Ontario Confidential iii

5.6.3 Mixed Invocation Styles ................................................................................................ 25

6 Business Process Management (BPM) Exception Handling Standards ....................... 26

6.1 Minimum Data Set for eHO BPM Exception Handling .............................................................. 26

6.2 BPM Exception Handling ........................................................................................................... 28

6.2.1 Fault Handler ................................................................................................................. 29

6.2.2 Compensation Handlers ................................................................................................ 29

6.3 Design-Time and Run-Time BPM Exceptions ............................................................................ 29

6.3.1 Handling Design-Time Exceptions ................................................................................. 30

6.3.2 Handling Run-Time Exceptions ..................................................................................... 30

6.4 Common Patterns for BPM Exception Handling ....................................................................... 31

6.4.1 Internal Business Exception Pattern ............................................................................. 31

6.4.2 Timeout Exception Pattern ........................................................................................... 32

6.4.3 System Fault Pattern ..................................................................................................... 32

6.4.4 Business Exception Throw-Catch Pattern ..................................................................... 33

6.4.5 Unsolicited External Business Exception Pattern .......................................................... 33

6.4.6 Solicited Response Exception Pattern ........................................................................... 34

6.4.7 Transaction Compensation Pattern .............................................................................. 35

7 References .................................................................................................................... 36

SOA Version: 1.4


eHealth Ontario Confidential iv

Document Location

Local Drive – TBD

Document Revision History

Version Date Author Description

1.0 2013-05-03 HIAL SOA Practice Created initial draft.

1.1 2013-06-17 HIAL SOA Practice Updated to address initial team review comments.

1.2 2013-07-17 HIAL SOA Practice Updated to address team review comments.

1.3 2013-07-23 HIAL SOA Practice Updated to address further team review comments.

1.4 2013-07-30 HIAL SOA Practice Updated to address further team review comments.

SOA Version: 1.4


eHealth Ontario Confidential 5

1 Purpose

The purpose of this document is to define and set the eHealth Ontario SOA Service logging and

exception handling standards to be used by the service designers/developers, SOA & enterprise

architecture/development/solution delivery/operational/maintenance/support teams throughout

the eHO SOA service lifecycle.

The intention of the eHO SOA service logging and exception handling standards is to use best

industry SOA logging & exception handling practices as well as reuse and apply existing eHO

logging and exception handling standards. The standards will be aligned with the existing, latest

eHO architectural principles, best practices, service specifications, standards and policies (Ref1,

Ref2, etc. - see reference table in section 5 of this document).

This document are intended to be used by different eHO Ontario project teams to consistently

streamline SOA service logging & exception handling processes for the new eHO services.

2 Scope

The eHO SOA service logging & exception handling standards described in this document

applies to eHO service side logging only (not to eHO third parties/ partners/etc.) and to all new

eHO SOA services that will be developed. The scope of this document will cover following

items:

A description of three different types of eHO SOA service logging (troubleshooting,

monitoring, auditing).

A description of the applicable eHO service troubleshooting logging standards, minimum

data set required to be logged for the eHO service troubleshooting logging.

A description of the applicable eHO service monitoring logging standards, minimum data

set required to be logged for the eHO service monitoring logging.

A description of the applicable eHO service auditing logging standards, minimum data

set required to be logged for the eHO service auditing logging.

A description of the applicable eHO SOA web service exception handling standards,

minimum data set to be logged for each eHO SOA web service exception.

eHO SOA service monitoring and exception handling standard will be used by the various eHO

SOA teams during entire SOA service lifecycle. Proper eHO service logging and exception

handling will enable eHO to effectively perform following activities: audit and tracing,

diagnostic & troubleshooting potential problems, monitor services, storing the logs for later

analysis, service performance tuning, debugging, etc.

SOA Version: 1.4



3 eHO SOA Service Logging Standards

The eHO SOA service logging standard will reuse existing eHO logging and monitoring

standards (Ref1) and will comply with other related/applicable eHO enterprise architecture

standards, as recommended by the eHO Standards Team.

Following table describes types of eHO SOA service logging that will be used for three different

types of logging activities:

Type of Logging Activity Description

Troubleshooting

This type of logging captures specific business & system technical data and it is used for eHO SOA service troubleshooting purposes (problem tracing, exception handling & root cause analysis, logging exceptions, debugging, etc.)

Monitoring

This type of logging captures specific service technical and business data and is used for overall eHO SOA service health check monitoring purposes (performance analysis / business activities / optimisation / tuning, etc.)

Auditing

This type of logging captures specific service business data and is used for eHO SOA

service auditing purposes (privacy audit logging, auditing business activities, etc.)

Table 1 – Types of eHO SOA Service Logging

3.1 eHO SOA Service Troubleshooting Standards

Following table describes eHO SOA service troubleshooting standards that will be used:

# eHO SOA Service Troubleshooting Standard

Name Short Description

1 CBE101 IBM Common Base Events Specification V1.0.1, IBM.

(CBE101)

2 LOG4J Java-based logging utility framework

Version 1.2

3 Logging and Monitoring Standard Ontario Logging and Monitoring Standard

Version: 1.1

Logging and Monitoring Standard_v1.1_20120402.doc

4 eHealth Ontario Provincial Client Registry Project Java Coding Standards

PCR - EMPI PubSub Java Coding Standards - v1.2 - Accepted - 20120823.doc Version 1.2

Table 2 - eHO SOA Service Troubleshooting Standards

SOA Version: 1.4



3.1.1 Minimum Data Set for eHO SOA Troubleshooting

Following table describes minimal data set (information) required to be logged (if available) for

the eHO SOA service troubleshooting (logging) purposes:

# eHO SOA Service Troubleshooting

Minimal Data Set Short Description

1 sys system name (eg: HIAL)

2 app Application name

3 appId Application ID (eg: OLIS_GTWY_WSP_DEL, OLIS_BKBN_WSP

(corresponding to IF in the app)

4 txId Transaction ID

5 msgId Unique message ID

6 action the WS-Addressing action from the request (if there is one)

7 source SubjectDN if available

8 sourceIP The client IP address

9 sourceId “uao” from SAML token (applies only to services that require SAML

token for authentication)

10 role Role of the user that performed the action User role/privilege level -

eg. supervisor, root, administrator, etc.

11 targetURI The full URL of the outgoing message

12 status Outcome of the transactions/action/operation

(eg: SUCCESS for successful transactions

ERROAR for transactions that contain errors)

Status of the message

13 entryTime Timestamp (UTFC format)

14 elapsedTime The overall execution time from the time it receives the requests and

the time it forwards the response

15 message Entire message content

16 tid Original unique uuid generated by IF (stored in http header)

17 sessionId Unique session ID

18 threadID Thread ID

19 segmentId Federated segment will be used for federated HIAL (there are four

segments: Prov, CSWO, CNEO, CGTA)

20 loggingLevel Trace/Debug/Info/Warn/Error/Fatal

21 notification Specify if notification is required (to whom and where notification

should be sent)

SOA Version: 1.4



# eHO SOA Service Troubleshooting


22 logFileID Unique troubleshooting logging file ID

23 userId User ID who requested web service or performed the action/operation

Table 3 – Minimum Data Set for the eHO SOA Service Troubleshooting

Beside mandatory information (specified in the minimum data set), additional troubleshooting

information will be logged depending on the project specific troubleshooting needs and

requirements. Level of additional information that will be logged is project specific and each

project has to decide on additional eHO service information that will be logged with the

troubleshooting minimum data set.

3.2 eHO SOA Service Monitoring Standards

Following table describes eHO SOA service monitoring standards that will be used:

# eHO SOA Service Monitoring Standard Name Short Description

1 CBE101 IBM Common Base Events Specification V1.0.1, IBM.

(CBE101)


Version 1.2


Version: 1.1




Table 4 - eHO SOA Service Monitoring Standards

3.2.1 Minimum Data Set for eHO SOA Service Monitoring

Following table describes minimal data set (information) required (if available) to be logged for

the eHO SOA service monitoring purposes:

# eHO SOA Service Monitoring




SOA Version: 1.4



# eHO SOA Service Monitoring











10 role Role of the user that performed the action User role/privilege level -

eg. supervisor, root, administrator, etc.


12 status Outcome of the transactions/action/operation (eg: SUCCESS for

successful transactions ERROAR for transactions that contain errors)












21 notification Specify if notification is required (to whom and where notification

should be sent)



24 policyId Policy involved with the activity or operation

25 ruleId Rule involved with the activity or operation

Table 5 – Minimum Data Set for the eHO SOA Service Monitoring

SOA Version: 1.4



Beside mandatory information (specified in the minimum data set), additional monitoring

information will be logged depending on the project specific monitoring needs and requirements.

Level of additional information that will be logged is project specific and each project has to

decide on additional eHO service information that will be logged with the monitoring minimum

data set.

3.3 eHO SOA Service Auditing Standards

Following table describes eHO SOA service auditing standards that will be used:

# eHO SOA Service Auditing

Standard Name Short Description

1 eHO ATNA eHO Audit Trail and Node Authentication Standard

2 Health Care Audit Event

Implementation Guide

(eHO Health Care Audit Event

Standard)

Ontario Health Care Audit Event Specification - Implementation Guide û

Version 1.0 û 2012-06-18.pdf

Version: Release 1.0

3 CBE101 IBM Common Base Events Specification V1.0.1, IBM. (CBE101)


Version 1.2


Version: 1.1




Table 6 – eHO SOA Service Auditing Standards

3.3.1 Minimum Data Set for eHO SOA Service Auditing


the eHO SOA service auditing purposes:

# eHO SOA Service Auditing Minimal

Data Set Short Description

1 sys System name (eg: HIAL, ETC…)




SOA Version: 1.4



# eHO SOA Service Auditing Minimal

Data Set Short Description








10 role Role of the user that performed the action User role/privilege level - eg.

supervisor, root, administrator, etc. . Capture privileged accounts/roles

used to perform sensitive operations.


12 status Outcome of the transactions/action/operation

(eg: SUCCESS for successful transactions

ERROAR for transactions that contain errors)












21 notification Specify if notification is required (to whom and where notification should

be sent)



24 policyId Policy involved with the activity or operation

25 ruleId Rule involved with the activity or operation

Table 7 – Minimum Data Set for the eHO SOA Service Auditing

SOA Version: 1.4



Beside mandatory information (specified in the minimum data set), additional auditing

information will be logged depending on the project specific auditing needs and requirements.

Level of additional information that will be logged is project specific and each project has to

decide on additional eHO service information that will be logged with the auditing minimum

data set.

4 SOA Service Exception Handling (EH) Standards

The eHO SOA service exception handling standard will reuse existing eHO logging standards

(Ref1) as well as standards from section 3 of this document, to capture eHO SOA service

exception handling related information and will comply with other related/applicable eHO

enterprise architecture standards /architectural principles/best practices/specifications/policies.

Following table describes eHO SOA service exception handling standards that will be used:

# eHO SOA Service Exception

Handling Standard Name Short Description

1 WSDL v2.0 Web Services Description Language v2.0

2 SOAP v1.1

Simple Object Access Protocol v1.1

3 SOAP v1.2 Simple Object Access Protocol v1.2

4 WS-Notification v1.3 WS-Notification is used for exposing asynchronous web services.



Version 1.2

7 Logging and Monitoring Standard

Ontario Logging and Monitoring Standard

Version: 1.1




Table 8 – eHO SOA Service Exception Handling Standards

SOA Version: 1.4



4.1 Minimum Data Set for eHO SOA Service Exception Handling


the eHO SOA service auditing purposes:


Handling Minimal Data Set Short Description













supervisor, root, administrator, etc.
















be sent)

SOA Version: 1.4




Handling Minimal Data Set Short Description



Table 9 – Minimum Data Set for the eHO SOA Service Exception Handling

Beside mandatory information (specified in the minimum data set), additional service exception

handling information will be logged depending on the project specific auditing needs and

requirements.

NOTE: Level of additional information that will be logged is project specific and each project

has to decide on additional eHO service information that will be logged with the auditing

minimum data set. It will be required to fully describe the exception and involved operations

/transactions/ services/processes etc.) how service exception root cause could be traced,

analysed and determined.

4.2 SOAP Fault

eHO will use SOAP Fault elements for handling web service exceptions. The SOAP <Fault>

element content will be used to transmit exception/error and status information within a SOAP

message back to the the service requestor (sender of the SOAP message). There are two types of

eHO Web Services: SOAP v1.1 based Web Services and SOAP v1.2 based Web Services. SOAP

v1.1 and v1.2 have different Fault element structure.

4.2.1 SOAP v1.1 Fault Element

The SOAP 1.1 Fault element defines the following four sub-elements that will be used when

handling eHO SOAP v1.1 based web service exception:

Fault Sybelement

Name Description

Required - R

Optional - O

faultcode Standard code that provides more information about the fault. A set of code values is predefined by the SOAP specification, as defined below. This set of fault code values can be extended by the application.

Predefined fault code values include:

VersionMismatch—Invalid namespace defined in SOAP envelope element. The SOAP envelope must conform to

M

SOA Version: 1.4



Fault Sybelement

Name Description

Required - R

Optional - O

thehttp://schemas.xmlsoap.org/soap/envelope namespace.

MustUnderstand—SOAP header entry not understood by processing party.

Client—Message was incorrectly formatted or is missing information.

Server—Problem with the server that prevented message from being processed.

faultstring Human-readable description of fault. M

faultactor URI associated with the actor (SOAP node) that caused the fault. In RPC-style messaging, the actor is the URI of the Web service. O

detail Application-specific information, such as the exception that was thrown. This element can be an XML structure or plain text.

O

Table 10 –SOAP v1.2 Fault Sybelements

4.2.2 SOAP v1.2 Fault Element

The SOAP 1.2 Fault element defines the following sub-elements that will be used when handling

eHO SOAP v1.2 based web service exception:

Fault Sybelement

Name Description

Required - R

Optional - O

env:Code Information pertaining to the fault error code. The env:Code element consists of the following two subelements:

env:Value

env: Subcode

The subelements (value and subcode) are defined below.

R

env:Value Code value that provides more information about the fault. A set of code values is predefined by the SOAP specification, including:

VersionMismatch—Invalid namespace defined in SOAP envelope element. The SOAP envelope must conform to thehttp://schemas.xmlsoap.org/soap/envelope namespace.

MustUnderstand—SOAP header entry not understood by processing party.

Sender—Message was incorrectly formatted or is missing information.

Receiver—Problem with the server that prevented the message from being processed.

DataEncodingUnknown—Received message has an unrecognized encoding style value. You can define encoding styles for SOAP headerblocks and child elements of the SOAP body, and this encoding style must be recognized by the Web services server.

R

env:Subcode Subcode value that provides more information about the fault. This subelement can have a recursive structure.

O

env:Reason Human-readable description of fault. R

SOA Version: 1.4



Fault Sybelement

Name Description

Required - R

Optional - O

The <env:Reason> element contains one or more <Text> elements, each of which contains information about the fault in a different language.

env:Node Information regarding the actor (SOAP node) that caused the fault. O

env:Role Role being performed by actor at the time of the fault. O

env:Detail Application-specific information, such as the exception that was thrown. O

Table 11 –SOAP v1.2 Fault Sybelements

4.2.3 Modeled WSDL Faults

Service operations defined in the WSDL file have three types of messages:

input

output

fault

Modelled WSDL faults are business error conditions that are defined in a WSDL operation.

Modeled faults are mapped directly into the fault element in the WSDL file. A modeled fault is

mapped to an exception that will be thrown explicitly from the business logic of the service

implementation code (eg: Java code). In this case, the business exception is mapped to a

wsdl:fault element definitions in the WSDL file (when the Web service is deployed) as well as

defined in the SOAP Fault element.

NOTE: All faults that will be logged/monitored/audited have to be modeled in WSDL file and

defined in WSDL:fault element and SOAP fault element.

4.2.4 Un-modeled WSDL Faults

An un-modeled fault is mapped to an exception (for example, java.lang.RuntimeException) that

will be generated at run-time when no business logic fault is defined in the WSDL fault and

SOAP Fault. In this case, Java exceptions are represented as generic SOAP Fault exceptions

(javax.xml.ws.soap.SOAPFaultException) will be thrown.

SOA Version: 1.4



5 ESB Exception Handling Standards

The eHO ESB exception handling standard will reuse existing eHO logging standards (Ref1) as

well as standards from section 3 of this document, to capture eHO ESB exception handling

related information and will comply with other related/applicable eHO enterprise architecture

standards /architectural principles/best practices/specifications/policies.

Following table describes eHO ESB exception handling standards that will be used:


Handling Standard Name Short Description


2 SOAP v1.1






Version 1.2



Version: 1.1




Table 12 – eHO ESB Exception Handling Standards

5.1 Minimum Data Set for eHO ESB Exception Handling


the eHO ESB exception handling purposes:

# eHO ESB Exception Handling


1 failureString Exception message (attribute of the failinfo element)

2 errorSeverity Error severity (Single-letter exception message severity type code)

3 origin Mediation primitive name (attribute of the failinfo element)

SOA Version: 1.4





4 invocationPath List of previous primitives in the flow, executed up to the point of the failure (attribute of the failinfo element)

5 mediationName The ID/name of the Fail mediation primitive instance that generated the mediation flow exception.

6 moduleName The ID/name of the mediation module instance that contains the Fail primitive.















18 status

Outcome of the transactions/action/operation (eg: SUCCESS for

successful transactions ERROR for transactions that contain errors)












SOA Version: 1.4






be sent)



Table 13 – Minimum Data Set for the eHO ESB Exception Handling



requirements.


has to decide on additional eHO ESB messaging information that will be logged with the

auditing minimum data set. It will be required to fully describe the exception and involved

operations /transactions/ services/processes etc.) how ESB exception root cause could be traced,


5.2 Mediation Modules

Mediation modules are ESB components that can change the format, content, or target of service

requests. They operate on messages that are in-flight between service requesters and service

providers. You are able to route messages to different service providers and to amend message

content or form. Mediation modules can provide functions such as message logging, and error

processing that is tailored to your requirements.

5.3 Components of the Mediation Modules

Mediation modules contain the following items:

Imports, which define interactions between modules and service providers.

Exports, which define interactions between modules and service requesters.

Mediation components (eg, Service Component Architecture (SCA) Components), which are

building blocks for mediation modules (eg, SCA modules).

Mediation modules and components can be customized. Usually, mediation modules contain a

specific type of component called a mediation flow component. Mediation flow components

define mediation flows. A mediation flow component can contain none, one, or a number of

mediation primitives.

SOA Version: 1.4



5.4 Mediation Primitives

Mediation flow components operate on message flows between service components. The

capabilities of a mediation component are implemented by mediation primitives, which

implement standard service implementation types. A mediation flow component has one or more

flows. For example, one for request and one for reply. Custom mediation primitives with special

mediation capabilities are also possible.

5.5 Error handling in the Mediation Flow Component

This topic provides information on the various ways to deal with errors in the mediation flow.

5.5.1 Mediation Flow Modeled Faults

WSDL operations have three types of messages:

input

output

fault

Service provider implementation needs to define WSDL operations with all possible business

exceptions (in the WSDL:fault element). In ideal implementation other exceptions should not be

propagated back to the service consumer. In cases where propagation of faults is required by

business, a custom or business friendly exception message should be passed in.

In mediation flows exception handling is done using Input Fault nodes. All business exceptions

can be returned to the service consumer using Input Fault nodes. An Input Fault node is created

when a source operation has a modeled fault message defined. The Input Fault node has an input

terminal for each fault message type that is defined in the source operation. Any message that is

sent to an Input Fault node will result in a modeled fault error message being returned from the

source operation. Wiring to this node means that the fault message is returned to the service

requester.

The Input Fault node is created in the request and response flows. Mediation primitives that

process messages have a fail terminal. When there is a failure in the mediation primitive, the fail

terminal is called and exception information is sent, along with the input message. The exception

information is stored in the failInfo element in the message context. The fail terminal of

mediation primitive must be wired to mediation primitive in order to access the failInfo. If the

fail terminal on mediation primitive is not wired, the flow fails with a runtime exception. The

Stop mediation primitive has one input terminal and no out terminals. When the fail or out

SOA Version: 1.4



terminal on a mediation primitive is wired to the Stop mediation primitive, that particular branch

comes to an end. The mediation flow editor generates warnings if the out terminal of mediation

primitive is not wired. The Stop mediation primitive is used to stop these warnings. In the

runtime, out terminals that are not wired are automatically propagated to stop.

A Callout Fault node is created in the response flow for each target operation that has a modeled

fault defined. The Callout Fault node has an out terminal for each fault message type that is

defined in the target operation. When a modeled fault occurs, the Callout Fault node sends a

message to the mediation primitive or node to which it is wired. If the fail terminal on the

Callout Response node is not wired and an unmodeled fault is received, a mediation runtime

exception will occur.

Errors inside mediation flows

Mediation primitives that process messages have a fail terminal, which propagates exception

information along with the input message when there is a failure in that primitive. The exception

information is stored in the failInfo element in the message context.

You must wire the fail terminal of mediation primitive to another primitive to access failInfo

exception details. The fail terminal of a primitive provides failure information about the current

primitive in the failinfo element. failinfo have following key attributes

Failinfo Attribute Name Description

failureString This attribute provides a exception message

origin This attribute gives the primitive name.

invocationPath

This attribute gives the list of previous primitives flowed through leading up to the failure.

Table 14 – Mediation Flow failinfo Attributes

5.5.2 Mediation Flow Unmodeled Faults

Errors that are returned, and are not defined as WSDL faults are called unmodeled faults. There

is no Input or Callout Fault node created for these types of faults in the mediation flow. In this

case, the input message type is sent to the Callout Response node's fail terminal. The failure

information is captured in the failInfo element of the message context. To handle an unmodeled

fault, the fail terminal has to be wired to a Callout Response node to mediation primitive. For

example, the fail terminal has to be wired on a Callout Response node to Message Logger

mediation primitive to log all unmodeled faults. Property of the Callout Response node has to be

SOA Version: 1.4



wired to determine whether the entire request message or just the message header information

should be passed out of the fail terminal (there can be a performance overhead if you choose to

pass the entire request message). If the fail terminal on the Callout Response node is not wired

and an unmodeled fault is received, a mediation runtime exception will occur.

5.5.3 Mediation Component Error Flow

A mediation flow component has an error flow for each source operation. The error flow acts as

a catch-all for messages that are propagated from any unwired or fail terminal on any primitive

or node, in either a request or a response flow. By default, an error flow consists of:

An Error Input node, which has a “catchall” terminal, with the type set to anyType. The Error

Input node propagates the Service Message Object (SMO) from the unwired terminal that

contains the error information.

An Input Response node for (request and response) operations. You can use this node to

return a message from the source operation.

An Input Fault node, created when a source operation has a WSDL fault message defined.

The Input Fault node has an input terminal for each fault message type that is defined in the

source operation. Any message that is sent to an Input Fault node results in a WSDL fault

error message being returned from the source operation.

Mediation primitives can be wired to the Error Input node to capture error information. For

example, a Message Logger mediation primitive is wired to log the SMO. Error handling logic

can be also defined in a subflow, so that it can be reused in multiple error flows. Error flow can

be used to audit any unhandled errors that may occur in the operation request or response flows.

5.6 Common Patterns for ESB Exception Handling

When a service component is called synchronously or asynchronously; unexpected runtime

errors can occur. In SCA, error handling is put in place to make sure that a message is not lost.

This topic provides information on how messages are handled by the SCA runtime when an error

occurs. You will find information for both synchronous and asynchronous invocation styles.

5.6.1 Synchronous Invocation

A transaction is a unit of activity, within which multiple updates to resources can be made

dependent such that all or none of the updates are made permanent. Transaction qualifiers can be

used to control transactional behavior of service invocations.

Note: In this section, we have assumed that all components are set to run in a global transaction.

SOA Version: 1.4



When a service component is called synchronously, and performs a synchronous invocation,

both the service requester and the service provider run in the same thread of execution. The

calling component within ESB is blocked until a response is received from the provider.

Figure 1 – Synchronious Invocation Error Handling

As shown in Figure 1 there are no queues in a synchronous flow. If an unhandled error occurs at

any point in the flow, any active transactions will rollback and an unmodeled fault is returned to

the service requester.

5.6.2 Asynchronous Invocation

When a service component is called asynchronously, the service requester and the service provider run in different threads of execution. The SCA runtime returns control to the requester immediately.

Figure 2 – Asynchronious Invocation Error Handling

Figure 2 shows how errors can be handled within an asynchronous flow. The flow has been split into transaction boundaries (A, B, C, D), each new boundary is marked by a new queue (1, 2, 3, 4). If an error occurs within a transaction boundary, the message is rolled back to the queue at the start of the transaction. For example, if an error occurs within the mediation flow component, the message is rolled back to queue number 2, because it is within the transaction boundary B.

http://pic.dhe.ibm.com/infocenter/esbsoa/wesbv7r5/topic/com.ibm.websphere.wesb.programming.doc/topics/esbprog_commonerrorpatterns.html#esbprog_commonerrorpatterns__sync_error

SOA Version: 1.4



Figure 3 – Asynchronious Invocation Error Handling Without Queue 2

As default, to improve performance, when the first asynchronous invocation is made, queue 2 is omitted from the flow. As shown in Figure 3 one thread of execution will start from queue 1. If an exception occurs at the mediation flow component, the message will be sent back to queue 1, because it is within transaction boundary A. The message is redelivered to the export and the previously omitted queue 2 is reintroduced as shown in Figure 4. Any subsequent retries, will include queue 2. This performance optimization occurs automatically. Specifically JMS, MQ and asynchronous SCA bindings all have this optimized behaviour.

Figure 4 – Asynchronious Invocation Error Handling

As a default, when a message is rolled back to an internal module destination, SCA retry logic indicates that the message will be redelivered up to five times. If the message fails again, it will be automatically forwarded to the defined exception destination. This can be viewed via the Service Integration Bus Explorer in the Administrative Console. If the Failed Event Manager is enabled, messages on the exception destination are removed and stored in a database as failed events. Each module has its own internal exception queue. Binding retries can be configured at the binding, or on the messaging provider. Binding retries occur at least once, so that the Failed Event Manager can be aware of any fault.

The Failed Event Manager is a web-based client for working with and resubmitting the failed invocations. It is an integration application and is available in the Administrative console. It displays the number of failed events and provides a number of search capabilities. Messages that exceed their retry count are automatically retrieved by the Failed Event Manager. Asynchronous export and import bindings can be configured to send failed messages to the Failed Event Manager before they exceed their retry count.

SOA Version: 1.4



5.6.3 Mixed Invocation Styles

When a service requester calls a service provider, the invocation can be made either synchronously or asynchronously. There are situations where the service requester makes a synchronous call, but the service provider must be called asynchronously by the mediation flow component. In this occasion, queues 1 and 2, and boundaries A and B will not exist, and the flow will look similar to Figure 5. In this situation, if an error occurs before boundary C, it will be sent back to the service requester.

Figure 5 – Synchronious and asynchronious Invocation Error Handling

If the service requester performs an asynchronous invocation, and the service provider is a synchronous service, the mediation flow component will call the import synchronously. In this situation, queues 3 and 4, and boundaries C and D will not exist within Figure 6. In this situation, if an error occurs after boundary B, it will be sent back to the service provider.

Figure 6 – Asynchronious and Synchronious Invocation Error Handling

http://pic.dhe.ibm.com/infocenter/esbsoa/wesbv7r5/topic/com.ibm.websphere.wesb.programming.doc/topics/esbprog_commonerrorpatterns.html#esbprog_commonerrorpatterns__asynchoperror3

SOA Version: 1.4



6 Business Process Management (BPM) Exception Handling Standards

The eHO BPM exception handling standard will reuse existing eHO logging standards (Ref1) as

well as standards from section 3 of this document, to capture eHO BPM exception handling

related information and will comply with other related/applicable eHO enterprise architecture

standards /architectural principles/best practices/specifications/policies.

Following table describes eHO BPM exception handling standards that will be used:

# eHO SOA BPM Exception Handling

Standard Name Short Description

1 BPEL v2.0 WS-BPEL Web Service Execution Language v2.0

2 BPMN v2.0 Business Process Modeling Notation v2.0


4 SOAP v1.1






Version 1.2



Version: 1.1




Table 15 – eHO BPM Exception Handling Standards

6.1 Minimum Data Set for eHO BPM Exception Handling


the eHO ESB exception handling purposes:

# eHO BPM Exception Handling


1 failureString Exception message (attribute of the failinfo element)

2 errorSeverity Error severity (Single-letter exception message severity type code)

SOA Version: 1.4





3 origin Mediation primitive name (attribute of the failinfo element)

4 invocationPath List of previous primitives in the flow, executed up to the point of the failure (attribute of the failinfo element)

5 mediationName The ID/name of the Fail mediation primitive instance that generated the mediation flow exception.

6 moduleName The ID/name of the mediation module instance that contains the Fail primitive.



























SOA Version: 1.4







be sent)



30 processID BPM Process flow ID

31 activityID BPM Process Activity ID

Table 16 – Minimum Data Set for the eHO BPM Exception Handling



requirements.


has to decide on additional eHO BPM messaging information that will be logged with the

auditing minimum data set. It will be required to fully describe the exception and involved

operations /transactions/ services/processes etc.) how BPM exception root cause could be traced,


6.2 BPM Exception Handling

Due the complexity in this SOA layer, exception/fault handling is critical for managing business

process & orchestration errors. Most common way of handling business process/orchestration

type of exceptions/errors is using handlers. Business process handler consists of a group of

activities that represent a specific course of action, which is associated with a particular activity.

A handler runs when certain situations occur (exception, fault, etc...) within the parent activity

(the activity with which the handler is associated).

Faults are any exceptional conditions that can change the normal processing of a business

process. A well-designed process should consider faults and handle them whenever possible.

The following two types of handlers are used for handling business process/orchestration

exceptions/faults:

Fault handlers

Compensation handlers

SOA Version: 1.4



6.2.1 Fault Handler

Use a fault handler to handle partial and unsuccessful work that is a result of a fault (problem or

exceptional situation during process execution). A fault handler is a collection of specific

activities that run when a fault is thrown on a particular activity with which the handler is

associated. When a fault occurs in a business process the flow navigation moves to the fault

handler.

Fault handlers can be added on invoke or scope activity. A fault handler can catch a specific fault

name, fault type, or both using one and more “catch” elements. Each path within the fault

handler is preceded by either a “catch” or a “catch all” element. One “catch” element can be

added for each fault that can potentially occur within the scope or the invoke activity. Each

“catch” is succeeded by a set of activities to deal with that particular fault. Optionally, the fault

hander can end with a “catch-all” element/construct to deal with any other faults that are not

caught by any of the existing “catch” elements in the fault handler.

6.2.2 Compensation Handlers

Compensation handler (compensate activity) will be invoked within the scope of the activity that

owns the compensation handler. Activity will invoke a specific compensation handler within its

scope. Compensation is an undo/roll back action for work that has completed successfully by the

activity, before the exception/fault occurred.

Compensation activity must be predefined and configured within the target activity scope for the

compensation. The target activity specifies the activity whose compensation handler or

compensation operation executes when this exception/fault compensation activity is invoked.

6.3 Design-Time and Run-Time BPM Exceptions

In general, in BPM there are two types of exceptions:

Design-Time exceptions

Run-Time exceptions

Following table describes both types of BPM exceptions:

BPM Exception

Type Description

Design-Time

Design-time exceptions or Business Exceptions are checked exceptions declared in a business interface/operation/method signature (defined as the WSDL fault element). Business Exceptions identify error conditions that are anticipated by the process/activity/mediation/ component/service. These exceptions are referred to as modeled or "checked exceptions".

SOA Version: 1.4



BPM Exception

Type Description

Run-Time

Run-time exceptions are also known as "system exceptions" and they are not declared in the WSDL fault element or in the business interface/operation/method signature. In general, they represent error conditions that are not anticipated by the application. When a Run-time Exception is thrown from a process/activity/mediation/component/ service, the current transaction will be compensated (rolled back). These exceptions are referred to as modeled or "unchecked exceptions". Run-time Exceptions are used to signal an unexpected condition in the runtime execution of the business process. Following three actions can be done with This type of exception can be handled on the following three ways:

Catch the run-time exception and perform some alternative logic.

Catch the run-time exception and re-throw it to the client.

Remap the run-time exception to a business exception

Table 17 – Design-time and Run-time BPM exceptions

6.3.1 Handling Design-Time Exceptions

Some of the business process exceptions can be predicted and predefined at design time (certain

faults returned by the business process/orchestration (such as data entry validation errors – some

data violates one of the underlying business rules). For this kind of exception, Fault Handlers or

Compensation Handlers will be used and fault/compensation logic will be built directly

(whenever it is possible) in the particular business process/ service activity itself, as part of the

solution.

As part of the Fault/Compensation handler exception handling, transaction rollback may be

required to roll back changes that have already been committed in order to maintain the integrity

and atomicity of data (before exceptions) for that specific unit of work. In some situations,

business process/ orchestration could be long running and orchestrated services are loosely

coupled with third party services, it will not be always easy and practical to hold resources in

uncommitted state or to roll back the state (if they are committed). In this case, explicitly

compensation roll back logic has to be implemented for each unit of work. Some business

process/orchestration tools (BPM/BPMN 2/BPEL Tools) support this kind of functionality out of

the box.

6.3.2 Handling Run-Time Exceptions

Some exceptions are hard to predict and determine until run-time (such as communication link to

a third party service is not available, etc.). In order to handle run-time exceptions, run-time error

has to be detected/captured and proper exception/fault handling action will be taken.

SOA Version: 1.4



For this kind of exception, Fault Handlers or Compensation Handlers will be preceded by

“catch” and “catch all” elements. Each “catch” element will be succeeded by a set of activities to

deal with that particular fault. One “catch all” element has to be added for each activity to

capture all run-time faults that can potentially occur within the scope or the invoked activity.

“catch all” element will be succeeded by a set of activities to deal with any other possible faults

that are not caught by any of the existing “catch” elements in the fault or compensation handler.

6.4 Common Patterns for BPM Exception Handling

This section describes common patterns for the BPM exception/error handling.

6.4.1 Internal Business Exception Pattern

Internal business exception pattern represents the exception that is detected internally by logic in

a process activity that completes normally but with a bad business result. In that case this activity

should be followed with a gateway that tests the business result. One gateway's branch leads to

the correct path, and the other branch leads to the exception path. Following model depicts this

pattern:

Figure 7 – Internal Business Exception Pattern

NOTE: One restriction is if the exception is enclosed in a subprocess, the exception path cannot

cross the subprocess boundary.

SOA Version: 1.4



6.4.2 Timeout Exception Pattern

When a process activity is not completed by a particular time and date or by some specified

duration after it starts. For that, use the timeout exception pattern based on an attached timer

event. In an attached timer event, the clock starts when the activity it is attached to is first

enabled. If the activity completes before that duration expires, the normal flow out of the activity

is enabled. If not, the activity is aborted and the exception flow out of the timer event is enabled.

Following model depicts this pattern:

Figure 8 – Timeout Exception Pattern

6.4.3 System Fault Pattern

A system fault means the process activity cannot compete successfully because of a technical

problem. (Such as: a database query that cannot be executed because of bad SQL syntax or

because the server). An error intermediate event attached to a service task indicates the system

fault pattern and It means that the task could not complete successfully. Following model depicts

this pattern:

Figure 9 – System fault Pattern

SOA Version: 1.4



6.4.4 Business Exception Throw-Catch Pattern

An error event can also be used to handle business exceptions when the simple internal business

exception pattern described earlier is insufficient. Typically that occurs when the detected

business exception in a subprocess needs to end a parallel thread of the subprocess before

beginning the exception flow. In that case, an error end event in the subprocess can “throw” the

error result signal that is “caught” by an error intermediate event attached to the subprocess

boundary. In this business exception throw-catch pattern, paired events are linked by a common

ErrorCode attribute.

The thrown error signal is caught by the event labeled Catch Error on the subprocess boundary.

Like all attached events, it aborts the activity (the entire subprocess) and then triggers the

exception flow. Error event attached to a subprocess may have one or more error end events in

the expanded view of the subprocess that specify where the error signal is thrown.

Figure 10 – Business Exception Throw-Catch Pattern

6.4.5 Unsolicited External Business Exception Pattern

Previous mentioned BPM exception patterns have been used to handle exceptions that are

internal to the process. The unsolicited external business exception pattern uses an attached

message event, which catches the signal from the external entity. If the exception signal occurs

while the activity it is attached to is running, the activity is aborted and processing continues on

SOA Version: 1.4



the exception flow that lead to that handler For example, in the diagram below a customer can

cancel the order after B has started but before C has ended.

Figure 11 – Unsolicited External Business Exception Pattern

6.4.6 Solicited Response Exception Pattern

The preceding pattern is used to respond to unsolicited external events. This pattern will consider

exception responses solicited from external entities. In this case, event gateway will be typically

be used, since we are waiting for the event, not aborting on the event. A common scenario is a

request for additional information, or perhaps a service request. An event gateway pauses the

process to wait for a response. The normal response on one gate represents the happy path. An

exception response, such as item out of stock, could be placed on another gate to define the

exception path. No response at all within a specified timeout interval that would be handled by a

timer event on a third gate. It could lead to a separate exception path or one shared with the

exception response, following model describe this pattern:

Figure 12 – Solicited Resonse Exception Pattern

SOA Version: 1.4



6.4.7 Transaction Compensation Pattern

BPMN provide functionality for handling business transaction recovery through compensation.

A business transaction is a set of activities that must complete atomically, meaning either all

activities in the set are performed successfully or the state of the system must be restored if at

least one failed. Any activity participating in the transaction that needs to be undone if the

transaction fails can be linked to its compensating activity via a compensation intermediate

event, drawn with a rewind icon inside. BPMN provides a way to specify all of this in the

diagram. Actually, it specifies two alternative ways. Following diagram depicts the

compensation activity capability:

Figure 13 – Transaction Compensation Pattern

A cancel event (represented as an X icon in the diagram bellow), attached to the border of a

transactional subprocess, is a special type of error event. Like a regular error event, it aborts the

subprocess when triggered, but before starting on the exception flow it implicitly commands

compensation of the transaction. That means that all activities in the transactional subprocess that

have completed and have defined compensating activities should execute those compensating

activities to restore a consistent state of all the resources. Once compensation is done, the

exception flow proceeds. As with the regular error event, throw of the cancel signal can

optionally be shown explicitly by a cancel end event inside the transactional subprocess.

SOA Version: 1.4



Figure 14 – Cancel Event

7 References

ID Reference Location/Description

Ref1 Ontario Logging and Monitoring Standard

Version 1.1

Logging and Monitoring Standard_v1.1_20120402.pdf

Ref2

Audit Log Service Rationalization Workshop Findings and Architecture Recommendation

Architecture Recommendation - Audit Log Service Rationalization.doc

Embed doc here

Ref3 Integration Facility-Technical Design R3-0.3 Integration Facility Technical Design – R3.doc

Ref4 ON Provincial EHR Logical Architecture Principles

LA-AP Architectural Principles.pdf

Ref5 ON Provincial EHR Logical Architecture Architecture Decisions

LA-AD Architecture Decisions.pdf

SOA Version: 1.4




Ref6 W3C, SOAP 1.1 http://www.w3.org/TR/2000/NOTE-SOAP-20000508/

Ref7 SOAP Version 1.2 Part 0 http://www.w3.org/TR/2007/REC-soap12-part0-

20070427/#L11549

Ref8 W3C, SOAP Version 1.2 Part 1: Messaging Framework

http://www.w3.org/TR/soap12-part1/

Ref9 W3C, SOAP Version 1.2 Part 2 http://www.w3.org/TR/2007/REC-soap12-part2-20070427/

Ref10 Functional Design Requirements EMPI-IF Integration Project Version: 1.14 (Draft Copy)

EMPI-IF Functional Design Requirements v1.14 (Accepted) 12132013_marked.doc

Ref11

Provincial Client Registry Consumer Implementation Guide - Transport specification Version 0.02

eHealth Ontario - CIG-PCR Transport specification - Draft v0.02.doc

Ref12

Health Care Audit Event Implementation

Guide (eHO Health Care Audit Event

Standard)

Version: Release 1.0

http://www.ehealthontario.on.ca/en/standards/view/health-care-audit-event

Ontario Health Care Audit Event Specification -

Implementation Guide û Version 1.0 û 2012-06-18.pdf

Ref13

eHealth Corporate standards (OLIS HL7 Messaging & Nomenclature Standard, Provincial Client Registry, eReferral, Discharge Summary, Clinical Document Specification, Consent Directive, Health Care Audit Event)

http://www.ehealthontario.on.ca/en/standards

Ref14 CBE101 IBM Common Base Events Specification V1.0.1, IBM. (CBE101)

Ref15 eHealth Ontario Provincial Client Registry Project Java Coding Standards Version 1.2

PCR - EMPI PubSub Java Coding Standards - v1.2 - Accepted - 20120823.doc

Ref16 WebSphere Enterprise Service Bus, Version 7.5

IBM WS ESB (WESB) Error handling in the ESB & mediation flow component

http://pic.dhe.ibm.com/infocenter/esbsoa/wesbv7r5/index.jsp?topic=%2Fcom.ibm.websphere.wesb.programming.doc%2Ftopics%2Fesbprog_errorhandlinginmfc.html

Ref17 Getting started with IBM Business Process Manager V7.5

http://pic.dhe.ibm.com/infocenter/dmndhelp/v7r5mx/index.jsp?topic=%2Fcom.ibm.wbpm.main.doc%2Ftopics%2Fcbpm_wbpm_gsg.html

http://www.w3.org/TR/2000/NOTE-SOAP-20000508/

http://www.w3.org/TR/2007/REC-soap12-part0-20070427/#L11549

http://www.w3.org/TR/2007/REC-soap12-part0-20070427/#L11549

http://www.w3.org/TR/soap12-part1/

http://www.w3.org/TR/2007/REC-soap12-part2-20070427/



http://www.ehealthontario.on.ca/en/standards







SOA Version: 1.4




Ref18

Getting Started with IBM WebSphere Process Server and IBM WebSphere Enterprise Service Bus Part 1: Development

IBM WS Process Server Exceptions Handling

http://www.redbooks.ibm.com/redbooks/pdfs/sg247608.pdf

Ref19 Handling Errors and Business Exceptions

http://www.sdn.sap.com/irj/scn/go/portal/prtroot/docs/library/uuid/80c19d47-4492-2a10-47a0-a2116a2aa9ff?QuickLink=index&overridelayout=true&23158463661009

Ref20

Ontario HIAL Goods and Services to Design, Build, Test, & Deploy the Ontario HIAL Solution Appendix F: Technology Stack

Appendix F - Technology Stack.doc

Ref21

Ontario HIAL Goods and Services to Design, Build, Test, & Deploy the Ontario HIAL Solution Appendix J: eHealth Ontario Standards

Appendix J - eHealth Ontario Standards.doc

Table 18 – References

http://www.redbooks.ibm.com/redbooks/pdfs/sg247608.pdf

soa service logging and exception handling standards · soa version: 1.4 service logging and...

Documents