Using App Connect integrations in webMethods Integration

This tutorial describes how to integrate remote App Connect runtimes with the IBM® webMethods Hybrid Integration platform. Learn how to connect App Connect runtimes, then monitor and administer them after integration. You can also optimize deployment flexibility and performance by distributing integration logic between IBM hosted runtimes and self hosted runtimes.

Scenario

A coffee shop owner tracks customer arrivals by capturing their vehicle registration plates and mapping them to user profiles. When a customer drives to the shop, their profile is retrieved, and an AI analytics tool analyzes their past preferences. Based on the past data, the AI tool generates personalized menu suggestions.

When the customer arrives, the coffee shop owner presents suggestions, which enhances the customer's experience, encourages loyalty, and increases sales.

Before you begin

  • You must have administrator access to complete the steps in this tutorial.
  • This tutorial assumes that you have basic knowledge of the App Connect and webMethods Integration capabilities.
  • You need an active instance of webMethods Hybrid Integration with the App Connect and webMethods Integration capabilities enabled.
  • You need a local installation of IBM App Connect Enterprise software version 13.0.3.1 or later. You can download IBM App Connect Enterprise Evaluation Edition and install it locally.
  • Download the ace_runtime_tutorial.zip file and extract the contents, which include the following files that are used in this tutorial.
    • Number_plate_lookup.bar contains a callable flow that converts customer registration plates into customer details such as customer number, email address, and other attributes.
    • Coffee_AI.bar contains a callable flow that accepts a customer number and returns personalized food and drink recommendations.
    • coffee_shop_pi.zip is a project interchange archive that contains the complete source code for all integrations that are referenced in this tutorial.

About this tutorial

In this tutorial, you create an IBM hosted runtime in App Connect and a remote runtime (integration server) in App Connect Enterprise. You deploy one integration to the IBM hosted runtime, and the other integration to the remote runtime, which you register with webMethods Hybrid Integration. You then add the deployed integrations as callable flows to a webMethods Integration workflow and configure logic to map user profiles to registration plates.

This tutorial guides you through the following steps:
  1. Creating an IBM hosted runtime
  2. Creating a self hosted runtime
  3. Building integration logic with webMethods Integration

Creating an IBM hosted runtime

  1. Log in to webMethods Hybrid Integration.
  2. Open the main menu Icon that represents the main menu and select App Connect.
  3. From the App Connect navigation pane, click Manage Icon that represents the App Connect Manage page.
  4. On the Manage page, click BAR files, then Import BAR file.
  5. Click Default deployment location to open the Import BAR file dialog box for the local App Connect instance.
  6. Drag or select the Number_plate_lookup.bar file from your local file system, then click Import. The BAR file is imported and listed on the BAR files page.
  7. Open the menu The icon that represents the BAR file menu for the imported BAR file and click Deploy.
  8. On the Deploy integration page, click Create runtime.
  9. On the Create runtime page, set the Runtime name to customer-ir.
  10. Set Replicas to Single to save on resources.
  11. Click Create. The runtime is created and is selected on the Select runtime page.
  12. Click Next.
  13. On the Add configurations page, select default-switch-server-privatenetworkagent and retain the other default selections. These configurations allow other runtimes in your webMethods Hybrid Integration instance to call the callable flows that are deployed to this runtime.
  14. Click Next.
  15. Review the summary, then click Deploy.

    This step completes the first part of your coffee shop integration that runs on an IBM hosted runtime that is associated with your webMethods Hybrid Integration instance.

Creating a self hosted runtime

The following steps describe how to create an App Connect Enterprise integration server to use as a remote runtime. The remote runtime is then registered with webMethods Hybrid Integration by using a switch server.

  1. Create a stand-alone App Connect Enterprise integration server to use as the remote runtime.
    1. Open the App Connect Enterprise command environment for your operating system.

      On Windows, open the Start menu and click IBM App Connect Enterprise Console 13.0.x.x.

      On Linux®, locate and source the mqsiprofile script in the directory where you installed App Connect Enterprise (source install_dir/server/bin/mqsiprofile).

    2. Run the mqsicreateworkdir command and specify the full path to the directory that you want to use as the integration server's work directory, as shown in the following example.
      mqsicreateworkdir c:\intServerName

      For more information, see mqsicreateworkdir command in the App Connect Enterprise documentation.

      The successful command completion message indicates that the App Connect Enterprise integration server is created.

  2. Configure the remote runtime to be available in webMethods Hybrid Integration.
    1. Go to your App Connect capability in webMethods Hybrid Integration.
    2. From the App Connect navigation pane, click Connect > Private networks.
    3. On the Private network connections page, click Create to create a private network agent.
    4. Change the default name to pr-agent and click Create.
    5. Open the Actions menu Icon that represents the Actions menu for the private network connection for the new private network agent and click View setup instructions.
    6. On the Remote administration tab, expand step 2 and click Download the configuration. The switchclient.json file is saved to your default download location.
    7. Move the downloaded switchclient.json file to the config/switch folder in the work directory of your App Connect Enterprise integration server. If the switch folder doesn't exist, create it.
    8. In the App Connect Enterprise console, run the IntegrationServer command to start the App Connect Enterprise integration server.
      IntegrationServer --work-dir <workDirLocation> --name <uniqueName>

      Replace <workDirLocation> with the location of the work directory that you specified in step 1, and set the uniqueName to on-premise-ir.

    9. Check the App Connect Enterprise console for messages that indicate that the integration server connected to the switch server in webMethods Hybrid Integration, as shown in the following example.
      2025-06-19 14:42:26.374542: IBM App Connect Enterprise administration security is inactive.
