IBM API Connect Tutorial: Part-4 Integrate MQ with API Connect

Here, I’ll write a tutorial on how to integrate IBM MQ with IBM API Connect v2018. The same is valid for v10 as well. So far, IBM has not povided us with any in built policy to integrate with MQ. However, MQ integration is very crucial for any enterprise. In this tutorial, I’ll cover how we can integration API Connect with MQ. We’ll follow the same custom extension framework that I have explained in my previous article on creating custom gateway extension of crypto object. We don’t have to always depend on IBM to deliver such features.

If you have not read my previous articles on APIC, please go through those:

• https://iteritory.com/install-ibm-api-connect-lte-in-local-windows-system/
• https://iteritory.com/ibm-api-connect-tutorial-part-1-develop-your-first-api/
• https://iteritory.com/ibm-api-connect-tutorial-part-2-ibm-apic-map-policy-with-example/
• https://iteritory.com/ibm-api-connect-tutorial-part-3-create-custom-gateway-extension-of-crypto-object/

Use Case

Before proceeding, let’s build the a use case for this tutorial to integrate MQ with API Connect. We’ll keep it very simple. Let’s expose a REST API that will accept a JSON payload from user and then it’ll persist the same into a MQ Queue.

Following will be our input data:

{
	"mqpoc":"REST 2 MQ pattern"
}

After successful execution, we would like to see the same message in the queue.

Assumption

I am assuming that you already have installed or have access to MQ. In my POC, I have installed IBM MQ in my laptop where I am also running the APIC LTE.

Creating the CLI script for MQ Queue Manager

There is no inbuilt policy for MQ Queue Manager connectivity in APIC. We are also not supposed to create Datapower objects manually in the APIC domain. Hence, we’ll to write a custom gateway extension containing the CLI commands to create a MQ Queue Manager object in the APIC domain of Datapower Gateway. Now, most of us are unsure of the syntax and how to use such CLI commands in Datapower. Like I showed in previous article, let’s do the easy hack.

• Let’s login to any application domain (other than the APIC domain)
• In this domain, let’s create a Queue manager object. I have used below configuration

• After saving the above configuration, we’ll go to File Management and expand the config folder. There’ll be a file with the name of Datapower domain itself. Let’s open the file.

• In this .cfg file, let’s search for the object that we just created. Basically, this file contains all the CLIs of the objects created in Datapower from GUI.

• We’ll now copy the above commands that are used to create the MQ Queue Manager object. Our CLI script will be as follows:

top; configure terminal;

mq-qm "AUDTIQM"
  hostname x.x.x.x(1414)
  queue-manager "QM1"
  ccsid 819
  channel-name "DEV.APP.SVRCONN"
  heartbeat 300
  maximum-message-size 1048576
  cache-timeout 60
  no automatic-backout 
  total-connection-limit 250
  initial-connections 1
  sharing-conversations 0
  no share-single-conversation 
  no permit-insecure-servers 
  no permit-ssl-v3 
  ssl-cipher none
  no auto-recovery 
  convert 
  auto-retry 
  retry-interval 10
  retry-attempts 6
  long-retry-interval 600
  reporting-interval 10
  no alternate-user 
  polling-tolerance 10
  xml-manager default
  ssl-client-type proxy
exit

• I have masked my IP with x.x.x.x; please replace with your IP when you test.
• Now, switch to the APIC domain in Datapower and head to File Management. Expand the temporary\config folder.
• There will be quite a few files with names starting with a number. Note the highest number. For example, in the below snippet, you can see the highest number is 30.

• We’ll now save the CLI script (that we copied above) with a number greater than the number present above. For example, I’ll save the script with a name 40.gw_ext_mq_qm.cfg
• We’ll create a folder C:\apigwextqm and save the 40.gw_ext_mq_qm.cfg files in this folder.
• Next, we will right click on this .cfg file and add it to a zip file named apigwextqm.zip

Create Gateway Extension

• Now, open the command prompt and execute following command to login to API management using admin user.

apic login --server 127.0.0.1:2000 --username admin --password 7iron-hide --realm admin/default-idp-1

• Thereafter, execute the following command to create the gateway extension

apic gateway-extensions:create C:\apigwextqm\apigwextqm.zip --scope org --org admin --gateway-service datapower-api-gateway --availability-zone availability-zone-default --server 127.0.0.1:2000

• Upon successful execution, it will give an output like:

gateway-extension   https://127.0.0.1:2000/api/orgs/42535da0-4c43-45cc-bed4-d190f4789235/availability-zones/4f8893e7-569b-4cb9-976a-9776d4abca1d/gateway-services/b65c04c9-e934-4c54-be12-ec7e131eecae/gateway-extension

• We can also run the following command and check the output to confirm that the gateway extension is actually created

apic gateway-extensions:get --scope org -o admin --gateway-service datapower-api-gateway --availability-zone availability-zone-default --server 127.0.0.1:2000 --output -

• Upon successful execution, it will give an output like:

type: gateway_extension
api_version: 2.0.0
name: gateway-extension
gateway_service_url: >-
  https://127.0.0.1:2000/api/orgs/42535da0-4c43-45cc-bed4-d190f4789235/availability-zones/4f8893e7-569b-4cb9-976a-9776d4abca1d/gateway-services/b65c04c9-e934-4c54-be12-ec7e131eecae
scope: org
created_at: '2021-04-08T19:23:27.267Z'
updated_at: '2021-04-08T19:23:27.267Z'
org_url: 'https://127.0.0.1:2000/api/orgs/42535da0-4c43-45cc-bed4-d190f4789235'
url: >-
  https://127.0.0.1:2000/api/orgs/42535da0-4c43-45cc-bed4-d190f4789235/availability-zones/4f8893e7-569b-4cb9-976a-9776d4abca1d/gateway-services/b65c04c9-e934-4c54-be12-ec7e131eecae/gateway-extension

• Apply the extension to the gateway server by restarting the API Connect gateway service object. Complete the following steps on each Gateway server in the Gateway service.
  • Log in to the Datapower (https://localhost:9091/dp/login.xml); switch to the domain reserved for API Connect
  • Search for API Connect Gateway Service
  • Set the Administrative State to disabled.
  • Apply the changes.
  • Set the Administrative State to enabled.
  • Apply the changes.

Verify the just created MQ QM objects

In the same APIC domain, let’s search for Queue Manager and see the object we just created using CLI commands:

Let’s build the API

Now, the easy part i.e. to build an API with a gateway script in assembly that puts the input message to the MQ. Following is the swagger for this API:

swagger: '2.0'
info:
  title: REST to MQ POC API
  version: 1.0.0
  description: REST to MQ POC API
  x-ibm-name: resttomqpocapi
basePath: /rest2mq
schemes:
  - https
paths:
  /:
    post:
      parameters:
        - name: body
          schema:
            $ref: '#/definitions/input'
          in: body
          required: true
      responses:
        '200':
          description: success
          schema:
            type: string
definitions:
  input:
    title: Root Type for input
    description: input data
    type: object
    properties:
      mqpoc:
        type: string
    example:
      mqpoc: REST 2 MQ pattern
securityDefinitions:
  clientSecret:
    type: apiKey
    description: Client Secret
    name: X-IBM-Client-Secret
    in: header
    x-key-type: client_secret
  clientID:
    type: apiKey
    name: X-IBM-Client-Id
    in: header
security:
  - clientID: []
    clientSecret: []
x-ibm-configuration:
  cors:
    enabled: true
  gateway: datapower-api-gateway
  type: rest
  phase: realized
  enforced: true
  testable: true
  assembly:
    execute:
      - gatewayscript:
          version: 2.0.0
          title: gatewayscript
          source: "var apim = require('apim');\r\nvar urlopen  = require('urlopen');\r\nvar inpMsg = JSON.stringify(apim.getvariable('message.body'));\r\n\r\nvar dpmqurl = { target: 'dpmq://AUDTIQM/?',\r\n    requestQueue: 'DEV.QUEUE.1',\r\n    transactional: false,\r\n    sync: false,\r\n    timeOut: 10000,\r\n    data: inpMsg };\r\nconsole.log(dpmqurl)\r\nurlopen.open (dpmqurl, function (error, response) {\r\n    // handle the error when connecting to MQ\r\n    if (error) {\r\n        var msg = error + 'errorCode=' + error.errorCode;\r\n        console.error(\"MQ error is %s\", msg);\r\n        throw error;\r\n    }\r\n    var responseCode = response.statusCode; \r\n\tvar successMsg = \"Successfully put message to out queue. MQ status code is: \" + responseCode;\r\n    console.info(successMsg);\r\n\tcontext.message.body.write(successMsg);\r\n\tcontext.message.header.set('Content-Type', \"text/plain\");\r\n});"
  properties:
    target-url:
      value: 'http://example.com/operation-name'
      description: The URL of the target service
      encoded: false
  application-authentication:
    certificate: false
  activity-log:
    enabled: true
    error-content: header
    success-content: activity

Publish & Test the API

• Import the above swagger in API designer toolkit. In the assemble section of the API Designer, click on red encircled play button to publish the above API. Wait for the deployment to complete

• Click on the test button. Please refer to the red encircled button below.

• A new pane/sub-window will open on the left on top of the policy pallet. Select the operation

• Scroll down; generate data and click on Invoke button.
• It’ll invoke the API. The result will also be shown in the same pane

• Now, let’s open the MQ Explorer and verify whether we have received the same message that we have sent as input.

Conclusion

Well, that’s it for today. We just learnt how to integrate MQ with APIC seamlessly. Stay tuned!

Reference

• https://www.ibm.com/docs/en/api-connect/2018.x?topic=behavior-configuring-your-gateway-server-extensions
• https://www.ibm.com/docs/en/datapower-gateways/2018.4?topic=module-urlopenopen-error-responses
• https://www.ibm.com/docs/en/api-connect/2018.x?topic=reference-api-connect-context-variables