The <activationByGroupingKey> element contains elements that specify the events that can activate and deactivate a rule instance that is defined by the <groupingKey> element. Because the <groupingKey> element is not valid for the filter and timer rules, the <activationByGroupingKey> element does not apply to these rules.
The function that is provided by the <activationByGroupingKey> element is for use in rules where you define a grouping key. It allows you to control the activation and deactivation of rule instances based on the grouping key. When you code the <activationByGroupingKey> element, each rule instance can be individually activated and deactivated based on the <activateOnEvent> and <deactivateOnEvent> conditions within <activationByGroupingKey>.
The following example illustrates the use of the <activationByGroupingKey> element within a computation rule.
<computationRule name="StockReporter"> <variable dataType="java.lang.Integer" name="totalSharesTraded"> <varInitializer expressionLanguage="java"> return new Integer(0); </varInitializer> </variable> <activationInterval> <activationTime> <start> <inactiveWhenLoaded/> </start> </activationTime> <activationByGroupingKey> <activateOnEvent> <eventType type="StartReporting"/> </activateOnEvent> </activationByGroupingKey> </activationInterval> <eventSelector> <eventType type="StockSharesTraded"/> </eventSelector> <groupingKey> <attributeName>stockSymbol</attributeName> </groupingKey> <computeFunction assignTo="totalSharesTraded" expressionLanguage="java"> return new Integer(act_lib.getIntVariable("totalSharesTraded") + act_event.getIntAttribute("sharesTraded")); </computeFunction> <timeWindow> <timeInterval unit="ISO-8601" duration="PT10M"/> </timeWindow> <onTimeWindowComplete> <action expressionLanguage="java"> StockReport.createReport(act_eventList.get(0).getStringAttribute("stockSymbol"), act_lib.getIntVariable("totalSharesTraded")); </action> </onTimeWindowComplete> </computationRule>
<activationByGroupingKey> has no attributes.
<activationByGroupingKey> contains the following elements.
The elements must be coded in the order that is shown. If an element is optional, it does not need to be coded, but all elements that are coded must follow the correct order.
Element | Required or optional? |
---|---|
<activateOnEvent> | Optional. 0 or 1 occurrence is allowed. |
<deactivateOnEvent> | Optional. 0 or 1 occurrence is allowed. |
Rule behavior can differ based on the current rule activity and on the interactions between the <activateOnEvent> and <deactivateOnEvent> definitions within the <activationInterval> and <activationByGroupingKey> elements. The following example illustrates how these definitions can interact.
In this example, a duplicate rule is defined to suppress events from systems that are in maintenance mode and to provide, at the end of the maintenance period, a summary report of the number of events that were suppressed.
By default, a rule within which a grouping key is defined allows all grouping key values to be processed. Therefore, when events meet the event selection criteria for the rule, all rule instances are active and ready to accept these events according to any value of the grouping key. The activation interval for the rule is the same as it would be if the rule did not have a grouping key because in essence, all events that meet the event selection criteria for the rule are processed.
<duplicateRule name="Maintenance_Supression"> <activationInterval> <activationTime> <start> <inactiveWhenLoaded/> </start> <stop> <after duration="PT2H" unit="ISO-8601"/> </stop> </activationTime> <activateOnEvent> <eventType type="StartMaintenanceModeAllHosts"/> </activateOnEvent> <deactivateOnEvent> <eventType type="StopMaintenanceModeAllHosts"/> </deactivateOnEvent> </activationInterval> <groupingKey missingAttributeHandling="ignoreEvent"> <attributeName>hostname</attributeName> </groupingKey> <timeWindow> <runUntilDeactivated/> </timeWindow> <onDetection> <action expressionLanguage="java" name="DropEvent"> <![CDATA[act_lib.exitRuleSet();]]> </action> </onDetection> <onTimeWindowComplete> <action expressionLanguage="java" name="CreateSummaryOfSupressedEvents"> <![CDATA[Helper.createSummaryEvent("MaintenanceSummary", act_eventList, act_lib);]]> </action> </onTimeWindowComplete> </duplicateRule>
In some situations, you might want to control which rule instances become active and when they become active. For these situations, you should code the <activationByGroupingKey> element.
<activationByGroupingKey> <activateOnEvent> <eventType type="StartMaintenanceMode"/> <stopAfter duration="PT2H" unit="ISO-8601"/> </activateOnEvent> <deactivateOnEvent> <eventType type="StopMaintenanceMode"/> </deactivateOnEvent> </activationByGroupingKey>
Starting rule state | Rule state is potentially affected by | Ending rule state |
---|---|---|
Inactive | Time defined within <activationInterval> <activationTime> <start> |
|
activate() method | ||
Event A , defined within <activationInterval> <activateOnEvent> | ||
Event A[1] , defined within <activationByGroupingKey> <activateOnEvent> (without <stopAfter>) |
|
|
Event A[2] , defined within <activateOnEvent> (with <stopAfter>) |
|
|
|
Time defined within <activationInterval> <activationTime> <start> | No change has occurred in the rule state. It is the same as the starting rule state. |
activate() method | ||
Event A , defined within <activationInterval> <activateOnEvent> | ||
Event A[1] , defined within <activationByGroupingKey> <activateOnEvent> (without <stopAfter>) | ||
Event A[2] , defined within <activateOnEvent> (with <stopAfter>) | ||
|
Time defined within <activationInterval> <activationTime> <start> | No change has occurred in the rule state. It is the same as the starting rule state. |
activate() method | ||
Event A , defined within <activationInterval> <activateOnEvent> | All grouping key values are allowed. | |
Event A[1] , defined within <activationByGroupingKey> <activateOnEvent> (without <stopAfter>) |
|
|
Event A[2] , defined within <activateOnEvent> (with <stopAfter>) |
|
|
|
Time defined within <activationInterval> <activationTime> <start> | No change has occurred in the rule state. It is the same as the starting rule state. |
activate() method | ||
Event A , defined within <activationInterval> <activateOnEvent> | All grouping key values are allowed. | |
Event A[1] , defined within <activationByGroupingKey> <activateOnEvent> (without <stopAfter>) | The grouping key value of 1 is now allowed, in addition to the grouping key values that were previously allowed. | |
Event A[2] , defined within <activateOnEvent> (with <stopAfter>) | The grouping key value of 2 is now allowed, in addition to the grouping key values that were previously allowed. |
Starting rule state | Rule state is potentially affected by | Ending rule state |
---|---|---|
Inactive | Time defined within <activationInterval> <activationTime> <stop> | No change has occurred in the rule state. It is the same as the starting rule state. |
deactivate() method | ||
Event D , defined within <activationInterval> <deactivateOnEvent> | ||
Event D[1] , defined within <activationByGroupingKey> <deactivateOnEvent> | ||
Duration defined within <activationByGroupingKey> <activateOnEvent> <stopAfter> ends for event A[2] | ||
|
Time defined within <activationInterval> <activationTime> <stop> |
|
deactivate() method | ||
Event D , defined within <activationInterval> <deactivateOnEvent> | ||
Event D[1] , defined within <activationByGroupingKey> <deactivateOnEvent> |
|
|
Duration defined within <activationByGroupingKey> <activateOnEvent> <stopAfter> ends for event A[2] | The rule instance with a grouping key value of 2 is deactivated. | |
|
Time defined within <activationInterval> <activationTime> <stop> |
|
deactivate() method | ||
Event D , defined within <activationInterval> <deactivateOnEvent> | ||
Event D[1] , defined within <activationByGroupingKey> <deactivateOnEvent> |
|
|
Duration defined within <activationByGroupingKey> <activateOnEvent> <stopAfter> ends for event A[2] |
|
|
|
Time defined within <activationInterval> <activationTime> <stop> |
|
deactivate() method | ||
Event D , defined within <activationInterval> <deactivateOnEvent> | ||
Event D[1] , defined within <activationByGroupingKey> <deactivateOnEvent> |
|
|
Duration defined within <activationByGroupingKey> <activateOnEvent> <stopAfter> ends for event A[2] | The rule instance with a grouping key value of 2 is deactivated. |