CA API Gateway 9.1

9.4 9.1

Route via JMS Assertion

The Route via JMS assertion allows you to configure the JMS transportation of outbound service messages from the Gateway. In order to use this assertion in a policy, ensure that the JMS destinations have been:
gateway
The 
Route via JMS 
assertion allows you to configure the JMS transportation of outbound service messages from the Gateway. In order to use this assertion in a policy, ensure that the JMS destinations have been:
  1. Configured in the appropriate server (TIBCO EMS, IBM WebSphere over LDAP, or any other custom server).
  2. Referenced in the JNDI directory.
  3. Registered in the Policy Manager.
For more information, see Manage JMS Destinations.
 
 
 If multiple JMS properties with the same name exist in the message, only the last one added will be used by the Route via JMS assertion and the incoming request listener.
The Administrator is responsible for installing and configuring the items required for JMS routing. If you encounter errors during the execution of a JMS policy, contact your Administrator.
The Route via JMS assertion and destinations support the JMS 1.0 standard.
Context Variables Created by This Assertion
The Route via JMS assertion sets the following context variables with the header information from the JMS response message.
 The response context variables are not set if the JMS Destination is configured for “No replies (one-way)” (JMS Destination Properties > [Outbound Options] tab > Outbound Reply Behavior). For more information, see Manage JMS Destinations.
Variable
Description
 
${response.jms.header.
 
<name>
 
}
 
Returns the value of the JMS response header, where <
name
> is the header name.
 
${response.jms.headernames} 
 
This is a multivalued context variable that returns the names of all headers that are present.
 
${response.jms.allheadervalues} 
 
This is a multivalued context variable that returns all the header names and values that are present, in the format 
headername:headervalue.
.
The following are possible headers:
JMSDestination
JMSDeliveryMode
JMSExpiration
JMSPriority
JMSMessageID
JMSTimestamp
JMSCorrelationID
JMSReplyTo
JMSType
JMSRedelivered
 For a list of the context variables created when the Gateway receives a JMS request, see Manage JMS Destinations.
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 
    JMS Routing Properties
     automatically appear; when modifying the assertion, right-click 
    Route via JMS 
    in the policy window and select 
    JMS 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
    Security
    Request
    Response
  3. Configure each tab as necessary. Refer to the appropriate section below for a complete description of each tab.
  4. Select the target outbound destination to use from the 
    JMS Destination
     drop-down list. If the target destination you need doesn't exist, click [
    New Destination
    ] to create a new JMS destination. See Manage JMS Destinations for information on defining this destination.
  5. If you selected a template outbound destination in the previous step, complete the destination configuration in the 
    Dynamic Properties
     section. Dynamic properties are those properties that are set at runtime, rather than at design time.
  6. Click [
    OK
    ] when done.
Configuring the [Target] Tab
The [Target] tab is used to select the JMS queue or topic, and configure dynamic properties and timeout.
  1. Select the target outbound destination to use from the 
    JMS Destination
     drop-down list. If the target destination you need doesn't exist, click [
    New Destination
    ] to create a new JMS destination. See Manage JMS Destinationsfor information on defining this destination.
  2. If you selected a template outbound destination in the previous step, complete the destination configuration in the 
    Dynamic Properties
     section. Dynamic properties are those properties that are set at runtime, rather than at design time.
    For more information about template destination, see 
    "Template Outbound Destinations"
     in Manage JMS Destinations.
    (1) If a value was entered during destination definition then it is displayed here, but cannot be modified. (2) If many destinations are in use, you can improve performance by reducing the idle time and increasing the cache size. These are controlled using the 
    io.jmsConnectionCacheMaxIdleTime
     and 
    io.jmsConnectionCacheMaxSize
     cluster properties, respectively.
    Dynamic Property
    For information on this property, see...
     
    Initial Context Factory class name
     
    JMS Destination Properties, [JNDI] tab
     
    JNDI URL 
     
    JMS Destination Properties, [JNDI] tab
     
    JNDI User Name 
     
    JMS Destination Properties, [JNDI] tab
     
    Tip:
     You may reference a context variable for the JNDI User Name in JMS Routing Properties.
     
    JNDI Password 
     
    JMS Destination Properties, [JNDI] tab
     
    Tip:
     You may reference a context variable for the JNDI Password in JMS Routing Properties.
     
    Connection Factory Name
     
    JMS Destination Properties, [Destination] tab
     
    Tip:
     You may reference a context variable for the Connection Factory Name in JMS Routing Properties.
     
    Destination Name
     
    JMS Destination Properties, [Destination] tab
     
    Tip:
     You may reference a context variable for the Destination Name in JMS Routing Properties.
     
    Destination User Name 
     
    JMS Destination Properties, [Destination] tab
     
    Tip:
     You may reference a context variable for the Destination User Name in JMS Routing Properties.
     
    Destination Password 
     
    JMS Destination Properties, [Destination] tab
     
    Tip:
     You may reference a context variable for the Destination Password in JMS Routing Properties.
     
    Wait for Reply on specified queue
     
    JMS Destination Properties, [Outbound Options] tab
     
    Note:
     If the Outbound Reply Behavior in the template queue is not "Wait for Reply", then this field is blank and uneditable
  3. Optionally enter a 
    JMS response timeout
     value if you wish to override the global default (defined in the 
    jms.ResponseTimeout
     cluster property) for this one destination. The value must be greater than 
    0
     (zero). Enter a value in milliseconds or enter a context variable that will contain the timeout value. The assertion will wait for this period of time for a response before timing out. 
    Tip:
     The global default is specified by the 
    jms.ResponseTimeout
     cluster property.
    Ensure that the JMS response timeout is not greater than the HTTP response timeout on the client, otherwise data may be lost. (The client response timeout may vary, but for web browsers it is usually two minutes.)
