Learn how to create a callable flow in IBM® App Connect Enterprise (ACE) that updates on-premises data and augments data for SaaS applications when called from a simple event-driven flow in IBM App Connect on IBM Cloud™.

For example, using ACE callable flows can enable non-technical / line of business (LoB) users of App Connect on IBM Cloud to create flows that make simple calls to enterprise capabilities, to securely interact with data in enterprise systems and packaged applications.


This tutorial demonstrates a very simple event-driven flow in App Connect on IBM Cloud that is triggered by a change to a Google Sheets document. The worksheet row is passed to an on-premises ACE callable flow to record the data and augment the response back to the event-driven flow, which then updates another worksheet in the same Google Sheets document. Google Sheets was used as a readily-available SaaS application for a simple demonstration, but for the event and actions you could use other applications from the App Connect on IBM Cloud catalog and specialized processing from the Toolbox. For example, see the tutorial Syncing Salesforce leads with an on-premises sales system.

In this tutorial, you perform the activities of two roles:

  • A non-technical / LoB user, working with SaaS applications as part of their normal activities, and using App Connect on IBM Cloud to connect those applications with enterprise systems.
  • An enterprise IT practioner, using App Connect Enterprise to securely expose enterprise systems for simple use by non-technical / LoB users.

First, find or create everything you need:

  • (Non-technical / LoB user) Google account with a simple Google Sheets document
  • (Non-technical / LoB user) IBM Cloud account with IBM App Connect service – Custom Enterprise, Cloud Connector, or Lite plans.
  • (Enterprise IT practioner) IBM App Connect Enterprise (ACE) on-premises installation, configured with an integration server and its work directory.

If you have not bought IBM App Connect Enterprise (ACE), you can develop and test integration solutions without charge by using the following free options:

See also:

Next, complete the following steps: (Click section title to expand)

  • Configure App Connect on IBM Cloud for ACE callable flows

    In this section we use App Connect Designer to configure callable flows, to enable secure connectivity between flows running in IBM App Connect on IBM Cloud and in an integration server in your on-premises App Connect Enterprise.

    If you have already configured callable flows between App Connect on IBM Cloud and the integration server in your on-premises App Connect Enterprise, you can skip this step.

    1. Click the hamburger menu (top left)
    2. Expand Manage
    3. Select Callable flows (If you don’t see this option, you need to select an Enterprise plan for App Connect on IBM Cloud.)

    Next, click Connect Callable Flows.

    This opens the “Set up an agent” dialog.

    Click Download the configuration, this opens a dialog to save the agentx.json file.

    Leave the “Set up an agent” dialog open (note the dialog contains instructions for installing the agent into the work directory of the integration server in App Connect Enterprise).

    After saving the agentx.json. Copy it to the work directory of the integration server in App Connect Enterprise: workdirectory/config/iibswitch/agentx

    Now on your on-premises ACE software, start the integration server; for example:

    IntegrationServer --name myIntegrationServer --work-dir c:\mywrk\myaceworkdir

    You should see the ACE server start, and the log indicate ...The integration server component 'agentx' has been started:

    Switch back to the App Connect Designer window and then test the agent connection:

    Click Test your Agent


    You should see at least 1 agent found

    You can now close the “Set up an agent” dialog.

  • Create and deploy an ACE callable flow

    In this section we use the App Connect Enterprise Toolkit (Enterprise Toolkit) to develop and deploy a simple callable flow into an on-premises ACE integration server so that the flow is visible in App Connect on IBM Cloud

    Note: If you do not want to create the callable flow from scratch, you can import the project interchange file that was used for this example: MyCallableFlows-PI.zip.

    1. Open your Enterprise Toolkit
    2. Create a simple callable flow similar to the one shown below. In my sample I am using a Trace node to write a copy of the incoming payload to a file and a Compute node to modify the incoming message to add a status element.

      In the sample callable flow, the default logging file path is for use on Linux. If you are testing in App Connect Enterprise on Windows, change the ‘File path’ value to a suitable directory; for example, C:\temp\logger.out.

    3. Check that the Enterprise Toolkit is connected to your ACE integration server (started in the step “Configure App Connect on IBM Cloud for ACE callable flows”). If it is connected, it is shown in the Integration Explorer view:

      • Tip: If the integration server is not shown as connected, complete these steps to connect the server…
        1. In the Integration Explorer view, right-click Integration servers, and then click Connect to an integration server. In the Connection details dialog, enter the host name and port for the integration server. Ensure that the port matches the value of the adminRestApiPort property that was specified in the server.conf.yaml file (in this example, the port is 7600, and the host name is localhost). If the integration server is secured, you must also specify the user name and password.
        2. Click Finish. The connection for your integration server is now displayed in the Integration Explorer view in the toolkit.
    4. Deploy the callable flow to your ACE integration server. You should see the flow deployed successfully in the ACE log:

      Switch back to App Connect Designer, and in the “Callable flows” view you should now see the new flow. Note the name should match the Endpoint name specified when creating the flow.

      Tip: If you do not see a new callable flow in the “Callable flows” list, refresh the browser window to update the list.

  • Configure the flow in App Connect on IBM Cloud

    In this section we configure the event-driven flow in App Connect on IBM Cloud (without any coding). This flow is to be triggered by a change to a simple Google Sheets spreadsheet, and calls the ACE callable flow to manipulate a new row entered on the spreadsheet. Finally it adds a new row to a second sheet in the spreadsheet document.

    First, look at the empty Google Sheets document to be used. As you see in the image below, I have a simple spreadsheet with two worksheets. The first worksheet is the input used to trigger the flow in App Connect on IBM Cloud.

    Note the first row of each worksheet needs to be populated with the column names to be used in the mappings of the flow; in this example, Name, Message, and Status.

    1. Configure the flow to be triggered by Google Sheets.

      In App Connect Designer, click the Dashboard link, then select New >Event-driven flow

      This opens the Flow editor, and prompts you for how to start the flow.

      Select Google Sheets as our starting point. (If you have not already done so, connect App Connect to your Google Sheets account.)

      Next expand ‘Row’ and then select ‘New complete row appended’

      This will open the configuration panel for Google Sheets. Choose the appropriate Spreadsheet name from the dropdown and then the input worksheet used to drive the flow.

      (Click image to view full size.)

    2. Add an action to invoke (call) the ACE callable flow.

      In the flow diagram, select the (+) after the Google Sheets event node.

      Next, in the Applications list expand ‘Callable flow’ then select ‘Invoke’ to add the action to the flow.

      (Click image to view full size.)

      In the Callable Flow configuration, choose the Application and Endpoint from the dropdown list.

      Then under Message.JSON.Data, click the ‘Add property’ to add a property for each of the columns to pass to the ACE callable flow. In this example, add the ‘aName’ and ‘aMessage’ properties of Message.JSON.Data that we defined earlier in the ACE callable flow. We’ll next configure the ‘Name’ and ‘Message’ columns to pass to these Message.JSON.Data properties.

      After adding the properties, click on the Edit Mappings link to open the mapping dialog

      For each property, add the mapping by selecting the mapping icon and then navigate to the appropriate column in the sheet

    3. Add an action to create a new row in Google Sheets (Status worksheet).

      In the flow diagram, select the (+) after the Callable flow node.

      In the Applications list expand Google Sheets > Rows, select ‘Create row’, and then populate the spreadsheet name and target worksheet (Status) to use.

      (Click image to view full size.)

      Complete the mapping to the target spreadsheet for each column, by clicking on the mapping icon and choosing Callable flow / Invoke … Message.JSON.Data (for Name, Message, and Status)

      To complete the mapping in each field, click ‘Message.JSON.Data’ and then select ‘Edit expression’ to append the element name. The JSON element names used here must match what your ESQL code uses in the ACE callable flow; for example, ‘myName’: {{$CallableflowInvoke.message.myName}}

    4. Give your flow a suitable name; in this example: Update Google Spreadsheet
    5. To exit and start the flow, open the options menu [⋮] in the banner and click Start flow; then click Dashboard.

      Otherwise, just return to the Dashboard, You can start the flow from there, as outlined in the Test the flow step.

  • Test the flow

    In this section we test the flow in App Connect on IBM Cloud, by inserting a row into our Google Sheets worksheet (Sheet1) and see the result in the other worksheet (Status).

    In App Connect, when the flow is created it will be left in a Stopped state unless you choose to start when exiting the editor. To start the flow from the Dashboard, click start from the hamburger icon on the flow tile.

    This results in the flow status changing to ‘Running’.

    Next in your Google Sheets spreadsheet enter a new row in the worksheet you chose as your input (sheet1).

    View the worksheet that you chose as the target for the flow (Status). You can see the new row added by the App Connect flow. Also if you look at the file you used in the Trace node of the ACE callable flow, you can see what the input message passed to the ACE flow looks like.

    Also, on the App Connect dashboard if you look at the tile for flow you can see when the flow last ran successfully.


Now you have learned the process to build a simple App Connect Flow and using an ACE callable flow to augment the input data. You can take this same process to build more complex business solutions using the wide array of applications available in IBM App Connect.

Read more

Assets used in this demo

Project Interchange for On Premise App Connect Enterprise flow

This tutorial is based on the blog post Creating a simple event trigger application….

Join The Discussion

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