Skip to Content
Technical Articles

IDoc-REST (Async-Sync) Scenario Approach with ALEAUD


IDoc is a standard SAP format for electronic data exchange between systems. A typical use case is the integration of a SAP Backend system like SAP S/4HANA via SAP Process Orchestration with a 3rd Party REST service. This requires the connection of an asynchronous IDoc message with a synchronous REST call.

The connection of an asynchronous and a synchronous interface is typically no issue as long no messages are failing. In this case both technical errors (e.g. HTTP 40X) and application errors (e.g. HTTP 500) will be raised on SAP Process Orchestration.

On the other hand there is no monitoring in the backend system possible if the IDoc was successfully transferred to the target service.



To improve and simplify the operation of the scenario, errors should be visible and raised where the equivalent processor is. Technical errors on SAP Process Orchestration, application errors on SAP Backend.

Additionally confirmation should be sent back to the sender system that the message was successfully processed by the target system.

Key Implementation Steps

(1) Set Adapter-specific Message Attributes in IDoc Sender channel

By setting the adapter-specific message attributes the IDoc adapter will store the IDoc metadata (IDoc number, etc.) to the message header. This information will be used later.


(2) Preserve IDoc number of source IDoc in REST receiver channel

To keep the reference to the original IDoc it is required to preserve the IDoc number during the complete message processing. The DynamicConfigurationBean is used to save the IDoc number of the source message to the module context. After the processing of the REST adapter the DynamicConfigurationBean restores the IDoc number from the module context back to the message header of the response message.


(3) Implement Async-Sync bridge in REST receiver channel

RequestResponseBean and ResponseOnewayBean are used to implement the standard async-sync bridge by module adapters.


(4) Call REST Adapter with Parameters

Depending on the REST service there might by additional parameters necessary.


(5) Implement HTTP Status Code handling in REST receiver channel

In case of a non-technical error (typically HTTP 500) a response message should be triggered. From PI monitoring perspective the message will be treated as successful and no error will be raised.

Additionally for successful processing a response message should be triggered as positive acknowledgement.


(6) Map response message to ALEAUD IDoc

Following fields have to be mapped for a valid ALEAUD message.

DOCNUM = The IDoc number of the source IDoc message. UDF required to read the adapter-specific message attributes

DynamicConfiguration conf = (DynamicConfiguration)container.getTransformationParameters().get(StreamTransformationConstants.DYNAMIC_CONFIGURATION);

DynamicConfigurationKey docnums = DynamicConfigurationKey.create(“”, “DOCNUMS”);

return conf.get(docnums);

STATUS = 68 (Error) / 53 (Success)

STATXT = Error text in case of error


The ALEAUD IDoc will trigger an update of the original IDoc and will change the IDoc status.

IDOC Status 40 = Error (Error text visible)

IDOC Status 41 = Positive Acknowledgment (IDoc successfully processed by target service)




SAP Note 2501469 – Improved HTTP result conversion for custom error messages


You must be Logged on to comment or reply to a post.
  • Hi Martin,

    very useful article. Implemented in our environment and works.
    Perfect described and understandable.







  • Hi Martin,

    It is very useful blog for new comers like me. I am working on the same scenario just as explained. I have done all the configurations as mentioned and everything is working except I am not able to write an UDF to populate the IDOC number (DOCNUM) back to ALEAUD.

    Can you please share the udf for the same which will help me alot.

    Thank you in advance.

  • Hi Martin,


    It is very nice blog. I almost have the same scenario and i have achieved the async sync bridge with the classic IDOC.

    My issue is I am unable to get the IDOC number back in response interface. As you know we dont need to create the sender channel for classic way which i cannot Set Adapter-specific Message Attributes in IDoc Sender channel.

    Is it possible to do the same scenario using classic IDOC instead of IDOC_AAE ?

    Please let me know.

    Thanks for the blog again.

    • This should be possible. The IDoc number is also part of the payload. For example by using an UDF at the request mapping which saves the IDoc number of the payload to the DynamicConfiguration.

      • Hi,

        I have configured IDOC_AAE and performed all the steps as mentioned but I am not getting DOCNUM in the response.

        I have created 1 rest receiver channel where I have mentioned the write and read modules to capture the docnum. And the same rest channel works as rest sender in the runtime as we are async sync bridge. Everything is working and no errors so far but not getting the doc number in the response even though i have mapped with the udf but no luck. I will appreciate your suggestions.

        Is there any other place where I can see the dynamic configuration is working in the payload.

        Please help.

        • The module configuration looks ok. I would recommend to check first if in the DynamicConfiguration of the request message the IDOC number is available.


          • Hi Martin,


            Yes, I am not getting the value in the Dynamic Configuration of the request message. I am not sure why it is not populating in the dynamic configuration. Do i need to use any udf in the request mapping for this. If yes, where can i use that as the receiver doesn’t require the data in the structure.



            Please find my request IDOC structure