Learn how to use IBM® App Connect Enterprise to expose a REST API to a queue in IBM MQ on IBM Cloud™.

Scenario:

Your company wants to expose a custom JSON-based REST API to their developers for sending messages to a stock control application through an MQ queue that is hosted in MQ on IBM Cloud. The format of the messages that the application expects is a custom COBOL copy book structure. An integration solution needs to be constructed that receives a simple JSON REST request, converts the JSON to the COBOL structure and then sends that to the correct queue. The integration solution is imported to run in IBM App Connect on IBM Cloud (with a plan that provides enterprise capabilities).

First, find or create everything you need:

  • An MQ on IBM Cloud instance with a queue manager running. The following tutorial presumes you have a trial queue manager called TEST1, but you can use an existing queue manager and change the details used in the tutorial.

    For instructions about how to set up a trial MQ instance with an API key, see the MQ on IBM Cloud tutorial. If you complete the MQ on IBM Cloud tutorial you will have almost everything you need setup in MQ for this App Connect tutorial.

    You need to find out the following information:

    • Hostname of the queue manager. For example: test1-1bf5.qm.eu-gb.mqcloud.ibm.com.
    • Port of the queue manager. For example: 30499.
    • API key username that has access to put messages to queues. For example: app1.
    • API key user’s password.
  • An IBM Cloud account with an IBM App Connect service that provides enterprise integration capabilities; for example, the Lite or Custom Enterprise plans.
  • Optionally you can also install IBM App Connect Enterprise for Developers if you want to look at and change the deployed flow. It is not necessary for running the tutorial but it is useful for examining the flow to understand how it works.
    (Note: The enterprise integration project for this tutorial was developed with the IBM App Connect Enterprise Toolkit, but can be examined with the Integration Toolkit of IBM Integration Bus (IIB) v10.)
  • If you want a bit more information before you start, you can read more about the App Connect Enterprise Developer edition and how to use MQ on IBM Cloud on the following pages:

Import the enterprise integration project into ACE or IIB, and take a look at the message flow and message set:

You do not need to do this step unless you want to look at or change the flows. A separate BAR file is also provided for deploying the integration into App Connect on IBM Cloud, as described in a later step.

  • Read more

    All the resources required for this tutorial are provided in a project interchange file.

    The steps are the same for ACE v11 Enterprise Toolkit and IIB v10 Integration Toolkit (the toolkit):

    1. Download the project interchange file, by clicking the link above and saving the file to your local machine.
    2. Open the toolkit.
    3. Import the project into the toolkit. Click File > Import, expand IBM Integration, then select Project Interchange, and then select the downloaded project interchange file.

    A new project called RestToStockApp will appear in the toolkit. It contains one flow called RestToStockApp.msgflow that implements a REST service:
    (Click image to view full size.)

    The REST service has one subflow called postStock.subflow that implements a POST to stock resource operation to create a new stock. The flow performs the following actions:

    • JSON to COBOL – Convert incoming JSON doc into COBOL copy book format.
    • MQ Output – Put the message to a queue.
    • Set return to success – Create a response that contains the word “Success”

    IMPORTANT: there are two critical things that must be set on the MQOutput node.

    1. The first is the Message context that must be set to Default. If this is not set an MQ error 2035 will happen.
    2. The second is the policy property must be set because the flow will need to use a policy to correctly work:
      (Click image to view full size.)

Modify MQ Cloud to allow SSL connections.

To allow SSL connections to be used with MQ Cloud you need to configure the serverconn channel correctly:

  1. In the admin view for the queue manager, double-click the channel CLOUD.APP.SVRCONN.
  2. Select the SSL page and then set:
    • SSL cipher spec – TLS_RSA_WITH_AES_128_CBC_SHA256
    • SSL authentication – optional

    (Click image to view full size.)

  3. Save the channel and ensure no one is using it, because changes will not be applied until it is no longer running.

