Technology Blogs by SAP
Learn how to extend and personalize SAP applications. Follow the SAP technology blog for insights into SAP BTP, ABAP, SAP Analytics Cloud, SAP HANA, and more.
cancel
Showing results for 
Search instead for 
Did you mean: 
mandy_krimmel
Advisor
Advisor
This blog describes how to use the ID mapping feature in the XI receiver adapter. This feature will be available for customers with the 25-November-2018 release. The blog describes the configuration options in a sample scenario.

Configuring ID Mapping in the XI Receiver Adapter


The blog Configuring Scenario Using the XI Receiver Adapter describes how to use the XI receiver adapter in an EO scenario that connects to a backend using XI protocol. The scenario described in the blog is a straight forward scenario where asynchronous requests are sent from one sender to a backend using the XI receiver adapter. In this blog, we want to use the XI adapter in a more complex splitter scenario using ID mapping to ensure duplicate messages can be detected by the XI backend.

We are going to build an asynchronous scenario to send a bulk flight booking request from SOAP UI to Cloud Integration. In Cloud Integration we split the request into single booking requests and use the XI receiver adapter to send them as single XI messages to the XI backend. If the same order numbers are sent again from the sender application the messages are forwarded with the same XI message ID to the XI receiver backend to make sure the receiver can detect them as duplicates.

First, I’ll explain the general usage of the message ID mapping in the XI receiver.

Message ID Mapping in XI Receiver


With the November 2018 release of SAP Cloud Integration the version 1.9 of the XI receiver adapter is available. In this version you'll find a new drop down for XI Message ID Determination. Using this drop down you can define how the XI Message ID for the outbound call shall be generated:



The following three options are available:

  • Generate: For each call a new XI Message ID is generated. This option is useful if you have several XI receiver channels in one integration flow or configure the XI receiver adapter in a splitter or a looping process call and want to make sure that the message ID from the previous call is not reused in the next call. This avoids that the same XI message ID is reused in different calls. Note, that this option is not useful if you want to avoid that the same inbound message is processed multiple times in the receiver system.

  • Reuse: If the header SAPMessageIdEx is set, for example by the inbound adapter or by a previous XI adapter call, the message ID contained in that header is reused for the outbound request in the XI receiver. If the header is not available in runtime, a new XI message ID is generated. This option can be useful if the message ID coming from the sender adapter shall be reused for the outbound call. Using this option, the XI adapter will always send the same message from the sender system with the same message ID to the receiver system, so the receiver is able to detect this as a duplicate and can handle it accordingly. But if multiple XI receiver calls are executed in one integration flow, as for example in a splitter or looping scenario, this would lead to the problem that the same XI message ID would be used for different messages and the XI receiver system would judge them as duplicates and not process them.

  • Map: This option maps a defined source message ID to the XI message ID used for the outbound call. If Map is defined, the source ID for the target XI message ID must be defined using a header or property. This is the purpose of the Source for XI Message ID field where you enter the unique ID to be used to generate the XI message ID. Using this option, the XI adapter will be able to send the same source message with the same message ID to the XI receiver system also in complex scenarios, so that the receiver is able to detect duplicates and can handle them accordingly. The difference to the Reuse option is that you can define the source ID based on any unique ID contained in the inbound message.


Let’s use the Map option in a more complex scenario.

Target Scenario


Imagine, you have a large inbound payload containing several orders which you split into single orders in the integration flow with the goal to send each order as a separate XI message. You want to make sure each order is processed only once in the XI receiver system.



First, we need to configure the receiver system.

Configure the Receiver System to Receive the XI Message from Cloud Integration


The first step is to configure the receiver backend to receive a message via the XI 3.0 protocol. You need to check that the local integration engine is configured.

Configure Local Integration Engine


Configure the local integration engine in the backend using transaction SXMB_ADM -> Integration Engine Configuration. Here, the Role of the Business System should be Application System.

Construct XI Engine URL


You then need to construct the URL under which the local integration engine of the application system can be called. This URL needs to contain the HTTPS port that the system exposes. Check this in transaction SMICM -> Goto -> Services. Using the host name and port of the HTTPS service, construct the URL using the following pattern:

https://<host name>:<port>/sap/xi/engine?type=receiver&sap-client=<client>

Get the Name of the Business System


To be able to configure the XI receiver channel, you need to know the name of the business system of the application system. The easiest way to find this information is to use transaction SLDCHECK in the application backend. In the section LCR_GET_OWN_BUSINESS_SYSTEM, you can find the ID of the business system. It usually has the pattern: <SID>_<client>.


Check Available Interfaces


