SOA Service Logging and Exception Handling Standards

Transcription

1 SOA Service Logging and Exception Handling Standards

2 Contents 1 Purpose Scope eho SOA Service Logging Standards eho SOA Service Troubleshooting Standards Minimum Data Set for eho SOA Troubleshooting eho SOA Service Monitoring Standards Minimum Data Set for eho SOA Service Monitoring eho SOA Service Auditing Standards Minimum Data Set for eho SOA Service Auditing SOA Service Exception Handling (EH) Standards Minimum Data Set for eho SOA Service Exception Handling SOAP Fault SOAP v1.1 Fault Element SOAP v1.2 Fault Element Modeled WSDL Faults Un-modeled WSDL Faults ESB Exception Handling Standards Minimum Data Set for eho ESB Exception Handling Mediation Modules Components of the Mediation Modules Mediation Primitives Error handling in the Mediation Flow Component Mediation Flow Modeled Faults Mediation Flow Unmodeled Faults Mediation Component Error Flow Common Patterns for ESB Exception Handling Synchronous Invocation Asynchronous Invocation ehealth Ontario Confidential ii

3 5.6.3 Mixed Invocation Styles Business Process Management (BPM) Exception Handling Standards Minimum Data Set for eho BPM Exception Handling BPM Exception Handling Fault Handler Compensation Handlers Design-Time and Run-Time BPM Exceptions Handling Design-Time Exceptions Handling Run-Time Exceptions Common Patterns for BPM Exception Handling Internal Business Exception Pattern Timeout Exception Pattern System Fault Pattern Business Exception Throw-Catch Pattern Unsolicited External Business Exception Pattern Solicited Response Exception Pattern Transaction Compensation Pattern References ehealth Ontario Confidential iii

4 Document Location Local Drive TBD Document Revision History Version Date Author Description HIAL SOA Practice Created initial draft HIAL SOA Practice Updated to address initial team review comments HIAL SOA Practice Updated to address team review comments HIAL SOA Practice Updated to address further team review comments HIAL SOA Practice Updated to address further team review comments. ehealth Ontario Confidential iv

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. ehealth Ontario Confidential 5

6 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 Logging and Monitoring Standard Ontario Logging and Monitoring Standard Version: 1.1 Logging and Monitoring Standard_v1.1_ doc PCR - EMPI PubSub Java Coding Standards - v1.2-4 ehealth Ontario Provincial Client Registry Accepted doc Project Java Coding Standards Version 1.2 Table 2 - eho SOA Service Troubleshooting Standards ehealth Ontario Confidential 6

7 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 1 sys system name (eg: HIAL) Short Description 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 10 role uao from SAML token (applies only to services that require SAML token for authentication) 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) ehealth Ontario Confidential 7

8 # eho SOA Service Troubleshooting Minimal Data Set Short Description 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) 2 LOG4J Java-based logging utility framework Version Logging and Monitoring Standard Ontario Logging and Monitoring Standard Version: 1.1 Logging and Monitoring Standard_v1.1_ doc PCR - EMPI PubSub Java Coding Standards - v1.2-4 ehealth Ontario Provincial Client Registry Accepted doc Project Java Coding Standards Version 1.2 Table 4 - eho SOA Service Monitoring Standards 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 Minimal Data Set 1 sys system name (eg: HIAL) Short Description 2 app Application name ehealth Ontario Confidential 8

9 # 3 appid eho SOA Service Monitoring Minimal Data Set Short Description 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 10 role uao from SAML token (applies only to services that require SAML token for authentication) 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) 22 logfileid Unique troubleshooting logging file ID 23 userid User ID who requested web service or performed the action/operation 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 ehealth Ontario Confidential 9

10 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 û pdf Version: Release CBE101 IBM Common Base Events Specification V1.0.1, IBM. (CBE101) 4 LOG4J 5 Logging and Monitoring Standard Java-based logging utility framework Version 1.2 Ontario Logging and Monitoring Standard Version: 1.1 Logging and Monitoring Standard_v1.1_ doc 6 ehealth Ontario Provincial Client Registry Project Java Coding Standards PCR - EMPI PubSub Java Coding Standards - v1.2 - Accepted doc Version 1.2 Table 6 eho SOA Service Auditing Standards Minimum Data Set for eho SOA Service Auditing Following table describes minimal data set (information) required (if available) to be logged for the eho SOA service auditing purposes: # eho SOA Service Auditing Minimal Data Set Short Description 1 sys System name (eg: HIAL, ETC ) 2 app Application name 3 appid Application ID (eg: OLIS_GTWY_WSP_DEL, OLIS_BKBN_WSP (corresponding to IF in the app) ehealth Ontario Confidential 10

