Connecting to and using IBM MQ from an App Connect Designer instance in a containerized environment (local connector) and App Connect Enterprise as a Service

If you are using an App Connect Designer instance within an installation of IBM Cloud Pak for Integration or IBM App Connect Enterprise certified container, and have enabled locally available connectors, you can choose to use a local connector to connect to your IBM MQ account.

The following information describes how to use IBM App Connect to connect IBM MQ to your other applications.

What to consider first

Before you use App Connect Designer with the IBM MQ connector, take note of the following considerations.

App Connect supports connecting to the following queue managers:
  • Queue managers running on IBM MQ on IBM Cloud
  • Queue managers running on a local cluster (that is, from an IBM MQ deployment in the same IBM Cloud Pak for Integration environment as App Connect Designer)
  • Queue managers running on-premises

Ensure that your queue manager is running before you start a flow that uses the IBM MQ connector.

Connecting to IBM MQ from App Connect Designer 12.0.1.0-r4 or later

To create an integration flow that passes data between IBM MQ queues and other apps, you must connect App Connect to each app in the flow. You can add an account for connecting to IBM MQ either from the App Connect Designer Connect > Applications and APIs page, or when you add an IBM MQ node to a flow in the flow editor.

IBM MQ queue managers can be configured to secure data in transit. To connect to a queue manager from App Connect, you'll need to select an authorization method that reflects how the queue manager is secured. App Connect supports the following authorization methods for connecting to IBM MQ:

  • Basic authentication: This authorization method typically requires a username and password for authenticating to the queue manager.
  • Standard ("one way") Transport Layer Security (TLS) authentication: This authorization method requires App Connect to ensure that it trusts the queue manager. While setting up the connection, you must provide the queue manager's public certificate so that it can be imported into the App Connect trust store.
  • Mutual ("two way") TLS authentication: This authorization method requires App Connect to ensure that it trusts the queue manager, and similarly requires the queue manager to ensure that it trusts App Connect. While setting up the connection, you must provide the queue manager's public certificate so that it can be imported into the App Connect trust store. You will also need to manually import a user-generated public certificate for App Connect into the queue manager's trust store.

Prerequisites for standard and mutual TLS authentication

If you want to use standard or mutual TLS authentication to connect App Connect to an IBM MQ queue manager, you must complete the following steps before attempting to connect:

  1. Ensure that the queue manager and the server connection channel that it uses are TLS-enabled. This includes ensuring that the channel is configured with a cipher specification (and an SSL authentication setting of Required for mutual authentication).

    • SSL properties to enable TLS for a channel on IBM MQ on IBM Cloud

  2. From your IBM MQ instance, download the public certificate that will be presented by the queue manager, and which App Connect requires to trust the queue manager. You will need to provide this certificate when you set up a connection later.

    • If using an IBM MQ on IBM Cloud service instance, you can download the public certificate for the queue manager as follows:
      1. From the navigation pane, click Manage and then click the name of the queue manager that you want to connect to.
      2. Click the Key store tab.
      3. Identify the certificate that is marked as "In use: Queue manager" (for example, Default: qmgrcert), click the Show toolbar icon Show toolbar icon on the certificate tile, and then click Download public certificate to download the PEM file.

      Locating the public certificate of a queue manager on the Key store tab on IBM MQ on IBM Cloud

  3. Applicable for mutual TLS authentication only:
    1. Generate a public certificate/private key pair in PEM format, with an optional password. You can use tools such as keytool or OpenSSL to generate the public certificate and private key. This certificate and key will be automatically imported into an internal App Connect client keystore when you set up a connection later, and will be used for client-side authentication.
    2. Configure the queue manager to trust the client certificate from App Connect by importing the generated public certificate (from the previous step) into the queue manager's trust store in your IBM MQ instance.

      • If using an IBM MQ on IBM Cloud service instance, you can import the certificate as follows:
        1. Click Manage in the navigation pane and then click the name of the queue manager that you want to connect to.
        2. Click the Trust store tab, click Import certificate, and then select your PEM file from the file browser window.
        Locating the public certificate of a queue manager on the Key store tab on IBM MQ on IBM Cloud

Connecting to an IBM MQ queue manager

To connect App Connect to a queue manager, you’ll need to select your preferred authorization method and then provide the connection details. If you are not the owner or administrator of your queue manager, you can obtain this information from your administrator. Different connection details are required for each authorization method:

