Creating a JMS Trigger

About this task

When you create a JMS trigger, keep the following points in mind:
  • The JMS connection alias you want Integration Server to use to obtain connections to and receive messages from the JMS provider must already exist. Although a JMS connection alias does not need to be enabled at the time you create the JMS trigger, the JMS connection alias must be enabled for the JMS trigger to execute at run time.
    Note: If you want to manage destinations and durable subscribers on a webMethods Broker that is used as a JMS provider, the JMS connection alias must be enabled when you work with the JMS trigger.
  • If you use a JNDI provider to store JMS administered objects, the Connection Factories that you want the JMS trigger to use to consume messages must already exist.
  • If you use a JNDI provider to store JMS administered objects and the JMS provider is not webMethods Broker, the destinations (queues and topics) from which this JMS trigger will receive messages must already exist.
    Note: webMethods Broker is deprecated.
  • If the JMS provider is webMethods Broker or Software AG Universal Messaging, the destinations (queues and topics) from which the JMS trigger receives messages do not need to exist before you create the JMS trigger. Instead, you can create destinations using the JMS trigger editor. You can also create, modify, and delete durable subscribers via the JMS trigger. For more information, see Managing Destinations and Durable Subscribers on the JMS Provider through Designer.
  • If the JMS provider is Universal Messaging, administered objects can be created on demand. If you specify a destination that does not exist in the JNDI namespace and the JMS connection alias used by the JMS trigger is configured to create administered objects on demand, Integration Server creates the destination the first time the JMS trigger starts. For more information about creating administered objects on demand, see webMethods Integration Server Administrator’s Guide .
  • The transaction type of the JMS connection alias determines whether or not the JMS trigger is transacted (that is, it receives and processes messages as part of a transaction). Transacted JMS triggers have slightly different properties and operate differently than non-transacted JMS triggers. For more information about building a transacted JMS trigger, see Building a Transacted JMS Trigger.
  • The trigger service that you want to specify in the routing rule must already exist on the same Integration Server on which you create the JMS trigger. For more information, see Standard JMS Trigger Service Requirements.
  • A standard JMS trigger can contain multiple routing rules. Each routing rule must have a unique name. For more information about using multiple routing rules, see Building Standard JMS Triggers with Multiple Routing Rules.
  • A standard JMS trigger that contains an All (AND) or Only one (XOR) join can only have one routing rule and cannot have a batch processing size (Max batch messages property) greater than 1. A JMS trigger with an Any (Or) join can have multiple routing rules. For more information about batch processing, see About Batch Processing for Standard JMS Triggers.
  • Integration Server uses a consumer to receive messages for a JMS trigger. This consumer encapsulates the actual javax.jms.MessageConsumer and javax.jms.Session.

To create a JMS trigger

