activationByGroupingKey element

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.

Details

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>

Attributes

<activationByGroupingKey> has no attributes.

Contained within

<activationByGroupingKey> is contained within the following element:

Contains

<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.

Table 1. Elements contained within the <activationByGroupingKey> element
Element Required or optional?
<activateOnEvent> Optional. 0 or 1 occurrence is allowed.
<deactivateOnEvent> Optional. 0 or 1 occurrence is allowed.

Relationship between <activationInterval> and <activationByGroupingKey> elements

The <activateOnEvent> and <deactivateOnEvent> elements are contained within both of these elements:
  • <activationInterval>
  • <activationByGroupingKey>, which is also contained within <activationInterval>

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.

In the following example, the grouping key is hostname, and the definitions within the <activationInterval> element specify the following actions:
  1. Activate all rule instances when an event of type StartMaintenanceModeAllHosts is received.
  2. Deactivate all rule instances either after 2 hours or when an event of type StopMaintenanceModeAllHosts is received.
<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.

The following example extends the previous example and illustrates how you can use the grouping key value to select which rule instances are allowed to process. The definitions within the <activationByGroupingKey> element specify the following actions:
  1. Allow the rule instances for specific host names to process when events of type StartMaintenanceMode are received for those host names.
  2. Deactivate these rule instances either after 2 hours of activation or when an event of type StopMaintenanceMode is received for the respective host name.
    <activationByGroupingKey>
      <activateOnEvent>
        <eventType type="StartMaintenanceMode"/>
        <stopAfter duration="PT2H" unit="ISO-8601"/>
      </activateOnEvent>
      <deactivateOnEvent>
        <eventType type="StopMaintenanceMode"/>
      </deactivateOnEvent>
    </activationByGroupingKey>
The following statements summarize what happens when you code the <activationByGroupingKey> element:
  • When the <activateOnEvent> element is coded within the <activationByGroupingKey> element, only the events that share the grouping key value of the event that met the <activationByGroupingKey> <activateOnEvent> condition are allowed to process.
  • When the <deactivateOnEvent> element is coded within the <activationByGroupingKey> element, the events that share the grouping key value of the event that met the <activationByGroupingKey> <deactivateOnEvent> condition are not allowed to process.

The effect of different activation and deactivation definitions on rule state

Table 2 and Table 3 show how the state of a rule is affected by different activation and deactivation definitions. In these tables, the following conventions are used:
  • A is an activating event.
  • In the notation "A[x], " x represents the grouping key value. For example, A[1] is an activating event with a grouping key value of 1.
  • D is a deactivating event.
  • In the notation "D[x], " x represents the grouping key value. For example, D[1] is an deactivating event with a grouping key value of 1.
Table 2. Rule state changes based on different activation definitions
Starting rule state Rule state is potentially affected by Ending rule state
Inactive Time defined within <activationInterval> <activationTime> <start>
  1. The rule is activated.
  2. The <onActivation> actions run.
  3. All grouping key values are allowed.
activate() method
Event A , defined within <activationInterval> <activateOnEvent>
Event A[1] , defined within <activationByGroupingKey> <activateOnEvent> (without <stopAfter>)
  1. The rule is activated.
  2. The <onActivation> actions run.
  3. Only the grouping key value of 1 is allowed. When the rule pattern is matched for this rule instance, the grouping key value of 1 is no longer allowed.
Event A[2] , defined within <activateOnEvent> (with <stopAfter>)
  1. The rule is activated.
  2. The <onActivation> actions run.
  3. Only the grouping key value of 2 is allowed, and it is allowed only for the duration that is specified by the <stopAfter> element. The rule pattern for this rule instance can be matched multiple times during this duration.
  • Active
  • Allowing all grouping key values
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>)
  • Active
  • Allowing only grouping key values that have triggered rule instances based on <activationByGroupingKey> <activateOnEvent> definitions
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.
  • When the rule pattern is matched for this rule instance, the grouping key value of 1 is no longer 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.
  • This value is allowed only for the duration that is specified by the <stopAfter> element.
  • The rule pattern for this rule instance can be matched multiple times during this duration.
  • Active
  • Allowing all grouping key values except those that are not allowed based on <activationByGroupingKey> <deactivateOnEvent> definitions
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.
Table 3. Rule state changes based on different deactivation definitions
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]
  • Active
  • Allowing all grouping key values
Time defined within <activationInterval> <activationTime> <stop>
  1. All rule instances are deactivated.
  2. The <onDeactivation> actions run.
  3. The rule is deactivated.
deactivate() method
Event D , defined within <activationInterval> <deactivateOnEvent>
Event D[1] , defined within <activationByGroupingKey> <deactivateOnEvent>
  • The grouping key value of 1 is no longer allowed.
  • If the rule instance with a grouping key value of 1 is active, it is deactivated.
Duration defined within <activationByGroupingKey> <activateOnEvent> <stopAfter> ends for event A[2] The rule instance with a grouping key value of 2 is deactivated.
  • Active
  • Allowing only grouping key values that have triggered rule instances based on <activationByGroupingKey> <activateOnEvent> definitions
Time defined within <activationInterval> <activationTime> <stop>
  1. All rule instances are deactivated.
  2. The <onDeactivation> actions run.
  3. The rule is deactivated.
deactivate() method
Event D , defined within <activationInterval> <deactivateOnEvent>
Event D[1] , defined within <activationByGroupingKey> <deactivateOnEvent>
  • The grouping key value of 1 is no longer allowed.
  • If the rule instance with a grouping key value of 1 is active, it is deactivated.
Duration defined within <activationByGroupingKey> <activateOnEvent> <stopAfter> ends for event A[2]
  • The grouping key value of 2 is no longer allowed.
  • The rule instance with a grouping key value of 2 is deactivated.
  • Active
  • Allowing all grouping key values except those that are not allowed based on <activationByGroupingKey> <deactivateOnEvent> definitions
Time defined within <activationInterval> <activationTime> <stop>
  1. All rule instances are deactivated.
  2. The <onDeactivation> actions run.
  3. The rule is deactivated.
deactivate() method
Event D , defined within <activationInterval> <deactivateOnEvent>
Event D[1] , defined within <activationByGroupingKey> <deactivateOnEvent>
  • The grouping key value of 1 is no longer allowed.
  • If the rule instance with a grouping key value of 1 is active, it is deactivated.
Duration defined within <activationByGroupingKey> <activateOnEvent> <stopAfter> ends for event A[2] The rule instance with a grouping key value of 2 is deactivated.