Skip to content
CA API Gateway - 9.3
Documentation powered by DocOps

Route via MQ Native Assertion

Last update August 31, 2018

The Route via MQ Native assertion allows you to configure the MQ Native transportation of outbound service messages from the CA API Gateway.

Note: MQ Native will not be operational until the appropriate .jar files have been installed.

Context Variables Used by This Assertion

The Route via MQ Native assertion utilizes the following context variables.

Notes: (1) The <prefix> is the target of the message. For example, if the message target is a request, then the prefix is "request"; if the message target is a response, then the prefix is "response". (2) "Request" MQ Native variables are set as soon as the Gateway receives the MQ message (the Route via MQ Native assertion need not have run yet).

Context Variable Description
${<prefix>.mqnative.md.<field>}

Returns the value of the case sensitive message descriptor field.

Example: ${request.mqnative.md.expiry}

The value for byte[] type descriptors must be entered as a Base64-encoded string. The date must be in the format yyyy-MM-dd-HH.mm.ss.SSSSSS.

${<prefix>.mqnative.additionalheader.
<folder name>.<name>
}

Returns the value of the message header. Specifying the folder name is optional.

Example: ${request.mqnative.additionalheader.folder.rfh2Field2}

${<prefix>.mqnative.property.<name>}

Returns the value of the message property.

Example: ${request.mqnative.property.folder.testStringProperty}

${<prefix>.
mqnative.additionalheadernames}

A a multivalued context variable that retrieves all message header names. The suffix .length can be applied.

Example: ${request.mqnative.additionalheadernames}

${<prefix>.

mqnative.alladditionalheadervalues}

A multivalued context variable that retrieves all message header values.The suffix .length can be applied.

Example: ${request.mqnative.alladditionalheadervalues}

${<prefix>.
mqnative.propertynames}

A multivalued context variable that retrieves all message property names.The suffix .length can be applied.

Example: ${request.mqnative.propertynames}

${<prefix>.
mqnative.allpropertyvalues}

A multi-valued context variable that retrieves all message property values.The suffix .length can be applied.

Example: ${request.mqnative.allpropertyvalues}

Defined MQ Header Prefixes

Header name prefixes for MQ Message Descriptor, Property, and Header are listed in the table below.

Header Name Prefix Description
mqnative.md

This is the header name prefix for MQ Message Descriptor.

Example: mqnative.md.expiry

mqnative.property

This is the header name prefix for MQ Message Property.

Example: mqnative.property.folder.propertyname

mqnative.additionalheader

This is the header name prefix for MQ Message Header.

Example: mqnative.header.folder.headername

To customize the Message Descriptors, Properties, and Additional Headers, use the Manage Transport Properties/Headers Assertion. Leave the Header Value empty to remove an attribute from the MQ Message Descriptor, MQ Message Property and MQ Additional Header.

Note: If a header contains the wrong prefix, it is ignored.

Using the Assertion

  1. Do one of the following:
    • To add the assertion to the Policy Development window, see Add an Assertion.
    • To change the configuration of an existing assertion, proceed to step 2 below.
  2. When adding the assertion, the Native MQ Routing Properties automatically appear; when modifying the assertion, right-click Route via MQ Native in the policy window and select MQ Native Routing Properties or double-click the assertion in the policy window. The assertion properties are displayed. These properties are organized across the following tabs:
         Target

         Request
         Response
  3. Configure each tab as necessary. Refer to the appropriate section below for a complete description of each tab.
  4. Click [OK] when done.

Configuring the [Target] Tab