Use transaction SPROXY to find out which XI services are available in the system. For our sample we are using a service of the PI flight booking demo examples. Look for the service interface FlightBookingOrderRequest_In in namespace http://sap.com/xi/XI/Demo/Airline.



Check that the interface is Active. The interface will process the request and send back an asynchronous response (interface FlightBookingOrderConfirmation_Out) to Cloud Integration. The configuration for the response processing is described in the blog Configure Scenario Using the XI Sender Adapter and can be done as soon as the request configuration is successfully finished.

If the interface is not available in your backend, you can use another Inbound interface for your scenario.

Check or Generate Flight Data


The flight data must be available in the backend for you to retrieve it. Check if there are flights available using transaction SXIDEMO2. Select Display Availability Data to see if there are generated flights and free seats available in the client. You will need this information to trigger requests for the configured airline and for generated flights. In the sample screenshot below, you can see that in this tenant flights are generated for airline LH (Lufthansa). You can see the available flight dates (FLDATE) with the relevant connection ID (CONNID), and the maximum and free seats for Economy, Business, and First Class.



If no flights are available, you can generate flight data using transaction SXIDEMO3. Select Yes to define the client as an airline system and select the airline that you want to generate flight data for.



If the flight booking interfaces are not available in your backend or you cannot use the sample implementation, you'll would have to create your own proxy implementation of the synchronous and asynchronous interfaces you want to use.

We now have all the details we need to configure the integration flow in the Cloud Integration tenant.

Configure Integration Flow in Cloud Integration


We configure the integration flow in the Design section of the Web UI.

Configure SOAP Sender Channel


Create an integration flow and configure the connection from the Sender participant to the Start event. Select SOAP -> SOAP 1.x as the adapter. On the Connection tab, in the Address field, define the URL path to be used to generate the inbound URL. Keep the defaults for the other settings:


Configure Splitter to Split the Booking Requests


In the next step we configure the splitting of the bulk order into single orders. For this, add an Iterating Splitter from the palette. In the Processing tab, select XPath as Expression Type and configure the XPath Expression with xmlns:ns1=http://sap.com/xi/XI/Demo/Airline:



In the XPath expression the namespace prefix ns1 is used, so you also have to define it in the namespace mapping. For this, in the Runtime Configuration define the namespace xmlns:ns1=http://sap.com/xi/XI/Demo/Airline in the Namespace Mapping field:


Configure Content Modifier to set the Order ID as Header


After the orders are split into single messages we retrieve an unique ID for each of the orders. In our sample scenario it is the order number. After the splitter we define a Content Modifier step and in the Exchange Property tab we define the property OrderID with an XPath as /ns1:FlightBookingOrderRequest/AgencyData/OrderNumber. This step reads the order number for each split part and sets it as property.


Configure the XI Receiver Channel


To trigger the single booking requests in the backend, we add a Receiver after the Content Modifier. Connect the End Message event with the new Receiver and select the XI adapter.

After adding the XI receiver channel, you need to configure the XI channel.

First, you configure the Connection Details on the Connection tab.

  • Configure the Address field with the XI Engine URL that you constructed in a previous steps.

  • Select the Proxy Type that you want to use to connect to the backend. On-Premise indicates that in our sample scenario we are using the cloud connector configured with a Location ID to connect to the on-premise backend. The configuration of the cloud connector is not described here. If you need the cloud connector to connect to the backend, see the SAP documentation about the cloud connector.

  • Select the Authentication Type required. In this sample scenario we use Basic Authentication, so we have to enter the Credential Name as well. Make sure that you deploy the credentials on the tenant before you deploy the integration flow.


In addition to the connection details, you need to define the XI-specific configuration:

  • Define the XI Identifiers for Sender system. Define a name for the Sender Communication Component. This name is used in the backend to identify the sender of the message.

  • Define the XI Identifiers for Receiver. Define the name for the Receiver Communication Component. Set the business system of the receiver backend here using the name you retrieved in a previous step using SLDCHECK.

  • As Service Interface define the interface you want to call in the backend, for our scenario we use FlightBookingOrderRequest_In.

  • For Service Interface Namespace, define the namespace of the interface you want to call in the backend. For our scenario we use http://sap.com/xi/XI/Demo/Airline.




On the Delivery Assurance tab, you specify the Delivery Assurance Parameters:

  • We want to make sure each booking order is executed in the XI Receiver exactly once. To enable this, we need to define the correct mapping of the source ID to the XI message ID. In our sample scenario we want to map the OrderID to the XI message ID to make sure each order is executed with the same XI Message ID so that the XI receiver can detect duplicates. We select Map for the XI Message ID Determination and enter the property defined in the last step, ${property.OrderID}, in the field Source for XI Message ID.

  • As we want to execute an asynchronous booking call to the asynchronous interface FlightBookingOrderRequest_In, we select Exactly Once as Quality of Service. We keep the defaults for the other values.



