B2b web Service Guidelines V2 rsvz enterprise Architecture

1. Error Handling

   1. Guideline

1. 
   In general, a distinction MUST be made between the following conceptual Error Types:
   
   1. 
      Business Errors indicate violation of some business rule
      
   2. 
      System Errors are infrastructure related errors
      

Business errors are identified as part of a business process. The guidelines do not define how these errors are reported to a consumer.

2. 
   When applicable, the SOAP faults that are defined in Helper_Vx.wsdl MUST be used to report System Errors:
   

• 
  AuthenticationFault
  
• 
  AuthorizationFault
  
• 
  SystemFault
  
• 
  ValidationFault
  
• 
  FluxSyncFault
  

3. 
   Depending on the operation type, whether or not a specific fault may appear, MUST adhere to the rules summarized in the table below. ‘Yes’ means the given fault may appear in the result, ‘No’ means the given fault must never appear in the result, ‘n/a’ indicates that there is no reply possible.
   

In POW, FluxSyncFaults MUST be reported by invoking a HandleFluxSyncFault operation on the service interface provided by the consumer.

4. 
   SOAP faults defined by the Guidelines have further restrictions:
   
   1. 
      {soap}faultcode: element MUST contain either {soap}Client or {soap}Server.
      
   2. 
      {soap}Client: this value MUST only be used for AuthenticationFault, AuthorizationFault, ValidationFault and FluxSyncFault, with the interpretation given by the SOAP 1.1 specification.
      
   3. 
      {soap}faultstring SHOULD contain a (high-level) human readable description of the fault.
      
   4. 
      {soap}faultactor SHOULD contain “{MetaInfo}ErrorBaseStruct.Origin.Organization + ‘.’ + {MetaInfo}ErrorBaseStruct.Origin.Application
      

2. Explanation

• 
  A Business Error is a violation of some business rule.
  It may be interpreted by the (human or machine) user, and resolved, e.g. by changing input data.
  
• 
  A System Error is purely software-technical, often infrastructure related.
  A user is typically informed in a general way, saying that ‘a general system error occurred – please contact your system administrator at phone...”. Users will merely report it to the helpdesk, and technical personnel (system operators, developers…) take action to resolve it.
  

The table below shows how concrete errors map to these conceptual errors:

Business Errors may be reported as a specific fault – defined in a service interface definition - but they can also be an ordinary one-way message or an ordinary reply in a request-reply message. However, System Errors should never be communicated as an ordinary xml element in a reply or message.

1. Handling of System Errors - Idempotence

   1. Guideline

1. 
   System Errors include the following:
   

• 
  TCP/IP errors
  
• 
  HTTP errors
  
• 
  SOAP faults generated by SOAP infrastructure
  
• 
  AuthenticationFault, AuthorizationFault, SystemFault, ValidationFault and FluxSyncFault faults
  

2. 
   Senders that detect a System Error, and that want to resend the same message, MUST use the same {MetaInfo}ApplHeader.MessageID, {MetaInfo}ApplHeader.Origin (MetaInfo < V6) and – when applicable - {MetaInfo}ApplHeader.FluxDescriptor.
   

3. 
   Receivers MUST implement idempotence via the combination of Origin and MessageID:
   If an incoming message has the same MessageID and sender - identified by {MetaInfo}OriginOrganization (MetaInfo < V6) or client certificate (MetaInfo >= V6)- as a previous message, and that message was already processed by business logic, then:
   
   1. 
      This message MUST NOT be processed again by the business logic.
      
   2. 
      The original response SHOULD be returned, or a new one MAY be generated giving the same result.
      

2. Explanation

3. Example