The [Target] tab is used to select the MQ Native Queue to use.

  1. Choose the connection to use from the MQ Native Queues drop-down list. If the connection you need doesn't exist, click [New Queue] to create a new connection. See Managing MQ Native Queues for more information on defining the queue.
  2. If a template outbound queue was chosen as the MQ Native Queue in the previous step, complete the Dynamic Properties section. Dynamic properties are those properties that are set at runtime, rather than at design time.
    • Queue Name: Enter a dynamic queue name. You may reference a context variable.
      The dynamic queue name setting is enabled for outbound queues that have been designated as a template, and the queue name has been left empty. For details, see "Configuring the MQ Connections Properties" under Managing MQ Native Queues. 
    • Wait for Reply on specified queue: Enter a dynamic reply queue name. You may reference a context variable.
      The dynamic reply queue name is enabled for outbound queues that have been designated as a template, has the "Wait for Reply on specified queue" option selected, and the reply queue name is empty. For details, see "Configuring the MQ Connections Properties" and "Configuring the Outbound Options" under Managing MQ Native Queues. 
  3. Specify the direction for the message: Put to Queue (default) or Get from Queue.

    Note: To specify the queue name dynamically, be sure to enter a context variable for the Queue Name under "Dynamic Properties" above.

  4. Specify any Advanced Options as necessary. These options apply to messages being put to a queue or drained from a queue.

    • Open Options: Establish a connection to the queue using the options specified here. Enter a value that represents the sum of the constant fields for the MQOPEN API call. The Open options are on a per-connection basis. These options apply only when the Gateway initiates a connection to a MQ Queue/Queue Manager.
      Example:
      You want to use the constant fields MQOO_OUTPUT (16) and MQOO_FAIL_IF_QUIESCING (8192). Add these values together and enter the resulting 8208 into the Open Options field.
      If you do not specify Open options here, the Gateway consults either the io.mqRoutingPutOpenOptions or io.mqRoutingGetOpenOptions cluster properties (depending on message direction selected). If these cluster properties are not defined, then the Gateway uses the defaults from the MqNativeConstants class.
    • Message Options: Depending on the message direction, either put a message to the queue or get a message from the queue using the options specified here. Enter a value that represents the sum of the constant fields for the MQGET API call. 
      Example:
      You want to use the constant fields MQGMO_FAIL_IF_QUIESCING (8192) and MQGMO_NO_SYNCPOINT (4). Add these values together and enter the resulting 8196 into the Message Options field.
      If you do not specify Message options here, the Gateway consults the io.mqRoutingPutMessageOptions or io.mqRoutingGetMessageOptions cluster properties (depending on message direction selected). If these cluster properties are not defined, then the Gateway uses the defaults from the MqNativeConstants class.

    Tips: (1) For a list of the Constant Field Values, see: https://www.ibm.com/support/knowledgecenter/en/SSFKSJ_7.1.0/com.ibm.mq.javadoc.doc/WMQJavaClasses/constant-values.html#com.ibm.mq.constants (2) To configure Open Options and Get Message Options for inbound listeners, see "Configuring the [MQ Connection Properties] Tab" in MQ Native Queue Properties.

  5. In the Current WSS header handling section, specify how to handle the security header:

    Option Description
    Don't modify the request Security header

    Instructs the Gateway to leave the security header in the outgoing SOAP request message as-is. The security header in the request may still have been modified if the Gateway needed to decrypt any encrypted material during message processing.

    Use this setting if the protected service needs to do its own checking of the request's original security header, or if the protected service does not care whether its request messages have a security header.

    For best performance, use this setting whenever possible to minimize the amount of per-request message modification.

    Note: Do not modify the Security header if the policy uses WS-Security. For more information, see the Add or Remove WS-Security Assertion.

    Remove Layer 7 actor and mustUnderstand attributes from processed Security header

    Instructs the Gateway to remove the "mustUnderstand" attribute and "Layer 7" actor from the security header in the outgoing SOAP message.

    Use this setting if the presence of the Layer 7 actor causes issues with the back end service. In certain cases, this actor may cause the back end service to ignore the Security headers because it believes it is addressed to someone else. You will also use this setting if the back end service does not support Security and would reject a request with "mustUnderstand" asserted on the Security header.

    An alternative might be to remove the Security header completely, however this will incur a performance penalty for the extra processing required to remove these from the messages. You may want to keep the Security headers intact for logging purposes.

    Remove processed Security header from request before routing

    Instructs the Gateway to remove any security header that was processed by the gateway before forwarding the request to the protected service.

    Use this setting when the protected service is not expecting security headers in the forwarded SOAP requests.

  6. Enter an MQ response timeout value if you wish to override the global default (defined in the io.mqResponseTimeout cluster property) for this one queue. The value must be greater than 0 (zero). Enter a value in milliseconds. The assertion will wait for this period of time for a response before timing out.

