Technical Articles
IDoc-REST (Async-Sync) Scenario Approach with ALEAUD
Situation
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.
Approach
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(“http://sap.com/xi/XI/System/IDoc_AAE”, “DOCNUMS”);
return conf.get(docnums);
STATUS = 68 (Error) / 53 (Success)
STATXT = Error text in case of error
Result
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)
Example
References
SAP Note 2501469 – Improved HTTP result conversion for custom error messages
Hi Martin,
very useful article. Implemented in our environment and works.
Perfect described and understandable.
Thanks
Martin
Nice Blog Martin. Keep it up.
Cheers?
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.
Thanks for your feedback. I added a code example to the blog.
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
Thank you Martin.
I have added one more udf in the request mapping and that did the trick. it is working fine now.
Hi Guys,
I am slightly new to Sync-Async bridge config.
I have configured IDOC to REST ( GET operation ) to read Product details from a 3rd party.
The IDOC ( obviosuly is sync ) and my receiver service interface is ( Async ) .
Note : I have only 1 ICO.
When i run the scenario end-end, I get an error :
12/9/2019 02:24:27.247 PM
Information
Processing IDoc document list with 1 IDoc document(s) in single XI message
12/9/2019 02:24:27.247 PM
Information
Sender Party: Sender Service:DR2 Receiver Party: Receiver Service: Communication Channel:IDocAAE_Sender_75
12/9/2019 02:24:27.248 PM
Information
Processing IDoc document with number 0000000023435027
12/9/2019 02:24:27.248 PM
Information
Sending an XI message to module processor...
12/9/2019 02:24:27.248 PM
Information
MP: processing local module localejbs/AF_Modules/MessageLoggerBean
12/9/2019 02:24:27.249 PM
Information
MP: processing local module localejbs/CallSapAdapter
12/9/2019 02:24:27.249 PM
Information
Application attempting to send an XI message asynchronously using connection IDoc_AAE_http://sap.com/xi/XI/System
12/9/2019 02:24:27.257 PM
Information
Trying to put the message into the send queue
12/9/2019 02:24:27.278 PM
Information
Message successfully put into the queue
12/9/2019 02:24:27.278 PM
Information
The application sent the message asynchronously using connection IDoc_AAE_http://sap.com/xi/XI/System. Returning to application
12/9/2019 02:24:27.285 PM
Information
The message was successfully retrieved from the send queue
12/9/2019 02:24:27.290 PM
Information
Message status set to DLNG
12/9/2019 02:24:27.290 PM
Information
Trying to put the message into the send queue
12/9/2019 02:24:27.306 PM
Information
Message successfully put into the queue
12/9/2019 02:24:27.307 PM
Information
The message was successfully retrieved from the send queue
12/9/2019 02:24:27.310 PM
Information
Message status set to DLNG
12/9/2019 02:24:27.328 PM
Information
Trying to put the message into the send queue
12/9/2019 02:24:27.352 PM
Information
Message successfully put into the queue
12/9/2019 02:24:27.353 PM
Information
The message was successfully retrieved from the send queue
12/9/2019 02:24:27.357 PM
Information
Message status set to DLNG
12/9/2019 02:24:27.357 PM
Information
Executing Request Mapping "http://pentland.com/test/MATMAS05_ZMATMAS_3PL_to_ProductCatalogueSKU" (SWCV 14d63e506fdf11e0a1e0f9baac10071c)
12/9/2019 02:24:27.419 PM
Information
Trying to put the message into the send queue
12/9/2019 02:24:27.448 PM
Information
Message successfully put into the queue
12/9/2019 02:24:27.448 PM
Information
The message was successfully retrieved from the send queue
12/9/2019 02:24:27.451 PM
Information
Message status set to DLNG
12/9/2019 02:24:27.452 PM
Information
Trying to put the message into the send queue
12/9/2019 02:24:27.473 PM
Information
Message successfully put into the queue
12/9/2019 02:24:27.473 PM
Information
The message was successfully retrieved from the send queue
12/9/2019 02:24:27.477 PM
Information
Message status set to DLNG
12/9/2019 02:24:27.477 PM
Information
Delivering to channel: RESTReceiverProductCatalogueSKUGET
12/9/2019 02:24:27.477 PM
Information
MP: processing local module localejbs/AF_Modules/DynamicConfigurationBean
12/9/2019 02:24:27.478 PM
Information
DC: processing ...
12/9/2019 02:24:27.478 PM
Information
write property module.idocnumber from key (http://sap.com/xi/XI/System/IDoc_AAE)DOCNUMS with value 0000000023435027;
12/9/2019 02:24:27.478 PM
Information
DC: processing ...
12/9/2019 02:24:27.478 PM
Information
write property module.idocnumber from key (http://sap.com/xi/XI/System/IDoc_AAE)DOCNUMS with value 0000000023435027;
12/9/2019 02:24:27.478 PM
Information
DC: successfully processed
12/9/2019 02:24:27.478 PM
Information
MP: processing local module localejbs/AF_Modules/RequestResponseBean
12/9/2019 02:24:27.478 PM
Information
RRB: entering RequestResponseBean
12/9/2019 02:24:27.478 PM
Information
RRB: suspending the transaction
12/9/2019 02:24:27.478 PM
Information
RRB: forwarding the request message
12/9/2019 02:24:27.478 PM
Information
RRB: leaving RequestResponseBean
12/9/2019 02:24:27.478 PM
Information
MP: processing local module localejbs/sap.com/com.sap.aii.adapter.rest.app/RESTAdapterBean
12/9/2019 02:24:27.484 PM
Information
Set HTTP Header Authorization to ***
12/9/2019 02:24:27.484 PM
Information
Calling server: GET XXXXXXXXXXXXXXXXXXXX
12/9/2019 02:24:28.011 PM
Information
Server returned code: 200
12/9/2019 02:24:28.011 PM
Information
Processing result
12/9/2019 02:24:28.023 PM
Information
REST call finished
12/9/2019 02:24:28.023 PM
Information
MP: processing local module localejbs/AF_Modules/DynamicConfigurationBean
12/9/2019 02:24:28.023 PM
Information
MP: processing local module localejbs/AF_Modules/ResponseOnewayBean
12/9/2019 02:24:28.024 PM
Information
ROB: entering ResponseOnewayBean
12/9/2019 02:24:28.024 PM
Information
ROB: resuming the transaction
12/9/2019 02:24:28.024 PM
Information
ROB: sending to the messaging system ...
12/9/2019 02:24:28.024 PM
Error
ROB: error during processing: com.sap.engine.interfaces.messaging.api.exception.ConfigException: No sender agreement configured that matches the messages header fields (sender party: "", sender service: "SALSIFY", interface: "http://pentland.com/test ProductCatalogueSKU_In_Response", receiver party: "", receiver service: "DR2")
12/9/2019 02:24:28.024 PM
Error
MP: exception caught with cause com.sap.engine.interfaces.messaging.api.exception.ConfigException: No sender agreement configured that matches the messages header fields (sender party: "", sender service: "SALSIFY", interface: "http://pentland.com/test ProductCatalogueSKU_In_Response", receiver party: "", receiver service: "DR2")
12/9/2019 02:24:28.027 PM
Error
Exception caught by adapter framework: No sender agreement configured that matches the messages header fields (sender party: "", sender service: "SALSIFY", interface: "http://pentland.com/test ProductCatalogueSKU_In_Response", receiver party: "", receiver service: "DR2")
12/9/2019 02:24:28.028 PM
Error
Transmitting the message to endpoint <local> using connection IDoc_AAE_http://sap.com/xi/XI/System failed, due to: com.sap.engine.interfaces.messaging.api.exception.ConfigException: No sender agreement configured that matches the messages header fields (sender party: "", sender service: "SALSIFY", interface: "http://pentland.com/test ProductCatalogueSKU_In_Response", receiver party: "", receiver service: "DR2")
12/9/2019 02:24:28.033 PM
Information
Message status set to WAIT
12/9/2019 02:24:28.033 PM
Information
The asynchronous message was successfully scheduled to be delivered at Mon Dec 09 14:29:28 GMT 2019
Can you please guide me what could go wrong ?
Regards
Saurabh
Hi Experts,
Can someone help please ?
Regards
Saurabh
Hi All,
This worked. The solution was using the virtual receiver.
Regards
Saurabh
Is the module.idocnumber available directly for use as a parameter of IDoc_AAE Adapter or it is supposed to be defined in the UDF?
module.idocnumber is used to temporary store the IDoc number. Otherwise the IDoc number is lost after the sync call as it is not part of the response message/payload.
Thanks Martin. Got it.
Great post, Thanks for sharing! I had a similar project request and was able to implement using your example.
I did everything like the post, but receiveing the message:
MP: exception caught with cause com.sap.engine.services.jndi.persistent.exceptions720.NameNotFoundException: Object not found in lookup of ResponseOneWayBean.
Error message
Can someone take a look at this?
Module names are case-sensitive. Please use AF_Modules/ResponseOnewayBean.
It worked, thank you so much Martin.
Hi Martin,
Thanks for your blog.
I am wondering if we are able to write something on the dynamic config on the request mapping with an UDF and read that value on the response mapping with another UDF?
Because in my scenario, I need to pass some other values too apart from idoc number like last 4 digits of RCVPRN on the original idoc or VKORG field on the original idoc data.
I have tried with below UDFs but couldn't get the value on the response mapping.
Thanks very much.
Hi Again,
I've sorted that by adding each and every field to the module configuration.
Any easier solutions or comments are more than welcome.
Thanks.