SAP HANA Cloud Integration (SAP HCI) is a cloud-based solution for connecting on-premise as well as on-demand enterprise applications with each other. Its core task is the routing of messages across a company’s distributed IT landscape, including the connectivity to partners and suppliers. Such integration scenarios can be synchronous or asynchronous in nature. Synchronous message handling follows this basic procedure:
1. A sender opens a connection to SAP HCI and sends a request message.

2. After sending the request message to SAP HCI, the sender does not close the connection because a reply is expected.

3. SAP HCI finds the receiver for the respective request message (e.g., by inspecting the message’s content), opens a connection to the receiver, and routes the message to the receiver.

4. After sending the message to the receiver, SAP HCI does not close the connection either.

5. The receiver acts on the request message by creating a response message and returns it to SAP HCI via the still opened connection.

6. After SAP HCI receives the message, it closes the connection to the receiver and routes the received message as a reply message to the original sender.

7. The sender can now close the connection to SAP HCI after receiving the final reply message.

Obviously, the connection from the sender to SAP HCI and the connection from SAP HCI to the receiver are still open as long as the message processing is ongoing. The communication involves a bidirectional message transfer in one session. This message handling procedure significantly differs from the following asynchronous message handling procedure:

1. A sender opens a connection to SAP HCI and sends a message.

2. After SAP HCI receives the message correctly, it acknowledges its reception to the sender.

3. After receiving the acknowledgment from SAP HCI, the sender closes the connection.

4. SAP HCI opens a connection to the receiver of the message and forwards it accordingly.

5. After receiving the message completely, the receiver acknowledges the message’s reception to SAP HCI.

6. After receiving the acknowledgment from the receiver, SAP HCI closes the connection.

The connections are immediately closed as soon as the receiving parties confirm the messages. The overall communication just involves the message transfer in one direction. These are in short the main differences between synchronous and asynchronous communication.

How does this information affect the discussion about SAP HCI? First, SAP HCI has to support both communication styles as it is a general-purpose integration infrastructure that is prepared for all kinds of integration requirements. However, in the articles I have written so far in this series, all communications were synchronous. These articles have been useful so far because you were able to see the immediate results of the integration flow invocations in the Simple Object Access Protocol (SOAP) clients that were used to call the message handling chains. Now the time has come to take a closer look at asynchronous message handling and how to influence the communication style.

You will learn more about the inner working of SAP HCI during message processing and how the system determines whether a scenario is synchronous or asynchronous. The SOAP channel is used as an example to explain the differences between synchronous and asynchronous message delivery to the SAP HCI server. On the receiving side, the email adapter will be introduced to allow asynchronous message reception. Finally, the message monitor is used to help you understand how SAP HCI handles your messages during the execution of your integration flows.

Synchronous vs. Asynchronous Communication from an SAP HCI Perspective

Let me repeat some main aspects regarding the synchronous versus asynchronous discussion from my first SAP HCI article in this series called “Your First HCI Integration Flow.” Two of the key terms used in that article were Exchange and Message Exchange Pattern (MEP) as shown in Figure 1.

Figure 1

The Exchange container

An Exchange is a term coming from Apache Camel terminology. It represents a container for a message while it is being processed inside the integration engine. Apache Camel itself is the integration framework on which SAP HCI is built. You know from my other article that the Exchange is only filled with an In message if it is an asynchronous scenario, whereas the Out message within the Exchange only plays a role for synchronous scenarios. In addition, the MEP field within the Exchange determines the communication type (synchronous, asynchronous). The MEP field can contain two potential values:

• InOnly: The route handles a one-way message and the sender doesn’t expect a reply from the respective receiver. The Exchange carries an In message only. InOnly represents the asynchronous use case.
• InOut: The route handles a request-response message. The sender expects a reply from the route, which is stored as an Out message in the Exchange. InOut stands for the synchronous communication style.

However, which component determines whether a message should be handled synchronously or asynchronously? The answer: It is the channel. This answer might surprise you, but I show you how to influence synchronous and asynchronous message handling in SAP HCI by using the SOAP adapter.

I’m reusing the scenario in my last article, titled “Working with Lists in SAP HANA Cloud Integration.” The scenario is shown in Figure 2 and the associated input message is shown in Figure 3.

Figure 2

Demo scenario for splitting and joining messages

Figure 3

Example input message for demo scenario

The integration flow in essence splits the incoming message into three individual messages. Each of the three single messages contains exactly one order. The two Content Modifier steps are executed three times (for each of the single messages). The first Content Modifier extracts the order number from the single message and writes it into the message’s header area. The second Content Modifier retrieves the order number from the header area again and writes the number, embedded inside order tags, into the body area of the message. As this is done three times, the resulting message contains just the three order numbers, each one surrounded by order tags (Figure 4).

Figure 4

Result message after invoking the integration flow

