Learn how to remotely debug App Connect Enterprise integration solutions that are running in IBM® App Connect on IBM Cloud™ (with a plan that provides enterprise capabilities) and IBM App Connect Enterprise on premises.


You have a hybrid integration solution that comprises several message flows, partly running on IBM App Connect on IBM Cloud and partly running on your local machine. You want to debug messages passing through the message flows and perhaps change the data as messages are passing through those flows. This scenario involves a integration solution that has 3 message flows:

  • 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 page:

    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

        The integration server is displayed as a tile in the dashboard:

      2. 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. When 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 “Connect callable flows” and then 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 *