Bridges Construction Site (1/3): Asynchronous - sy...

Former Member · ‎03-26-2014

Hello colleagues!

I saw a bunch of good articles on this topic, for example:

Generic PI Async-Sync Bridge Configuration for Any Adapters by william.li

But we had some interesting conversations on our local russian xi/pi forum recently that shows me some gaps in the information about bridges.

This is translation from Russian, this text was initially created for my web-site. Sorry for copyrighted pictures. :smile:

Source: http://sap.pitroff.ru/navodim-mostyi-ili-kak-svyazat-mezhdu-soboy-asinhronnyiy-i-sinhronnyiy-interfe...

-------------------

1. What is the "bridge" in the integration?

Sometimes SAP Process Integration development gives you a challenge. For example, you want to receive a file from a system (asynchronous mode), convert it to an RFC-call for SAP ERP ( synchronous mode ), and upload the response as a file to an FTP server ( asynchronous mode) .

Or another task: your ABAP program needs to request additional information from the external system (synchronous mode). The problem is that external system using web-services in asynchronous mode only, so you need to call external system and provide some web-service to get answer. More than that – you need to transfer this response to the initial ABAP program, waiting for the answer.

These problems can be summarized as follows :

Figure 1 : Asynchronous - synchronous bridge

Figure 2 : Synchronous - Asynchronous Bridge

There are two solutions possible for this kind of problems:

Use ccBPM. To do this you need to create the integration process in SAP PI and use it to build the bridge elements .
➕ - the bridge can be used in a complex process with multiple systems.
➖ - development and testing time, the complexity of monitoring and debugging , ccBPM is not available in Single Stack installations.

I recommend this way only if you want to use a bridge as a part of complex ccBPM processes.
You can read more about ccBPM async-sync and sync-async bridges on help.sap.com: «Example: Sync / Async Communication».

Use standard adapter modules.
➕ - speed of development is comparable with ordinary interface uses standard design elements; simple debugging and monitoring.
➖ - you need to be careful filling module parameters; it is difficult for beginners; source code of modules is not available; confusing ( and sometimes contradictory ) information on the Internet .

Let's take a closer look to the second method for constructing bridges.

2 . Async-Sync Bridge. RequestResponseBean and ResponseOnewayBean.

Let's start from the asynchronous-synchronous bridge, this is the case when the sender system is operating in asynchronous mode, i.e. sending a request and waiting for a response are handled by two different (independent) tasks. Target system synchronizes request and response, and sends a response to the same channel which the request came from (Fig.1).

The bridge using two standard modules for using in communication channels:

• RequestResponseBean is responsible for converting an asynchronous message to the synchronous and for transferring it to the next module in the adapter modules chain or to send it to the messaging subsystem of PI.

• ResponseOnewayBean – the module, which converts a synchronous response message to the asynchronous and redirects it to the receiver.

The modules can be used in the sender communication channel or in the receiver communication channel.

Additional Information: adapter modules are executed one after another in the stacking order (top-down) on the «Module» tab of the Communication Channel settings. Output of each module is the input for the next one. The list of modules usually includes standard adapter module - CallSAPAdapter.

Module parameters can be configured on the «Module» tab too - in the «Module Configuration» section.

For using modules in the Communication Channel you should go to the tab «Module» and enter the following values:

MODULE NAME	TYPE	MODULE KEY
AF_Modules/RequestResponseBean	Local Enterprise Bean	RqResp
CallSAPAdapter	Local Enterprise Bean	sap
AF_Modules / ResponseOnewayBean	Local Enterprise Bean	RespOneW

«Module Key» can be anything - so long as it is unique and the keys would be difficult to confuse - it will help us later to determine the parameters of modules.

Further settings depends on the location of our modules: sender communication channel or receiver communication channel.

2.1 Asynchronous - synchronous bridge with modules in Sender Communication Channel.

If we use Sender Communication Channel for bridge's modules, the scheme of message processing would be next:

Figure 3 : The logic of the asynchronous-synchronous bridge with modules in the Sender CC.

Receiving an asynchronous message from external system via communication channel, sending it to the module RequestResponseBean. The module changes the message type from asynchronous to synchronous by changing the message header.
Depending on the parameter passThrough, module pass the message down the chain of modules or directly sending it to the message processing subsystem of PI (skipping step 3).
Message processing by the standard adapter module, transfering it to PI message processing subsystem.
Sending a request via synchronous communication channel.
Synchronous call to the external system, obtaining the response.
Receiving a response from the synchronous communication channel.
Return the response to the module ResponseOnewayBean, changing the message type from synchronous to asynchronous. Detereming the receiver system for the response (using module parameters).
Sending response to the selected channel.
Delivery of the message to the external system via asynchronous communication channel.

