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
