SIM:RuleDef

From RuleCore Support

Overview

Rules are defined using the AddRuleDef system event and are found in the SIM as RuleDef items in the container located at /SysInfo/Items/Type[@name="RuleDef"]

The RuleDef contains:

• Directives on how to initialize instances of the rule, below the Initialize element.
• Directives on how to terminate instances of the rule, below the Terminate element.
• Directives on what key to use when creating instances of the rule, below the Key element.
• Directives on when to trigger the rule, below the Trigger element.
• Directives on when to report the result of rule triggers, below the Report element.
• References to at least one view under the Views element - ViewRef
• A reference to a situation under the Situations element - SituationRef
• References to actions under the Actions element - ActionRef

Contents

Initialize

The Initialize section specifies which events (or rule lifecycle activities) that may trigger the creation of Rule instances. Each initialization event is specified by either an Assert/Event or a Timestamp element.

Event

The Assert/Event element specifies which events and/or event content that may trigger creation of rule instances. Zero or more Assert/Event elements may be specified.

The Event element refers to an Event definition. The Expression element contains an expression saying what event content to let through. More details on the Expression syntax can be found here.

Example:

  <Initialize>
    <Assert>
      <Event>
        <base:XPath>sim:EventDef[@eventType="ItemDelivered"]</base:XPath>
      </Event>
      <Expression>
        <base:XPath>string(base:EventBody/user:SomeValue)='ABC'</base:XPath>
      </Expression>
    </Assert>
  </Initialize>

Time

The Time element specifies the time(s) at which rule instances should be created. Zero or more Time elements may be specified.

  <Initialize>
    <Assert>
      <Time>
        <ISO8601>2009-05-01T04:00:00</ISO8601>
      </Time>
    </Assert>
  </Initialize>

On Creation

The OnCreate element specifies that the rule instance(s) should be created upon rule creation, i.e. when it goes online. What instances are created is deduced from the property values specified in the Key section. One instance is created for each combination of the property values.

  <Initialize>
    <OnCreate/>
  </Initialize>

Terminate

The Terminate section specifies which events that may trigger the termination of (all) existing Rule instances.

Event

The Assert/Event element specifies which events and/or event content that may trigger creation of rule instances. Zero or more Assert/Event elements may be specified.

The Event element refers to an Event definition. The Expression element contains an expression saying what event content to let through. More details on the Expression syntax can be found here.

Example:

  <Initialize>
    <Assert>
      <Event>
        <base:XPath>sim:EventDef[@eventType="ItemDelivered"]</base:XPath>
      </Event>
      <Expression>
        <base:XPath>string(base:EventBody/user:SomeValue)='ABC'</base:XPath>
      </Expression>
    </Assert>
  </Initialize>

Time

The Time element specifies the time(s) at which rule instances should be created. Zero or more Time elements may be specified.

  <Initialize>
    <Assert>
      <Time>
        <ISO8601>2009-05-01T04:00:00</ISO8601>
      </Time>
    </Assert>
  </Initialize>

Rule Triggered

The Triggered element specifies that a rule instance should be terminated when the rule has triggered a certain amount of times and optionally for what reason.

The following example makes a rule instance terminate when it has triggered twice, either as a result of a situation being detected or if a situation is considered being undetectable.

<Terminate>
  <Triggered count="2">
    <SituationDetected/>
    <UndetectableSituation/>
  </Triggered>
</Terminate>

View Empty

The ViewEmpty element specifies that a rule instance should be terminated if the named view has become empty. E.g.

<Terminate>
  <ViewEmpty name="ZoneEntriesGBG"/>
</Terminate>

Key

The Key section specifies which combination of Property values should be used to form the key of a particular Rule instance. For each unique combination of Property values a separate Rule instance may be created.

Example:

<Key>
  <Property name="Driver"/>
  <Property name="Zone"/>
</Key>

If the rule is defined to be instantiated upon creation or at a specific point in time, it it possible to explicitly specify the values for each of the key properties; e.g.

<Key>
  <Property name="Driver">
    <Values>
      <Value>Driver1</Value>
      <Value>Driver2</Value>
    </Values>
  </Property>
  <Property name="Zone">
    <Values>
      <Value>Göteborg V</Value>
    </Values>
  </Property>
</Key>

Triggers

The Trigger element specifies when the rule should trigger. Currently the rule may trigger as a result of either a situation being detected or a situation is considered to be undetectable.

Example:

<Trigger>
  <SituationDetected/>
  <UndetectableSituation/>
</Trigger>

Trigger Reporting

The Report element specifies when to report the results of rule triggers. Events created as a result of a rule trigger are queued up until the next report point.

There are several options;

• report at rule instance termination, use the AtTermination element.
• report every X'th time the rule triggers, use the Every@trigCount attribute.
• report every X'th time period, use the Every@timeframe attribute.
• report maximum X times, use the Max@count attribute.

Example:

<Report>
  <Every trigCount="5" timeframe="00:05:00"/>
  <Max count="10"/>
  <AtTermination/>
</Report>

Views

The Views section contains references to the view definitions that are to be used for the rule and its Situation and Action items.

The view defines a view into the inbound stream of events. The view is a private and continuously updated window into inbound event stream automatically maintained for each rule instance.

The view is defined using a number of view properties which all must be true for the event to be accepted into the view.

The type view property is the only required property. The others can be combined as needed.

Situations

Each rule contains a reference to a situation located under the Situations element

The reference is defined using the SituationRef element. The element contains an XPath expression which must evaluate to an SituationDef in the SIM.

The expression's default evaluation context is /sim:SysInfo/sim:Items/sim:Item[@name="SituationDef"]

Example:

<Situations>
  <SituationRef name="ProcessorDetected"><base:XPath>sim:SituationDef[@name="ProcessorTx"]</base:XPath></SituationRef>
</Situations>

Actions

Each rule contains references to actions under the <Actions> element.

The <SituationDetected> is used to select the action to be executed when the situation named in its situationName attribute is detected. The SituationDetected element contains a <ActionRef> element selecting the action.

The <UndetectableSituation> is used to select the action to be executed when the situation named in its situationName attribute is determined to be undetectable. The UndetectableSituation element contains an <ActionRef> element selecting the action.

The ActionRef element contains an expression which must evaluate to an ActionDef item in the SIM. The expression default evaluation context is /sim:SysInfo/sim:Items/sim:Item[@name="ActionDef"]

Example

<Actions>  
  <SituationDetected situationName="S1">
    <ActionRef name="A1" eventVisibility="internal"><base:XPath>sim:ActionDef[@name="A1"]</base:XPath></ActionRef>
  </SituationDetected>
  <UndetectableSituation situationName="S1">
    <ActionRef name="A2"><base:XPath>sim:ActionDef[@name="A2"]</base:XPath></ActionRef>
  </UndetectableSituation>
</Actions>

See Also

• ViewDef
• SituationDef
• ActionDef