Module parameters for RequestResponseBean when placing it in the Sender Communication Channel:

Parameter

Function

Possible Values

Default values

passThrough

Specifies where module must pass the processed message :

- PI message processing subsystem - false

- Next module in the chain - true

true / false

false

timeout

Response waiting time

in milliseconds

300000

Please remember that all parameters in Java are context-dependent and there is no verification of parameters names/values during saving and activation of Communication Channel!

Errors in spelling and register of letters will only emerge during testing, and sometimes it's very difficult to understand the cause of an error.

Parameters of ResponseOnewayBean module (if it defined in a Sender Communication Channel):

Parameter	Description	Possible Values	Default values
receiverParty	Name of Communication Component and Party (if used) for the receiver system.	* Optional	If not specified - the system uses datafrom the message header .
receiverService		* Optional
receiverChannel	Communication Channel name for the receiver system	* Optional	If not specified - the system looks for the receiver agreement, based on the information from the message header.
adapterType	Comm. channel parameters: type and namespace of adapter used for connection to the receiver system.	* Optional	Values can be taken from the Communication Channel in the Integration Builder: Field "Adapter Type". Example values : Type = File, Namespace = http://sap.com/xi/XI/System
adapterNamespace		* Optional

* - Theoretically , you can skip parameters at all. Will only need to create an "artificial » receiver agreement, which will be given:

system sender = synchronous system

reciever = target asynchronous system

interface = original request interface

I named it "artificial " because PI will not let you choose such set of parameters in agreement - you will have to put these parameters in the fields of an object manually (by copy-paste). It is this " mess " is formed in the header of message returned from a synchronous system as a result of the bridge.

If adapter types of the initial asynchronous system and the final destination are not the same - you will still have to configure adapterType and adapterNamespace in the communication channel.

In practice - accurate definition of all necessary parameters would do the job better.

You can also handle application error messages (optionally):

Parameter	Description	Possible Values
receiverChannelOnFault	Communication Channel name to receive error messages
replaceInterfaceOnFault	true - change interface and namespace of application error message; false - keep original interface and namespace	true/false
interfaceOnFault	Interface name for changing in the error message header
interfaceNamespaceOnFault	Interface namespace for changing in the error message header

Once we have established all necessary modules in the Sender Communication Channel, we should only create routing rules that bind the initial asynchronous system with the synchronous system.

This can be done in two ways:

• create a bunch Receiver Determination -> Interface Determination -> Receiver Agreement

• create Integrated Configuration

Routing of the response from a synchronous system is automatic; bridge module will send a message to the endpoint.

2.2 Example of asynchronous- synchronous bridge with modules in Sender Communication Channel.

Ok, if you have broken through a lot of words above - let's try to do it in the real world. :smile:

The schema of the bridge:

Figure 4 : Schematic of the asynchronous-synchronous example bridge - SOAP-RFC-File.

The initial system requests additional information about the person / partner on some ID. Technically, the system using an asynchronous web-service.

Requested information is stored in the ERP ( in this particular example - it is ABAP-part of PI installation). Information request could be done via synchronous RFC call to the Z-function module.

