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.
The
Route via MQ Native
assertion allows you to configure the MQ Native transportation of outbound service messages from the Layer7 API Gateway
. 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.
(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
- 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.
- When adding the assertion, theNative MQ Routing Propertiesautomatically appear; when modifying the assertion, right-clickRoute via MQ Nativein the policy window and selectMQ Native Routing Propertiesor double-click the assertion in the policy window. The assertion properties are displayed. These properties are organized across the following tabs:TargetRequestResponse
- Configure each tab as necessary. Refer to the appropriate section below for a complete description of each tab.
- Click [OK] when done.
Configuring the [Target] Tab
The [
Target
] tab is used to select the MQ Native Queue to use.- Choose the connection to use from theMQ Native Queuesdrop-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.
- 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.
- Specify the direction for the message:Put to Queue(default) orGet from Queue.To specify the queue name dynamically, be sure to enter a context variable for theQueue Nameunder "Dynamic Properties" above.
- Specify anyAdvanced Optionsas 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 resulting8208into the Open Options field.If you do not specify Open options here, the Gateway consults either theio.mqRoutingPutOpenOptionsorio.mqRoutingGetOpenOptionscluster 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 resulting8196into the Message Options field.If you do not specify Message options here, the Gateway consults theio.mqRoutingPutMessageOptionsorio.mqRoutingGetMessageOptionscluster properties (depending on message direction selected). If these cluster properties are not defined, then the Gateway uses the defaults from the MqNativeConstants class.
(1) For a list of the Constant Field Values, see: MQ Native Queue Properties. - In theCurrent WSS header handlingsection, specify how to handle the security header:OptionDescriptionDon't modify the request Security headerInstructs 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 headerInstructs 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 routingInstructs 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.
- Enter anMQ response timeoutvalue if you wish to override the global default (defined in theio.mqResponseTimeoutcluster property) for this one queue. The value must be greater than0(zero). Enter a value in milliseconds. The assertion will wait for this period of time for a response before timing out.
- (Available in v10.1 CR1)Enter anMQ PUT Timeoutvalue in milliseconds to create a thread pool with the following cluster property values. This thread pool provides PUT threads to PUT messages in the IBM MQ Server. The timeout value must be greater than0(zero).Update the value of these cluster properties to create the thread pool using custom values; otherwise the thread pool is created with the default values.
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
.- Choose the message source from the drop-down list:Request(default) orResponse.
- Configure the properties of the [Request] tab as follows.SettingDescriptionMQ Message DescriptorsPass through MQ message descriptorsSelect 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 descriptorsTo 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.PropertiesPass throughSelect 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 HeadersSelect 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 HeadersPass throughSelect 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 PropertiesSelect 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 asChoose 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.WhenMQRFHandMQRFH2are selected as additional headers, you can define the format of data that is following this header by adding the property,mqnative.MQRFH.formatField, using the Manage Transport Properties/Headers Assertion.
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:
|
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.
|