System Error Analysis The figure below shows a sender and receiving application, SOAP service endpoints and a HTTP transport. The arrows show the message exchange. The red crosses show possible locations of infrastructure-related errors. Component Contains... Error examples Send – Service Endpoint Generated code from WSDL or Service Bus HTTP client software TCP/IP client software Invalid message or operation detected Problem with http or tcp/ip client infrastructure HTTP Transport tcp/ip network, routers, gateways, firewalls... Any failure in any network component Recv – Service Endpoint Generated code from WSDL or Service Bus HTTP server software TCP/IP server software Crash Validation error Receiver Application Business logic interpreting request. For request-reply only generates a response (no response for pseudo one-way). Crash System error Business error Remember that for pseudo one-way the reply message contains a fixed ‘delivery ack’ message or a fault. Also for request-reply the reply message contains a business result or a fault. Assuming the errors occur where red crosses appear, the following table describes in detail what the error is, and what the possible consequences are. They are grouped by Request-Reply and Pseudo One Way. Error in... Processed by Receiver App? Comment Request-Reply 1 No The sender application immediately detects an error, typically as a SOAP fault or another means determined by the tools used.  The sender MUST redo the operation. 2 No The sender application immediately detects an error, a TCP/IP error like ‘connection lost’.  The sender MUST redo the operation. 3 No The sender application immediately detects an error: Crash, System malfunction: TCP/IP error General system or software error:: HTTP error, SOAP fault Validation Error: SOAP fault of type SystemError.  The sender MUST redo the operation. 4a Unsure The sender application immediately detects an error. Crash, System malfunction: TCP/IP error or SOAP fault General system or software error: HTTP error or SOAP fault  The sender MUST redo the operation. If the transport between the endpoint at the receiver and the receiver itself is not reliable, and the recSince it is unsure whether the operation has already been processed by business logic, the operation must be resent, using the same MessageID/Origin. The receiver must reject an already processed message, based on this MessageID/Origin. Note: alternatively the operation itself can be idempotent, by including the old and new values. This is out of scope of this specification, since it involves the applications themselves. 5 Yes (but not always known to sender) The sender application immediately detects an error: Crash, System malfunction: TCP/IP error  The sender MUST redo the operation, since request may not be processed. General system or software error:: HTTP error, SOAP fault  The sender MUST redo the operation, since request may not be processed. Validation Error in reply: SOAP fault of type SystemError  The sender MUST redo the operation after receiver has fixed the problem. 6 Yes, but not known to Sender Idem to 2. 7 Yes The sender application immediately detects an error, typically as a SOAP fault or another means determined by the tools used. Typically the sender side must correct the problem and redo the operation. Pseudo One-Way Note that the reply message is either a ‘delivery ack’ or SOAP fault. Also, there is no processing in the Receiver Application for what error handling is concerned. 1 No Idem request-reply. 2 No Idem request-reply. 3 No Idem request-reply. 4b Unsure Problems at this stage are where the Receiver Application cannot be reached by the Receiver Service Endpoint. In this case a SOAP fault with a specific SystemError is returned.  The sender MUST retry the operation. 5 Unsure The Sender Application immediately detects an error: Crash, System malfunction: TCP/IP error  The sender MUST retry the operation, since request may not be processed General system or software error: HTTP error, SOAP fault  The sender MUST retry the operation, since request may not be processed 6 Yes, but not known to Sender Idem request-reply. 7 Yes Idem request-reply. This shows that multiple types of errors can be detected: TCP/IP errors, HTTP errors, SOAP faults. It also shows that in general a sender cannot know whether a message has been functionally processed or not when receiving a system error. If the transport between the Receiver Service Endpoint and the Receiver Application is not reliable, then the Receiver Application MUST ensure the operation is idempotent. Idempotency Choices For idempotency there are two options: The operation is made idempotent, e.g. by adding the old and new state in the message. The receiver uses the MessageID/Origin of the operation to detect and prevent re-execution. The first solution is visible at the functional application level, so functional analysis is necessary. Also the size of messages is doubled. Therefore the second solution is the one chosen.

9. Support for Fluxes

   1. Guideline

1. 
   When a Flux is used it MUST be documented in an Interface document using a Flux Chart.
   
2. 
   If an operation (i.e. message) is part of a Flux, a FluxDescriptor element of type FluxDescriptorStruct MUST be provided as first parameter after the ApplHeader by the sending party that starts the flux, and it must be preserved in all further operations that are part of that flux.
   

3. 
   NISSE MUST check that all operations that participate in a Flux are consistent with that Flux.
   
4. 
   SIFs MAY check that all operations that participate in a Flux are consistent with that Flux.
   

2. Explanation

1. Binary content

   1. Guideline

1. 
   Binary data MUST be defined as an element of type xs:base64Binary in XML Schemas.
   
2. 
   A web service MUST use MTOM for transferring binary content.
   
3. 
   Policy assertions MUST NOT be used to indicate the use of MTOM.
   

2. Explanation

3. Example

Date: Wed, 02 Jun 2010 08:33:16 GMT

Transfer-Encoding: chunked

Content-Type: multipart/related;start="";type="application/xop+xml";boundary="uuid:6a38ae26-b022-40d6-944c-f79d4c7a7df3";start-info="text/xml"

Content-Id:

Content-Type: application/xop+xml;charset=utf-8;type="text/xml"

Content-Transfer-Encoding: binary

Content-Id: <95ddae49-0d13-4619-8c05-257bca13204b@example.jaxws.sun.com>

Content-Type: application/octet-stream

Content-Transfer-Encoding: binary