Skip to Content
Technical Articles
Author's profile photo Mandy Krimmel

Cloud Integration – How to configure Session Handling in Integration Flow

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.

Assigned Tags

      You must be Logged on to comment or reply to a post.
      Author's profile photo Former Member
      Former Member

      Hi Mandy! Thanks a lot for sharing this new feature with the community!

      Author's profile photo Vikas Singh
      Vikas Singh

      Session Handling feature is a step forward on the path of a complete Intaas. Very detailed blog. KUDOS for the feature and the details.

      Author's profile photo Piotr Radzki
      Piotr Radzki

      thanks Mandy, very helpful!

      Author's profile photo Manu Bhutani
      Manu Bhutani


      We are getting socket closed error as shown below. We tried increasing timeout but still same issue. Session handling is ‘On exchange’ at present.



      Author's profile photo Mandy Krimmel
      Mandy Krimmel
      Blog Post Author


      Please open a ticket on LOD-HCI-PI-GB so that the respective colleagues can have a look why the session timeout is not working.

      Best regards,


      Author's profile photo Vinay Puttaswamy
      Vinay Puttaswamy

      Hi Manu,

      Did you get any update from SAP on this issue . Even I am facing the same issue , especially when my odata query is quite big and has nested structures in it.





      Author's profile photo Manu Bhutani
      Manu Bhutani

      Hi Vinay Puttaswamy,

      As of now we didn't get a concrete answer, we were suggested to increase the time out but that didn't help. After 2 days the we didn't get this error. We didn't do anything to resolve.



      Author's profile photo Pushkar Patel
      Pushkar Patel

      Hi Mandy,

      Thanks for informative blog.

      We are receiving an invalid response error (below) while connecting to SF Tenant connecting using SF ODATA adapter.  Other iflows are working fine.  After doing further analysis,I came across note "2832169 - Cloud Integration Error" which talks about session reuse as one of the resolution.


      Do you think it can be related to HTTP session handling ?

      We are testing few bulk scenario simultaneously ( not with SF) where we have processed few big ( 50-60 MB files with transformation. Does CPI  tenant stores those files / payloads even after undeploying the iflows or running it none log info mode.

      I have created a ticket for SAP , waiting for their response. Came across your blog, thought it would be interesting to know your opinion.

      Error Details We're Sorry...but the server, while acting as a gateway or proxy, received an invalid response from the upstream server it accessed in attempting to fulfill the request (error code 502). : 503 : HTTP/1.1
      Author's profile photo Mandy Krimmel
      Mandy Krimmel
      Blog Post Author


      hard to say from the distance. If you have opened a ticket for the respective adapter the experts will check the error message and give you a suggestion if this is related to the session handling.

      Have you tried with activated session handling?

      The payloads are not stored in the CPI tenant, they are only available in memory during processing and depending on the flow steps only parts of the payloads in case of streaming-enabled steps.

      Only if tracing is activated the payload is stored for a certain time interval.

      Best regards,


      Author's profile photo Pushkar Patel
      Pushkar Patel

      Thanks Mandy for your reply.

      I have received reply from SAP this morning. Been advised their SuccessFactors operations team evaluated the issue and they found out that it was caused due OS Patching affecting the API servers, generating the error in the APIs"

      Thanks again for your input.

      Author's profile photo Mandy Krimmel
      Mandy Krimmel
      Blog Post Author

      Thank you for coming back and sharing the solution 🙂

      Author's profile photo Dhinesh Kumar R
      Dhinesh Kumar R

      Hi Mandy,

      Thanks for the wonderful blog.Trying to understand if the session reuse is applicable only if the authentication type is "BASIC" or is it applicable to "Client Certificate" authentication as well

      Author's profile photo Mandy Krimmel
      Mandy Krimmel
      Blog Post Author

      ist applicable for both,



      Author's profile photo Balu Badugu
      Balu Badugu

      Hi Mandy,

      I am unable to use session reuse 'on Integration flow' if I use OAuth2 authentication in SF adapter to improve performance. Could you please let me know if this can be possible .




      Author's profile photo Deepak G Deshpande
      Deepak G Deshpande

      Hi Balu,

      Can you elaborate the issue? Or may be you create a ticket explaining the problem and we can respond/update you in the ticket?




      Author's profile photo Balu Badugu
      Balu Badugu

      Hello Deepak,


      Thank for responding, I am getting below error stating HTTP session reuse is not supported "ON Integration Flow" with OAuth2 Authentication.





      Author's profile photo Punith Oswal
      Punith Oswal

      Hello Mandy,


      Thanks for this information.

      I have a scenario, where i have used XI Sender Adapter to receive proxy messages from ECC system, the number of messages/call is quite high, example around 500 messages/calls per minute,  For this scenario, as this is an inbound call to CPI, HTTP transaction handling should be "on exchange" is that correct ?


      I am currently using "None" and i got some connection issue with error log shown below:


      Error message: Error Details

      Inbound processing in endpoint at ********** failed with message "Fault:java.lang.IllegalArgumentException: Unable to query *(messageID)*", caused by "SQLTransientConnectionException:it-db-rt.l0*** - Connection is not available, request timed out after 30000ms."


      Can this error be avoid with proper HTTP transaction handling?


      Please clarify.





      Author's profile photo Mandy Krimmel
      Mandy Krimmel
      Blog Post Author


      this error sounds more like an issue with the DB connectivity in Cloud Integration. Does the error occur in the XI adapter in Cloud Integration? Or in the receiver backend?

      I dont think that session handling would help here.

      I would suggest to open a ticket for this issue on LOD-HCI-PI-CON-SOAP

      best regards


      Author's profile photo Frank Hinrichsen
      Frank Hinrichsen

      Hi Mandy

      First, thank for a super nice blog.

      I have implemented "HTTP session reuse" in my Iflows and achieved some optimization on this. But I’m not 100% satisfied with the result as I sometimes see multiple token calls.

      My scenario is stateless, REST API call, using HTTP receiver adapter

      Main Iflow will call a Local Integration Process to enrich data. This Iflow will use the API (GET method). After that the main Iflow will call the API(POST method).

      Both Iflows are configured to use "HTTP session reuse" and both are using the same API and security material.

      Security material is setup accordingly to support this, using Grant type: Client credentials.

      The REST API token request has a limit to how many times it can be called. Token is valid for 1 hour. I want to reuse the token for as long time as possible.

      Our CPI instance has 6 nodes. Could that have any effect on the session reusability. Is the JSESSIONID cookie only reusable on node level?

      Could you elaborate on how this works in CPI.

      Other solution to fix this is also appreciated



      Author's profile photo Mandy Krimmel
      Mandy Krimmel
      Blog Post Author


      The session reuse feature creates an in-memory cookie store on the different worker instances. This means that each worker will have its own session. The validity time and scope (domain and path) is defined by the server sending the cookie

      Best regards