IBM webMethods Hybrid Integration allows the usage of many IBM integration capabilities within one SaaS system. It allows these capabilities to be exposed to on premise systems as well as to applications running directly on the internet.

The App Connect Enterprise capability that can run within webMethods Hybrid Integration allows many different connectivity options ranging from protocols like IBM MQ to direct application connectivity using a vast palette of connectors.

For this tutorial we will show how the App Connect support for simple TCPIP protocols can be used, so that an on premise, raw, TCPIP based application can access integration logic directly running in webMethods Hybrid Integration. It is common for raw TCPIP protocols to be used in industries such as Healthcare or Manufacturing. This tutorial will show how these on premise based applications can still securely use the webMethods Hybrid Integration for complex integration patterns without the need to install on premise integration software.

We will use a simple scenario to demonstrate how webMethods Hybrid Integration can be used by these types of TCPIP app. To reduce the need for hard to get tools the tutorial will use the standard telnet command as the simple raw TCPIP app.

Scenario

A simple lookup of patient's details based on their name is needed. The protocol for this integration will be a simple raw TCPIP request/reply where each request and response is delimited by a new line.

The user will type the patient’s name into the simple TCPIP application and get sent back the patient details.

Prerequisites

I have included all artifacts required to set up the scenario which will be described in detail here.
To follow along and setup a similar system, you will need:

• An instance of webMethods Hybrid Integration, with the following capability enabled:
  • App Connect
• The following App Connect Enterprise artifacts:
  • The TCPIP_Patient_Lookup.bar file contains an integration flow which is triggered by the TCPIP server input node and provides patient details based on their name.
  • Project interchange TCPIP_Patient_Lookup_PI.zip containing the source for all integrations used.
• The command line executable telnet.
  • Can be installed on MacOs using brew install telnet.
  • Can be installed on Windows using:
    1. Open the Control Panel.
    2. Go to "Programs" and select "Turn Windows features on or off"
    3. In the list of features, search for and select "Telnet Client."
    4. Confirm the operation by clicking "OK"

You can follow this article without setting anything up yourself if you would like to understand more about the webMethods Hybrid Integration product.

Setting the scene.

We are going to set up an ACE integration flow running in webMethods Hybrid Integration which can be connected to by a simple TCPIP application running on-premise. The system will look like:

We will start from the position that you have a webMethods Hybrid Integration instance with the App Connect capability enabled but nothing set up on premise or any flows deployed to webMethods Hybrid Integration. For this tutorial the on-premise system can be any machine you have access to like a laptop.

The tutorial will go through the steps to deploy an integration to the webMethods Hybrid Integration instance and setup the private connectivity to it using the ACE switch technology.

Before starting, ensure you have downloaded the bar file: https://github.com/jareeve/tcpip_patient_lookup/raw/refs/heads/main/TCPIP_Patient_Lookup.bar and that you have telnet available on the machine you will use as on premise.

Once fully setup the telnet command will be able to connect via the secure agent over the switch and then to the TCPIP server input node running in the integration flow. The switch uses encrypted tunnels for the part flowing over the public internet, but the local traffic will be unencrypted. It is also possible to do full end to end encryption but that is beyond the scope of this tutorial.

The flow is a very basic TCPIP server based flow that receives newline delimited data and sends back newline delimited responses. Download https://github.com/jareeve/tcpip_patient_lookup/raw/refs/heads/main/TCPIP_Patient_Lookup_PI.zip and import it into the ACE Toolkit if you would like to see how it is written.

Setting the system up: creating the switch configuration

The first setup step will be to create the switch configuration setup to allow port forwarding from the on premise system to the webMethods Hybrid Integration instance.

Log in to the webMethods Hybrid Integration instance and navigate to the App Connect capability using the hamburger menu to the left of the main header:

Once in the App Connect view, select Connectivity from the left hand navigation bar and from there select private networks. On a new instance you should just see the default entry:

We will need a connection file for the integration running in the webMethods Hybrid Integration instance and for the secure agent we will need to setup on premise. Click on the create button to make these two entries. The one we will use in webMethods Hybrid Integration should be called tcpip-endpoints and the one we will use on premise should be called tcpip-listeners. The exact names do not matter but use these names because the rest of the tutorial will reference them:

