Learn how to use IBM App Connect on IBM Cloud with IBM App Connect Enterprise (ACE) software to create a simple event-driven flow on IBM Cloud that is augmented by an on-premises ACE flow.

Scenario

This tutorial demonstrates a very simple App Connect flow that is triggered by a change to a Google Sheets document. The spreadsheet row is passed to an on-premises ACE flow to augment the content and response back to the App Connect flow, which updates another sheet in the same Google Sheets document.

Requirements

  • Google account with a simple Google Sheets document
  • IBM Cloud account with IBM App Connect service – Custom Enterprise, Cloud Connector, or the Lite plans.
  • 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:

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 your on-premises ACE work directory).

    After saving the agentx.json. Copy it to your ACE directory: 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

    APPC-CallableFlow2

    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 this example, the flow uses 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 the following steps:

      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 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, click Exit and switch on.

      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.


Conclusion

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.

Assets used in this demo

Project Interchange for On Premise App Connect Enterprise flow

Join The Discussion

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