Skip to Content

Troubleshooting SOAP, HTTP and Mail Adapter Scenarios with TCPGateway

When I started to work with the SOAP adapter, I find out that for troubleshooting it is necessary to trace the HTTP or SMTP stream. This is useful to see the settings of the HTTP/SMTP header fields like Content-Type.

When you look at SAP Note 856597 (User required) and scroll down until you see the attachments, you find a file with name


Download the file, extract the file using Winzip and then you find following files and folders:


The index.htm provides you information for use cases for SOAP and IMAP protocol.

To start the TCPGateway, you start program aiitcpgw.bat. You need a JRE (Java Runtime Environment) installed on the computer.

Example with SOAP adapter

I want to show how to trace a web service call. I use the receiver SOAP adapter. In my example the URL of the web service is ‘http://pwdf2153:54000/XISOAPAdapter/MessageServlet?channel=:File_SOAP_SOAP_File:SOAP_Sender‘. In fact the target is just a sender SOAP adapter, which is good enough to do first tests.

First I configure the TCPGateway in a way that it points to the web service address. So I put the server name to Target Hostname and the port number to Target Port. I can add any free port number as listen Port, for my convenience I use the same port number as target port, but this is not required. After filling these entries I click on Add


Now I set redirect the URL in the SOAP adapter receiver channel. I only change the server and port, but the rest of the URL, namely the path and the query string, I leave untouched. As server name I use the IP address of my local PC, where the TCPGateway is running. Sometimes you cannot access a local PC from the XI server, in this case the TCPGateway has to be installed on XI server directly.


When I send a message now, then I see the HTTP stream for the request and the response message in the TCPGateway after clicking on the tab with the port number.


You can see the HTTP header fields, the message and all attachments. In the response you can see the status code and the fault messages.

Example with Internet Proxy

You can trace connections routed through an internet proxy as well. The only difference from the above example is, that you redirect the proxy server settings with to the TCPGateway. In this example I use my proxy server proxy on port 8080.


In the receiver channel I have to change the proxy settings. Here I use on HTTP adapter channel


Example with Mail adapter

The TCPGateway can as well be used for SMTP, POP3 und IMAP4 protocol. For this example I add my mail server address and the standard port 25 (for SMTP) as the target.


In the receiver mail adapter channel I put the IP address of my local PC to the mail server URL.


After sending a message I see the SMTP stream in the TCPGateway.


You must be Logged on to comment or reply to a post.
  • >>>>>Sometimes you cannot access a local PC from the XI server, in this case the TCPGateway has to be installed on XI server directly.

    I guess that's why I never managed to run
    this tool even though I tried 🙂


    • Hi Michal,

      There is often no access from XI to a local PC. But a consultant should have access to the XI server and can run the TCPGateway there.


      • Stefan,

        Heard so much about TCP Gateway.....but after seeing your blog, really got good idea for the topic.

        I would appreciate if you could send me( some link/docs, giving some more detailed information on TCP Gateway


        • Pooja,
          Just follow this blog by Stefan, and you will be easily be able to crack the TCP Gateway tool.

          Just download it from the SOAP Adapter FAQ on Service Market place, read the Read Me document in the attachment and this blog and you will be set to use this tool.


  • Hi Stefan
    I remember that day on the XI forum when you had helped me crack using the TCP gateway as well. This blog would sure go a long way in helping others as well.


    • Hi Bhavesh,

      I found out that nobody had a blog mentioning the TCPGateway so far. I use this tool very often and it helped me a lot.


    • You are right. I should have mentioned your blog, as your blog inspired me to write this blog.
      In fact you mentioned the TCPGateway very short and I thought it was necessary to go more in detail.


    • I was not aware that this was an issue of interest.
      It is not a secret. When you download the tool, you see this written in the README file:

      "The program includes software developed by the Apache Software Foundation"

      Best regards

  • If you have access to XI machine, it'd be a better idea to use a sniffer to monitor the port which you are using in receiver adapter. Also, with a sniffer, you could even monitor messages coming into XI (before they reach sender adapter).

    I think they are more useful because you don't have to change anything in your adapter configuration, since sniffers work in passive (listening) mode. 🙂



    • This blog describes the TCPGateway. You might choose the tool that fits best to your requirements.
      If you think, a sniffer is better, why don't you write a blog about sniffers?


      PS: The TCPGateway can be used as well for monitoring incoming messages. Just redirect the address in the sender to the TCPGateway.

    • Henrique,
      I have no clue what sniffers are, and so, if you write a blog on that we can for ourselves see which is the better tool to use for monitoring.

      Looking forward to the blog.


  • HI Stefan,
    Very Nice blog.
    I have tried the TCP Gateway on XI server and still not receive any SOAP messages triggered by Client webservice. Can you pls help me on this?
    • When you install it on XI server, you have to check that the listener port is not used and it must be different from the target port.

      Change the target of the client web service client to the listener port of the TCP gateway.

      In my experience I never used the TCP gateway on sender SOAP adapter, the channelmonitor should provide enough information.
      If the web service client cannot reach the XI server at all, there might be a firewall issue.


  • Nice blog, but how to deal with ssl connections? I really need to see the synchronous http response just after the ssl-encryption has been handled.
    • This is not possible as the ssl decryption is done inside the J2EE engine.
      Try to set up the scenario without HTTPS first.
  • Thanks for sharing this info. I was looking for some tool like this to monitor my out going message.. I had configured as stated in this blog. And I am able to see data when i send message from my XI system, but every thing is appearing in strange characters and not readable form. I tried to change character set to UTF-8 and ISO-8859-1 nut thn also not getting and readable form.
    Can u suggest on this?
    and keep it writing such blogs....

    • It is difficult to say anything to this without knowing more details. Maybe you open a thread in the forum and describe your settings.
      Some ideas: Your file is binary, pdf, zip, or encrypted by ssl.


  • Hi,

    is it possible to run that tcpgw in batch (without gui) ?

    we are having this issue, that connections between sap-ucon (NW-7.40 as-java component) and SAP-PI (NW-7.31) runs well and quick and without processing-delay.  IDOC processing with /httpAdapter in PI/PO


    but changing the target-system from PI (NW-7.31) to PO (NW-7.50) this issue appears:

    => that connections between sap-ucon (NW-7.40 as-java component) and SAP-PO (NW-7.50) are having a delay of about 5 seconds between each message-execution / message-processing using /httpAdapter in PI/PO. - so execution + message-processing is much slower in PO than in PI.


    using that tcpgw between ucon and PO NW-750, the execution is quick as before ucon to PI NW-7.31  ???

    any idea ?