Configure Transaction Handling


As we are using the XI Adapter in a Splitter step, it is necessary to set Transaction Handling to Required for JMS or Required for JDBC, to make sure the transaction is rolled back if an error occurs after the first split.

In our sample scenario we use the XI adapter with Data Store as temporary storage. So, we use the JDBC transaction handler and set Transaction Handling in the Integration Process to Required for JDBC:



There are some limitations on configuring transaction handling, which flow steps it can be used in, and in which combinations. These are described in detail in the blog ‘How to configure Transaction Handling in Integration Flow‘.

This completes the configuration of the integration flow. Save and deploy it.

Set Up Sender Application and Trigger the Integration Flow


After the integration flow is deployed you can download the WSDL in the Endpoints section for the deployed integration flow in the Integration Content monitor. Generate a request from a SOAP test client, for example SOAP UI. In the SOAP UI, trigger a multi-orders request with a payload like the one below to your inbound endpoint.
 <ns1:FlightBookingOrderRequests xmlns:ns1='http://sap.com/xi/XI/Demo/Airline'>
<ns1:FlightBookingOrderRequest>
<AgencyData>
<AgencyID>00000110</AgencyID>
<OrderNumber>00000001</OrderNumber>
<ItemNumber>01</ItemNumber>
<OrderType>Single</OrderType>
</AgencyData>
<FlightID>
<AirlineID>LH</AirlineID>
<ConnectionID>401</ConnectionID>
<FlightDate>2018-11-01</FlightDate>
</FlightID>
<ClassCode>Y</ClassCode>
<PassengerName>Max Mustermann</PassengerName>
<PassengerBirthdate>2000-12-31</PassengerBirthdate>
</ns1:FlightBookingOrderRequest>
<ns1:FlightBookingOrderRequest>
<AgencyData>
<AgencyID>00000110</AgencyID>
<OrderNumber>00000002</OrderNumber>
<ItemNumber>01</ItemNumber>
<OrderType>Single</OrderType>
</AgencyData>
<FlightID>
<AirlineID>LH</AirlineID>
<ConnectionID>401</ConnectionID>
<FlightDate>2018-11-01</FlightDate>
</FlightID>
<ClassCode>Y</ClassCode>
<PassengerName>Mandy Krimmel</PassengerName>
<PassengerBirthdate>2000-12-31</PassengerBirthdate>
</ns1:FlightBookingOrderRequest>
</ns1:FlightBookingOrderRequests>

The URL to be called can be found in the Endpoints section for the deployed integration flow in the Integration Content monitor or in the downloaded WSDL.

Monitoring


Message Monitoring


When you check the processing in Cloud Integration, you will see that a successful call has three message processing logs for the scenario execution for two orders. One contains the main processing from the SOAP sender to the asynchronous XI receiver, containing the splitting and storing the single splits into the data store. The second and third message processing log only contain the asynchronous sending of the single order requests from the XI data store to the receiver backend.



To see how the mapping is done you may increase the log level of the integration flow to DEBUG or TRACE. Only then you see the source and target ID in the message processing log:


Message Processing Log in Case of a Duplicate Message


In case the same order is received and processed again in Cloud Integration the same XI message ID is used to send the order to the XI backend. In such a case the XI receiver answers with a DUPLICATE_DETECTED message. But note, that this is not an error according to the XI protocol, it is more a notification that this message has already been processed in the XI backend and it is not processed again. In Cloud Integration the overall status of the message processing is COMPLETED because this is not an error.

The XI DUPLICATE_DETECTED message can be seen in the message processing log only if the log level is DEBUG or TRACE.


Monitor ID Mapping


For the monitoring of the ID mapping table there is an OData API. You may use this to find the XI message for a source message or vice versa.

For example, you can use the Postman tool to call the OData API for the ID mapper component.

Use the following URL to retrieve the source ID for a XI message ID:

https://<tmn-server>/api/v1/IdMapToIds('<xi message ID')/FromId2s

https://server/api/v1/IdMapToIds('c014e4cc-bb2a-4c85-b659-57a1ab98a0b6')/FromId2s

The call returns the source ID for this XI message ID.

 

To retrieve the XI message ID for a source ID, use the following URL:

https://<tmn-server>/api/v1/IdMapFromIds('<source ID')/ToIds

https://server/api/v1/IdMapFromIds('abc')/ToIds

The call returns all the XI message IDs for the source ID. Note that it can be multiple XI message IDs if the same source ID is used in different XI receiver channels.
4 Comments