Procedure

  1. In the Package Navigator view of Designer, click File > New > JMS Trigger.
  2. In the New JMS Trigger dialog box, select the folder in which you want to save the JMS trigger.
  3. In the Element name field, type a name for the JMS trigger using any combination of letters, numbers, and/or the underscore character.
  4. Click Finish.
  5. In the JMS connection alias name field in the Trigger Settings tab, click .
    Note: A transacted JMS connection alias cannot be assigned to a JMS trigger if a cluster policy is applied to the connection factory used by the JMS connection alias.
  6. In the Select a JMS connection alias for triggerName dialog box, select the JMS connection alias that you want this JMS trigger to use to receive messages from the JMS provider. Click OK.

    Designer sets the Transaction type property to match the transaction type specified for the JMS connection alias.

    If a JMS connection alias has not yet been configured on Integration Server, Designer displays a message stating the JMS subsystem has not been configured. For information abut creating a JMS connection alias, see webMethods Integration Server Administrator’s Guide .

  7. In the JMS trigger type list, select one of the following:
    Select To...
    Standard Create a standard JMS trigger.
    SOAP-JMS Create a SOAP-JMS trigger.
  8. Under JMS destinations and message selectors, specify the destinations from which the JMS trigger will receive messages. For more information, see Adding JMS Destinations and Message Selectors to a JMS Trigger.
    Note: For SOAP-JMS triggers, you can specify one destination only.
  9. If you selected multiple destinations, select the join type. The join type determines whether Integration Server needs to receive messages from all, any, or only one of destinations to execute the trigger service.
    Select... If you want...
    All (AND) Integration Server to invoke the trigger service when the trigger receives a message from every destination within the join time-out period. The messages must have the same activation.
    Any (OR) Integration Server to invoke the trigger service when the trigger receives a message from any of the specified destinations.

    This is the default join type.

    Note: Using an Any (OR) join is similar to creating multiple JMS triggers that listen to different destinations. While a JMS trigger with an Any (OR) join will use fewer resources (a single thread will poll each destination for messages), it may cause a decrease in performance (it may take longer for one thread to poll multiple destinations).
    Only one (XOR) Integration Server to invoke the trigger service when it receives a message from any of the specified destinations. For the duration of the join time-out period, the Integration Server discards any messages with the same activation that the trigger receives from the specified destinations.
  10. If this is a standard JMS trigger, under Message routing, add routing rules. For more information, see Adding Routing Rules to a Standard JMS Trigger.
  11. In the Properties view, set properties for the JMS trigger.
  12. Enter comments or notes, if any, in the Comments tab.
  13. Click File > Save.

Adding JMS Destinations and Message Selectors to a JMS Trigger

About this task

The destination is the queue or topic to which the JMS trigger subscribes on the JMS provider. When a JMS trigger subscribes to a topic, you can also indicate whether Integration Server creates a durable subscriber or a non-durable subscriber for the topic.

To add a JMS destination to a JMS trigger

Procedure

  1. In the Package Navigator view of Designer, open the JMS trigger.
  2. In the Trigger Settings tab, under JMS destinations and message selectors, click .
  3. In the Destination Name column, do one of the following to specify the destination from which you want the JMS trigger to receive messages.
    • If the JMS connection alias uses JNDI to retrieve administered objects, specify the lookup name of the Destination object.
    • If the JMS connection alias uses the native webMethods API to connect directly to webMethods Broker, specify the provider-specific name of the destination.
    • If the JMS connection alias creates a connection on webMethods Broker or Universal Messaging, click to select from a list of existing destinations. You can also create a destination and then select it. After you select the destination, click OK.
      Note: If you do not see and the Enable Destination Management with Designer option is enabled for the JMS connection alias, refresh the package that contains the JMS trigger.

      If the Order By mode for the selected destination does not match the existing message processing mode, Designer prompts you to change the processing mode. This situation can occur only when the JMS provider is webMethods Broker.

      For instructions for creating a destination, see Creating a Destination on the JMS Provider.

  4. In the Destination Name column, in the Destination Type column, select the type of destination:
    Select... If...
    Queue The destination is a queue. This is the default.
    Topic The destination is a topic.
    Topic (Durable Subscriber) The destination is a topic for which there is a durable subscriber.
    Note: Designer populates Destination Type automatically if you selected a destination from the list of existing destinations on the JMS provider.
  5. In the JMS Message Selector column, click . In the Enter JMS Message Selector dialog box, enter the expression that you want to use to receive a subset of messages from this destination and click OK.

    For more information about creating a JMS message selector, see Creating a Message Selector.

  6. If you specified the destination type as Topic (Durable Subscriber), in the Durable Subscriber Name column, do one of the following:
    • Enter a name for the durable subscriber.
    • If the JMS connection alias creates a connection on webMethods Broker or Universal Messaging, click to select from a list of existing durable subscribers for the topic. In the Durable Subscriber List dialog box select the durable subscriber and click OK.

      If the durable subscriber that you want this JMS trigger to use does not exist, you can create it by entering in the name in the Durable Subscriber Name column. The name must be unique for the connection where the connection name is the client ID of the JMS connection alias. webMethods Broker or Universal Messaging, will create the durable subscriber name using the client ID of the JMS connection alias and the specified durable subscriber name.

    Note: Designer populates Durable Subscriber Name automatically if you selected a Topic (Durable Subscriber) destination from the list of existing destinations on webMethods Broker or Universal Messaging.
  7. If you want the JMS trigger to ignore messages sent using the same JMS connection alias as the JMS trigger, select the check box in the Ignore Locally Published column. This property applies only when the Destination Type is Topic or Topic (Durable Subscriber).
    Note: If the JMS connection alias specified for this trigger has the Create New Connection per Trigger option enabled, then Ignore Locally Published will not work. For the JMS trigger to ignore locally published messages, the publisher and subscriber must share the same connection. When the JMS connection alias uses multiple connections per trigger, the publisher and subscriber will not share the same connection.
  8. Repeat this procedure for each destination from which you want the JMS trigger to receive messages.
  9. Click File > Save.