The screenprints for the input as well as for the result message are taken from a SoapUI test client. Therefore, the scenario is currently a synchronous scenario. Otherwise, there would not have been a response back. However, where did I define that it should be a synchronous scenario? I didn’t define it. It is getting even more mysterious when I tell you that the incoming message was built using a WSDL file containing the description of an asynchronous interface. You can verify it by downloading the associated WSDL file. Its name is SendOrderList_Async.wsdl (Figure 5).

You will find the following lines in it (Figure 6).

Figure 6

Definition of the service's operation

Obviously the operation consists of just an input message, but no output message that would be needed for a synchronous interface. Then why is SAP HCI interpreting it as a synchronous message exchange? Now I will reveal the secret: It’s not SAP HCI that makes it a synchronous call, it is the SOAP sender channel in Figure 2. So it makes sense to take a closer look at the SOAP adapter’s configuration (Figure 7).

Figure 7

Configuration of the SOAP channel in the demo scenario

Just the Address field is set with a string that is used to create the URL for invoking the integration flow. Besides that, you find no information about synchronous or asynchronous message handling at all. So what should the channel do once it receives a message from a client? It knows absolutely nothing about the data that arrives at its address. It knows nothing about how the data it receives was constructed. It also knows nothing about whether it is based on a synchronous or asynchronous WSDL file. Note: the WSDL file I mentioned above was just used in the SoapUI client to create a proper input message, but the WSDL file was never used in any of the SAP HCI configuration steps for that scenario.

Hence, SAP HCI knows nothing about the data it should process. This is the payload-agnostic behavior of Camel I was talking about in my first article in my series. You can actually push anything to SAP HCI. It works as long as you don’t have processing steps in your route that rely on a specific format.

Let’s continue with the description. As the channel doesn’t know which type the incoming message is, it switches automatically to default mode. Default mode for the SOAP channel means all messages are handled as synchronous messages. Therefore, the MEP field in the Exchange is set to InOut. This explains the synchronous behavior of my scenario.

The message walks through the steps of the integration flow and a result message is created at the end of the chain when you reach the End event (Figure 2). Here some magic happens. As there is no additional step to process, the last status of the message’s body is copied automatically into the body of the Exchange’s Out message. Remember: synchronous messages have both of the following in an Exchange: an In and an Out message and the reply needs to be in the Out message. The Out message (including body, headers, and attachments) is returned to the caller.

The next question is: Can you make the route behave asynchronously? Yes, you can. You just have to make the SOAP channel aware of the concrete message it receives. The configuration of the SOAP channel provides a dedicated field for this named URL to WSDL (Figure 6). It allows you to point to the WSDL. Just click the Select button. In the Select WSDL Resource dialog box, click the Upload from File System button (Figure 8)

Figure 8

Add a WSDL file to the SOAP channel

The normal file picker dialog opens. Select the file SendOrderList_Async.wsdl from your file system. The final configuration of the SOAP adapter, including the link to the WSDL file, should look like the one shown in Figure 9.

Figure 9

Configuration of SOAP adapter after assigning the WSDL file

Save and deploy your change. By adding the WSDL file to the SOAP channel’s configuration, the correct asynchronous message handling can be ensured. The channel knows that it receives an asynchronous XML message compliant to the WSDL and sets the MEP field of the Exchange to InOnly. However, a validation of the incoming message against the WSDL is not done for the incoming data. SAP HCI provides a dedicated processing step for that purpose – the XML Validator that requires the assignment of a WSDL file in its configuration.

Once the integration flow is deployed you can invoke your integration flow again from your SOAP test client of choice. If you are using SoapUI, you receive nothing back as a reply message. You just get the acknowledgment from SAP HCI about the successful reception of the message as an HTTP response code 202 (Figure 10).

Figure 10

Returned header from SAP HCI after invoking an asynchronous route via SOAP channel

What happened to my message inside SAP HCI? Where can I track this, now that I don’t have my SoapUI showing the result? Simply navigate to SAP HCI’s message monitor by clicking the three horizontal bars in the upper left corner () and choosing Monitor from the drop-down menu (Figure 11).

Figure 11

Switching to SAP HCI's monitoring environment

The monitoring dashboard opens. Click the tile for the successfully completed integration flows in the Message Monitor area of the screen (Figure 12).

Figure 12

Tile for switching to the monitor of completed messages

By clicking the Completed link of your successfully finished message (Figure 13) you receive more details about the message processing steps within SAP HCI. In case of errors, you would open the Failed Messages tile in Figure 12 and click a Failed link instead, but the navigation and the information you receive is the same. Make yourself familiar with the message log to use it for root cause analysis in erroneous situations.

Figure 13

Navigating to the successful completed message within the message monitor

Note that the SOAP channel supports both communication styles: synchronous and asynchronous. You have seen how to influence its behavior. This is not the case for all adapters. The SFTP adapter, for example, supports asynchronous message handling only. Therefore, it merely supports InOnly as an entry in the MEP field. Consequently, communication styles are highly adapter dependent and differ from adapter to adapter.

Adding an Asynchronous Receiver

