Step 8: Synchronize the Publishable Document Types
7. Working with Triggers
Introduction . . . 110
Overview of Building a Trigger . . . 110
Creating a Trigger . . . 113
Setting Trigger Properties . . . 121
Modifying a Trigger . . . 142
Deleting Triggers . . . 143
Testing Triggers . . . 144
7 Working with Triggers
Introduction
Triggers establish subscriptions to publishable document types and specifies how to process instances of those publishable document types. When you build a trigger, you create one or more conditions. 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.
Overview of Building a Trigger
Building a trigger is a process that involves the following basic stages:
When you build a trigger, you use the upper half of the editor to create, delete, and order conditions. You use the lower half of the editor to create a condition by selecting the publishable document types to which you want the trigger to subscribe and the service you want the Integration Server to execute when it receives instances of those documents.
Note: With webMethods Developer, you can create Broker/local triggers and JMS triggers. A Broker/local trigger is trigger that subscribes to and processes documents published/delivered locally or to the Broker. A JMS trigger is a trigger that receives messages from a destination (queue or topic) on a JMS provider and then processes those messages. This guide discusses development and use of Broker/local triggers only. Where the terms “trigger” or “triggers” appear in this guide, they refer to Broker/local triggers.
Stage Description
1 Creating a new trigger on Integration Server. During this stage, you create the new trigger on the Integration Server where you will do your development and testing. For more information, see “Creating a Trigger” on page 113.
2 Creating one or more conditions for the trigger. During this stage, you associate publishable document types with services, create filters to apply to incoming documents, and select join types. For more information, see “Creating a Trigger” on page 113.
3 Setting trigger properties. During this stage, you set parameters that configure the run‐time environment of this trigger, such as trigger queue capacity, document processing mode, fatal and transient error handling, and exactly‐
once processing. For information about this stage, see “Setting Trigger Properties” on page 121.
4 Testing and debugging. During this stage you can use the tools provided by Developer to test and debug your trigger. For more information, see “Testing Triggers” on page 144.
7 Working with Triggers
The editor for building triggers
Service Requirements
The service that processes a document received by a trigger is called a trigger service. A condition specifies a single trigger service.
Before you can enable a trigger, the trigger service must already exist on the same Integration Server. Additionally, 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:PublishableDocumentTypeName
For example, suppose that you want a 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.
Use the upper half of the editor to create, delete, and order conditions.
Use the lower half of the editor to name the condition...
...and specify the service that should be invoked...
...when instances of this publishable document type are received.
7 Working with Triggers
Trigger service input signature must contain a document reference to the publishable document type
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.
You can configure the trigger service to generate audit data when it executes by setting Audit properties for the trigger service. If a trigger service generates audit data and includes a copy of the input pipeline in the audit log you can use webMethods Monitor to re‐invoke the trigger service at a later time. For information about creating services, declaring input and output signatures, and configuring service auditing, see the webMethods Developer User’s Guide.
Tip! You can insert a document reference into the input signature of the target service by dragging the publishable document type from the Navigation panel to the input side of the service’s Input/Output tab.
Tip! You can copy and paste the fully qualified document type name from the Navigation panel to the document reference field name. To copy the fully qualified name, right‐click the document type in the Navigation panel, and select Copy. To paste the fully qualified name in for the field name, right‐click the document reference field, select Rename, and press CTRL + V.
... this publishable document type.
The input signature of this service declares a document reference to...
The name for this document reference must be the fully qualified name of the publishable document type.
7 Working with Triggers
Trigger Validation
When you save a trigger, the Integration Server evaluates the trigger and specifically, the conditions in the trigger, to make sure the trigger is valid. If the Integration Server determines that the trigger or a condition in the trigger is not valid, Developer displays an error message and prompts you to cancel the save or continue the save with a disabled trigger. The Integration Server considers a trigger to be valid when each of the following is true:
The trigger contains at least one condition.
Each condition in the trigger specifies a unique name.
Each condition in the trigger specifies a service.
Each condition in the trigger specifies one or more publishable document types.
If multiple conditions in the trigger specify the same publishable document type, the filter applied to the publishable document type must be the same in each condition.
For more information about creating filters, see “Creating a Filter for a Document” on page 116.
The syntax of a filter applied to a publishable document type is correct.
The trigger contains no more than one join condition.
Creating a Trigger
A trigger defines a subscription to one or more publishable document types. In a trigger, the conditions that you create associate one or more publishable document types with a service.
When you create a trigger, keep the following points in mind:
The publishable document types and services that you want to use in conditions must already exist. For more information about requirements for services used in triggers, see “Service Requirements” on page 111.
A trigger can subscribe to publishable document types only . A trigger cannot subscribe to ordinary IS document types . For information about making IS document types publishable, see “Making an Existing IS Document Type Publishable” on page 57.
Tip! You can insert a document reference into the input signature of the target service by dragging the publishable document type from the Navigation panel to the input side of the service’s Input/Output tab.
7 Working with Triggers
Multiple triggers (and multiple conditions within a trigger) can reference the same publishable document type. At run time, for each trigger, the Integration Server invokes the service specified for the first condition that matches the publishable document type criteria.
A trigger can contain only one join condition (a condition that associates more than one publishable document types with a service). A trigger can contain multiple simple conditions (a condition that associates one publishable document type with a service).
Each condition in a trigger must have a unique name.
You can save only valid triggers. For more information about requirements for a valid trigger, see “Trigger Validation” on page 113.
1 On the File menu, click New.
2 In the New dialog box, select Trigger, and click Next.
3 In the New Trigger dialog box, do the following:
a In the list next to Folder, select the folder in which you want to save the trigger.
b In the Name field, type a name for the trigger using any combination of letters, and/or the underscore character. For a list of reserved words and symbols, see
“Naming Rules for webMethods Developer Elements” on page 210.
c Click Next.
4 In the newTriggerName dialog box, select Broker/Local trigger.
5 Click Finish.
Developer generates the new trigger and displays it in the Developer window.
Developer automatically adds an empty condition named “Condition1” to the trigger.
6 In the editor, use the following procedure to build a condition.
a In the Name field, type the name you want to assign to the condition. Developer automatically assigns each condition a default name such as Condition1 or Condition2. You can keep this name or change it to a more descriptive one. You must specify a unique name for each condition within a trigger.
b In the Service field, enter the fully qualified service name that you want to associate with the publishable document types in the condition. You can type in the service name, or click to select the service from the Select dialog box.
Important! When you create triggers, work on a stand‐alone Integration Server instead of an Integration Server in a cluster. Creating, modifying, disabling, and enabling triggers on an Integration Server in a cluster can create inconsistencies in the corresponding trigger client queues on the Broker.
To create a trigger
7 Working with Triggers
c Under Document types and filters, click . Developer displays the Select one or more publishable document types dialog box.
d In the Select one or more publishable document types dialog box, select the publishable document types to which you want to subscribe. You can select more than one publishable document type by using the CTRL or SHIFT keys.
Developer creates a row for each selected publishable document type in the table under Document types and filters.
e In the Filter column next to each publishable document type, enter a filter that you want the Integration Server to apply to each instance of this publishable
document type. The Integration Server executes the trigger service only if instances of the document type meet the filter criteria. Filters are optional for a trigger condition. For more information about filters, see “Creating a Filter for a Document” on page 116.
f If you specified more than one publishable document type in the condition, select a join type.
For more information about join types and join conditions, see Chapter 9, Note: An XSLT service cannot be used as a trigger service.
Tip! Click the next to the Filter column to view and edit the filter in a larger text editor.
Join Type Description
All (AND) The Integration Server invokes the trigger service when the server receives an instance of each specified publishable document type within the join time‐out period. The instance documents must have the same activation ID. This is the default join type.
For more information about activation IDs, see “About the Activation ID” on page 91.
Any (OR) The Integration Server invokes the trigger service when it receives an instance of any one of the specified publishable document types.
Only one (XOR) The Integration Server invokes the trigger service when it receives an instance of any of the specified document types.
For the duration of the join time‐out period, the Integration Server discards any instances of the specified publishable document types with the same activation ID.
7 Working with Triggers
7 In the Properties panel, specify the join time‐out period, trigger queue capacity, document processing mode, and document delivery attempts in case of error. For more information about trigger properties, see “Setting Trigger Properties” on page 121.
8 In the Properties panel, under Permissions, specify the ACLs you want to apply to the trigger, if any. See the webMethods Developer User’s Guide for instructions for this task.
9 On the File menu, click Save to save the trigger.
Notes:
Integration Server validates the trigger before saving it. If Integration Server
determines that the trigger is invalid, Developer prompts you to save the trigger in a disabled state. For more information about valid triggers, see “Trigger Validation” on page 113.
Integration Server establishes the subscription locally by creating a trigger queue for the trigger. The trigger queue is located in the trigger document store. Documents retrieved by the server remain in the trigger queue until they are processed.
If you are connected to the Broker, 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 publishable document type specified in the trigger conditions and saves the subscriptions with the trigger client.
If you are not connected to a Broker when you save the trigger, the trigger will only receive documents published locally. When you reconnect to a Broker, the next time Integration Server restarts, the 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. The Broker validates the filters in the trigger conditions when Integration Server creates the subscriptions.
If a publishable document type specified in a trigger condition does not exist on the Broker (that is, there is no associated Broker document type), Integration Server still creates the trigger client on the Broker, but does not create any subscriptions. The Integration Server creates the subscriptions when you synchronize (push) the publishable document type with the Broker.
You can also use the pub.trigger:createTrigger service to create a trigger. For more information about this service, see the webMethods Integration Server Built‐In Services Reference.
Creating a Filter for a Document
You can further refine a condition by creating filters for the publishable document types.
A filter specifies criteria for the contents of a published document. For example, suppose that the document EmployeeInformation contains a person’s age and state of residence. The first field in the document is an integer named age and the second field is a String named
7 Working with Triggers
state. The following filter will match only those documents where the value of age is greater than 65 and the value of state is equal to FL.
%age% > 65 and %state% L_EQUALS "FL"
Both the Broker and Integration Server evaluate a document against a subscription’s filter
No condition matches in trigger triggerName for document documentTypeName with activation activationID.
Filters can be saved with the subscription on the Broker and with the trigger on the Integration Server. The location of the filter depends on the filter’s syntax, which is evaluated at design time. For more information about filter evaluation at design time and run time, see “Filter Evaluation at Design Time” below.
Filter Evaluation at Design Time
When you save a trigger, Integration Server and the Broker evaluate the filter. Integration
Note: The Broker saves as much of a filter as possible with the subscription. For example, suppose that a filter consists of more than one expression, and only one of the expressions contains syntax the Broker considers invalid. The Broker saves the expressions it considers valid with the subscription on the Broker. (The Integration Server saves all the expressions.)
7 Working with Triggers
For more information about naming conventions and restrictions for Broker elements, see
“Naming Rules for webMethods Broker Document Fields” on page 210. For more information about filter syntax and the Broker, see “Conditional Expressions” appendix in the webMethods Developer User’s Guide.
Filters and Performance
When a filter is saved only on Integration Server and not on the Broker, the performance of Integration Server can be affected. When the Broker applies the filter to incoming documents, it discards documents that do not meet filter criteria. The Broker never places the document in the subscriber’s queue. The Integration Server only receives documents that meet the filter criteria.
If the subscription filter resides only on the Integration Server, the Broker automatically places the document in the subscriber’s queue. The Broker does not evaluate the filter for the document. The Broker routes all of documents to the subscriber, creating greater network traffic between the Broker and the Integration Server and requiring more processing by the Integration Server.
You can use the Broker Administrator to view the filters saved with a subscription. For more details about syntax that prevents filters from being saved on the Broker, see
“Conditional Expressions” appendix in the webMethods Developer User’s Guide.
Creating a Filter for a Publishable Document Type
The following procedure describes how to create a filter for a publishable document type in a trigger condition.
1 In the Navigation panel of Developer, open the trigger.
2 In the top half of the editor, select the condition containing the publishable document type to which you want to apply the filter.
3 In the lower half of the editor, next to the publishable document type for which you want to create a filter, enter the filter in the Filter field.
The Integration Server provides syntax and operators that you can use to create expressions for use with filters. For more information, see the “Conditional Expressions” appendix in the webMethods Developer User’s Guide.
4 On the File menu, click Save to save your changes to the trigger. The Integration Server and Broker save the filter with the subscription.
Tip! You can use the Broker Administrator to view the filters saved with a subscription.
T
To specify a filter for a publishable document type in a trigger condition
7 Working with Triggers
Notes:
If the Integration Server is not connected to a Broker when you save the trigger, the Broker evaluates the filter the next time you enable and save the trigger after the connection is re‐established or when you synchronize the document types specified in the trigger.
If you need to specify nested fields in the filter, you can copy a path to the Filter field from the document type. Select the field in the document type, right click and select Copy. You can then paste into the Filter field. However, you must add % as a preface and suffix to the copied path.
If multiple conditions in the trigger specify the same publishable document type, the filter applied to the publishable document type must be the same in the conditions. If the filters are not the same, the Developer displays an error message when you try to save the trigger.
Using Multiple Conditions in a Trigger
You can build triggers that can contain more than one condition. Each condition can associate one or more documents with a service. You can use the same service or different services for each condition. You can create only one join condition in a trigger, but a trigger can contain any number of simple conditions.
When a trigger receives a document, the Integration Server determines which service to invoke by evaluating the trigger conditions. The Integration Server evaluates the trigger
When a trigger receives a document, the Integration Server determines which service to invoke by evaluating the trigger conditions. The Integration Server evaluates the trigger