Results

Notes:
  • If you specify a new durable subscriber name and the JMS connection alias that the JMS trigger uses to retrieve messages is configured to manage destinations, Integration Server creates a durable subscriber for the topic when the JMS trigger is first enabled.
  • If you specify a destination type of Topic (Durable Subscriber) but do not specify a durable subscriber name, Designer changes the destination type to Topic when you save the JMS trigger.

Creating a Destination on the JMS Provider

About this task

If the JMS connection alias that the JMS trigger uses to retrieve messages is configured to manage destinations, you can create a destination on the JMS provider while using the JMS trigger editor.

Keep the following points in mind when creating destinations using Designer:

  • The JMS connection alias used by the JMS trigger must use Universal Messaging, Nirvana, or webMethods Broker as the JMS provider.
    Note: Prior to version 9.5 SP1, Software AG Universal Messaging was named webMethods Nirvana.
  • The JMS connection alias used by the JMS trigger must be configured to manage destinations.
  • The JMS connection alias must be enabled when you work with the JMS trigger.
  • If the JMS connection alias creates a connection on a webMethods Broker in a webMethods Broker cluster, you will not be able to create a destination at the webMethods Broker.

To create a destination on the JMS provider

Procedure

  1. In the Package Navigator view of Designer, open the JMS trigger that uses a JMS connection alias that connects to the JMS provider on which you want to create the destinations.
  2. In the Trigger Settings tab, under JMS destinations and message selectors, click .
  3. In the Destination Name column, click .
  4. In the Destination List dialog box, click Create New Destination.
  5. In the Create New Destination dialog box, provide the following information:
    In this field... Specify...
    Destination Name A name for the destination.
    Destination Key A name for the destination key. If you do not specify a destination key, Integration Server uses the destination name as the destination key.

    In the Destination List, when a destination has a destination key Designer displays the destination name using this format: destinationKey (destinationName)

    Destination Type The type of destination. Select one of the following:
      Select... To...
      Queue The destination is a queue.

    This is the default.

      Topic The destination is a topic.
      Topic (Durable Subscriber) The destination is a topic for which you want to create a durable subscriber.
    Durable Subscriber Name A name for the durable subscriber. The name must be unique for the connection, where the connection name is the client ID of the JMS connection alias. The JMS provider (webMethods Broker, Universal Messaging, or Nirvana) will create the durable subscriber name using the client ID of the JMS connection alias and the specified durable subscriber name.

    This field only applies if the destination is Topic (Durable Subscriber).

    Order By How webMethods Broker distributes messages received by this destination.

    This field only apples if the JMS provider used y the trigger JMS connection alias is the webMethods Broker and the destination is Queue.

      Select... To...
      Publisher Distribute messages received by this destination one at a time in the order in which they were received from the publisher.
      None Distribute the messages received by this destination in any order.

    This is the default.

     
    Note: An order mode of publisher maps to a serial message processing mode. An order mode of none maps to a concurrent message processing mode.
  6. Click OK to create the destination.
  7. If you want the current JMS trigger to retrieve messages from the new destination, select the destination and click OK.

    Designer adds the destination to the JMS destinations and message selectors list. If the Order By mode for the new destination does not match the existing message processing mode, Designer prompts you to change the processing mode.

