This blog discusses options how to configure session re-use for http-based receiver adapters in your integration flow. It describes the different configuration options available and existing limitations. It provides some sample configurations explaining when to use which option and why.

Session Handling Configuration in Integration Flow

Many integration scenarios use one or several HTTP based outbound calls from SAP Cloud Integration. For some scenarios re-using sessions across several calls can be useful to improve performance or to connect to a server keeping a state (stateful service).

What is a Session and why Could Re-Use Make Sense?

Calling an HTTP service in a backend will create a session on the backend server, if the server supports sessions. In this case the server will create a session cookie (for example a JSESSIONID cookie) and send it back to Cloud Integration. Subsequent calls from the client to this server will be done with the same cookie, so that the server can correlate the call to the correct session.

The session cookie can be set for the whole server, or for the specific path called. This can be configured in the server, but normally the session is set for the whole server.

The session is hold on the server for a specific time, afterwards the session is removed and with the next request coming in a new session is created. This session timeout value is set by the server and can normally be configured there.

In case session re-use is configured, authentication is done only with the first call, all subsequent calls re-use the session and no additional authentication takes place. Because authentication and the creation of the session on the server can be a costly process, re-using the same session can improve the performance of the scenario significantly. But you have to carefully check the restrictions below, if those are accepted for your scenario.

In addition to the performance improvement session re-use brings, it may also be useful when communicating with stateful services, where a single action typically involves more than one request. In this case, subsequent calls will not only skip additional authentication but can furthermore update the state on the server.

Adapters Applicable for Session Handling

In Cloud Integration several adapters can be used for connecting to receiver backends, the adapters using HTTP protocol can potentially use HTTP session handling. But as for example Success Factors servers do not support sessions for REST APIs, the SuccessFactors Adapter with protocol REST and OData V4 does not support session handling.

Those adapters support session re-use:

• SOAP Receiver Adapter with both protocols, SOAP1.x and SAPRM
• IDOC Receiver Adapter
• HTTP Receiver Adapter
• SuccessFactors Receiver Adapter with protocols OData V2 and SOAP
• SuccessFactors Sender Adapter with protocol SOAP
• ODC Receiver Adapter
• OData Receiver Adapter
• AS2 Receiver Adapter (with 10-December 2017 Release)
• XI Adapter

Configuration Options in Cloud Integration

The session handling is configured on integration flow level for all adapters supporting HTTP session handling as listed above. This means, session re-use is possible for different kind of adapters used towards the same backend in the same integration flow.

There are three configuration options available, default is None:

• None: If no sessions shall be re-used you select None. In this case no session will be maintained between the integration flow and the server called by these adapters.
• On Exchange: If this configuration option is selected, the session will be re-used for the whole processing of one message, meaning for one message exchange. This makes sense if the integration flow executes several calls to the same backend during one message exchange, for example in case of a loop or multicast scenario. Then the subsequent calls are much faster because no authentication is to be executed. It can also be used if the server keeps a state and you want to connect several times to the stateful service within one exchange
• On Integration Flow: Using this configuration the session is re-used across several calls of the integration flow. Even parallel calls to the same integration flow would be done with the same session ID. You can expect the highest performance improvement using this option but this option only works for stateless services.

Old Version of Integration Flow without Session Handling Configuration

In the past, with the older version of integration flow, there was no configuration option available for session handling on integration flow level. This means, if you open existing integration flows and select the integration flow runtime configuration, you will not have the option to configure the session handling. Within this version the default option without session re-use is used.

You need the newest version of the integration flow to have the configuration options. Currently you need to create a new integration flow and remodel the flow to have the options for session handling configuration or use the migration of the integration flow configuration, available with the 12-December 2017 update to avoid to remodel the whole integration flow.

The migration is described in detail in Blog ‘Versioning and Migration of Components of an Integration Flow’.

Recommendations and Restrictions

There are some important restrictions existing for configuring sessions. Carefully check out the listed restrictions and recommendations.

Session re-use is only possible with the adapters listed above.

In case session handling will configured in an integration flow without any of these adapters, the configuration setting will be ignored.

Session handling can only be configured on integration flow level.

This means the configuration will be applicable for all adapters supporting session handling in the integration flow, there is no option to take one of the adapter channels out.

Authentication takes place only with the first call.

