Tutorial: Using the assembly canvas to create messaging workflows with Kubernetes resources

Connect MQ with an App Connect Integration runtime to facilitate your workflows.

Putting a message on a queue enables secure, once-only delivery that is asynchronous, meaning that the system stores a sent message until the consumer picks it up. For example, if a server is down on the payment system, you can place payment orders on a queue and hold them until conditions are correct for them to be received.

Using the assembly canvas in the Platform UI to create Kubernetes resources simplifies the build process. These resources contain default values for complex configurations that you would otherwise have to set up manually. For example, mutual TLS (in which both ends of a connection supply a certificate to establish identity) is configured automatically for the Messaging channel.

Before you begin

Confirm the following prerequisites before you begin the tutorial:

  • IBM Cloud Pak® for Integration 16.1.2 or later is installed. For more information, see Installing. Within that installation:

    • These operators are installed:

      • IBM Cloud Pak for Integration

      • IBM App Connect

      • IBM MQ operator

      • cert-manager Operator for Red Hat OpenShift For more information, see Installing the operators.

    • The Platform UI is deployed. For more information, see Deploying the Platform UI.

Overview

Tip:
  • In this procedure, a node refers to any instance or resource that you create in the canvas.
  • For any configuration fields that are not called out in these steps, keep the default values.

  1. Start a new assembly canvas.

  2. Create MQ nodes (instances and resources).

  3. Configure those MQ nodes.

  4. Create and configure a Configuration resource and an Integration runtime.

  5. Deploy and test the assembly canvas.

Before you begin the procedure, log in to the Platform UI.

1. Start a new assembly canvas

Tip: If you need to leave your assembly for a period of time while you are working on it, it is not saved automatically. To save your configuration, click the Create button. Your assembly appears in the list on the home page. When you are ready to continue, click the Options menu icon at the end of the row for your assembly, then select Edit

  1. On the home page, click Build with assembly canvas.

    Click Build with assembly canvas.

  2. In the "Build with assembly canvas" dialog, enter the name for your canvas, demo-integration. Click Build.

2. Create MQ nodes

  1. Click to open the Independent instances dropdown.

    Click to expand Independent instances.

  2. From the Independent instances section, drag and drop these nodes on the canvas: Messaging server, Messaging channel, Messaging queue, and Messaging user. Use the screenshot as a guide. In a real-world situation, the exact arrangement doesn't matter.

  3. Connect the nodes. To connect them, hover over the connector (to the right of the node) until it changes color, then drag the connector line to the connector on other node.

    1. Connect the Messaging user to the Messaging channel and the Messaging queue. This step establishes the management for user creation, access controls, SSL mappings, and certificates so that MQ client applications can securely connect to the Queue manager. (The Queue manager is created by the Messaging server.)

    2. Connect the Messaging channel and the Messaging queue to the Messaging server. This step establishes a channel and a queue.

    Create the MQ instances (nodes), then connect the Messaging user to the Messaging channel and the Messaging queue, and connect the Messaging channel and the Messaging queue to the Messaging server.
    Tip: Linking nodes together adds auto-populated data to the configuration for each node. For example, in the next section, you will find that the Messaging user has configuration fields for the Messaging channel and Messaging queue that is it connected to.

  4. Click to open the Resources dropdown.

    Click to expand Resources, then click Configuration.

  5. Click and drag a Configuration resource to the left of the Messaging user node. This Configuration facilitates communication between the Messaging user and the Integration runtime that we create later.

  6. Connect the Configuration resource to the Messaging user instance. Hover over the connector on the right side of the Configuration until it changes color, then drag the connector line to the connector on the Messaging user.

    Connect the Configuration to the Messaging user.

3. Configure the nodes

Configure the fields as described. Fields that are auto-populated when you create the nodes are omitted from this list.

3.1 Configure the Configuration

  1. Double-click the Configuration (currently c1).

  2. At the top of the edit panel, the UI form tab should be highlighted.

  3. Enter the following values:

    • Metadata section

      • Name - demoruntimeconfig

      • Namespace - <your_namespace>

    • Spec section

      • data: YWNjb3VudHM6IHt9

      • type: accounts
        Tip: The value YWNjb3VudHM6IHt9, when base64 decoded, is equal to account:{} (which is an empty string).

  4. Click Update. The name of this Configuration is now updated. If you double-click the Messaging user that the Configuration is connected to, you will note that in the Configuration section, the Name field is automatically updated as well.

3.2 Configure a Messaging user

  1. Double-click the Messaging user (user1).

  2. At the top of the edit panel, the UI form tab should be highlighted.

  3. Enter the following values:

    • Metadata section

      • Name - The name of this node. Enter a name for this instance, such as demouser.

      • Namespace - This defaults to the namespace where the Platform UI is installed.

    • User section

      • Queues

        • Auth - Enter the following values: GET, INQ, PUT, BROWSE, PASSALL. Press Enter after each item in the list.

          In the Queues.Auth field, enter GET, PUT, BROWSE, INQ, PASSALL. Press Enter after each string.

          • The specified values allow these actions for an authorized user:

            • GET: Retrieves a message from a queue.

            • INQ: Makes an inquiry on a specific queue.

            • PUT: Puts (writes) a message on a specified queue.

            • BROWSE: Retrieves copies of messages on a queue without removing them.

            • PASSALL: Passes all context on the specified queue, for example, passing the context from a retrieved message to a message that your create with PUT.

    • Configurations - The values in this section match the BAR file account associated with the MQ account.

      • Name - This should already be updated to the name you entered for the Configuration node, demoruntimeconfig.

      • Account name - demoq

  4. Click Update.