2025-06-19 14:42:26.389164: The HTTP Listener has started listening on port '76XX' for 'RestAdmin https' connections.
2025-06-19 14:42:26.726828: The connection agent for remote administration successfully registered using App Connect agent identifier 'b8c15821-64XX-4XXX-84e5-475f52dXXXXX'.
2025-06-19 14:42:26.727092: Integration server has finished initialization.

      You now have an App Connect Enterprise runtime that is running locally and is registered with the webMethods Hybrid Integration switch server.

  3. In your webMethods Hybrid Integration instance, open the main menu and click Integration runtime management.

    You can see that the IBM hosted runtime is already visible but the remote App Connect Enterprise runtime that you just set up isn't yet listed. You can also see some webMethods Integration runtimes if that capability is added.

  4. Add the remote runtime.
    1. On the Integration runtime management page, click Register runtime > App Connect runtimes.
    2. On the Register runtime page, select switch-deployment-location and click Next.

      This deployment location is already registered with the remote runtime through the private network connection.

    3. Select the on-premise-ir runtime and click Add Runtime. The runtime is added and is displayed as a card on the Integration runtime management page.

    You now have one self hosted runtime and one IBM hosted runtime, both of which are enabled for callable flows.

  5. Deploy the Coffee_AI.bar file to the self hosted runtime on-premise-ir.
    1. On the Integration runtime management page, click on-premise-ir.
    2. Click Deploy BAR. The Coffee_AI.bar file is deployed to the remote runtime.

Building integration logic with webMethods Integration

  1. Go to your webMethods Integration capability in webMethods Hybrid Integration. The Projects page is displayed.
  2. Add a project.
    1. Click Add Project.
    2. In the New Project dialog box, enter the name as Coffee shop.
    3. Retain the other default values and click Create. The Coffee Shop project is created.
  3. Add callable flows.
    1. Click the Callable flows tab.
    2. On the Callable flows tab, click Add flows. In the Add callable flows dialog box, you can see the two callable flows that were deployed. One is in the IBM hosted runtime, and the other is in the self hosted runtime.
    3. Click Add to add the callable flows to the project. The callable flows are now available for use in the workflow editor.
  4. Create a workflow.
    1. Click Integrations > Workflows.
    2. Click Add.
    3. On the Start Building your Workflow page, click Create New Workflow. The workflow canvas is displayed with the Start and Stop actions.
    4. Click the Edit icon for the workflow name to rename the workflow.
    5. In the Edit Workflow name dialog box, enter a name for the workflow, such as Recommendations.
    6. Click Done.
  5. Create a trigger to start the workflow.
    1. Double-click the first action, Start, in the workflow canvas.
    2. Click the Settings icon.
    3. In the Trigger dialog box, select webhook from the list of triggers, then click Next.
    4. In the Body section of the Webhook dialog box, add the following JSON command, then click Next. 
      { "plate": "HF17QQQ"}
    5. From the Webhook authentication list, select none.
    6. Click Next and review your webhook configuration.
    7. Click Done to finish the webhook setup.
  6. Configure logic for mapping user profiles to vehicle registration plates.
    1. On the Connectors panel, click Services. All App Connect connectors are listed.
    2. Drag the Number_plate_callable_flow connector onto the canvas. The connector automatically gets connected to the Start action.
    3. Double-click the Number_plate_callable_flow step to start configuring it.
    4. In the Number_plate_callable_flow settings dialog box, click Next.
    5. On the Mapping page, map the plate field from the incoming webhook data to the plate field in the REST API call query.
    6. Click Next.
    7. On the Test this action page, click Test. The test runs the REST call and shows that the response data is returned.
    8. Click Done.
  7. Configure logic for generating suggestions.
    1. Drag the coffee_suggester connector onto the canvas. It automatically gets connected to the previous step in the workflow.
    2. Double-click the coffee_suggester connector to configure it.
    3. In the Settings dialog box, click Next.
    4. On the Mapping page, map the customerNumber field from Number_plate_callable_flow to the customerNumber field of the coffee_suggester callable flow.
    5. Click Next.
    6. On the Test this action page, click Test. The test returns a data structure that contains the suggestion.
    7. Click Done.
  8. Configure an email to receive the recommendations.
    1. Drag the Send an email connector onto the canvas. It automatically gets connected to the previous step in the workflow.
    2. Double-click the email step to start the configuration.
    3. In the To field, specify an email address.
    4. Click Next and map the food name from Incoming data to the body field in the Send an Email connector.
    5. Click Next.
    6. On the Test this action page, click Test. The test returns a data structure that contains the suggestion.
    7. Click Done.
  9. Save the completed workflow.
  10. On the workflow canvas, click Run. You can see that each step runs and you receive an email with the recommendations.

What you learned in this tutorial

You developed an integration that allows a coffee shop owner to track and analyze customer behavior and offer personalized menu recommendations by using AI analytics. As part of this process, you created workflows in webMethods Integration by using App Connect integrations. You also registered App Connect Enterprise runtimes for integration runtime management so that you can monitor all your integrations from a centralized control plane.