Layer7 API Gateway 10.0

PDF
index 10.0 congw.10.0 9.4 9.3 9.2 9.1 9.0 8.4 8.3
Japanese English

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
  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. 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.
    (1) For a list of the Constant Field Values, see: 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.
    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.
  7. (Available in v10.1 CR1)
     Enter an
    MQ PUT Timeout
     value 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 than
    0
     (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
.
  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.
      When
      MQRFH
       and
      MQRFH2
       are 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:
  • 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.
    When
    MQRFH
     and
    MQRFH2
     are 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.
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.