Results

Notes:

  • Integration Server adds the new destination to the webMethods Broker as a shared-state client.

  • If you specify a destination type of Topic (Durable Subscriber) but do not specify a durable subscriber name, Designer changes the destination type to Topic when you save the JMS trigger.

About Durable and Non-Durable Subscribers

When a JMS trigger receives messages from a topic, you can specify whether or not the JMS trigger is a durable subscriber.

A durable subscriber establishes a durable subscription with a unique identity on the JMS provider. A durable subscription allows subscribers to receive all the messages published on a topic, including those published while the subscriber is inactive (for example, if the JMS trigger is disabled). When the associated JMS trigger is disabled, the JMS provider holds the messages in guaranteed storage. If a durable subscription already exists for the specified durable subscriber on the JMS provider, this service resumes the subscription.

A non-durable subscription allows subscribers to receive messages on their chosen topic only if the messages are published while the subscriber is active. A non-durable subscription lasts the lifetime of its message consumer. Note that non-durable subscribers cannot receive messages in a load-balanced fashion.

Creating a Message Selector

If you want the JMS trigger to receive a subset of messages from a specified destination, create a message selector. A message selector is an expression that specifies the criteria for the messages in which the JMS trigger is interested.

The JMS provider applies the message selector to messages it receives. If the selector evaluates to true, the message is sent to the JMS trigger. If the selector evaluates to false, the message is not sent to the JMS trigger.

By creating message selectors, you can delegate some filtering work to the JMS provider. This can preserve Integration Server resources that otherwise would have been spent receiving and processing unwanted messages.

The message selector must use the message selector syntax specified in the Java Message Service standard. The message selector can reference header and property fields in the JMS message only.

Note: If you want to filter on the contents of the JMS message body, write a local filter. Integration Server evaluates a local filter after the JMS trigger receives the message from the JMS provider. Only standard JMS triggers can use local filters.

Adding Routing Rules to a Standard JMS Trigger

About this task

The routing rule specifies the service that Integration Server invokes when the standard JMS trigger receive a message from a destination.

To add a routing rule to a standard JMS trigger

Procedure

  1. In the Package Navigator view of Designer, open the JMS trigger.
  2. In the Trigger Settings tab, under Message routing, click to add a new routing rule.
  3. In the Name column, type a name for the routing rule. By default Designer assigns the first rule the name “Rule 1”.
  4. In the Service column, click to navigate to and select the service that you want to invoke when Integration Server receives messages from the specified destinations.
  5. In the Local Filter column, click to enter the filter that you want Integration Server to apply to messages this JMS trigger receives. For more information about creating a local filter, see Creating a Local Filter.
  6. Click File > Save.

Creating a Local Filter

You can further refine the messages received and processed by a standard JMS trigger by creating local filters. A local filter specifies criteria for the contents of the message body. Integration Server applies a local filter to a message after the JMS trigger receives the message from the JMS provider. If the message meets the filter criteria, Integration Server executes the trigger service specified in the routing rule. If the message does not meet the filter criteria, Integration Server discards the message and acknowledges the message to the JMS provider.

If a JMS trigger contains multiple routing rules to support ordered service execution, you can use local filters to process a series of messages in a particular order. For more information about ordered service execution, see Building Standard JMS Triggers with Multiple Routing Rules.

When creating a local filter, you can omit the JMSMessage document from the filter expression even though it is part of the pipeline provided to the JMS trigger service. For example, a filter that matches those messages where the value of the myField field is “XYZ” would look like the following: 

%properties/myField% == "XYZ"

Note that even though the properties field is a child of the JMSMessage document, the JMSMessage document does not need to appear in the filter expression.

The following filter matches those messages where the data document within the JMSMessage/body document contains a field named myField whose value is “A”: 

%body/data/myField% == "A"
Note: When receiving a batch of messages, Integration Server evaluates the local filter against the first message in the batch only. Integration Server does not apply the filter to subsequent messages in the batch. For more information about batch processing, see About Batch Processing for Standard JMS Triggers.