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.
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.
- 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:
- IBM App Connect service with the Lite plan
- IBM App Connect Enterprise (ACE) developer edition
- Get started with IBM App Connect Enterprise, which includes the steps to create and start an integration server
- Configuring an integration server in the ACE v11 product documentation
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.
- Click the hamburger menu (top left)
- Expand Manage
- 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:
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
- Open your Enterprise Toolkit
- 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.
- 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:
- 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.
- Click Finish. The connection for your integration server is now displayed in the Integration Explorer view in the toolkit.
- 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.
- 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.
- 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.
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
- 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.
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’:
- Give your flow a suitable name; in this example:
Update Google Spreadsheet
- 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.
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
- Configure the flow to be triggered by Google Sheets.