11 # eho SOA Service Auditing Minimal Data Set Short Description 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 10 role uao from SAML token (applies only to services that require SAML token for authentication) 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. 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) 22 logfileid Unique troubleshooting logging file ID 23 userid User ID who requested web service or performed the action/operation 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 ehealth Ontario Confidential 11

12 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. 5 CBE101 IBM Common Base Events Specification V1.0.1, IBM. (CBE101) 6 LOG4J 7 Logging and Monitoring Standard Java-based logging utility framework Version 1.2 Ontario Logging and Monitoring Standard Version: 1.1 Logging and Monitoring Standard_v1.1_ doc 8 ehealth Ontario Provincial Client Registry Project Java Coding Standards PCR - EMPI PubSub Java Coding Standards - v1.2 - Accepted doc Version 1.2 Table 8 eho SOA Service Exception Handling Standards ehealth Ontario Confidential 12

13 4.1 Minimum Data Set for eho SOA Service Exception Handling Following table describes minimal data set (information) required (if available) to be logged for the eho SOA service auditing purposes: # eho SOA Service Exception Handling Minimal Data Set 1 sys system name (eg: HIAL) Short Description 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 10 role uao from SAML token (applies only to services that require SAML token for authentication) 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) ehealth Ontario Confidential 13

14 # eho SOA Service Exception Handling Minimal Data Set Short Description 22 logfileid Unique troubleshooting logging file ID 23 userid User ID who requested web service or performed the action/operation 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 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 faultcode Description 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: Required - R Optional - O M VersionMismatch Invalid namespace defined in SOAP envelope element. The SOAP envelope must conform to ehealth Ontario Confidential 14

15 Fault Sybelement Name faultstring faultactor detail Description 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. Human-readable description of fault. URI associated with the actor (SOAP node) that caused the fault. In RPC-style messaging, the actor is the URI of the Web service. Application-specific information, such as the exception that was thrown. This element can be an XML structure or plain text. Required - R Optional - O M O O Table 10 SOAP v1.2 Fault Sybelements 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 env:code Description 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. Required - R Optional - O R env:value env:subcode 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. Subcode value that provides more information about the fault. This subelement can have a recursive structure. env:reason Human-readable description of fault. R R O ehealth Ontario Confidential 15

16 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 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 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. ehealth Ontario Confidential 16

17 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: # 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. 5 CBE101 IBM Common Base Events Specification V1.0.1, IBM. (CBE101) 6 LOG4J 7 Logging and Monitoring Standard Java-based logging utility framework Version 1.2 Ontario Logging and Monitoring Standard Version: 1.1 Logging and Monitoring Standard_v1.1_ doc 8 ehealth Ontario Provincial Client Registry Project Java Coding Standards PCR - EMPI PubSub Java Coding Standards - v1.2 - Accepted doc Version 1.2 Table 12 eho ESB Exception Handling Standards 5.1 Minimum Data Set for eho ESB Exception Handling Following table describes minimal data set (information) required (if available) to be logged for the eho ESB exception handling purposes: # eho ESB Exception Handling Minimal Data Set Short Description 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) ehealth Ontario Confidential 17

18 # eho ESB Exception Handling Minimal Data Set Short Description 4 invocationpath 5 mediationname 6 modulename List of previous primitives in the flow, executed up to the point of the failure (attribute of the failinfo element) The ID/name of the Fail mediation primitive instance that generated the mediation flow exception. The ID/name of the mediation module instance that contains the Fail primitive. 7 sys system name (eg: HIAL) 8 app Application name 9 appid Application ID (eg: OLIS_GTWY_WSP_DEL, OLIS_BKBN_WSP (corresponding to IF in the app) 10 txid Transaction ID 11 msgid Unique message ID 12 action the WS-Addressing action from the request (if there is one) 13 source SubjectDN if available 14 sourceip The client IP address 15 sourceid 16 role uao from SAML token (applies only to services that require SAML token for authentication) Role of the user that performed the action User role/privilege level - eg. supervisor, root, administrator, etc. 17 targeturi The full URL of the outgoing message 18 status Outcome of the transactions/action/operation (eg: SUCCESS for successful transactions ERROR for transactions that contain errors) Status of the message 19 entrytime Timestamp (UTFC format) 20 elapsedtime The overall execution time from the time it receives the requests and the time it forwards the response 21 message Entire message content 22 tid Original unique uuid generated by IF (stored in http header) 23 sessionid Unique session ID 24 threadid Thread ID 25 segmentid Federated segment will be used for federated HIAL (there are four segments: Prov, CSWO, CNEO, CGTA) 26 logginglevel Trace/Debug/Info/Warn/Error/Fatal ehealth Ontario Confidential 18

