Error Response Control for Backend Data Provider

The response of an OData request causing an error looks like this example:

<error xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">
      <code>/IWBEP/CM_TEA/004</code>
      <message xml:lang="en">'TEAM_012345678' is not in the defined range.</message>
      <innererror>
           <transactionid>4FE1D144B9AD22F2E10000000A420C41</transactionid>
           <errordetails>
                <errordetail>
                     <code>/IWBEP/CM_TEA/002</code>
                     <message>'TEAM_012345678' is not a valid ID.</message>
                     <propertyref>Team/Team_Identifier</propertyref>
                     <severity>error</severity>
                </errordetail>
                <errordetail>
                     <code>/IWBEP/CM_TEA/004</code>
                     <message>Team ID 'TEAM_012345678' is not in the defined range.</message>
                     <propertyref>Team/Team_Identifier</propertyref>
                     <severity>error</severity>
                </errordetail>
                <errordetail>
                     <code>/IWBEP/CX_TEA_BUSINESS</code>
                     <message>'TEAM_012345678' is not a valid ID.</message>
                     <propertyref/>
                     <severity>error</severity>
                </errordetail>
          </errordetails>
     </innererror>
 </error>

This error response contains the following artifacts:

• Error code

  The T100 message class and number of the error message.

  In this example it is /IWBEP/CM_TEA/004.

• Error message

  The text of the error message.

  In this example it is Team ID 'TEAM_012345678' is not in the defined range.

• Transaction Id

  This ID identifies traces belonging to one transaction on all involved systems.

  In this example it is 4FDF3748112322F4E10000000A420C41.

• One or several error detail entries which each contains:

  • Inner error code

    The T100 message class and number of the error message or the name of the exception class that contributed this error. In this example it is /IWBEP/CM_TEA/004.

  • Inner error message

    The text of the error message.

    In this example it is Team ID 'TEAM_012345678' is not in the defined range.

  • Property reference

    The XPATH expression (entity type / property name) pointing to the corresponding property for this message if available. In this example it is Team/Team_Identifier or empty.

  • Severity

    Possible severities are info, warning and error. In this example it is error.

A backend data provider can control this error by the exception it raises and optionally also by adding messages to the message container of the raised exception.

To trigger an error a backend data provider application raises a business exception or a technical exception:

• A business exception is class /IWBEP/CX_MGW_BUSI_EXCEPTION or a class inheriting from it.

• A technical exception is class /IWBEP/CX_MGW_TECH_EXCEPTION or a class inheriting from it.

Each exception of the exception chain (provided by the previous exception when raising a business or technical exception) will be mapped to an error detail entry, as shown in the following example.

            <errordetail>    
    <code>/IWBEP/CX_TEA_BUSINESS</code>
    <message>'TEAM_012345678' is not a valid ID.</message>    
    <propertyref/>    
    <severity>error</severity>    
    <target>ID</target>
</errordetail>
         

One of these messages may be marked as the leading message. If a leading message is added to the message container its code and text will be used as the error code and error message of the error response.

A backend data provider can also use the message container (interface /IWBEP/IF_MESSAGE_CONTAINER) to add one or several messages to the exception it raises.

A backend data provider has several options of how to control the error response:

• Exception only

  The backend data provider triggers an exception.

• Exception with message container but without leading message

  The backend data provider triggers an exception where the message container contains one or several messages. Only messages with the attribute IS_LEADING_MESSAGE set to FALSE have been added to the message container.

• Exception with message container with leading message

  The backend data provider triggers an exception where the message container contains one or several messages. At least one message with the attribute IS_LEADING_MESSAGE set to TRUE has been added to the message container.

Depending on the option chosen by the backend data provider the framework behaves as follows.

A backend data provider can set the HTTP status code when raising a business or technical exception.

A backend data provider should log all messages relevant for error analysis but that are not relevant for an end user via the logger (class /IWBEP/CL_COS_LOGGER). This writes these logs into the Application Log and optionally also into the Computing Center Management System (CCMS).

It is possible to overwrite the outer message code of the error, for example <code>Message Code from Exception</code>:

<?xml version="1.0" encoding="utf-8"?>

<error xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">

    <code>Message Code from Exception</code>

    <message xml:lang="en">This is a message text of a business exception raised by the provider.</message>

    <longtext_url>/sap/opu/odata/iwbep/message_text;o=G1Y_400_BEP/T100_longtexts(MSGID='%2FIWBEP%2FCM_TEA',MSGNO='010',MESSAGE_V1='RAISE_BUSI_EXCEPTION_DETAILS',MESSAGE_V2='',MESSAGE_V3='',MESSAGE_V4='')/$value</longtext_url>

    <innererror>

        ...

    </innererror>

</error>

The base exception on the backend side /IWBEP/CX_MGW_BASE_EXCEPTION has a new parameter msg_code in the constructor, to set the message code. It is also possible to set the message code in the message container: /IWBEP/IF_MESSAGE_CONTAINER~SET_MESSAGE_CODE().