Defining Event Rules

Article
12/03/2008

If your application supports event-driven subscriptions, you must define at least one event rule.

Event rules are named sets of one or more Transact-SQL queries that create notifications for event-driven subscriptions. Optionally, event rules can manipulate the data in event chronicles. Event rules are processed for each event batch soon after the event batch arrives.

Note

The exact timing for firing event rules depends on the quantum duration and how the application processes events. For more information, see Specifying the Generator Quantum Duration and Specifying the Event Processing Order.

Each subscription class can contain one or more event rules. However, you cannot specify rule firing order. Event rules can fire in any order.

Event Rule Processing

Notification Services uses the following process to generate notifications from event rules:

Events arrive.
Notification Services creates one event batch per event class, and then adds each event batch to its respective event table.
Notification Services runs any chronicle rules for the event class, which maintains event chronicle tables.
If the chronicle rule fails, processing stops and the event batch is marked as failed. Event rules will not run because they depend on successful event batch processing.
Notification Services then fires event rules, which join event data with subscription data to generate notifications. Event rules operate against a view that lists only the current events for the event class and a subscription view that lists only enabled subscriptions. Event rules can also use event chronicle data.
The event rules add the resulting notifications to notification tables. This data is used to build and distribute notifications.

Because notifications are generated soon after events arrive, event rules are good for randomly occurring events and time-sensitive data. Auction update subscriptions and breaking news alerts are examples of applications that should use event rules.

Defining an Event Rule

An event rule is part of a subscription class. When you define a subscription class, you must define at least one rule, either event or scheduled. To define an event rule, you create an event rule item. You then provide a name, an action to perform, and the name of the linked event class. You also can provide a time-out value for the event rule action.

To define an event rule

If you are defining an application through XML, define event rules using the EventRule Element (ADF).
If you are defining event rules programmatically, create individual SubscriptionEventRule objects and add them to a subscription class using the SubscriptionEventRules property.
If you are defining event rules with condition actions programmatically, create individual SubscriptionConditionEventRule objects and add them to a subscription class using the SubscriptionConditionEventRules property.

Naming an Event Rule

Each event rule must have name that is unique within the application. This name is used to identify each rule for administrative purposes.

To name an event rule

If you are defining an event rule through XML, define the event rule name using the RuleName Element for EventRule (ADF).
If you are defining an event rule programmatically, define the event rule name in the SubscriptionEventRule class (NMO).
If you are defining an event rule with a condition action programmatically, define the event rule name using the SubscriptionConditionEventRule class (NMO).

Defining an Action or Condition Action

An action is the query that Notification Services runs each time it fires the rule. Event rules can contain simple actions and more complex condition actions:

An action contains a Transact-SQL query used to generate notifications based on matches between subscription fields and event fields. When subscribers create subscriptions, they define parameters for the predefined query. For information about defining simple actions, see Defining Actions.
A condition action also has a Transact-SQL query, but this query defines a view from which subscribers can define their subscriptions. Instead of providing parameters for a predefined query, subscribers select the fields they are interested in and then define their own conditions using a predetermined set of operators. For information about defining condition actions, see Defining Condition Actions.

Specifying a Time-out Value

The action time-out specifies the permitted length of time for statements in the action or condition action to complete. If the statements do not complete before the time-out occurs, Notification Services rolls back the transaction, marks the event rule as failed, and writes an error to the event log.

To specify a timeout value

If you are defining an event rule through XML, define the time-out value using the ActionTimeout Element for EventRule (ADF).
If you are defining an event rule programmatically, define the time-out value using the Microsoft.SqlServer.Management.Nmo.SubscriptionEventRule.ActionTimeout property (NMO).
If you are defining an event rule with a condition action programmatically, define the time-out value using the Microsoft.SqlServer.Management.Nmo.SubscriptionConditionEventRule.ActionTimeout property (NMO).

Linking the Rule to an Event Class

Each event rule must be associated with a single event class. Notification Services fires the event rule only after processing event batches from the specified event class.

To link the rule to an event class

If you are defining an event rule through XML, specify the event class name using the EventClassName Element for EventRule (ADF).
If you are defining an event rule programmatically, define the event class name using the Microsoft.SqlServer.Management.Nmo.SubscriptionEventRule.EventClassName property (NMO).
If you are defining an event rule with a condition action programmatically, define the event class name using the Microsoft.SqlServer.Management.Nmo.SubscriptionConditionEventRule.EventClassName property (NMO).

Share via