pub.trigger:createTrigger
WmPublic. Creates a webMethods messaging trigger.
Input Parameters
triggerName | String Fully qualified name for the new trigger that uses 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 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. |
properties | Document Optional. Properties that you want to assign to the trigger. |
| Key | Description |
| joinTimeOut | String Number of milliseconds Integration Server waits for the other documents in the join condition. Integration Server starts the join time-out period when it pulls the first document that satisfies the join condition from the trigger queue. You need to specify a join time-out only when your condition is an AND or XOR join type. You do not need to specify a join time-out for an OR join condition or a condition that does not use joins. Set joinTimeOut to -1 to indicate that the join condition never expires. The default is 1 day. |
| queueCapacity | String Maximum number of documents that Integration Server maintains in the queue for this trigger. The default is 10. |
| queueRefillLevel | String Number of unprocessed documents that must remain in the trigger queue before Integration Server retrieves more documents for the trigger from the Broker. The default is 4. The queueRefillLevel value must be less than or equal to the queueCapacity value. Note: | The queueRefillLevel parameter applies to a webMethods messaging trigger that receives documents from the Broker only. At run time, Integration Server ignores the queueRefillLevel if the trigger receives documents from Universal Messaging. |
|
| ackQueueSize | String Maximum number of pending document acknowledgments for the trigger. The value must be greater than zero. The default is 1. |
| maxRetryAttempts | String Maximum number of times Integration Server should attempt to re-execute the trigger service. If you want the trigger service to retry until it executes successfully, specify -1. The default is 5 retries. |
| retryInterval | String Number of seconds Integration Server waits between retry attempts. The default is 10 seconds. |
| onRedeliveryFailure | String Specifies how Integration Server handles retry failure for the trigger. Retry failure occurs when Integration Server reaches the maximum number of retry attempts and the trigger service still fails because of a run-time exception. Specify one of the following values:  Throw Exception to indicate that Integration Server throws a service exception when the last allowed retry attempt ends because of a run-time exception. This is the default. Suspend and Retry Later to indicate that Integration Server suspends the trigger when the last allowed retry attempt ends because of a run-time exception. Integration Server retries the trigger service at a later time. Note: | If you set onRedeliveryFailure to Suspend and Retry later, you must specify a service for the resumeTaskSvcName parameter. If you do not specify a service and the trigger suspends because of retry failure, Integration Server will not resume the trigger automatically. You must resume the trigger manually. |
Selecting Suspend and Retry Later 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 Fully qualified name of the service that Integration Server executes when one of the following occurs: During exactly-once processing, the document resolver service ends because of a transient error. Integration Server suspends the trigger and invokes the resumeTaskSvcName to determine when the resources associated with the document resolver service are available. After the resources become available, Integration Server resumes document retrieval and document processing for the trigger. A trigger ends because of retry failure and the onRedeliveryFailure variable is set to Suspend and Retry Later. Integration Server executes the resumeTaskSvcName to determine whether the resources associated with a trigger service are available. If the resources are available, Integration Server resumes document retrieval and document processing for the trigger. |
| isPriorityEnabled | Boolean Indicates whether the trigger receives messages in order of priority or in the order in which they are published. Specify one of the following values: true to indicate that documents should reach the trigger in order of priority. The higher the priority the faster the document will be received. false to indicate that documents should reach the trigger in the order in which they are published. This is the default. Note: | The isPriorityEnabled parameter applies to a webMethods messaging trigger that receives documents from the Broker only. At run time, Integration Server ignores the isPriorityEnabled value if the trigger receives a locally published documents or receives documents from Universal Messaging. |
All webMethods messaging triggers that receive documents from Universal Messaging receive higher priority documents in an expedited fashion. |
| isConcurrent | String Indicates whether the trigger uses a concurrent processing mode or a serial processing mode. Specify one of the following values: true to specify a concurrent processing mode. Integration Server processes as many documents in the trigger queue as it can at once. false to specify a serial processing mode. Integration Server processes documents in the trigger queue one after the other. This is the default. |
| serialSuspendOnError | String Indicates whether Integration Server suspends document processing and document retrieval automatically when a trigger service ends with an error. Set to: true to indicate that Integration Server suspends the trigger automatically if an error occurs during trigger service execution. false to indicate that Integration Server should not suspend a trigger if an error occurs during trigger service execution. This is the default. |
| maxExecutionThreads | String Maximum number of documents that Integration Server can process concurrently for this trigger. Integration Server uses one server thread to process each document in the trigger queue. |
| dupDetection | String Indicates whether Integration Server performs exactly-once processing for guaranteed documents received by this trigger. Set to: true to indicate that Integration Server performs exactly-once processing for guaranteed documents received by this trigger. false to indicate that exactly-once processing is not performed. This is the default. |
| dupHistory | String Indicates whether Integration Server uses a document history database as part of performing exactly-once processing. 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 Number of milliseconds that the document history database maintains an entry for a document processed by this trigger. The default is 2 hours. |
| dupResolverSvcName | String Fully qualified name of the service used to determine conclusively whether a document's status is New, Duplicate, or In Doubt. |
| executeUser | String Optional. Name of the user account whose credentials Integration Server uses to execute a service associated with the trigger. You can specify a locally defined user account or a user account defined in a central or external directory. The default is Administrator. Note: | The executeUser parameter applies to webMethods messaging triggers that receive message from Universal Messaging only. At run time, Integration Server ignores the executeUser value if the trigger receives documents from the Broker or locally published documents. To set the execution user for webMethods messaging triggers that receive documents from Broker or locally published documents, use Integration Server Administrator to set the User property on the Settings > Resources > Store Settings > Edit Document Store Settings screen. |
|
conditions | Document List Optional. Specifies the conditions for the trigger. A condition associates one or more publishable document types with a single service. The publishable document type acts as the subscription piece of the trigger. The service is the processing piece. When the trigger receives documents to which it subscribes, the Integration Server processes the document by invoking the service specified in the condition. Triggers can contain multiple conditions; however, a trigger can contain only one join condition. Note: | The order in which you list conditions in the conditions list is important because it indicates the order in which Integration Server evaluates the conditions at run time. When Integration Server receives a document, it invokes the service specified in the first condition that is satisfied by the document. The remaining conditions are ignored. For more information about the order in which conditions are evaluated, see the Publish-Subscribe Developer’s Guide. |
|
| Key | Description |
| conditionName | String Name you want to assign to the condition. By default, Integration Server assigns each condition a default name such as Condition1 or Condition2. |
| serviceName | String Fully qualified name of the service that to be invoked when the trigger receives documents or messages to which it subscribes. |
| joinType | String The join type for the condition. The join type determines whether Integration Server needs to receive all, any, or only one of the documents or messages in the condition to execute the trigger service. You must specify a joinType if the condition subscribes to more than one document type or message. That is, if messageTypeFilterPairs contains more than one pair, you must select a joinType. Specify one of the following: N/A to indicate this is not a join condition. AND to indicate that Integration Server invokes the trigger service when the server receives an instance of each specified message type within the join time-out period. The instance documents must have the same activation ID. This is the default join type. OR to indicate that Integration Server invokes the associated trigger service when it receives an instance of any one of the specified publishable document types. XOR to indicate that Integration Server invokes the associated trigger service when it receives an instance of any of the specified document types. For the duration of the join time-out period, Integration Server discards (blocks) any instances of the specified publishable document types with the same activation ID. |
| messageTypeFilterPairs | Document List Specifies the messages and document types to which a trigger subscribes and the filter that must be applied to instances of the message or document type |
| | Key | Description |
| | messageType | String Fully qualified name of the publishable document type or message to which the trigger subscribes. |
| | filter | String Optional. Filter that you want applied to each received document. The trigger processes only those documents that meet the filter criteria. If the publishable document type uses Broker as the messaging provider, specify a filter that you want Integration Server and/or Broker to apply to each instance of this publishable document type. If the publishable document type uses Universal Messaging as the messaging provider, specify the local filter that you want Integration Server to apply to each instance of the publishable document type received by the trigger. |
| | providerFilter | String Optional. Filter that you want Universal Messaging to apply to each instance of the publishable document type. Universal Messaging enqueues the document for the trigger only if the filter criteria is met. Note: | At run time, Integration Server ignores the providerFilter if the trigger receives documents from Broker or locally published documents. |
|
| Note: | If you specify multiple messageType values in one condition, you need to select a joinType. |
|
Output Parameters
None.
Usage Notes
The client executing this service must have write access to the folders and packages in which the client wants to save the new webMethods messaging trigger. If the client does not have write access, Integration Server throws a write permissions error. For more information about assigning access permissions to folders and packages, see webMethods Service Development Help.
The messaging connection alias assigned to the publishable document type determines the messaging provider used by any triggers that subscribe to the publishable document type.
Integration Server validates the webMethods messaging trigger before saving it. If Integration Server determines that the webMethods messaging trigger does not meet the following requirements, Integration Server throws a ServiceException and does not create the trigger.
The
webMethods messaging trigger contains at least one condition.
Each condition in the
webMethods messaging trigger specifies a unique name.
Each condition in the
webMethods messaging trigger specifies a service.
Each condition in the
webMethods messaging trigger specifies at least one publishable document type.
If more than one condition in the
webMethods messaging trigger specifies the same publishable document type and the trigger receives messages from the
Broker, the contents of
conditions/messageTypeFilterPairs/filter must be the same for each condition.
Software AG does not recommend using the same publishable document type in more than one condition in the same trigger.
If more than one condition in the
webMethods messaging trigger specifies the same publishable document type and the trigger receives messages from
Universal Messaging, the contents of
conditions/messageTypeFilterPairs/providerFilter must be the same for each condition. The contents of
conditions/messageTypeFilterPairs/filter can be different for each condition.
The
webMethods messaging trigger contains no more than one join condition.
The
webMethods messaging trigger receives messages using the same messaging connection alias. That is, the publishable document types to which the trigger subscribes must all specify the same messaging connection alias. For the publishable document types to which the trigger subscribes, the value of the
Connection alias name property can be:
The name of a specific messaging connection alias.
DEFAULT where the default messaging connection alias is the same as the alias specified for the other publishable document types to which the trigger subscribes.
The syntax of a filter in
conditions/messageTypeFilterPairs/filter must be correct. Create this filter using the conditional expression syntax described in
webMethods Service Development Help.
Integration Server validates the filter syntax when the
pub.trigger:createTrigger service executes.
Note: | Integration Server does not validate the syntax of the filter in conditions/messageTypeFilterPairs/providerFilter. |
A trigger service for a webMethods messaging trigger must meet the following requirements:
Before you can enable a
webMethods messaging trigger, the trigger service must already exist on the same
Integration Server.
The input signature for the trigger service needs to have a document reference to the publishable document type.
The name for this document reference must be the fully qualified name of the publishable document type. The fully qualified name of a publishable document type conforms to the following format:
folder.subfolder:PublishableDocumentTypeNameFor example, suppose that you want a webMethods messaging trigger to associate the Customers:customerInfo publishable document type with the Customers:addToCustomerStore service. On the Input/Output tab of the service, the input signature must contain a document reference named Customers:customerInfo.
If you intend to use the service in a join condition (a condition that associates multiple publishable document types with a service), the service’s input signature must have a document reference for each publishable document type. The names of these document reference fields must be the fully qualified names of the publishable document type they reference.
If the pub.trigger:createTrigger service executes successfully, Integration Server establishes the subscription locally by creating a trigger queue for the webMethods messaging trigger on the Integration Server.
If the trigger subscribes to one or more publishable document types that specify a Broker connection alias, one of the following occurs when the pub.trigger:createTrigger service executes:
If the
Broker connection alias is enabled,
Integration Server registers the trigger subscription with the
Broker by creating a client for the trigger on the
Broker.
Integration Server also creates a subscription for each
messageType specified in the trigger conditions and saves the subscriptions with the trigger client.
Broker validates the filters in the
webMethods messaging trigger conditions when
Integration Server creates the subscriptions.
If the
Broker connection alias is not enabled, the trigger will only receive documents published locally. When
Integration Server reconnects to
Broker, the next time
Integration Server restarts,
Integration Server will create a client for the trigger on the
Broker and create subscriptions for the publishable document types identified in the trigger conditions.
Broker validates the filters in the trigger conditions when
Integration Server creates the subscriptions.
If the trigger subscribes to a publishable document type that uses Universal Messaging as the messaging provider, one of the following happens upon saving the trigger.
If
Integration Server is currently connected to
Universal Messaging,
Integration Server creates a named object on the channel that corresponds to the publishable document type.
If
Integration Server is not currently connected to
Universal Messaging, you need to synchronize the publishable document type with the provider when the connection becomes available. Synchronizing the document type will create the named object on the channel that corresponds to the publishable document type.
If messageType specifies a publishable document type that does not exist on the Broker (that is, there is no associated Broker document type), Integration Server still creates the trigger and the trigger client on the Broker, but does not create any subscriptions on the Broker. Integration Server creates the subscriptions when you synchronize (push) the publishable document type with the Broker.
If messageType specifies a publishable document type that does not have a corresponding provider definition (channel) on Universal Messaging, Integration Server creates the trigger. On the Settings > Messaging > webMethods Messaging Trigger Management page, Integration Server Administrator displays an error that indicates the channel does not exist beneath the trigger name.
If a webMethods messaging trigger subscribes to a publishable document type that is not in the same package as the trigger or uses a triggers service that is not in the same package as the trigger, create package dependencies on the package containing the publishable document type and/or trigger service from the package containing the trigger. This ensures that Integration Server loads the package containing the publishable document type before loading the trigger.
If a webMethods messaging trigger subscribes to publishable document types associated with a Universal Messaging connection alias, you can create the following types of filters:
A provider filter that
Universal Messaging applies to the documents that it receives.
Universal Messaging saves the filter along with the subscription to the document type. When
Universal Messaging receives an instance of the publishable document type,
Universal Messaging applies the filter to the document and enqueues the document for the trigger only if the filter criteria is met. Use the
conditions/messageTypeFilterPairs/providerFilter field to specify a provider filter. For information about the syntax for provider filters for
Universal Messaging, see the
Universal Messaging documentation.
Note: | The scope of the provider filter depends on the encoding type for the publishable document type. When IData is the encoding type, Universal Messaging applies the filter to the custom header fields added to a published document via the _properties field. When protocol buffers is the encoding type, Universal Messaging applies the filter to the body of the document only. Because Integration Server includes the headers in the body of the published document as well as in the document header, you can still filter on the document headers when the encoding type is protocol buffers. |
A local filter that
Integration Server applies to the published document header or document contents after the trigger receives the document. Use the
conditions/messageTypeFilterPairs/filter to specify a local filter. Create the local filter using the conditional expression syntax described in
webMethods Service Development Help.
When the encoding type for a publishable document type is IData, it is optional to include _properties in the provider filter for a webMethods messaging trigger. However, when the encoding type is protocol buffers, you need to include _properties in the provider filter. If you want a provider filter that operates on the contents of _properties to work regardless of the encoding type, always include _properties in the filter expression.
If a webMethods messaging trigger subscribes to publishable document types associated with a Broker connection alias, you can specify a single filter that can be used by Broker and/or Integration Server. Use the conditions/messageTypeFilterPairs/filter to specify the filter. Create the filter using the conditional expression syntax described in webMethods Service Development Help.
For more information about creating webMethods messaging triggers, see webMethods Service Development Help.
See Also