3.3 Configure a Messaging channel

In this step, you rename the channel from the default value to the name you want to use.

  1. Double-click the Messaging channel (channel1).

  2. Enter the following values:

    • Metadata section

      • Name - demochannel01. The name string for the channel must always end in a number.

      • Namespace - Defaults to the namespace where the Platform UI is installed.
        Important: If the SNI route is enabled for the Integration runtime (the default setting for this tutorial), the Messaging channel name must be a unique value. If there is another Messaging channel with the same name on this cluster, the App Connect integration application will not start.

  3. Click Update.

3.4 Configure a Messaging queue

  1. Double-click the Messaging queue (queue1).

  2. Enter the following values:

    • Metadata section

      • Name - demoqueue

      • Namespace - Defaults to the namespace where the Platform UI is installed.

  3. Click Update.

3.5 Configure a Messaging server

  1. Double-click the Messaging server (server1).

  2. Enter the following values:

    • Metadata section

      • Name - messagingserver

    • License section

      • License accept - Select the checkbox to accept the license.

    • Storage section

      • Storage class - ocs-storagecluster-ceph-rbd

    • Version - This value should match your current IBM Cloud Pak for Integration version.

  3. Click Update.

After you configure these nodes, they are updated with values that correspond to the other nodes that they are connected to. For example, the Messaging queue configuration has a field, Messaging server.name, with a value of messagingserver (the corresponding Messaging server).

4. Create a Configuration resource and an Integration runtime

Create and configure a Configuration resource, then create and configure the Integration runtime instance with a BAR file. The Configuration provides access to the GitHub repo that contains the BAR file used in this tutorial.

Remember: The order in which you create the nodes (in this case, the Configuration and instance) does not matter in a real-world situation.

4.1 Create and configure a Configuration resource

This Configuration resource contains the credentials to access the BAR file that is used by the Integration runtime.

  1. Click to open the Resources dropdown.

  2. Click and drag a Configuration resource above the currect Configuration (demoruntimeconfig).

  3. Double-click the Configuration (c1).

  4. Enter the following values, which are the credentials used by the Integration runtime for accessing the BAR file:

    • Metadata section

      • Name - bar-auth

    • Data - Enter the GitHub base64-encoded credentials:

      eyJhdXRoVHlwZSI6IkJBU0lDX0FVVEgiLCJjcmVkZW50aWFscyI6eyJ1c2VybmFtZSI6IiIsInBhc3N3b3JkIjoiIn19Cg==
      Tip: The string above resolves to empty (placeholder) credentials: {"authType":"BASIC_AUTH","credentials":{"username":"","password":""}} This configuration is for a demo that is accessing a public repository. In a production environment, you will need to specify the values.

    • Description - Authentication for public GitHub, no credentials needed

    • Type - Select barauth.

Create a configuration called bar-auth

4.2. Create and configure an Integration runtime instance

  1. Click to open the dropdown for Independent Instances.

  2. Drag and drop an Integration runtime instance on the canvas to the left of the Configuration resources.

  3. Connect this instance to both Configurations by hovering over the connector and dragging the connector lines.

    Connect the new Integration runtime to the bar-auth and demoruntimeconfig nodes.

  4. Double-click the Integration runtime (ir1).

  5. At the top of the edit panel, the UI form tab should be highlighted.

  6. Enter the following values:

    • Details section

      • Name - demoruntime

      • Namespace - Defaults to <your_namespace> where the Platform UI is installed.

    • License section

      • License accept - Select the checkbox to accept the license.

    • BAR URLs - Click the Add + icon if the following field does not appear.

      • BAR URL

        https://github.com/demo-test-source/demo-source/raw/refs/heads/main/messaging-demo/message_timer_flow.bar

        This example URL links to a BAR file that is available in a public GitHub repository. A BAR file is a compressed file to which you can add a number of deployable resources. For more information about BAR files, see Creating a BAR file.

5. Deploy and test the assembly canvas

The completed assembly canvas should be similar to the screenshot:

Now that you have finished designing your assembly you are ready to create (build) it.

  1. Click Create.

    Click create to start building your assembly

    The assembly begins building and deploying the nodes. Your new assembly demo-integration appears in the list of deployed instances on the Platform UI home page. When the status changes to Ready, click the dropdown arrow to expand the list of all components in your assembly and confirm that they are ready (successful) as well.

    Your assembly appears in the list of created instances on the Platform UI home page. It has a status of Ready.

  2. Find another entry in the list for the messagingserver you created. Click the dropdown arrow to expand the list of Messaging components. Click the instance of type Queue manager to launch the Queue manager UI.

    From the list, click the instance named messagingserver.

  3. In the Queue manager UI, click the Manage messagingserver tile to get information about your queues.

    Click the Manage messagingserver tile.

  4. On the" Queue manager: messagingserver" page, click the Queues tab. In the name column, click demoqueue.

    In the name column, click demoqueue.

    The "Local queue" page opens, which provides information about messages on your queue.

You have successfully created an end-to-end assembly that allows to you to add a message to a queue.