Route via MQ Native Assertion

The Route via MQ Native assertion allows you to configure the MQ Native transportation of outbound service messages from the CA API Gateway.
gateway92
The
Route via MQ Native
assertion allows you to configure the MQ Native transportation of outbound service messages from the CA API Gateway.
Ensure the correct .jar files are installed (see Install the JMS Interface).
After 9.2 CR4 is installed, MQ Message application data is automatically converted to a format specified by the queue manager. This occurs when this routing assertion gets a message from the queue or when it gets a reply message after writing a message to a queue. Prior to CR4, no conversion is performed. If you need to disable this functionality in CR4 for whatever reason, set the
io.mqConvertMessageApplicationDataFormat
cluster property to 'false'.
CR4 also lets you force properties of an MQ Message to be returned in the MQRFH2 header when reading a message from a queue. This occurs when this routing assertion gets a message from the queue or when it gets a reply message after writing a message to a queue. To enable this behavior, set the
io.mqForceReturnPropertiesInMQRFH2Header
cluster property to 'true'.
Context Variables Used by This Assertion
The Route via MQ Native assertion utilizes the following context variables.
(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.
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
    .
    To specify the queue name dynamically, be sure to enter a context variable for the 
    Queue Name
     under "Dynamic Properties" above.
  4. 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.
    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.
  5. 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.