Messaging

Use the Messaging policy to trigger a messaging extension based on the specified conditions to enable request and response transformations.

In IBM API Studio, this policy is identified by the kind InvokeMessagingExtension.

Example of a Messaging policy in code view.

kind: InvokeMessagingExtension
apiVersion: api.ibm.com/v1
metadata:
  name: messaging-extension
  version: 1
  namespace: sample
  tags:
      - invoke
      - messaging
      - extension
      - policy
spec:
  condition: (${request.httpMethod} equals POST) or (${request.headers.name} notEquals ${request.payload.jsonPath[$.customer.name]})
   # other operators include Equals, Equals ignore case, Not equals, Not equals ignore case, Contains, Not Contains, Exists, Not Exists, IP Range, Greater Than, Lesser Than
  messageConfig:
    $ref: sample:MessageConfig:1.0 # refer 28-message-config.yml
  request_processing:
    transformations:
    set:
      - key: ${request.headers.h2}
        value: test4
      - key: ${request.query.q2}
        value: ${request.payload.jsonPath[$.customer.name]}
    setPayload:
      content-types:
        - application/json: |
                      {"empid" : "1"}
        - application/xml: | 
                      <a>a<a>
        - text/plain: |
                    sample text
      default-ContentType: application/json
      xsl:
        - feature:
            - name: http://javax.xml.XMLConstants/feature/secure-processing
              value: true
          $path: ./a/a.xsl
          content: sdsd
    remove:
  response_processing:
    transformations:
    set:
      - key: ${request.headers.h2}
        value: test4
      - key: ${request.query.q2}
        value: ${request.payload.jsonPath[$.customer.name]}
    copyEntireResponse: true
    abortAPIExecutionForFailure: true 
  namespaces:
      - prefix: ps1
        URI: http://test.com
      - prefix: ps2
        URI: http://test2.com

For the InvokeMessagingExtension policy kind, configure these specifications:

Code view	Form view	Description
`condition`	Conditions	Conditions are used to specify when the policy is run. You can add multiple conditions with logical operators. Provide the condition in the format: `{set} operator {value} condition {set} operator {value}` You can configure the following conditions in the Conditions section: Transform the requests that comply with all the configured conditions in the code view by using `and`, or in the form view by selecting the AND option. Transform the requests that comply with any one configured condition in the code view by using `or`, or in the form view by selecting the OR option. You can use the following operators in the code view and in the form view by using the Add condition button, which is optional. `Equals` `Equals ignore case` `Not equals` `Not equals ignore case` `Contains` `Not Contains` `Exists` `Not Exists` `IP Range` `Greater Than` `Lesser Than`
`messageConfig`	Messaging	Configures the messaging system details such as connection, destination, and message format. In the form view, click Create new message config and define these message configurations: Connection alias name. Specifies the name of an existing JMS connection alias configured in webMethods API Gateway. Create the alias in the webMethods API Gateway UI (Administration > General > Messaging > JMS connection alias definitions), and enter the same alias name here. The editor accepts only predefined alias names. Destination name. Specifies the name of the JMS destination associated with the selected connection alias. Enter a valid destination name that exists for the configured JMS connection. Destination type. Select either QUEUE or TOPIC. ReplyTo name, which is an optional field. ReplyTo type. Select either QUEUE or TOPIC. Time to live, enter the value in milliseconds. Time to wait, enter the value in milliseconds. Delivery mode. Select either Non persistent or Persistent. Properties. Defines JMS, AMQP properties for a message. Each property includes a key-value pair that defines a specific message attribute. Click Add JMS/AMQP REST property to add a new property to the message. JMS/AMQP key. Specify the name of the property. The key identifies the attribute included in the message header or metadata. JMS property value. Define the value assigned to the property key.
`request_processing`	Request transformation	Specifies the request processing parameters. You can configure the following `transformation` fields for both `setPayload` and `remove` functions: Add or update a new header, query, or path parameter in the message configuration request in the code view by using `set` and configure the `key` and `value`. In the form view, use the Add parameter button for this configuration where you can specify the Variable and Value. Set the payload content type in the code view by using `setPayload` and in the form view, use the Payload type field, which is an optional step. Configure the content type in the code view using `content-types`, and in the form view use the Payload type field, which is an optional step. These are the content types that can be configured: `application/json`in the code view and JSON in the form view. This is the default content type. On selecting this option, a code editor opens up for you to configure the content requirements. `application/xml`in the code view and XML in the form view. On selecting this, you get an option to upload an XML file. `text/plain`in the code view and Text in the form view. On selecting this, you get a plain text box to configure the file. Under `xsl`, you specify one or more transformation files that determine how the payload is modified before it’s sent or processed. In the form view, use the XSLT document section for this configuration. `$path`. Specifies the location of the XSL transformation file. IBM API Studio reads the file from the given path and applies the defined transformation rules. `feature`. Lists one or more transformation features as `name-value` pairs. The name must specify a valid feature, such as `http://javax.xml.XMLConstants/feature/secure-processing`, and the value must be set to `true` or `false`. You can include multiple XSL entries under `setPayload` to apply different transformations based on your configuration.
`response_processing`	Response transformation	Specifies the response processing parameters. Specify the response processing parameters in the code view by using `response_processing`, or in the form view using the Response transformation section. Configure the following details: Complete response from the messaging extension is forwarded back to the client in the code view when you set the `copyEntireResponse` to `true`. In the form view, you can configure this by selecting the optional Copy entire response field. Specify if the API execution should be stopped in case of messaging extension invocation failure in the code view when you set the `abortAPIExecutionForFailure` to `true`. In the form view, you can configure this by selecting the optional Abort API execution in case of failure field. In the code view, configure the `set` function and add the required details as `key` and `value`. In the form view, use the Add parameter button for this configuration where you can specify the optional Variable and Value fields.
`namespaces`	Namespace	Configure the metadata for the message configuration request. In the code view, under `namespaces`, configure the `prefix` and `URI`. In the form view, use the Custom metadata extension tab to configure the metadata. Click the Add namespace button and specify the optional Namespace prefix and Namespace URL fields.