Integration Server 10.3 | Built-In Services Reference Guide | Trigger Folder | Summary of Elements in this Folder | pub.trigger:createJMSTrigger
 
pub.trigger:createJMSTrigger
WmPublic. Creates a JMS trigger.
Input Parameters
triggerName
String Fully qualified name for the JMS new trigger. Names use any combination of letters, and/or the underscore character. Make sure to specify the name of the folder and subfolder in which you want to save the JMS trigger.
Note:
For a list of reserved words and symbols for element names, see webMethods Service Development Help.
package
String Name of the package in which you want to save the trigger.
aliasName
String Name of the JMS connection alias that you want this JMS trigger to use to receive messages from the JMS provider.
The JMS connection alias must already exist at the time this service executes. 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.
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.
jmsTriggerType
String Type of JMS trigger. Specify:
*Standard to create a standard JMS trigger. This is the default.
*SOAPJMS to create a SOAP-JMS trigger.
properties
Document Optional. Properties that you want to assign to the JMS trigger.
Key
Description
enabled
String Flag indicating whether the new JMS trigger is enabled or disabled. Set to:
*true to create the JMS trigger in an enabled state.
*false to create the JMS trigger in a disabled state. This is the default.
joinTimeout
String Optional. Number of milliseconds Integration Server waits for additional messages to fulfill the join. Integration Server starts the join time-out period when it receives the first message that satisfies the join.
Set joinTimeout to -1 to indicate that the join condition never expires.
The default is one day (86400000 milliseconds).
You need to specify a joinTimeout only when the joinType is AND or XOR. You do not need to specify a join time-out for an OR join.
Note:
You can specify a joinTimeout for a standard JMS trigger only. SOAP-JMS triggers cannot have joins.
joinType
String Specifies the join type for this standard JMS trigger. The join type indicates whether Integration Server needs to receive messages from all, any, or only one of destinations to execute the trigger service.
You only need to set joinType if the JMS trigger receives messages from multiple destinations.
Note:
You can specify a joinType for a standard JMS trigger only. SOAP-JMS triggers can receive messages from one destination only and therefore cannot have joins.
Set to:
*N/A to indicate that this JMS trigger does not have a join. That is, the JMS trigger receives messages from one Destination only.
*AND to invoke the trigger service when the standard JMS trigger receives a message from every destination within the join time-out period. The messages must have the same activation.
For more information about activation IDs, see Using webMethods Integration Server to Build a Client for JMS.
*OR to invoke the trigger service when the standard JMS trigger receives a message from any of the specified destinations.
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).
*XOR 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.
maxRetryAttempts
String Optional. Maximum number of times Integration Server should re-execute the trigger service when the trigger service ends because of a transient error that causes an ISRuntimeException. The default is 0 attempts (indicating the trigger service does not retry)
Note:maxRetryAttempts applies to non-transacted JMS triggers only.
retryInterval
String Optional. Length of time Integration Server waits between retry attempts. The default is 10 seconds.
Note:retryInterval applies to non-transacted JMS triggers only.
onTransientError
String Flag indicating how Integration Server handles transient errors for the JMS trigger.
For a non-transacted JMS trigger, indicates how Integration Server handles a retry failure for a JMS trigger. A retry failure occurs when Integration Server reaches the maximum number of retry attempts and the trigger service still fails because of an ISRuntimeException.
For a transacted JMS trigger, indicates how Integration Server handles a transient error that occurs during service execution, resulting in the entire transaction being rolled back.
Specify one of the following:
*Throw Exception/ Recover Only
This is the default.
For a non-transacted JMS trigger, indicate that Integration Server throws a service exception when the last allowed retry attempt ends because of an ISRuntimeException.
For a transacted JMS trigger, indicate that Integration Server recovers the message back to the JMS provider. Integration Server receives the message again almost immediately.
*Suspend and Retry Later/ Suspend and Recover
For a non-transacted JMS trigger, indicate that Integration Server suspends the trigger when the last allowed retry attempt ends because of an ISRuntimeException. Integration Server retries the trigger service at a later time when the resources needed by the trigger service become available.
For a transacted JMS trigger, indicate that Integration Server suspends the JMS trigger and then recovers the message back to the JMS provider. Integration Server executes the trigger service at a later time when the resources needed by the trigger service become available.
Selecting Suspend and Retry Later/ Suspend and Recover also instructs Integration Server to suspend the trigger when a transient error occurs during trigger preprocessing. For more information about transient error handling during trigger preprocessing, see webMethods Service Development Help.
resumeTaskSvcName
String Optional. Fully qualified name of the service that Integration Server executes when one of the following occurs:
*The trigger service ends because of a retry failure and onTransientError is set to Suspend and Retry Later/Suspend and Recover.
*The trigger service is part of a transacted JMS trigger and onTransientError property is set to Suspend and Retry Later/Suspend and Recover.
*The document resolver service used for exactly-once processing (dupResolverSvcName) ends because of a run-time exception and the watt.server.trigger.preprocess.suspendAndRetryOnError is set to true.
isConcurrent
String Flag indicating whether the JMS trigger uses a concurrent processing mode or a serial processing mode. Set to:
*true to specify a concurrent processing mode. Integration Server processes multiple messages for this trigger at one time.
*false to specify a serial processing mode. Integration Server processes messages received by this trigger one after the other. This is the default.
suspendOnError
String Flag indicating whether Integration Server suspends the JMS trigger when an exception occurs during trigger service execution. Set to:
*true to suspend the trigger when a trigger service ends with a fatal error.
*false to not suspend the JMS trigger when a trigger service ends with a fatal error. This is the default.
maxExecutionThreads
String Optional. Maximum number of messages that Integration Server can process concurrently on each connection for this trigger. maxExecutionThreads must be greater than or equal to connectionCount.
The default is 1.
Note:
This setting applies to concurrent JMS triggers only.
Note:
If the JMS provider from which the JMS trigger retrieves messages does not support concurrent access by durable subscribers, set the value of maxExecutionThreads to 1.
maxBatchSize
String Optional. Maximum number of messages that the trigger service can receive at one time. If you do not want the trigger to perform batch processing, leave this property set to 1. The default is 1.
A transacted JMS trigger can be used for batch processing if the JMS connection alias used by the trigger connects to a JMS provider that supports the reuse of transacted JMS sessions. If the JMS provider does not support the reuse of transacted JMS sessions, set maxBatchSize to 1. Consult the documentation for your JMS provider to determine whether or not the JMS provider supports the reuse of transacted JMS sessions. Note that webMethods Broker version 8.2 and higher and Software AG Universal Messaging version 9.5 support the reuse of transacted JMS sessions.
Note:
For a SOAP-JMS trigger the maxBatchSize must be set to 1.
dupDetection
String Flag indicating whether exactly-once processing is enabled for the JMS trigger. Set to:
*true to specify that exactly-once processing is provided for messages received by this trigger.
*false to specify that exactly-once processing is not provided for messages received by this trigger. This is the default.
dupHistory
String Flag indicating whether a document history database will be maintained and used to determine whether a message is a duplicate. Set to:
*true to indicate that Integration Server uses a document history database as part of exactly-once processing.
*false to indicate that Integration Server does not use a document history database as part of exactly-once processing. This is the default.
dupHistoryTTL
String Optional Number of milliseconds that the document history database maintains an entry for a document processed by this trigger.
The default is 2 hours (7200000 milliseconds).
dupResolverSvcName
String Optional. Specifies the service that you created to determine whether message's status is New, Duplicate, or In Doubt.
prefetchSize
String Optional. Specifies the maximum number of messages Integration Server attempts to retrieve for this JMS trigger when it requests more messages from the webMethods Broker.
The default is 10.
Note:
This parameter applies only when working with the webMethods Broker as a JMS provider.
acknowledgeMode
String Indicates how the JMS trigger acknowledges messages it receives to the JMS provider.
Note:acknowledgeMode applies to non-transacted JMS triggers only. When creating a transacted JMS trigger, Integration Server ignores acknowledgeMode. The JMS connection alias specified for aliasName determines whether or not the created trigger is transacted or non-transacted.
Set to:
*CLIENT_ACKNOWLEDGE to acknowledge or recover the message only after the JMS trigger processes the message completely. This is the default.
*AUTO_ACKNOWLEDGE to automatically acknowledge the message when it is received by the JMS trigger. The Integration Server will acknowledge the message before the trigger completes processing. The JMS provider cannot redeliver the message if Integration Server becomes unavailable before message processing completes.
*DUPS_OK_ACKNOWLEDGE to lazily acknowledge the delivery of messages. This may result in the delivery of duplicate messages.
executeUser
String Optional. Name of the user account whose credentials Integration Server uses to execute a service associated with the JMS trigger. You can specify a locally defined user account or a user account defined in a central or external directory. The default is Administrator.
connectionCount
String Optional. Specifies the number of connections a concurrent JMS trigger can use to retrieve messages from the JMS provider. connectionCount must be less than or equal to maxExecutionThreads. The default is 1.
Note:connectionCount applies only when the JMS connection alias specified for aliasName is configured to create a separate connection for each JMS trigger.
Note:
When using multiple connections to the webMethods Broker acting as the JMS provider, Integration Server uses a different client ID for each JMS trigger that uses the JMS connection alias. However, when Integration Server connects to other JMS providers, it uses the same client ID for each connection. Some JMS providers do not permit multiple connections to use the same client ID to retrieve messages from a Topic with a durable subscriber. Review the JMS provider documentation before configuring the use of multiple connections for a JMS connection alias and any concurrent JMS triggers that use the JMS connection alias.
destinations
Document List Destinations from which the JMS trigger receives messages.
Note:
For a SOAP-JMS trigger, you can specify one destination only.
Key
Description
destination
String Name or lookup name of the Destination from which you want the JMS trigger to receive messages.
Specify the lookup name of the Destination object when the JMS connection alias uses JNDI to retrieve administered objects. Specify the provider-specific name of the Destination when the JMS connection alias uses the native webMethods API to connect directly to the webMethods Broker.
destinationType
String Optional. Type of destination from which the JMS trigger receives messages. Set to:
*Queue to specify that the destination is a queue. This is the default.
*Topic to specify that the destination is a topic.
messageSelector
String Optional. Filter used to receive a subset of messages from the specified destination. A message selector allows a client to filter the messages it wants to receive by use of a SQL92 string expression in the message header. That expression is applied to properties in the message header (not to the message body content) containing the value to be filtered.
durableSubscriber Name
String Optional. Name of the durable subscriber that you want to create for this JMS trigger on the JMS provider. A durable subscriber creates a durable subscription on the JMS provider. A durable subscription allows the subscriber to receive all the messages published on a topic, including those published while the subscriber is inactive.
Note:durableSubscriberName applies when destinationType is set to Topic only.
durableSubscriber NoLocal
String Optional. Flag indicating whether the JMS trigger ignores messages sent by the same Integration Server on which the JMS trigger resides.
Set to:
*true to indicate that the JMS trigger ignores messages sent by the same Integration Server on which the JMS trigger resides.
*false to indicate that the JMS trigger receives and processes messages sent by the same Integration Server on which the JMS trigger resides. This is the default.
Note:durableSubscriberNoLocal applies when destinationType is set to Topic only.
Note:
If the JMS connection alias specified for this trigger has the Create New Connection per Trigger option enabled, then set durableSubscriberNoLocal to false. 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.
routingRules
Document List Optional. Routing rules for messages received by this standard JMS trigger.
Note:
You only need to specify routing rules for standard JMS triggers. SOAP-JMS triggers do not use routing rules.
Key
Description
ruleName
String Name for the routing rule.
serviceName
String Fully qualified name of the service Integration Server invokes when it receives a message from one of the specified destinations.
filter
String Optional. Filter that you want Integration Server to apply to messages the JMS trigger receives. A filter specifies criteria for the contents of the message body. Integration Server applies a local filter to message after the JMS trigger receives the message from the JMS provider.
Note:Integration Server evaluates the routing rules in the same order in which the rules appear in the routingRules document list. It is possible that a message could satisfy more than one routing rule. However, Integration Server executes only the service associated with the first satisfied routing rule and ignores the remaining routing rules. Therefore, the order in which you list routing rules is important.
Output Parameters
None.
Usage Notes
You can use pub.trigger:createJMSTriggers to create standard JMS triggers or SOAP-JMS triggers.
Even though WS endpoint triggers are SOAP-JMS triggers, you can create WS endpoint triggers via Integration Server Administrator only. For more information about WS endpoint triggers, see webMethods Integration Server Administrator’s Guide.
If you use a JNDI provider to store JMS administered objects, the Connection Factories and Destinations (queues and topics) that you want this JMS trigger to use to consume messages must already exist if the JMS provider is not . If they do not exist, the JMS trigger will be created but will not start. The JMS trigger will appear disabled in Designer and Integration Server Administrator. However, if the JMS provider is , 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 specified for the aliasName input parameter is configured to create administered objects on demand, Integration Server creates the destination the first time that JMS trigger starts. For more information about creating administered objects on demand, see webMethods Integration Server Administrator’s Guide
If you use the native webMethods API to connect directly to the webMethods Broker, the Destinations from which you want the JMS trigger to receive messages must exist on the Broker. However, if you intend to use a durable subscriber to receive messages, it can be created by Integration Server when the pub.trigger:createJMSTrigger executes successfully. For more information about creating Destinations on the Broker, see Administering webMethods Broker.
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 a standard 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.
A standard JMS trigger can contain multiple routing rules. Each routing rule must have a unique name.
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 (maxBatchSize input parameter value or Max batch messages property) greater than 1. A standard JMS trigger with an Any (Or) join can have multiple routing rules.
When you select Topic as the destinationType and specify a value for durableSubscriberName, Integration Server creates a a durable subscriber for the JMS trigger on the JMS provider. 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 nonvolatile storage. If a durable subscription already exists for the specified durable subscriber on the JMS provider, this service resumes the subscription.
When you select Topic as the destinationType, but do not specify a durable subscriber name, Integration Server creates a non-durable subscriber for the JMS trigger. A non-durable subscription allows subscribers to receive messages on their chosen topic only if the messages are published while the subscriber is inactive. A non-durable subscription lasts the lifetime of its message consumer. Note that non-durable subscribers cannot receive messages in a load-balanced fashion.
Integration Server uses a consumer to receive messages for a JMS trigger. This consumer encapsulates the actual javax.jms.MessageConsumer and javax.jms.Session.
Triggers and services can both be configured to retry. When a standard trigger invokes a service (that is, the service functions as a trigger service), Integration Server uses the trigger retry properties instead of the service retry properties. For a SOAP-JMS trigger, Integration Server uses the retry properties of the SOAP-JMS trigger instead of the retry properties of the service used as an operation in the web service descriptor.
When Integration Server retries a trigger service and the trigger service is configured to generate audit data on error, Integration Server adds an entry to the audit log for each failed retry attempt. Each of these entries will have a status of "Retried" and an error message of "Null". However, if Integration Server makes the maximum retry attempts and the trigger service still fails, the final audit log entry for the service will have a status of "Failed" and will display the actual error message. Integration Server makes the audit log entry regardless of which retry failure option the trigger uses.
Integration Server generates the following journal log message between retry attempts:
[ISS.0014.0031D] Service serviceName failed with ISRuntimeException.
Retry x of y will begin in retryInterval milliseconds.
If you do not configure service retry for a trigger, set the maxRetryAttempts to 0. Because managing service retries creates extra overhead, setting this property to 0 can improve the performance of services invoked by the trigger.
You can invoke the pub.flow:getRetryCount service within a trigger service to determine the current number of retry attempts made by Integration Server and the maximum number of retry attempts allowed for the trigger service. For more information about the pub.flow:getRetryCount service, see the webMethods Integration Server Built-In Services Reference.
Before a standard JMS trigger can be enabled, the trigger service must already exist on the same Integration Server.
The signature for a standard JMS trigger service must reference one of the following specifications:
*Use pub.jms:triggerSpec as the specification reference if the trigger service will process one message at a time.
*Use pub.jms:batchTriggerSpec as the specification reference if the trigger service will process multiple messages at one time. That is, the trigger service will receive a batch of messages as input and process all of those messages in a single execution. A trigger that receives and processes a batch of messages is sometimes referred to as a batch trigger.
If you create a concurrent JMS trigger that uses multiple connections to receive messages from the JMS provider, (you specified a value greater than 0 for connectionCount), keep the following points in mind:
*The JMS connection alias associated with this trigger must be configured to create an individual connection for each trigger. That is, the Create New Connection per Trigger option must be set to Yes for the JMS connection alias.
*If the JMS connection alias specifies a connection to the webMethods Broker, the following must be true:
*The webMethods Broker must be webMethods Broker version 7.1 or higher.
*The versions of following three Broker jar files installed on Integration Server must be the 8.0 SP1 or higher versions of the files.
* Software AG_directory /common/lib/wm-jmsclient.jar
* Software AG_directory /common/lib/wm-brokerclient.jar
* Software AG_directory / Integration Server_directory /instances/instance_name/lib/jars/wm- jmsnaming.jar
*The JMS trigger must be configured for concurrent processing (isConcurrent is set to true). You cannot use multiple connections with JMS triggers that perform serial processing.
*The JMS trigger must receive messages from Queues or from Topics using a durable subscriber. You cannot use multiple connections with JMS triggers that receive messages from Topics using a non-durable subscriber.
*The connectionCount value must be less than or equal to the maxExecutionThreads value.
SOAP-JMS triggers do not use routing rules. For SOAP-JMS triggers, Integration Server processes the SOAP message contained in the JMS message by executing an operation in a web service descriptor.
To use a SOAP-JMS trigger as a listener for provider web service descriptors, do the following:
*Create a provider web service endpoint alias for the JMS transport in which the SOAP-JMS trigger is specified as the JMS trigger that acts as a listener.
*Assign the web service endpoint alias to the JMS binder in the web service descriptor for which you want the SOAP-JMS trigger to listen for messages.
For more information about creating JMS triggers, see webMethods Service Development Help.
See Also
pub.trigger:deleteJMSTrigger
pub.jms:triggerSpec
pub.jms:batchTriggerSpec