Configuring the [Security] Tab
The [Security] tab is used to set the service authentication and WSS header handling.
  1. In the 
    Service Authentication
     section, indicate whether authentication should be used:Service Authentication during JMS routing
    Option
    Description
     
    None (Anonymous)
     
    Select this option if the identity of the requestor is not being authenticated (requests anonymous).
     
    Attach SAML Sender-Vouches
     
    Select this option to attach a SAML sender-vouches ticket to each outgoing back-end request that was authenticated by the Gateway. This ticket contains the user name of the authenticated user along with an expiration time, and is signed by the Gateway using the SSL certificate.
    When using SAML Sender-Vouches, indicate:
    •  
      SAML Version:
       Specify whether SAML 1.1 or 2.0 is being used.
    •  
      Ticket expiry:
       Enter the expiry period for the ticket, in number of minutes (whole number only). The default is 5 minutes.
     
    Note:
     This option is enabled only for SOAP web service policies. It differs from the Require SAML Token Profile assertion as follows:
    • The 
      Attach SAML Sender-Vouches
       option is being added to the outgoing message from the Gateway to the protected service.
    • The 
      Require SAML Token Profile Assertion
       requires that SAML security already be present in an incoming message from a client application to the Gateway.
    In the 
    Current WSS header handling
     section, specify how to handle the security header:WSS Header Handling during JMS routing
    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.
Configuring the [Request] Tab
The [Request] tab is used to select the message source for the request message and to configure property forwarding.
  1. Specify the 
    Message Source
     for the request message: from the drop-down list, choose from 
    Request
    , 
    Response
    , or any Message context variables that have been defined so far. These variables may have been created by the Set Context Variable assertion or in the 
    Response message properties
     section of a previous Route via JMS assertion.
  2. Select the 
    Use request settings
     check box if you need to change any of the following default JMS request settings:
    •  
      Delivery Mode:
       Choose the JMS delivery mode to use: Persistent or Non-Persistent.
    •  
      Priority:
       Specify a priority mode for the JMS request by entering a value between 0 and 9, where "0" is lowest priority and "9" is highest priority. The default is 
      4
      .
    •  
      Time To Live:
       Enter the length of time before the JMS message expires, in milliseconds. The default value of 
      0
       (zero) means the message never expires.
  3. Indicate how the properties from the JMS request message are handled:
    • Select Pass 
      through all JMS message properties
       if you are allowing all JMS message properties to pass through. (Note that there will be JMS message properties to pass through only if the original request is a JMS message.)
    • Select 
      Customize JMS message properties to forward
       if you want to do any of the following:
      • customize which or how JMS message properties are passed through
      • customize the values of the JMS message properties
      • create properties that did not exist in the original request (such as when the original request is not a JMS message).
      If you are customizing the JMS message properties to pass through, define which names and values can pass through in the table below:
      To...
      Do this
      Add a property to the list
      1. Click [
        Add
        ]. The JMS Message Property Setting dialog appears.
      2. Enter the 
        Property
         
        Name
        . (Note: Property names must obey the rules specified in the JMS Specification).
      3. Specify what to do for this property:
        •  
          Pass through original value:
           If the property is present in the incoming request, then pass it downstream as is.  
        •  
          Customize value:
           Insert a property with a custom string value. Enter the custom value in the adjacent box. You can either enter a fixed value or a string that contains context variables that resolves to the appropriate value during run time. For example,
           "Hello, my ID is ${requestId} and the time is ${gateway.time}. Have a nice
           day."
          Note:
           
           
          The Policy Manager checks that the custom value entered is appropriate for the specified property. However note that if a context variable is specified, it is not possible to validate the data type at design time and an incorrect data type will cause an error during runtime. The following data types are enforced for each property:
           JMSXUserID: String
           
           JMSXAppID: String
           
           JMSXDeliveryCount: int
           
           JMSXGroupID: String
           
           JMSXGroupSeq: int
           
           JMSXProducerTXID: String
           
           JMSXConsumerTXID: String
           
           JMSXRcvTimestamp: long
           
           JMSXState: 
          int
           
      4. Click [
        OK
        ]. The new property is added to the table.
      Modify a property in the list
      1. Select the property to modify and then click [
        Edit
        ], or double-click a row. The JMS Message Property Setting dialog appears.
      2. Modify the information as necessary. See 
        "Add a property to the list"
         above for details.
      3. Click [
        OK
        ]. The modified property appears on the table.
      Remove a property from the list
      1. Select the row to delete.
      2. Click [
        Remove
        ]. The property is removed immediately.
Configuring the [Response] Tab
The [
Response
] tab is used to configure the message destination and property forwarding.
  1. Select the 
    Message Destination
    :
    • Select
       Default Response
       to send the message to the default response destination.
    • Select 
      Save as context variable
       to save the response message to a context variable that you specify here. You can define a new variable or 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.
  2. Specify the response message size limit:
    •  
      Override maximum message size:
       Select this check box to override the permitted maximum size of the routing message. Clear this check box to use the value set in the 
      io.jmsMessageMaxBytes 
      cluster property.
      •  
        Restrict messages to:
         Enter the maximum permitted size of the response message, in bytes. You may specify a context variable. 
      •  
        Allow unlimited message size (not recommended):
         Select this option to allow response messages of unlimited size.
  3. Indicate how the properties from the JMS response message are handled:
    • Pass through all JMS message properties
    • Customize JMS message properties to forward 
    Please see 
    "Configuring the [Request] Tab"
     above for the descriptions of these settings.

Content feedback and comments