BASIC
Select this option to connect to the queue manager by using basic authentication, and then complete the following fields:
  • Queue manager name: Specify the name of the queue manager to connect to.
  • Queue manager hostname: Specify the fully qualified hostname or IP address of the IBM MQ server on which the queue manager is running; for example, myserver.abc.com or 192.0.2.24.
  • Listener port number: Specify the port number on which the queue manager is listening.
  • Username: Specify the username for authenticating to the queue manager. (If you are connecting to a queue manager that is running on the local cluster, you can leave the Username field blank if no authentication is required.)
  • API key/Password: Specify the API key if you're using an IBM MQ cloud deployment, or specify the password if you're using an IBM MQ server on premises or on the local cluster. (For the local cluster, you can leave the Password field blank if no authentication is required.)
  • Channel name: Specify the name of a server connection channel for the queue manager.
  • Private network connection: Select the name of a private network connection that App Connect uses to connect to your private network. This list is populated with the names of private network connections that are created from the Private network connections page in the Designer instance. You see this field only if a switch server is configured for this Designer instance. For more information, see Connecting to a private network from App Connect Designer. (In App Connect Designer 12.0.10.0-r1 or earlier instances that include this field, the display name is shown as Agent name.)
SSL
Select this option to establish a secure connection to the queue manager by using standard TLS authentication, and then complete the following fields:
  • Queue manager name: Specify the name of the queue manager to connect to.
  • Queue manager hostname: Specify the fully qualified hostname or IP address of the IBM MQ server on which the queue manager is running; for example, myserver.abc.com or 192.0.2.24.
  • Listener port number: Specify the port number on which the queue manager is listening.
  • Username: Specify the username for authenticating to the queue manager. (If you are connecting to a queue manager that is running on the local cluster, you can leave the Username field blank if no authentication is required.)
  • API key/Password: Specify the API key if you're using an IBM MQ cloud deployment, or specify the password if you're using an IBM MQ server on premises or on the local cluster. (For the local cluster, you can leave the Password field blank if no authentication is required.)
  • Channel name: Specify the name of a TLS-enabled server connection channel for the queue manager.
  • Queue manager certificate: Locate the public certificate that you downloaded earlier in PEM format for the queue manager, and then copy and paste the contents of the downloaded file into this field.

    Example:

    -----BEGIN CERTIFICATE----- MXIEFADAyMQswCQ4DCCAsgCCQDHlrUNBgkqhkiG9w0BAQs UQHDECAwJcmAZKYXN0aGFuMFqdXIwHhc1DVQQ8wDQYTwI0 GAswCQYDUwMTM4QIwODIWjDUwMTM4wJDV1MMjyBAQ0MMwJ qYXN0lwdXIwggIiMA0aGFuqGWcm3DQEBMQ8wDQYDVQA4IC KAoI7JsMKXWYkr2dbDrj4xcs3WmQxXcRkwAwgX2gIIMuBdz 8aYVsXE/zDbIoBImgIPvuw+6nJHvcPVF/CE+BI9abVou/P SoozeQ== -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- CQ4DCCAsgCCQDHlrMXIEFADAyMQswUNBgkqhkiG9w0BAQs AZKYXN0aGFuMFqdXIUQHDECAwJcmwHhc1DVQQ8wDQYTwI0 UwMTM4QIwODIWjDGAswCQYDUwMTM4wJDV1MMjyBAQ0MMwJ wdXIwggIqYXN0liMA0aGFuqGWcm3DQEBMQ8wDQYDVQA4IC MKXWYkr2dbDrKAoI7Jsj4xcs3WmQxXcRkwAwgX2gIIMuBdz 5aYVsXE/oBImgzDbIIPvuw+6nJHvcPVF/BE+CI9abVou/P DoozeQ== -----END CERTIFICATE-----

  • Cipher spec: Specify the cipher specification that is configured on the channel.
  • Peer name: Specify the distinguished name (DN) pattern to use for validating the DN of the certificate that is presented by the queue manager; for example, CN=John Smith, O=IBM, OU=Test, C=GB.
