This blog describes how to use the XI receiver adapter in the Send and the Request-Reply step. This feature will be available for customers with the 28-October-2018 release. The blog describes the configuration options in a sample scenario.
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 scenario in the Request-Reply and Send step.
We are going to build a synchronous scenario to send a flight booking request from SOAP UI to Cloud Integration. In Cloud Integration we use the XI receiver adapter in the Request-Reply step to synchronously retrieve flight data from the backend. If there are free seats available, an asynchronous booking request is made via a Send step to the backend using the XI receiver adapter.
If you want to configure an asynchronous booking response, follow the instructions in the blog Configuring Scenario Using the XI Sender Adapter.
First, I'll explain the general usage of the XI adapter in the Send and the Request-Reply steps.
Using the XI adapter in these two flow steps is not as straight forward as the usage of other adapters. This is because the XI adapter can execute synchronous calls (with quality of service Best Effort) and asynchronous calls (with quality of service Exactly Once). This has the following implications for configuration and processing:
To setup the scenario, we first configure the connection to the backend to be connected via the XI protocol.
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 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.
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>
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>.
Use transaction SPROXY to find out which XI services are available in the system. For our sample we are using the services of the PI flight booking demo examples. Look for the service interfaces FlightBookingOrderRequest_In and FlightSeatAvailabilityQuery_In in namespace http://sap.com/xi/XI/Demo/Airline.
Check that the interfaces are Active. These interfaces will process the requests 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 interfaces are not available in your backend, you can use other Inbound interfaces for your scenario.
The flight data must be available in the backend, in order 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, you cannot use the sample implementation, you 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.
We configure the integration flow in the Design section of the Web UI.
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:
Add a Content Modifier directly after the Start event. We use the Content Modifier to read the flight details into headers because we will need the details later when booking the flight. Set the following XPath expressions:
OrderNumber: p1:FlightBookingOrderRequest/AgencyData/OrderNumber
ClassCode: p1:FlightBookingOrderRequest/ClassCode
FlightDate: p1:FlightBookingOrderRequest/FlightID/FlightDate
ConnectionID: p1:FlightBookingOrderRequest/FlightID/ConnectionID
AirlineID: p1:FlightBookingOrderRequest/FlightID/AirlineID
PassengerName: p1:FlightBookingOrderRequest/PassengerName
PassengerBirthdate: p1:FlightBookingOrderRequest/PassengerBirthdate
Because we use p1 as the namespace, we need to define this in the Namespace Mapping: xmlns:p1=http://sap.com/xi/XI/Demo/Airline.
On the Message Body tab, we need to create the payload for the synchronous query call. The request is built based on the headers that we have defined. Set the following body in the Message Body:
After the Content Modifier add a Request-Reply step from the Call -> External Call section in the modeling palette. Connect the Request-Reply step with the Receiver participant and select the XI adapter. Once you have added the XI receiver channel in the Request-Reply step, you need to configure the XI channel.
First, you configure the Connection Details on the Connection tab.
In addition to the connection details, you need to define the XI-specific configuration:
On the Delivery Assurance tab, you specify the Quality of Service. As we want to execute a synchronous request-reply call to the synchronous interface FlightSeatAvailabilityQuery_In we select Best Effort here.
This Request-Reply call synchronously fetches the available seats in economy, business, and first class for the flight connection ID and date passed in the request. The response message is then used as the payload in the further processing. The response looks like this:
Based on these details, we either book a flight in economy if seats are available, or we do not book a flight and send a corresponding response with available seats in business and first class to the sender. You could also extend the scenario to book a seat in business or first class instead, or search for flights on the days before and after the flight date and offer this information to the sender. However, this is beyond the scope of this blog and is not described here.
To do a routing based on the response, we add a Router step after the Request-Reply call. We also add another End Message event. In the branch that goes to the first End event, configure Expression Type: XML with the Condition: //EconomyFreeSeats > '0'. This means that this branch is executed if there are free seats available in economy class.
The second branch can be defined as the default branch that is executed if no seats are available.
In the branch that goes to the first End event, we add another Content Modifier. Because our payload now contains the response, we need to make sure the generated XI message ID from the request-reply call is cleaned up and the new booking request is defined. Otherwise the same XI message ID would be used in the Send call with the response message as payload.
On the Message Header tab delete the header SapMessageIdEx, that defines the XI message ID. Use the Add option to create a new line. Select the Delete action and set the header SapMessageIdEx in the Select dialog:
We build the new booking request payload based on the flight dates we have saved as headers in the first Content Modifier. On the Message Body tab set the following body:
To trigger the booking request in the backend, we add another Receiver and a Send step from the Call -> External Call section after the Content Modifier. Connect the Send step with the new Receiver and select the XI adapter.
After adding the XI receiver channel in the Send step, you need to configure the XI channel.
First, you configure the Connection Details on the Connection tab, like in the Request-Reply call.
Configure the XI-specific configuration details as for the Request-Reply call, with the one difference that you define the interface FlightBookingOrderRequest_In in the Service Interface field.
On the Delivery Assurance tab, you specify the Quality of Service. As we want to execute an asynchronous send call to the asynchronous interface FlightBookingOrderRequest_In, we select Exactly Once here. We keep the defaults for the other values.
Because the Send call does not provide a response, the further processing is executed with the payload before the Send step. To build a meaningful response to go back to the sender, we add another Content Modifier after the Send step. On the Message Body tab, define the response:
In the event of an error, we want to provide a meaningful response and information about available seats in business or first class, so that the sender can book accordingly. To achieve this, add another Content Modifier between the Router and the second End Message event. On the Message Header tab, we define two headers for the free seats in business and first class:
FirstFreeSeats: //FirstFreeSeats
BusinessFreeSeats: //BusinessFreeSeats
Define the response in the Message Body as follows:
As we are using the XI Adapter in the Send 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 Send step.
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.
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 request with a payload like the one below to your inbound endpoint.
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.
When you check the processing in Cloud Integration, you will see that a successful call has two message processing logs for the scenario execution. One contains the main processing from the SOAP sender to the synchronous XI receiver, routing via router to the asynchronous XI receiver, and sending the response back to the original sender. The second message processing log only contains the asynchronous sending of the request from the XI data store to the receiver backend.
Usage of XI Adapter in Send and Request-Reply Step
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 scenario in the Request-Reply and Send step.
We are going to build a synchronous scenario to send a flight booking request from SOAP UI to Cloud Integration. In Cloud Integration we use the XI receiver adapter in the Request-Reply step to synchronously retrieve flight data from the backend. If there are free seats available, an asynchronous booking request is made via a Send step to the backend using the XI receiver adapter.
If you want to configure an asynchronous booking response, follow the instructions in the blog Configuring Scenario Using the XI Sender Adapter.
First, I'll explain the general usage of the XI adapter in the Send and the Request-Reply steps.
XI Adapter in Send and Request-Reply
Using the XI adapter in these two flow steps is not as straight forward as the usage of other adapters. This is because the XI adapter can execute synchronous calls (with quality of service Best Effort) and asynchronous calls (with quality of service Exactly Once). This has the following implications for configuration and processing:
- The XI adapter with quality of service Best Effort can be used in the Request-Reply step because a response is returned. Processing continues with the response message that is returned from the Request-Reply step.
- The XI adapter with quality of service Exactly Once can be used in the Send step because in this case the request is just sent out to the receiver without retrieving a response. Processing continues with the message before the Send step.
To setup the scenario, we first configure the connection to the backend to be connected via the XI protocol.
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 the services of the PI flight booking demo examples. Look for the service interfaces FlightBookingOrderRequest_In and FlightSeatAvailabilityQuery_In in namespace http://sap.com/xi/XI/Demo/Airline.
Check that the interfaces are Active. These interfaces will process the requests 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 interfaces are not available in your backend, you can use other Inbound interfaces for your scenario.
Check or Generate Flight Data
The flight data must be available in the backend, in order 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, you cannot use the sample implementation, you 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 Content Modifier to Retrieve the Flight Details
Add a Content Modifier directly after the Start event. We use the Content Modifier to read the flight details into headers because we will need the details later when booking the flight. Set the following XPath expressions:
OrderNumber: p1:FlightBookingOrderRequest/AgencyData/OrderNumber
ClassCode: p1:FlightBookingOrderRequest/ClassCode
FlightDate: p1:FlightBookingOrderRequest/FlightID/FlightDate
ConnectionID: p1:FlightBookingOrderRequest/FlightID/ConnectionID
AirlineID: p1:FlightBookingOrderRequest/FlightID/AirlineID
PassengerName: p1:FlightBookingOrderRequest/PassengerName
PassengerBirthdate: p1:FlightBookingOrderRequest/PassengerBirthdate
Because we use p1 as the namespace, we need to define this in the Namespace Mapping: xmlns:p1=http://sap.com/xi/XI/Demo/Airline.
On the Message Body tab, we need to create the payload for the synchronous query call. The request is built based on the headers that we have defined. Set the following body in the Message Body:
<ns1:FlightSeatAvailabilityQuery xmlns:ns1='http://sap.com/xi/XI/Demo/Airline'>
<FlightID>
<AirlineID>${header.AirlineID}</AirlineID>
<ConnectionID>${header.ConnectionID}</ConnectionID>
<FlightDate>${header.FlightDate}</FlightDate>
</FlightID>
</ns1:FlightSeatAvailabilityQuery>Configure Request-Reply with XI Receiver Channel
After the Content Modifier add a Request-Reply step from the Call -> External Call section in the modeling palette. Connect the Request-Reply step with the Receiver participant and select the XI adapter. Once you have added the XI receiver channel in the Request-Reply step, 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 for 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 steps using SLDCHECK.
- As Service Interface define the interface you want to call in the backend, for our scenario we use FlightSeatAvailabilityQuery_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 Quality of Service. As we want to execute a synchronous request-reply call to the synchronous interface FlightSeatAvailabilityQuery_In we select Best Effort here.
This Request-Reply call synchronously fetches the available seats in economy, business, and first class for the flight connection ID and date passed in the request. The response message is then used as the payload in the further processing. The response looks like this:
<n0:FlightSeatAvailabilityResponse xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/" xmlns:n0="http://sap.com/xi/XI/Demo/Airline" xmlns:xi="http://sap.com/xi/XI/Message/30">
<EconomyMaxSeats>380</EconomyMaxSeats>
<EconomyFreeSeats>376</EconomyFreeSeats>
<BusinessMaxSeats>41</BusinessMaxSeats>
<BusinessFreeSeats>41</BusinessFreeSeats>
<FirstMaxSeats>18</FirstMaxSeats>
<FirstFreeSeats>18</FirstFreeSeats>
</n0:FlightSeatAvailabilityResponse>Based on these details, we either book a flight in economy if seats are available, or we do not book a flight and send a corresponding response with available seats in business and first class to the sender. You could also extend the scenario to book a seat in business or first class instead, or search for flights on the days before and after the flight date and offer this information to the sender. However, this is beyond the scope of this blog and is not described here.
Configure Router
To do a routing based on the response, we add a Router step after the Request-Reply call. We also add another End Message event. In the branch that goes to the first End event, configure Expression Type: XML with the Condition: //EconomyFreeSeats > '0'. This means that this branch is executed if there are free seats available in economy class.
The second branch can be defined as the default branch that is executed if no seats are available.
Configure Content Modifier to Build Booking Request
In the branch that goes to the first End event, we add another Content Modifier. Because our payload now contains the response, we need to make sure the generated XI message ID from the request-reply call is cleaned up and the new booking request is defined. Otherwise the same XI message ID would be used in the Send call with the response message as payload.
On the Message Header tab delete the header SapMessageIdEx, that defines the XI message ID. Use the Add option to create a new line. Select the Delete action and set the header SapMessageIdEx in the Select dialog:
We build the new booking request payload based on the flight dates we have saved as headers in the first Content Modifier. On the Message Body tab set the following body:
<p1:FlightBookingOrderRequest xmlns:p1='http://sap.com/xi/XI/Demo/Airline'>
<AgencyData>
<AgencyID>00000110</AgencyID>
<OrderNumber>${header.OrderNumber}</OrderNumber>
<ItemNumber>01</ItemNumber>
<OrderType>Single</OrderType>
</AgencyData>
<FlightID>
<AirlineID>${header.AirlineID}</AirlineID>
<ConnectionID>${header.ConnectionID}</ConnectionID>
<FlightDate>${header.FlightDate}</FlightDate>
</FlightID>
<ClassCode>${header.ClassCode}</ClassCode>
<PassengerName>${header.PassengerName}</PassengerName>
<PassengerBirthdate>${header.PassengerBirthdate}</PassengerBirthdate>
</p1:FlightBookingOrderRequest>Configure the Send Step with XI Receiver Channel
To trigger the booking request in the backend, we add another Receiver and a Send step from the Call -> External Call section after the Content Modifier. Connect the Send step with the new Receiver and select the XI adapter.
After adding the XI receiver channel in the Send step, you need to configure the XI channel.
First, you configure the Connection Details on the Connection tab, like in the Request-Reply call.
Configure the XI-specific configuration details as for the Request-Reply call, with the one difference that you define the interface FlightBookingOrderRequest_In in the Service Interface field.
On the Delivery Assurance tab, you specify the Quality of Service. As we want to execute an asynchronous send call to the asynchronous interface FlightBookingOrderRequest_In, we select Exactly Once here. We keep the defaults for the other values.
Configure Content Modifier to Build the Response
Because the Send call does not provide a response, the further processing is executed with the payload before the Send step. To build a meaningful response to go back to the sender, we add another Content Modifier after the Send step. On the Message Body tab, define the response:
<p1:FlightBookingOrderConfirmation xmlns:p1="http://sap.com/xi/XI/Demo/Airline">
<BookingStatus>Successful</BookingStatus>
<BookingStatusAdditional>Order ${header.OrderNumber} for flight booking created.</BookingStatusAdditional>
</p1:FlightBookingOrderConfirmation>Configure Content Modifier to Build the Response for the Error Case
In the event of an error, we want to provide a meaningful response and information about available seats in business or first class, so that the sender can book accordingly. To achieve this, add another Content Modifier between the Router and the second End Message event. On the Message Header tab, we define two headers for the free seats in business and first class:
FirstFreeSeats: //FirstFreeSeats
BusinessFreeSeats: //BusinessFreeSeats
Define the response in the Message Body as follows:
<p1:FlightBookingOrderConfirmation xmlns:p1="http://sap.com/xi/XI/Demo/Airline">
<BookingStatus>No free seats available in economy class.</BookingStatus>
<BookingStatusAdditional>${header.BusinessFreeSeats} seats available in business class, ${header.FirstFreeSeats} seats available in first class.</BookingStatusAdditional>
</p1:FlightBookingOrderConfirmation>Configure Transaction Handling
As we are using the XI Adapter in the Send 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 Send step.
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 request with a payload like the one below to your inbound endpoint.
<ns1:FlightBookingOrderRequest xmlns:ns1='http://sap.com/xi/XI/Demo/Airline'>
<AgencyData>
<AgencyID>00000110</AgencyID>
<OrderNumber>00000001</OrderNumber>
<ItemNumber>01</ItemNumber>
<OrderType>Single</OrderType>
</AgencyData>
<FlightID>
<AirlineID>LH</AirlineID>
<ConnectionID>401</ConnectionID>
<FlightDate>2018-04-01</FlightDate>
</FlightID>
<ClassCode>Y</ClassCode>
<PassengerName>Max Mustermann</PassengerName>
<PassengerBirthdate>2000-12-31</PassengerBirthdate>
</ns1:FlightBookingOrderRequest>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.
When you check the processing in Cloud Integration, you will see that a successful call has two message processing logs for the scenario execution. One contains the main processing from the SOAP sender to the synchronous XI receiver, routing via router to the asynchronous XI receiver, and sending the response back to the original sender. The second message processing log only contains the asynchronous sending of the request from the XI data store to the receiver backend.
- SAP Managed Tags:
12 Comments
