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

Route via JMS Assertion

Last update November 22, 2017

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.

Note: 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.

Note: 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

Tip: 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 RequestResponse, 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 PropertyName. (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.

Was this helpful?

Please log in to post comments.