MTLS
Select this option to establish a secure connection to the queue manager by using mutual TLS authentication, and then complete the following fields:
  • Queue manager name: Specify the name of the queue manager to connect to.
  • Queue manager hostname: Specify the fully qualified hostname or IP address of the IBM MQ server on which the queue manager is running; for example, myserver.abc.com or 192.0.2.24.
  • Listener port number: Specify the port number on which the queue manager is listening.
  • Username: Specify the username for authenticating to the queue manager. (If you are connecting to a queue manager that is running on the local cluster, you can leave the Username field blank if no authentication is required.)
  • API key/Password: Specify the API key if you're using an IBM MQ cloud deployment, or specify the password if you're using an IBM MQ server on premises or on the local cluster. (For the local cluster, you can leave the Password field blank if no authentication is required.)
  • Channel name: Specify the name of a TLS-enabled server connection channel for the queue manager.
  • Queue manager certificate: Locate the public certificate that you downloaded earlier in PEM format for the queue manager, and then copy and paste the contents of the downloaded file into this field.

    Example:

    -----BEGIN CERTIFICATE----- MXIEFADAyMQswCQ4DCCAsgCCQDHlrUNBgkqhkiG9w0BAQs UQHDECAwJcmAZKYXN0aGFuMFqdXIwHhc1DVQQ8wDQYTwI0 GAswCQYDUwMTM4QIwODIWjDUwMTM4wJDV1MMjyBAQ0MMwJ qYXN0lwdXIwggIiMA0aGFuqGWcm3DQEBMQ8wDQYDVQA4IC KAoI7JsMKXWYkr2dbDrj4xcs3WmQxXcRkwAwgX2gIIMuBdz 8aYVsXE/zDbIoBImgIPvuw+6nJHvcPVF/CE+BI9abVou/P SoozeQ== -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- CQ4DCCAsgCCQDHlrMXIEFADAyMQswUNBgkqhkiG9w0BAQs AZKYXN0aGFuMFqdXIUQHDECAwJcmwHhc1DVQQ8wDQYTwI0 UwMTM4QIwODIWjDGAswCQYDUwMTM4wJDV1MMjyBAQ0MMwJ wdXIwggIqYXN0liMA0aGFuqGWcm3DQEBMQ8wDQYDVQA4IC MKXWYkr2dbDrKAoI7Jsj4xcs3WmQxXcRkwAwgX2gIIMuBdz 5aYVsXE/oBImgzDbIIPvuw+6nJHvcPVF/BE+CI9abVou/P DoozeQ== -----END CERTIFICATE-----

  • Cipher spec: Specify the cipher specification that is configured on the channel.
  • Client keystore: Locate the public certificate and private key files, which you generated earlier, for client-side authentication. Then copy and paste the contents of both the public certificate and private key into this field in PEM format, using a single space as a separator. Alternatively, you can concatenate the two files to PEM format and then paste the PEM file contents into this field (for example: cat server.crt server.key > server.pem).

    Example:

    -----BEGIN ENCRYPTED PRIVATE KEY----- MIIJnzBJBgkqhkiG9w0BBQ0qwwDgQID/15qTEH7xMCAggA MB0tRIjYgSCCVDiHwqfHd9XwHjD7PQo7RmSQeyEJvtAuQR AnBIkRVn/4uqwcHXbFUTBf4dS6GFAxLjiOaX8BwiKdpmw5 3ULOLuUG/Bn/kRd7wUhyo0esKCWe2aWPCwS7XIiNmuf17m 2mCTwzyLPJiPzjNp/6+X98oPDoHNZ7teWQVWl2D5yCvTUW Io/1L4zwMPB2cCf3Et8bSOpb+utx13Q6z2/SD2W0x3qhAu RKdPGuFgLFBrOeK9sCSlrpquQjYk7+XeIO4Q7T1vAKhwRS SnD8zsa75/TgfZh/HCkxxFUGZg== -----END ENCRYPTED PRIVATE KEY----- -----BEGIN CERTIFICATE----- MIIE4DCCAsgCCQDHlrUD9NYdhkiGAyMQswCQYDVQQGEwJJ UFqdXIwHhcNMjEwODA1DVQGFuMQ8wDQYTjESMBAGYWlwI0 DUwMTM4QQGEwJGAWjhcNAyBAQswCQYDESMMjIwODI0MMwJ aGFuMQ8wDQYDN0lwdXIwggSIbDAZKYWcm3DQEBAQUAA4IC CAQ8DwA7JsMKXWxcs3WMIMuBdzX2T7mQuHms5YfZ3HxXcRk 8aYVBSQSXE/zDgISVPvuw+6nJ1dJPVF/CE+BI9jkjVou/P AoozeQ== -----END CERTIFICATE-----

  • Client keystore password: If you secured the generated private key with a password, specify this password.
  • Certificate label: Specify a label (or unique identifier) for the certificate to be used when establishing the SSL client connection to the queue manager.
  • Peer name: Specify the distinguished name (DN) pattern to use for validating the DN of the certificate that is presented by the queue manager; for example, CN=John Smith, O=IBM, OU=Test, C=GB.

  • Connection details form for IBM MQ using basic authentication

  • Connection details for IBM MQ using TLS authentication

  • Connection details for IBM MQ using mutual TLS authentication

