Forward Error HandlingLocate this document in the navigation structure

Use

Forward Error Handling (FEH) is a functionality provided by the ABAP runtime. You can use it when implementing service providers. It allows the processing of errors detected on the provider side when performing asynchronous service communication.

Asynchronous communication implies that the receiver of a service request can receive a service call and detect errors, processing them after the sending application's session has ended. In contrast to synchronous communication, in asynchronous communication if the receiver returns the errors immediately, neither the sending application session nor the user of that consumer application is readily available to take care of timely error removal. This may be evident if the service is anyway uni-directional, because no “rejection message” is foreseen in the consumer-provider interaction - as is the case for inbound Notification and Information services. The statement also applies to services following the Request-Confirmation and Query-Response transaction patterns.

You can develop asynchronous inbound service operations so that they support forward error handling. This way, if the system detects an error while executing a service call, it behaves as follows:

  • It does not reject immediately to perform the requested service.

  • It does not send back immediately a “rejection message” containing error information to the service consumer.

Instead, the system uses the FEH framework and tries to resolve the issue on the provider side. For example, if the issue is expected to be temporary only, the system can try to re-execute the service call after certain period of time. Alternatively, it might be needed to contact a business user to resolve the issue.

Issues typically occur during data conversion or business logic processing. When administrators or business users detect that the system tries to handle the errors on the provider side, they can investigate the error messages to solve the issue. The resolution process depends on the type of error. An error may be resolved automatically, resolved manually, or rejected and delegated back to the consumer.

Prerequisites

In addition to the generated proxy class, you need a class for the service implementation. For more information, see Point-to-point Communication for Asynchronous Services.

Procedure

Implementation Overview

All access to Web services and XI runtime information has to be implemented in the proxy class, for example:

  • Deactivate extended XML handling.

  • Set update task local.

    The proxy class calls method EXECUTE of your service implementation class.

Do the following within the service implementation class:

  • Call the mapping from input message proxy structure to the business logic API.

  • If any error occurs, collect the data for forward error handling, and at the latest initialize the FEH framework.

  • Else, call the business logic API.

  • If any error occurs during business logic execution, collect the data for forward error handling, and at the latest initialize the FEH framework.

  • If an error occurred during the service execution, for example, in mapping or business logic, raise the exception corresponding to your fault message.

Implementation Steps for the Service Class

  1. Create a DDIC structure, which contains the complete API input parameters.

    In case the inbound service has a corresponding outbound Confirmation or Response service, you should in addition include a RESPONSE_REGISTRATION field, typed as a GUID, and the Message Header structure message. It may be needed in a confirmation message.

  2. In the EXECUTE method, create an instance of class CL_FEH_REGISTRATION using static method S_INITIALIZE. In case of bulk messages, pass abap_false in parameter IS_SINGLE.

    If you design the service implementation as described above, the next steps are as follows. If you prefer a different design, the exact next steps are somewhat different, but your design has to ensure the same perceivable run-time behavior, in particular with respect to the service execution restart capabilities.

  3. Create a PROCESS method with at least the following parameters:

    • I_PRE_MAPPING

      Proxy DDIC structure containing the entire message before the inbound mapping (typed optional).

    • I_POST_MAPPING

      DDIC structure containing the data after inbound mapping. This is the information passed to the business logic API (typed optional).

    • I_REF_REGISTRATION

      Instance of CL_FEH_REGISTRATION.

    • <Fault message exception>

      Instead of raising the exception in this method you may return BAPIRETTAB and handle the errors in the underlying methods.

    This method is to be called by the EXECUTE method. The process method itself can be called from the proxy implementation with I_PRE_MAPPING filled and from the Retry-Callback method. In the Retry-Callback the parameter I_PRE_MAPPING is filled if the error occurred in the mapping. If the error occurred in the business logic API, the parameter I_POST_MAPPING is filled.

    Thus, the method process can be called with pre-mapping data or business logic API data.

  4. If I_POST_MAPPING is false, call the inbound mapping method.

  5. If any error occurs during this mapping:

    • Determine the main error.

    • Categorize the error.

    • Call the COLLECT method from instance I_REF_REGISTRATION.

      The parameters of method COLLECT should be filled as follows:

      • SINGLE_BO

        The input data to the mapping as structure.

      • SINGLE_BO_REF

        Reference to the input data to the mapping. You must supply either SINGLE_BO or SINGLE_BO_REF. Do not supply both.

      • ERROR_CATEGORY

        Error category of the main error, as in the table /SAPPO/SERR_CAT.

      • MAIN_MESSAGE

        Main error message.

      • MESSAGES

        Table of other error messages (optional).

      • MAIN_OBJECT

        Object that caused the errors (-OBJCAT and -OBJTYPE as in table /SAPPO/S_OBJECT, -OBJKEY should be filled with the object key).

      • OBJECTS

        List of further objects involved (optional).

      • PRE_MAPPING

        Pass abap_true.

    • Skip the next two steps.

  6. Call the business logic API with the mapped data.

  7. If the API call returns an error, proceed in the following way:

    • Determine the main error.

    • Categorize the error.

      You can refer to /SAPPO/SERR_CAT.

    • Call method COLLECT from instance I_REF_REGISTRATION. The parameters of method COLLECT are to be filled as follows:

      • SINGLE_BO

        The input data to the API call as structure.

      • SINGLE_BO_REF

        Reference to the input data to the API call. You must supply either SINGLE_BO or SINGLE_BO_REF. Do not supply both.

      • ERROR_CATEGORY

        As described in step 5 above.

      • MAIN_MESSAGE

        Error message from the application call.

      • MESSAGES

        As described in step 5 above.

      • MAIN_OBJECT

        As described in step 5 above.

      • OBJECTS

        As described in step 5 above.

      • PRE_MAPPING

        Pass abap_false, respectively leave this field blank.

  8. Finally, if any error occurs, raise the exception that is the proxy for your inbound service's standard fault message.