IBM API Connect User Defined Policy construct

IBM API Connect Tutorial: Part-5 Create user defined policy in IBM API Connect

IBM API Connect comes with a some very useful policies for development, but they are not always sufficient. In an enterprise, there will always be need for more and more reusable policies. IBM has provided us with a framework, using which we can create user defined policy suited for our own need. In my previous blog, I have covered how to integrate MQ with IBM API Connect. I have also shown how to drop a message into MQ queue using gateway script. In this article, I’ll extend that particular POC. I’ll now create IBM API Connect user defined policy UDP. Let’s learn how to create user defined policy in IBM API Connect.

Use Case

Let’s consider that an organization has a requirement of auditing various metadata about the transaction and payload at various points of the API assembly. The audit information need to be put to IBM MQ. To achieve this, we can use a custom gateway extension and gateway script at various points. But it means that, we have to copy paste the same GW script multiple times across. It’s also a hassle to use this framework in different APIs; as we have to copy the script from another API assembly etc. Instead of this, we can package the gateway script and custom gateway extension to create a user defined policy. This policy will be available in the policy pallet for all the API developers. The developers can just drag and drop this user defined policy at any point of the API assembly.

This policy will extract the transaction metadata and message/request body to create an audit payload. Thereafter, it’ll put the message to MQ.

The functionalities of this policy are listed below:

  • It reads the parameters set by developer in the policy
  • The policy has a default queue manager and queue tied up with it. However should there be a requirement, it also provides an option for developers to provide a different queue manager and queue name.
  • User can log the target application name (backend) in the policy itself. However, if it is not set in policy level, consumer can pass the backend application name in the http header. The http header settings can be useful for internally exposed APIs.
  • Transaction Id and correlation Id can be set by user in the content variables (custom.transactionId and custom.correlId) with relevant values. However, if not set in the assembly, these values can be sent by consumers in http headers as well.
  • Using all these information, it creates an audit payload and puts to MQ queue.

You can send this audit feed from MQ queue to any data store for storage and visualization. However, our tutorial will be limited to just putting the payload to MQ.

Basic Constructs of IBM API Connect User Defined Policy

Following image shows the basic construct and their respective description of user defined policy.

 Basic Constructs of IBM APIC UDP (User Defined Policy)
Basic Constructs of IBM APIC UDP (User Defined Policy)

Let’s build AuditFW User Defined Policy

We’ll name our policy AuditFW. This policy will take few input parameters instructing the policy:

  1. whether to log the payload or not
  2. Logging sequence number
  3. Whether to log the payload from request.body or message.body
  4. Any custom message from the audit point
  5. Whether to use a different Queue manager other than the default one
  6. Whether to use a different queue other than the default one.

Build the MQ Queue Manager Object

We need to build a configuration file for the MQ Queue Manager object. We’ll reuse the same configuration file that we created in the previous article.

Build the policy configuration file

Next, we will create a configuration file that’ll define the UDP. It will have following components:

  • assembly-setvar (to set the input parameters): This is the first assembly policy of our UDP. It will have few parameters (as explained above) that will be set by the API developer at the development time. These parameters will drive the policy behavior. As this is the first step to be executed, you will notice that we have used correlation-path “$.x-ibm-configuration.assembly.execute[0]”
  • assembly-gatewayscript: This is second assembly policy of our UDP. It’ll refer to the gateway script that will construct the audit message and put it to the queue.
  • api-rule: The API rule will combine two policies that we created above:
  • assembly: Now, we will create an assembly using the above rule:
  • assembly-function: Finally, we will create an assembly function that will wrap the input params and also the above created assembly:

Putting it all together, our configuration will look like below. Let’s save this configuration in a file named auditfw.cfg.

Build the gateway script

Now, we will build the gateway script that will read the user input, context variables and build audit payload. Thereafter, it will put the payload into the queue. Let’s take a look at the gateway script file. We’ll name the configuration file as auditfw-persist-to-mq.js as mentioned in the auditfw.cfg file.

Now, we will package all 3 files (queue manager configuration, policy configuration and gateway script) in a .zip file; we’ll name it as

Deploy the IBM API Connect user defined policy

We’ll deploy the policy in our local API connect LTE setup. So, let’s start the LTE by running following commands. Just to note, the commands are same for actual APIC setup as well; just that the argument values will change as per your environment setup.

apic-lte.exe start

Once the LTE starts, we will login to the API manager using admin user

$ apic login –server –username admin –password 7iron-hide –realm admin/default-idp-1

Thereafter, we’ll issue following command to apply the user defined policy in our API manager setup

apic gateway-extensions:create /C/gwext/ –scope org –org admin –gateway-service datapower-api-gateway –availability-zone availability-zone-default –server

If the command is executed successfully, we’ll see a result something like below


To verify that, it is indeed applied, we will run following commands

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

The result of the command will be as follows

type: gateway_extension
api_version: 2.0.0
name: gateway-extension
gateway_service_url: >-
scope: org
created_at: ‘2021-06-09T19:26:47.114Z’
updated_at: ‘2021-06-09T19:26:47.114Z’
org_url: ‘’
url: >-

To delete the gateway extension, we can issue following command

apic gateway-extensions:delete –scope org -o admin –gateway-service datapower-api-gateway –availability-zone availability-zone-default –server –output –

Apply the policy 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) using username admin and password admin; switch to the apiconnect domain
  • Search for API Connect Gateway Service
  • Set the administrative state to disabled
  • Apply the changes
  • Set the administrative state to enabled
  • Apply the changes
  • Save the configuration

Verify IBM API Connect User Defined Policy

In the user defined policy section of API Connect Gateway Service, we’ll notice the newly created policy

IBM API Connect User Defined Policy

We’ll check the queue manager object is created as part of the user defined policy:

IBM MQ Queue Manager Object

We’ll also check the gateway script file is present in the file management view:

IBM API Connect user Defined Policy gateway script

Test IBM API Connect User Defined Policy

It’s the easy part. We’ll build an API with the newly created user defined policy.

  • Launch the designer toolkit.
  • Build a simple API, go to assemble section and notice the last policy in the policy pane. This is the UDP we just created. We can drag and drop this policy in the assembly and configure.
  • PFB the swagger of the test API


That was a pretty long tutorial. But I hope to have shared some knowledge.



4 Responses

  1. raj devershetty
    June 9, 2021
    • Sadruddin Md
      June 10, 2021
  2. Snehitha
    May 8, 2023
    • Sadruddin Md
      November 11, 2023

Write a response

This site uses Akismet to reduce spam. Learn how your comment data is processed.