Configuring the [Request] Tab

The [Request] tab is used to select the message source and to configure any MQ messages properties that may be required. This tab is available only when the message direction in the [Target] tab is Put to Queue.

  1. Choose the message source from the drop-down list: Request (default) or Response.
  2. Configure the properties of the [Request] tab as follows.

    Setting Description
    MQ Message Descriptors
    Pass through MQ message descriptors

    Select this check box to allow all MQ descriptors in the source message to pass through. (Note that there will be MQ message properties to pass through only if the original request is an MQ message.)

    Clear this check box to pass through the default values of the descriptor to the result message.

    Customize message descriptors To customize message descriptors that existed prior to version 8.0, see Customizing MQ Messages. For message descriptors created in version 8.0, it is recommended to use the Manage Transport Properties/Headers Assertion to add customized values.
    Properties
    Pass through

    Select this check box to pass all message properties from the message source.

    Clear this box if you do not want the MQ message properties to pass through.

    Copy to Additional Headers

    Select this check box to copy the MQ Message properties to the message additional headers.

    Clear this check box to not perform the copy action.

    Additional Headers
    Pass through

    Select this check box to pass all MQ additional headers from the message source.

    Clear this box if you do not want the customized MQ additional headers to pass through.

    Copy to Properties

    Select this check box to copy the additional header name-value pair to the message properties.

    Clear this check box to not perform the copy action.

    Set Additional Header as

    Choose the additional header format from the drop-down list:

    • Original: This option retains the original primary header format (MQRFH or MQRFH2). The header is automatically populated with the values from the original primary header.
    • MQRFH: All additional headers in the message are replaced with a MQRFH header. The MQRFH header is automatically populated with the values from the original primary header.
    • MQRFH2: The primary additional header is replaced with a MQRFH2 header in the message. The MQRFH2 header is automatically populated with the values from the original primary header.

Configuring the [Response] Tab

The [Response] tab is used to configure the response message properties and to configure any advanced properties that may be required.

Configure the properties of the [Response] tab as follows.

Setting Description
Message Target Choose the message target from the drop-down list: Request, Response (default), or a Message Variable.
Target Variable If the target is a context variable, specify the Message variable in the Target Variable field. You can define a new variable or use an existing one. A validation message provides instant feedback on the context variable name entered. For an explanation of the validation messages displayed, see Context Variable Validation.
MQ Message Descriptors
Pass through all message descriptors

Select this check box to allow all MQ descriptors in the source message to pass through. (Note that there will be MQ message properties to pass through only if the original request is an MQ message.)

Clear this check box to pass through the default values of the descriptor to the result message.

Customize message descriptors To customize message descriptors that existed prior to version 8.0, see Customizing MQ Messages. For message descriptors created in version 8.0, it is recommended to use the Manage Transport Properties/Headers Assertion to add customized values to its properties and headers.
Properties
Pass through

Select this check box to pass all message properties from the message source.

Clear this box if you do not want the customized message properties to pass through.

Copy to Additional Headers

Select this check box to copy the primary header name-value pair to the message headers.

Clear this check box to not perform the copy action.

Additional Headers
Pass through

Select this check box to pass all message properties from the message source.

Clear this box if you do not want the customized message properties to pass through.

Copy to Properties

Select this check box to copy the primary header name-value pair to the message properties.

Clear this check box to not perform the copy action.

Set Additional Header as

Choose the additional header from the drop-down list:

  • Original: This option retains the original primary header format in MQRFH or MQRFH2. The header is automatically populated with the values from the original primary header.
  • MQRFH: All additional headers in the message are replaced with a MQRFH header. The MQRFH header is automatically populated with the values from the original primary header.
  • MQRFH2: This primary additional header is replaced with a MQRFH2 header in the message. The MQRFH2 header is automatically populated with the values from the original primary header.
Override maximum message size

Select this check box to override the permitted maximum size of the message. Clear this check box to use the value set in the io.mqMessageMaxBytes cluster property.

  • Restrict messages to: Enter the maximum permitted size of the message, in bytes.
  • Allow unlimited message size (not recommended): Select this option to allow response messages of unlimited size.
Was this helpful?

Please log in to post comments.