Learn how to remotely debug App Connect Enterprise Integrations which are running on IBM¬ģ App Connect on IBM Cloud‚ĄĘ (with a plan that provides enterprise capabilities)


You have a hybrid integration deployment, partly running on IBM App Connect, partly running on your local machine and you want to debug the message through the flows / change the data as the message is passing through the flow. This scenario involves a flow which has 3 parts

  • Calling Flow – This is exposed as a RestAPI and provides the ability to query users
  • Logging Callable Flow – This performs logging of the request (not implemented in this demo) and updates the message with the hostname and timestamp it was logged
  • User Callable Flow – This makes a request to a public RestAPI which returns the details of a specific user.

The ‘Calling Flow” and “User Callable Flow” are deployed to IBM App Connect on IBM Cloud‚ĄĘ (with a plan that provides enterprise capabilities) and the “Logging Callable flow” is deployed locally


First, find or create everything you need:

  • An IBM Cloud account with an IBM App Connect service instance that provides enterprise integration capabilities; for example, the Lite or Custom Enterprise plan.
  • Optionally, you can also install IBM App Connect Enterprise for Developers if you want to look at and change the deployed flow. It is not necessary for running the tutorial, but it is useful for examining the flow to understand how it works.
    (Note: The enterprise integration project for this tutorial was developed with the IBM App Connect Enterprise Toolkit, but can be examined with the Integration Toolkit of IBM Integration Bus V10.)
  • If you want a bit more information before you start, you can read more about the App Connect Enterprise Developer edition on the following pages:

Import the enterprise integration project into App Connect Enterprise or IBM Integration Bus, and examine the message flow:

You do not need to complete this step unless you want to look at or change the flows. A separate BAR file is also provided for deploying the integration into App Connect on IBM Cloud, as described in a later step.

Read more

All the resources required for this tutorial are provided in a project interchange file named RemoteDebuggingDemo

The steps are the same for App Connect Enterprise V11 Enterprise Toolkit and IBM Integration Bus V10 Integration Toolkit (the toolkit):

  1. Download the project interchange file, by clicking the link above and saving the file to a local directory.
  2. Open the toolkit.
  3. To import the project into the toolkit, click File > Import, expand IBM Integration, select Project Interchange, and click Next. Then browse to select the downloaded project interchange file and click Finish.

3 new projects are displayed in the toolkit.

This RestAPI project contains one flow called MessageProcessing.msgflow, which implements a REST service with the following resource path:

  • /getUser for getting the details of a customer

This API is built up of 3 flows:

  • Main Flow

  • Logging Callable Flow – This includes a java compute node which adds the name of the hostname it was processed on along with a timestamp

  • User Request Flow – This makes a request to a public RestAPI for the details of a specific user.


Configure the integration in App Connect on IBM Cloud:

  1. Locate both GetUsers.bar & MessageProcessing.bar within the downloaded zip file.
  2. Sign in to App Connect on IBM Cloud.
  3. For both the files perform the following steps
    1. From the App Connect on IBM Cloud dashboard, click New > Import a BAR file and select the BAR file that you downloaded. Then click Impor
    2. The integration server is displayed as a tile in the dashboard
    3. Start the integration by opening the options menu [‚čģ] for the integration server, and then clicking Start. When the integration shows Running, the integration is running and ready to use.
  4. Once you have imported both integrations they should both be shown running
  5. Validate that both applications have registered with the Switch by going to the Callable Flows page (= menu -> Callable Flows). You should see a table as shown below
  6. Click the “Connect callable flows” and the select “Download the configuration” to download an agent.json configuration file to use in the next section

Configure the integration locally:

Open a App Connect Enterprise command console and run the following commands

  • mqsicreateworkdir <workdir> (workdir can be any location on your machine)
  • cp <downloadLocation>/agentx.json <workdir>/config/iibswitch/agentx/
  • IntegrationServer –work-dir <workdir>

Deploy the OnPremLogging.bar to your local integration server by running

  • curl -X POST http://localhost:7600/apiv2/Deploy –data-binary @OnPremLogging.bar

Reload your web browser on the callable flows page and it should now show an additional registered provider as shown below:

Configure the integrations for remote debugging:

On your local integration server:

Update your servers configuration file by editing <workdir>/server.conf.yaml¬† and searching for “jvmDebugPort”, uncomment the line and change the value from 0 to 45678

Restart your integration server

Configure your integrations on IBM Cloud:

Stop both your integrations running in App Connect on IBM Cloud

Enable Remote debug on Integation 1 and 2 by selecting the … menu and selecting Enable remote debugging

Select both integration servers and then click “Next”

Click the “Download the configuration” to download your agentc.json

Start both your integration servers

Update your Integration Server for enabling remote debugging:

Copy the downloaded agentc.json into your Integration Servers configuration folders

  • mkdir¬†<workdir>/config/iibswitch/agentc/
  • cp <downloadLocation>/agentc.json <workdir>/config/iibswitch/agentc/

Check Integration Server logs which should show  some extra logging around agentc such as

component started: "agentx"
component starting: "agentc"
Starting agentc with config folder: '/Users/convery/Documents/Code/DebugServers//config/iibswitch/agentc'
2019-04-10 19:15:45.990580: The integration server component 'agentc' has been started. 
component started: "agentc"
2019-04-10 19:15:46.788060: The secure connectivity agent for cloud systems has established a connection to the Switch server with URL 'wss://ibm-sw-cmsvwpeckhwbrwtfe.ibmintegrationbus.ibmcloud.com:443/'.

Connect the toolkit debugger to your Integrations:

In the toolkit select the dropdown on the debug symbol and select “Debug Configurations”


Repeat the following steps for the following 3 connection details:

  • localhost:45678
  • localhost:10000
  • localhost:10001
  1. Select a new “IBM App Connect Enterprise Debug” configuration

2. Add new debug connection with hostname of localhost and port of 34567 (Local Integration Server)

3. Finally select “Debug” to connect to the integration server

(Note: It can take a couple minutes to make the initial connections)

Once you have enabled all 3 debug configurations switch to the debug perspective and you should see all 3 sessions.

Add Breakpoints

Expand the “GetUsers” folder, ¬†expand “Flows” and then double click “Request.msgflow” to open the flow. Right click on the first connection and select “Add Breakpoint”

Expand the “MessageProcessing” folder, ¬†expand “Resources”, expand “Subflow” and then double click “postGetUser.subflow” to open the flow. Right click on the first connection and select “Add Breakpoint”

Expand the “OnPremLogging” folder, ¬†expand “Flows” and then double click “LoggingProvider.msgflow” to open the flow. Right click on the first connection and select “Add Breakpoint”

Test Integration

On the App Connect on IBM Cloud click on the “MessageProcessing” tile and then

click the “Show API Explorer” link

Click the “Try It” link which will load a window you can use to test your message flow.

In the “body” enter { “id”:”1″} and select “Call Operation”

After calling the operation the toolkit will trigger and highlight the point in the flow where the message has been caught. You can then step through the flow just as you would as if all the flows were running within your local system

Join The Discussion

Your email address will not be published. Required fields are marked *