Now that you know how to make a SOAP invocation asynchronous, you probably want to deliver the message to an asynchronous receiver to verify the correct content of the received message. To keep the administration effort at a minimum, I use an email receiver. All you need to complete this exercise is a publicly accessible email account. Here is the list of modeling steps you have to complete to run the scenario with an email receiver:

1. Add a Receiver to the model on the right side of the integration flow. You find the Receiver beside the participants node () in the palette (Figure 14).

Figure 14

Select a Receiver from the palette

2. Position the Receiver on the right side of the Integration Process, close to the message end event (Figure 15).

Figure 15

Position the Receiver pool close to the End event

3. Connect the End event with the Receiver pool (Figure 16).

Figure 16

Connect the End event with the Receiver pool

4. In the Adapter Type dialog, click the Mail entry (Figure 17).

Figure 17

Click the email adapter

5. Configure the adapter according to your email account. The values shown in Figures 18 and 19 fit for a Google email account. For more details on how to configure the email adapter, take a look at the online documentation of SAP HANA Cloud Integration at https://cloudintegration.hana.ondemand.com/PI/help > Designing and Managing Integration Content.

Figure 18

The General tab for configuring the Mail adapter

Figure 19

The Connection tab for configuring the Mail adapter

Most of the fields are self-explanatory. However, one field needs further explanation. The Credential Name field in Figure 19 contains a simple string that refers to a deployed artifact of type CREDENTIALS on the SAP HCI server. You cannot define the user and password directly on the configuration screen. You need to deploy the credentials containing the user name and password on the server explicitly.

This step is necessary for connections with basic authentication needs as is the case for the email connection. When deploying the credentials on the server, you have to provide a unique name (such as FirstnameLastname in my example) for reference purposes. This name is exactly the one you have to enter in the Credential Name field. If you have the rights for deploying (ask your tenant administrator), you can execute the steps described in the sidebar “Create a User Credentials Artifact.” (For further details see the description in the SAP HCI Documentation. Follow the link Operating and Monitoring SAP HCI and navigate to Web-Based Monitoring > Managing Security Material > Deploying / Editing a User Credentials Artifact.) If you don’t have deployment rights, ask the tenant administrator to take over the steps for you.

The definition of the Mail Body field again uses Camel expressions. You are explicitly accessing the In message of the Exchange and taking its body, which contains nothing else than the message’s payload – exactly what you want to see in the email.

The final scenario should look similar to the one depicted in Figure 20. You can easily identify the sender on the left, the message processing steps in the middle, and the final receiver on the right. That’s the advantage of a graphical environment. It clearly and intuitively describes how the message arrives at the server, how it is handled within the SAP HCI server, and to which systems using which channels it is forwarded.

Figure 20

Asynchronous integration flow with the email receiver

Once you have finished your configurations, you can run the scenario again. This time the message is delivered to your email account. You should receive an email containing the three order numbers. Figure 21 shows the email’s content. In case you are experiencing issues with your connection to your Google email account, take a look at the sidebar “Troubleshooting the Connection to the Email Server” for further investigation.

Figure 21

The content of the received email

Create a User Credentials Artifact

To enable the tenant to connect to the email receiver using the credentials of the email account owner, you have added a Credential Name in the Mail adapter’s configuration of your integration flow as shown in Figure 19. It is nothing else so far than a placeholder for an artifact that I will create with the next steps.

1. Choose the Monitor tab of the WebUI (Figure 11).

2. Select the Security Material tile beneath the Manage Security Material section (Figure A).

Figure A

Select the Security Material tile

3. Click Add > User Credential (Figure B).

Figure B

Add a User Credential

4. Specify the properties of the User Credentials artifact. As Name enter the value that you have entered in the Credential Name field in the Mail adapter (Figure 19). As User enter your email box user name, and as Password/Repeat Password enter the associated password. Leave the SuccessFactors check box deselected. This setting is only relevant when you define credentials to be used when connecting to a SuccessFactors system (Figure C).

Figure C

Properties of a User Credentials Artifact

5. Click the OK button.

Dr. Volker Stiehl

Prof. Dr. Volker Stiehl studied computer science at the Friedrich-Alexander-University of Erlangen-Nuremberg. After 12 years as a developer and senior system architect at Siemens, he joined SAP in 2004. As chief product expert, Volker was responsible for the success of the products SAP Process Orchestration, SAP Process Integration, and SAP HANA Cloud Integration (now SAP HANA Cloud Platform, integration service). He left SAP in 2016 and accepted a position as professor at the Ingolstadt Technical University of Applied Sciences where he is currently teaching business information systems. In September 2011, Volker received his Ph.D. degree from the University of Technology Darmstadt. His thesis was on the systematic design and implementation of applications using BPMN. Volker is also the author of Process-Driven Applications with BPMN as well as the co-author of SAP HANA Cloud Integration and a regular speaker at various national and international conferences.

 

You may contact the author at editor@SAPpro.com.

If you have comments about this article or publication, or would like to submit an article idea, please contact the editor.