To connect to IBM MQ from the App Connect Designer Applications and APIs page for the first time, complete the following steps:
  1. Expand IBM MQ and click Connect.
  2. From the Authorization method drop-down list, select your preferred authorization method and then click Continue to display the connection fields.
  3. Enter the account information and then click Connect.

    This creates an account in App Connect.

Before you use the account that is created in App Connect in a flow, rename the account to something meaningful that helps you to identify it. To rename the account on the Applications and APIs page, select the account, open its options menu (⋮), then click Rename Account.

Connecting to IBM MQ from App Connect Designer 12.0.1.0-r3 or earlier

To create an integration flow that passes data between your queues in IBM MQ and other apps, you must connect App Connect to each app in the flow. You can add an account for connecting to IBM MQ either from the App Connect Designer Applications and APIs page, or when you add an IBM MQ node to a flow in the flow editor.

To connect, you’ll need the following connection details. If you are not the owner or administrator of your queue manager, you can obtain this information from your administrator.

Queue manager name
Specify the name of the queue manager to connect to.
Queue manager hostname
Specify the fully qualified hostname or IP address of the server on which the queue manager is running. For example, myserver.abc.com or 192.0.2.24.
Listener port number
Specify the port number on which the queue manager is listening.
Username
Specify the username for authenticating to the queue manager. (For the local cluster, you can leave the Username field blank if no authentication is required.)
Password
Specify the API key if using an IBM MQ cloud deployment, or specify the password if using an IBM MQ server on premises or on the local cluster. (For the local cluster, you can leave the Password field blank if no authentication is required.)
Channel name
Specify the name of the server connection channel.

To connect to a IBM MQ endpoint from the App Connect Designer Applications and APIs page for the first time, expand IBM MQ, then click Connect.

Before you use the account that is created in App Connect in a flow, rename the account to something meaningful that helps you to identify it. To rename the account on the Applications and APIs page, select the account, open its options menu (⋮), then click Rename Account.

Using IBM MQ action and event nodes in App Connect

The IBM MQ connector provides three action nodes: Get message from a queue, Publish message to a topic, Put message on a queue and one event node: New message on a queue.

Figure 1. IBM MQ event and action nodes on the App Connect Designer Applications and APIs page page
Screen shot to show IBM MQ action and event nodes on the catalog page
Get message from a queue
Figure 2. Fields for a "Get message from a queue" action node
Screenshot to show the fields for a Get message from a queue action node
  • In the Queue name field, specify the name of the queue to retrieve the message from.
  • The Message ID is a byte string that is used to distinguish one message from another. Use the Message ID field to retrieve a message from specific message ID.
  • The Correlation ID field is used for correlating a group of messages together. For example, if you want to share a reply queue, each instance on an application has its own unique correlation ID value. It sends this value to the remote server and requests that the value is sent back in the reply. This means that the originating application can issue an MQGET(by correlation ID) and see only its messages. The Message ID and Correlation ID fields are used to correlate response messages with request messages.
  • The Browse only field indicates whether to leave the original message on the queue after reading it. The default is No, which will delete the message after receiving it.
Publish message to a topic
Figure 3. Fields for a "Publish message to a topic" action node
Screenshot to show the fields for a Publish message to a topic action node
  • In the Topic string field, specify the name of the topic on which to publish the message.
  • In the Message type field, select a message type of Text or Binary.
  • The Message payload field is for your actual payload.
  • If required, you can define one or more MQMD headers. They can be specified as data properties with name, number, and string data types. To add an MQMD header, click Add property. You can then proceed to define properties and specify the data type.
    Figure 4. Adding MQMD header properties
    Screen shot to show MQMD header properties additions
    Note: Headers that accept a byte array should be passed in Base64 format.

    Click Edit mappings to expose these properties as fields and then specify their values, as shown in the following example.
    Figure 5. Specifying values for MQMD header properties
    Screen shot to demonstrate how you can specify values for MQMD header properties
Put message on a queue
This action node has the same fields as the Publish message to a topic action node, except you need to specify a Queue name instead of a Topic string.
New message on a queue
Figure 6. Fields for a "New message on a queue" event node
Screen shot to show the fields for a New message on a queue event node
  • In the Queue name field, specify the name of the queue to listen to for messages.
  • The Browse only field indicates whether to leave the original message on the queue after reading it. The default is No and will delete the message after reading it.

For more information about using an App Connect Designer instance in a containerized environment, see Creating and managing flows in App Connect Designer.