The answer must be saved to the file system (in this case - it's a folder on the PI server) in XML format, where ("according to the legend" :smile: ), it will be taken by an external system's agent.

To implement this interface , we need following development objects:

Figure 5 : Objects in the Integration Repository Development

All objects are created as usually(see Fig. 6-8) :

Figure 6 : Asynchronous - request

Figure 7 : Asynchronous - Reply

Figure 8 : RFC-module, imported from ABAP. Simple Z-Code to get some info from Z-table.

The only exception is the Operation Mapping:

Figure 9: Syncronous Operation Mapping between the two async interfaces and synchronous RFC

The problem is that the system will not give you possibility to create a two-way synchronous mapping, as the source interface SI_ExtSystem_Request_Async is asynchronous . But we know that the bridge will "create" visibility of synchronous operation

and the mapping will be carried out in both directions during runtime.

But (thanks to william.li who realised this possibility) we can create this mapping using a small trick:

Create Message Mapping MM_ExtSystem_Request_to_RFC for SI_ExtSystem_Request_Async and ZZ_EXT_REQUEST interfaces.
Create Message Mapping MM_RFC_to_ExtSystem_Response for ZZ_EXT_REQUEST.Response and SI_ExtSystem_Request_Async
THE TRICK: edit the source interface SI_ExtSystem_Request_Async: change the type to synchronous, add the message type from the interface SI_ExtSystem_Response as a response message type. Save, but do not activate.
Create Operation Mapping, source interface - SI_ExtSystem_Request_Async ( it's synchronous now), the target interface would be RFC module. Use Message Mappings from 1 and 2 as request and response mappings respectively. Save and activate mapping.
Reject the interface changes ( return it to its previous state - asynchronous).
Activate all changes.

Using this trick, we have got the mapping OM_ExtSystem_Request_to_RFC, it will perform all transformations in our interface.

Now we need to configure our interface - run the Integration Builder and create following objects:

Fig.10: Configuration objects

Communication channels CC_IntegrationServer_RFC_Receiver and CC_ExtSystem_File_Receiver have no special features, you can get adapter type from their technical names.

Most important step is to configure SOAP Sender Communication Channel CC_ExtSystem_SOAP_Sender and use bridge modules in it:

Figure 11 : The communication channel SOAP Sender

Configuring modules and RequestResponseBean ResponseOnewayBean:

Figure 12 : The communication channel SOAP Sender - Modules

Then create the routing from the source system to the ERP. I made it through the Receiver Determination + Interface Determination + Receiver Agreement ( you can also use the Integrated Configuration):

Figure 13 : Receiver Determination and other objects routing

Don't forget to add our mapping - OM_ExtSystem_Request_to_RFC - to the Interface Determination:

Figure 14 : Interface Determination and Operations Mapping

That's it!

Now let's check our bridge. Use the menu item «Display WSDL» of the Sender Agreement, then press «Save» and save WSDL of our service request to the local file.

Figure 15 : Uploading the WSDL for Sender SOAP Comm. Channel

Then create and send SOAP-request to PI using any tool (I used a freeware tool SOAPUI).

Figure 16 : Sending SOAP- request from SOAPUI in PI

If everything was set up correctly - we can find the answer in the target directory:

Figure 16 : File with additional information from ERP

So, we have set up an example of asynchronous-synchronous bridge using modules in the sender communication channel.

Congratulations to all who is still reading it - you did a half of the way!

Or you skip it - that's another option. :lol:

2.3 Asynchronous - synchronous bridge with modules in Receiver Communication Channel.

Suppose that we do not want (or cannot) affect the Sender Communication Channel. It is possible to place same modules in a synchronous communication channel of the receiver system.

Here is the logic scheme of the asynchronous-synchronous bridge with modules in the receiver channel:

Figure 17 : The logic of the asynchronous-synchronous bridge with modules in the receiver communication channel.

Receiving the asynchronous messages from external system.
Transfer the message to PI messaging system.
Message processing in PI, transfer it to a synchronous communication channel - to RequestResponseBean module. RequestResponseBean module change the message type from asynchronous to synchronous. Checks the parameter passThrough to forward the message to the next module in the modules chain or directly send it to the module ResponseOnewayBean (and skip steps from 4 to 6).
If passThrough=true the message goes to standard CallSapAdapter module.
Synchronous call to an external system, obtain the result.
Return the response to the module ResponseOnewayBean, which changes the type of message from synchronous to asynchronous .
Return the response message to message processing subsystem , which conducts header-based routing. The header was changed by RequestResponseBean module in step 3.
Sending the message to the selected channel.
Delivery of the message to an external system via asynchronous communication channel.

Bridge can be build using the same modules - RequestResponseBean and ResponseOnewayBean.

Module parameters for RequestResponseBean:

Parameter

Description

Possible Values

Default values

passThrough

Specifies where module must pass the processed message :

- directly to the ResponseOnewayBean module - false

- Next module in the chain - true

true / false

false

timeout

Response waiting time

in milliseconds

300000

Module ResponseOnewayBean, included in the Receiver Communication Channel have not so many parameters. We can only change an Interface name in the message header or change the delivery of application error message:

Parameter	Description	Possible Values
replaceInterface	true - to replace the interface name and its namespace in the message header; false - do not touch the message header	true / false
interface	New Sender Interface name in the message header (if replaceInterface = true).
interfaceNamespace	New Sender Interface namespace in the message header (if replaceInterface = true).
replaceInterfaceOnFault	In case of application error: true - to replace the error message interface name and its namespace in the message header; false - do not touch the message header	true / false
interfaceOnFault	New Error Message Interface name in the message header (if replaceInterfaceOnFault = true).
interfaceNamespaceOnFault	New Error Message namespace in the message header (if replaceInterface = true).

:!:

NOTE: There are some conflicts in the documentation (official and unofficial from help.sap.com and sdn.sap.com) about settings for modules in Async-Sync Bridge!

Example: «Configuring the Async / Sync Bridge Using the JMS Adapter» on help.sap.com describes some ResponseOnewayBean module parameters; it's subchapter - «Adding ResponseOnewayBean in the Module Processor» - describe another set of parameters.

In SDN articles connected to the bridges there are a lot of specific examples based on «Configuring the Async / Sync Bridge Using the JMS Adapter». Sometimes there are comments, that it works with one adapter and not working for the other (with the same settings).

Actually, you can't use parameter replaceInterface for ResponseOnewayBean with RFC-adapter as synchronous receiver - it does not work! However, the same substitution works fine when using synchronous request through SOAP-adapter.

Be careful , and analyze all possible sources of information in case of errors.

:!:

If we finished with communication channels - we need two routings to configure:

External System -> Sender Agreement ( if needed ) -> Reciever Determination -> Interface Determination -> Receiver Agreement -> Synchronous communication channel with modules
Synchronous System -> Sender Agreement ( if needed ) -> Reciever Determination -> Interface Determination -> Receiver Agreement -> Asynchronous communication channel.

Both routings also can be configured via Integrated Configuration.

2.4 Example : Asynchronous-synchronous bridge with modules in Receiver Communication Channel.

From theory - to practice! Let's see how to build a bridge, if you add modules to the receiver communication channel.

The interface schema looks like this:

Figure 18 : Schematic example of asynchronous- synchronous bridge SOAP-RFC-File

We need some preparations does not related directly to the configuration of the bridge.

At this time, synchronous SOAP-service would be the recipient. For simplicity, I used the function module from the previous example as a basis for SOAP-service (transaction SE80 -> Enterprise Service and SOAMANAGER were used for this).

Figure 19 : Creating a SOAP-service in transaction SE80

Figure 20 : SOAP-service configuration in SOAMANGER transaction

Figure 21 : SOAP-service configuration in SOAMANGER transaction

Download WSDL of our service and import it into the PI ESR repository - External Definition DOC_3I_ZZ_SOAP_EXT_REQUEST.

Then create a synchronous interface SI_SOAP_ADDINFO_Sync, using the message types from the previous import:

Figure 22 : Synchronous interface based on external WSDL

Synchronous part of the bridge is ready!

For async part we need following development objects:

Figure 23 : Objects in the Enterprise Service Repository

In total:

• Two asynchronous interface for asynchronous systems (Request and Response): SI_ExtSystem_Request_Async and SI_ExtSystem_Response

• Synchronous interface SI_SOAP_ADDINFO_Sync.

• Asynchronous SI_ERP_SOAP_Response_Async (transmits a message from ZZ_SOAP_EXT_REQUEST.Response from synchronous SI_SOAP_ADDINFO_Sync).

• Asynchronous Operations Mapping for request: OM_ExtSystemRequest_to_SOAP_Request

• Asynchronous Operations Mapping for response: OM_ERP_SOAPResp_to_ExtSystem_Response

Objects are created in the standard way, no technical tricks needed. There would be only one alert - during activation of OM_ExtSystemRequest_to_SOAP_Request mapping. System will alert about interfaces type mismatch, but the object would be activated so you can ignore it.

Now all development objects are ready - let's go for settings in Integration Directory:

Figure 24: Configuration objects

Let's build routing via Integrated Configuration this time (as opposed to 2.2). Create an object to send the request :

Fig. : 24 : Integrated Configuration - Request

Create a synchronous communication channel for SOAP-service - CC_IntegrationServer_SOAP_Receiver:

Figure 25 : The communication channel SOAP Receiver

Configure the modules in the communication channel :

Figure 26 : The communication channel SOAP Receiver - setting modules

ResponseOnewayBean module parameters specify the name and the namespace of interface to be replaced in the message header . As a result of the module processing response message from the SOAP changing the header and become asynchronous, sent from the interface SI_ERP_SOAP_Response_Async.

:!: WARNING:such substitution will not work with synchronous RFC! To create a bridge with synchronous RFC you need to use same technique as in Example 2.2 - with synchronous mapping and Receiver Determination (or Integrated Configuration).

You need two channels - sender and receiver - to create an Integrated Configuration. But we defined SOAP channel as the receiver , and use it for response routing is not possible. The solution is to create a dummy channel, which will take place in the Integrated Configuration on Inbound Processing tab. Type of adapter for this channel is not important, I chose SOAP:

Figure 27 : SOAP communication channel as a placeholder in the Integrated Configuration

Then adjust the reverse route in the usual way :

Figure 28 : Integrated Configuration - Reciever

Figure 29 : Integrated Configuration - Reciever Interface

Figure 30 : Integrated Configuration - Outbound Processing

Well that's it. Activate all the objects, test using SOAPUI, as in Example 2.2.

Result pleases us by XML-file with the requested information :

Figure 31 : File with additional information from the SOAP- service

--------------------------------------------------------------------------------

Thanks for you attention!

Next parts:

Bridges Construction Site (2/3): Synchronous - asynchronous bridge.

Bridges Construction Site (3/3): SAP PI bridges - "exotic" and recommendations.

With best regards,

Alexey Petrov