Configure the integration in App Connect on IBM Cloud:

  1. Download the BAR file containing the REST service (RestToStockAppproject.bar)
  2. Sign in to App Connect on IBM Cloud.
  3. In App Connect on IBM Cloud, return to the Dashboard and then click New > Import a BAR file… and select the downloaded BAR file:
  4. Open the integration once imported and turn off basic auth:
    (Click image to view full size.)
  5. From the hamburger in the top left corner select the Policy view.
  6. Create a new MQ Policy called MQ_STOCK1. The name must match the policy name defined on the MQ Output node. Fill in all the details as follows but replacing hostname, port and password with your own values:

    (Click image to view full size.)

    And the policy values shown in the above picture are:

    • Policy name – MQ_STOCK1
    • Host – test1-1bf5.qm.eu-gb.mqcloud.ibm.com
    • Port – 30499
    • Queue manager – TEST1
    • Channel name – CLOUD.APP.SVRCONN
    • User name – app1
    • Connect to internet – true
    • Use SSL – true
    • SSL peer name – CN=*.mqcloud.ibm.com
    • SSl cipher spec – TLS_RSA_WITH_AES_128_CBC_SHA256
  7. Attach the policy to the uploaded bar file by opening up the integration in the dashboard view, selecting the Attached policies tab, and then clicking the Manage button. Select the MQ_STOCK1 policy and then save it:

    (Click image to view full size.)

  8. Return to the dashboard and then start the integration.

When the integration shows Started the integration is running and ready to use.

Finally, test your integration:

POST a new Stock JSON object to the integration’s stock URL:

  1. From the dashboard open the integration.
  2. Select Show API explorer.
  3. Only one possible API is shown. Select Try it.
  4. Paste the example JSON doc into the parameters Body text box:

    (Click image to view full size.)

  5. Click Call operation and success should get returned (if this fails see Troubleshooting section).
  6. Check the DEV.QUEUE.1 in your MQ Cloud queue manager and it will have a new message on it.

(Click image to view full size.)

If all theses step work then you have the tutorial up and running. If it fails then an error message with the reason will be returned. Check the integration log for any errors (the log is accessed from the integration in the dashboard).

Here are some additional integrations you might want create and to try:

  • Create a flow that reads off one queue in MQ Cloud and writes to anther queue.
  • Create a flow that reads off a queue in MQ Cloud and then makes a rest call using an HTTP request node.

Troubleshooting the connection to MQ Cloud.


There are many ways that the SSL details can be set up incorrectly to cause the tutorial to fail. Here is a list of the most common errors and their cause:

  • Read more

    • CORS error returned in API explorer – Due to the integration not having fully started. Try again once started. Note: there is a delay from the integration showing started in the dashboard and the REST path being fully available:
    • MQ error code 2393 (MQRC_SSL_INITIALIZATION_ERROR) – The is something wrong with the SSL configuration. Check the following:
      • Both the policy and the channel have SSL cipher spec correctly and to the same value.
      • The channel has SSL authentication set to optional and NOT required.
      • You are using the correct channel and have set the properties on the correct channel.
      • The channel has been restarted since the changes. This will only happen correctly if all users disconnect from it including requiring stopping the integration.
      • The SSL peer name is correct on the policy. It is not necessary to set the SSL peer name to be secure so try leaving it empty.
      • The SSL peer name is not set on the MQ channel. It should not be set because we are not doing client authenication. If you do set it on the channel then you will always get 2393 (MQRC_HOST_NOT_AVAILABLE).
    • Timeout followed by MQ error code 2538 in integration log – You have either the host name or port set incorrectly for your queue manager. Check the values you have set it the policy.
    • MQ error code 2035 (MQRC_NOT_AUTHORIZED) – The api key used for the username is incorrect. This is not the same as the admin user account you log into MQ cloud with. It is an application user that is configured in the MQ Cloud instance like the following:

Join The Discussion

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