APICv10 Gateway Extensions: MQ Sample

API Connect gateway extensions are ways to infuse datapower objects or services into the APIC framework to be referenced or used on APIC.
For example, if there are MQ objects or custom logging targets that you would like to create within APIC, you cannot just create them in the APIC domain on the DataPower Gateway because they may be overriden by the APIC manager, or lost once pod is rebooted on OCP/k8s deployments.
The best way to get desired DataPower objects or services into the APIC framework, is to create gateway extensions on APIC.
More details about gateway extensions may be found in the IBM API Connect documentation Extending the Gateway server behavior.

This document will go over the example of creating an MQ object within the APIC domain via gateway extension.

If on OCP/k8s and you haven't enabled the DataPower webgui yet, you may use the following instructions to enable and get to the gateway webgui: APICv10: Enabling DataPower WebGUI

High-Level Steps

• Part 1 Create the DataPower object and export.
• Part 2: Create the manifest.json file to package together as the Gateway Extension zip & upload to APIC.
• Part 3 Use/reference the DataPower object on APIC API.

Create the DataPower object and export

Create the MQ object on a DataPower domain other than the default domain.
Ideally, you may create a sandbox application domain, which may be deleted later. It will not be needed; the domain is created to get the specific export of the object you would like to infuse into the apiconnect framework.

The following is an example of an MQ object and how to export the DataPower object.

NOTE: If you have certificates that are required with the service, you may:

1. unzip the export,
2. update the export.xml file with the following stanza into the section,

	<files>
		<file name="cert:///name_of_cert_here.pem" src="cert/name_of_cert_here.pem" location="cert" />
	</files>

3. and add a cert directory with the certificate in the directory to be uploaded during the import:
   

NOTE: The datapower export file have been renamed to dp-export-mq-with-tls.zip for this example.

Create the manifest.json file to package together as the Gateway Extension zip & upload to APIC

1. Create the manifest.json file as sampled below:
   More details on the manifest properties may be found in the IBM documentation for Gateway extension manifest.

{
    "extension": {
      "properties": {
        "deploy-policy-emulator": false
      },
      "files": [
        {
          "filename":"dp-export-mq-with-tls.zip",
          "deploy": "immediate",
          "type": "dp-import"
        }
    ]
  }   
}

2. Zip up the manifest.json and datapower export.
   

3. Navigate to the Cloud Manager > Topology section, locate the Gateway line item, select the elipsis (), and select Configure gateway extension.
   Add the gateway extension.
   

Once uploaded, you will see the gateway-extension set:

Verify that the MQ object is set by logging into the gateways apiconnect domain:

Use/reference the DataPower object on APIC API

You may now create APIs that uses the DataPower MQ object.
This section will help you build an API to use that DataPower MQ object.

1. Create an API with no security on it for testing purposes. Details about creating new REST APIs may be found in the API documentation: Createing a new REST OpenAPI definition, or you may use the sample API created here.

2. In the sample API, ensure that the Parse policy and the GatewayScript are position like so:
   

3. The following code goes into the Gateway and that is what will use the DataPower MQ object to put messages on the queue.

var urlopen  = require('urlopen');

var inpMsg = context.get('request.body');
console.log('****inpMsg: ' + inpMsg);

var dpmqurl = { target: 'dpmq://INPUT_QUEUE_MANAGER_OBJECT_NAME_HERE/?',
    requestQueue: 'INPUT_REQUEST_QUEUE_HERE',
    transactional: false,
    sync: false,
    timeOut: 10000,
    data: inpMsg };
console.log('****dpmqurl: ' + JSON.stringify(dpmqurl));

urlopen.open (dpmqurl, function (error, response) {
    // handle the error when connecting to MQ
    if (error) {
        var msg = error + ' errorCode= ' + error.errorCode;
        console.error("MQ error is %s", msg);
        throw error;
    }
    
    var vResponse = response.headers.MQMD
	context.message.body.write(vResponse);
	context.message.header.set('Content-Type', "application/xml");
});

With correct MQ inputs, you may test the API and check the message PUT into the queue.

NOTE: The MQ response headers are set to output as the response body as shown in the gatewayscript code:

    var vResponse = response.headers.MQMD
	context.message.body.write(vResponse);