19 # 27 notification eho ESB Exception Handling Minimal Data Set Short Description Specify if notification is required (to whom and where notification should be sent) 28 logfileid Unique troubleshooting logging file ID 29 userid User ID who requested web service or performed the action/operation Table 13 Minimum Data Set for the eho ESB 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 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, analysed and determined. 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. ehealth Ontario Confidential 19

20 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 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 ehealth Ontario Confidential 20

21 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 failurestring origin invocationpath Description This attribute provides a exception message This attribute gives the primitive name. This attribute gives the list of previous primitives flowed through leading up to the failure. Table 14 Mediation Flow failinfo Attributes 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 ehealth Ontario Confidential 21

22 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 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 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. ehealth Ontario Confidential 22

23 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 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. ehealth Ontario Confidential 23

24 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. ehealth Ontario Confidential 24

25 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 ehealth Ontario Confidential 25

26 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 3 WSDL v2.0 Web Services Description Language v2.0 4 SOAP v1.1 Simple Object Access Protocol v1.1 5 SOAP v1.2 Simple Object Access Protocol v1.2 6 WS-Notification v1.3 WS-Notification is used for exposing asynchronous web services. 7 CBE101 IBM Common Base Events Specification V1.0.1, IBM. (CBE101) 8 LOG4J 9 Logging and Monitoring Standard Java-based logging utility framework Version 1.2 Ontario Logging and Monitoring Standard Version: 1.1 Logging and Monitoring Standard_v1.1_ doc 10 ehealth Ontario Provincial Client Registry Project Java Coding Standards PCR - EMPI PubSub Java Coding Standards - v1.2 - Accepted doc Version 1.2 Table 15 eho BPM Exception Handling Standards 6.1 Minimum Data Set for eho BPM Exception Handling Following table describes minimal data set (information) required (if available) to be logged for the eho ESB exception handling purposes: # eho BPM Exception Handling Minimal Data Set Short Description 1 failurestring Exception message (attribute of the failinfo element) 2 errorseverity Error severity (Single-letter exception message severity type code) ehealth Ontario Confidential 26

27 # eho BPM Exception Handling Minimal Data Set Short Description 3 origin Mediation primitive name (attribute of the failinfo element) 4 invocationpath 5 mediationname 6 modulename List of previous primitives in the flow, executed up to the point of the failure (attribute of the failinfo element) The ID/name of the Fail mediation primitive instance that generated the mediation flow exception. The ID/name of the mediation module instance that contains the Fail primitive. 7 sys system name (eg: HIAL) 8 app Application name 9 appid Application ID (eg: OLIS_GTWY_WSP_DEL, OLIS_BKBN_WSP (corresponding to IF in the app) 10 txid Transaction ID 11 msgid Unique message ID 12 action the WS-Addressing action from the request (if there is one) 13 source SubjectDN if available 14 sourceip The client IP address 15 sourceid 16 role uao from SAML token (applies only to services that require SAML token for authentication) Role of the user that performed the action User role/privilege level - eg. supervisor, root, administrator, etc. 17 targeturi The full URL of the outgoing message 18 status Outcome of the transactions/action/operation (eg: SUCCESS for successful transactions ERROAR for transactions that contain errors) Status of the message 19 entrytime Timestamp (UTFC format) 20 elapsedtime The overall execution time from the time it receives the requests and the time it forwards the response 21 message Entire message content 22 tid Original unique uuid generated by IF (stored in http header) 23 sessionid Unique session ID 24 threadid Thread ID 25 segmentid Federated segment will be used for federated HIAL (there are four segments: Prov, CSWO, CNEO, CGTA) ehealth Ontario Confidential 27

28 # eho BPM Exception Handling Minimal Data Set Short Description 26 logginglevel Trace/Debug/Info/Warn/Error/Fatal 27 notification Specify if notification is required (to whom and where notification should be sent) 28 logfileid Unique troubleshooting logging file ID 29 userid User ID who requested web service or performed the action/operation 30 processid BPM Process flow ID 31 activityid BPM Process Activity ID Table 16 Minimum Data Set for the eho BPM 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 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, analysed and determined. 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 ehealth Ontario Confidential 28

29 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 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 Design-Time Description 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". ehealth Ontario Confidential 29

30 BPM Exception Type Run-Time Description 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 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 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. ehealth Ontario Confidential 30