If session re-use is configured, authentication takes place only with the first call, subsequent calls re-use the session under the same user initially logged in.

This means,

• if a second channel to the same backend would be configured with a different user in the integration flow, this setting would be ignored, the user from first call is also used for this call. So, do not use session re-use in case you need to have logins to the same backend with different users in the same integration flow.
• If option ‘On Integration Flow’ is used, the user from first execution of the integration flow would also be used for later executions of the integration flow. The user in the channel used for authentication, especially if configured as dynamic user (${header…}, ${property…}), would not be used. This may lead to unexpected runtime behaviors. So, only use ‘On Integration Flow’ option if you always use the same user for authentication towards the receiver system, else use ‘On Exchange’ or ‘None’.

Session is removed in the server after a certain idle time.

If there are no calls to the server for a certain time, the session is removed in the server. With the next request sent, authentication takes place again and a new session is created. This session timeout value can normally be configured in the server. This behavior needs to be taken into account especially if communication is done to a stateful service.

Use the Session Handling option On Integration Flow only for Stateless Services.

In case configuration option On Integration Flow is used, sessions will be shared between different calls of the integration flow. Calling a stateful service with this option may lead to unpredictable behavior in your scenario because sessions may be mixed between parallel integration flow executions.

Parallel Multicast or Splitter Scenarios may not reuse sessions if not configured correctly.

Session reuse may not work in parallel multicast or splitter scenarios if there are multiple calls to the same system without a session being established before the splitter or multicast. In order to enable session reuse in such cases you would have to make a call to the external system prior to the parallel multicast or splitter so that the Session ID retrieved in this call can be reused in the external calls modeled in parallel multicast or splitter.

If Cloud Connector is used, configure the Domain Mapping for Cookies.

If the receiver adapter uses the SAP Cloud Connector to connect to an on-premise system, you may need to configure the domain mapping for cookies in the Cloud Connector as described in the documentation chapter Configure Domain Mappings for Cookies. This is required if the virtual host does not match the backend host.

Monitoring the Session Cookies

With 12-November 2017 release you have the option to monitor the session cookies send during request using CPI monitoring. This is possible with setting DEBUG log level for the integration flow.

Set Log Level Debug

To enable the DEBUG log level select the deployed integration flow in Manager Integration Content monitor and select log level Debug.

In detail the log levels are described in the Blog ‘Configure Log Level in Message Processing’.

Check Message in Message Processing

After setting the Debug log level send a message and afterwards check the message in Monitor Message Processing in Operations view.

Select Message Processing Log to view the mpl for this message.

In the message processing log check the parts, where the message is send out to the receiver system. In the below sample Session Cookie Handler is used to receive and re-use the session cookies. In the first request you see that no cookie is set yet. In response section the Set-Cookie header contains the session cookie.

In the second request the re-used session cookies can be found. The cookies are not shown in plain text for security reason. Only the hash value is shown. You can use this info to check if in all the requests the same hash value is used.

Sample Scenarios 

In the following chapter we will showcase some simple sample configurations using the different options for session handling.

Scenario 1: Re-Use Sessions on Message Exchange Level

In this scenario, we connect to a stateful service, we call the same backend several times in a loop. First call is doing the authentication and fetching first block of data to process them, the subsequent calls are then fetching next blocks of data, all is done in the same session to enable the server to know which data was already fetched. After fetching the data, the message is processed in a script and forwarded to the receiver backend.

For such scenarios using stateful sessions on the receiver you need to select the HTTP Session Handling option On Exchange to make sure parallel requests are not mixing their sessions.

Scenario 2: Re-Use Sessions on Integration Flow Level

Within this scenario, we have only one call to a stateless service in a backend. But there is a high message load for this integration flow, meaning there are lots of calls in a short timeframe. To improve performance for the scenario you use the HTTP Session Handling option On Integration Flow.

With this setting all calls to the HTTP backend via this integration flow share the same session as long as the session is available on the server. No new authentication is done in this case.

Scenario 3: No Session Re-Use

In this scenario, there are two calls done to the same backend to fetch data, but it is mandatory to execute the calls under different users because different authorizations are checked in the backend.

In the first HTTP receiver channel credentials for one user are maintained, in second HTTP receiver channel a different user is configured. To avoid re-using the user credentials from first HTTP receiver call in second call as well, you need to use the HTTP session handling option None.