At this point, the two new Private Network Connections (PNA) are effectively the same, but we will now change them to have the correct configuration for each part of the system.

The first part will we change is the tcpip-listeners. This will define the ports that we have running on premise which our on premise application can connect to. To modify the contents of the tcpip-listeners make a note of the Configuration name. In the case shown above it is pnagent-3c0d8f25-a7e4-44b5-8aad-e4dceeec0798.

It is important at this step you note down the correct configuration name. Now change to the configuration view using the left hand menu and selecting Manage. Select the configurations tab. Identify the correct configuration and select update. In the editing window remove the admin, id, callableflow and endpoints entries. This should just leave the switch entry. Now add the following JSON to the document at the top level.

"listeners":[{
  "name": "tcpip sever",
  "localPort": 10001,
  "remoteHostname": "localhost",
  "remotePort": 10001
}],

It should look like:

Select update, and check that you receive a green success message. If it fails, then it means that the syntax is incorrect and you will need to try again.

Now identify the configuration for the tcpip-endpoints PNA. Repeat the process for this configuration but instead of adding listeners add the following endpoints:

"endpoints": [{
  "name": "tcpip-server",
  "hostname": "localhost",
  "port": 10001
}],

It should look like:

These endpoints are then used to expose the webMethods Hybrid Integration integration ports to on premise.

At this point we have all the configurations defined and need to set up the secure agent on premise.

In the private network view, select the View setup instructions on the tcpip-listener PNA. Follow all the instructions apart from the part about configuring the endpoints. We are not doing that in this case but instead will just user the listeners already defined in the file:

Once you have completed these steps you should have the local secure agent running and ready to forward tcpip traffic to the webMethods Hybrid Integration. The command line output should look like:

It is important it mentions the AgentC as this is the agent which forwards the traffic to the cloud.

Now we are ready to complete the setup by creating the required integration in webMethods Hybrid Integration.

Setting the system up: creating an Integration Runtime and deploying the integration

We now need to create a new integration runtime in webMethods Hybrid Integration with our required integration and switch config attached. Navigate to the Manage view:

Click on create runtime and then you wil need to create a runtime called tcpip which has the tcpip-endpoints PNA attached and the TCPIP_Patient_Lookup.bar deployed. You will need to know the configuration name for the tcpip-endpoints PNA. If you are not sure, then check the private network page. The create page should look like:

Then click on Create. The new runtime with the deployed BAR file will be created. It will be configured to expose its endpoints via the switch. We are now ready to drive the integration via telnet running on premise.

Critical note: it is important that you have the correct configuration on the correct system. Before proceeding, ensure that the local secure agent is using a switchclient.json which has “listeners” defined. And check the “tcpip” IWHI base server has the pna configuration containing the “endpoints” defined. If these are not correct, then the telnet command will be unable to connect to the flow.

Running the scenario

Now the whole system is set up, we can attempt to drive the flow using the telnet command.
From the command line type:

The prompt is now waiting for a patient name. The possible names to try are:

• John Reeve
• Dave Smith
• Alice Barr
• Claire House

For example:

This is now the tutorial working end to end.

To recap what exactly is happening when you use the telnet command:

1. The telnet app connects to the 10001 local port which is exposed by the secure agent on premise.
2. The secure agent sends the request to the request to connect to the switch server over an encrypted tunnel.
3. The switch server sends the request to the remote agent running in the ACE container.
4. The remote agent calls the TCPIP Server Input node over a local connection in the container.

The same process is followed for the sending and receiving of data.

Closing thoughts

From the above simple scenario we have shown how webMethods Hybrid Integration can be used to implement an integration flow that is triggered by a simple TCPIP interaction. The connectivity from on-premise to the flow running in the cloud is handled by the switch mechanism. It is currently not possible to expose this TCPIP server node directly to the public internet so it can only be accessed via this mechanism. This follows most use cases where it is unlikely to directly expose a simple TCPIP protocol directly to the public internet.

It is also possible to SSL enable the route from the on premise app to the agent running on-premise but this has not been done as part of this tutorial.

To start understanding all the amazing things webMethods Hybrid Integration can do and to try this for yourself, take a look at the webMethods Hybrid Integration product page .

If you have any more questions then please feel free to post a question here, or request a demo via the webMethods Hybrid Integration product page .