System.ExpressionFilter

  • Article

Applies To: System Center 2012 - Operations Manager, System Center 2012 R2 Operations Manager, System Center 2012 SP1 - Operations Manager

The System.ExpressionFilter condition detection module is a filtering module that takes any input data type and outputs the same data type. There are no changes to the data item flowing through a module of this type. The module either allows the data item through or stops the data item based on the expression specified as configuration, and the defined suppression settings.

Warning

The suppression settings are available to management packs using the Operations Manager 2012 schema only. If you use the suppression settings parameters in a management pack that is deployed to Operations Manager 2007, an error will be generated.

Usage

Use this module within a workflow to filter any type of data. The suppression settings can be used to specify that the workflow should not continue unless a specified number of matches occurs within a given sample count or a given time period.

Type Definition

<ConditionDetectionModuleType ID="System.ExpressionFilter" Accessibility="Public" Batching="true" Stateful="false" PassThrough="true">
  <Configuration>
    <IncludeSchemaTypes>
      <SchemaType>System.ExpressionEvaluatorSchema</SchemaType>
    </IncludeSchemaTypes>
    <xsd:element name="Expression" type="ExpressionType" xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
    <xsd:element name="SuppressionSettings" minOccurs="0" maxOccurs="1" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <xsd:complexType>
        <xsd:sequence>
          <xsd:element name="MatchCount" type="xsd:unsignedByte" />
          <xsd:element name="SampleCount" type="xsd:unsignedByte" minOccurs="0" maxOccurs="1" />
          <xsd:element name="WithinSeconds" type="xsd:unsignedInt" minOccurs="0" maxOccurs="1" />
        </xsd:sequence>
      </xsd:complexType>
    </xsd:element>
  </Configuration>
  <ModuleImplementation Isolation="Any">
    <Native>
      <ClassID>C6410789-C1BB-4AF1-B818-D01A5367781D</ClassID>
    </Native>
  </ModuleImplementation>
  <OutputType>System.BaseData</OutputType>
  <InputTypes>
    <InputType>System.BaseData</InputType>
  </InputTypes>
</ConditionDetectionModuleType>

Parameters

The System.ExpressionFilter module supports the following configuration parameters:

Parameter Type Overrideable Description

Expression

ExpressionType

False

Required parameter. Defines an expression that evaluates to true or false.

SuppressionSettings

Complex type

False

Optional parameter. Indicates whether multiple matches are required before a data item is output.

If the expression defined in the Expression parameter evaluates to true, and if the suppression settings do not take effect, the workflow will continue and the data will be passed on to the subsequent module in the workflow. If it resolves to false, then the data will not be passed to the next module and the workflow will end. For more information on the ExpressionType data type, see ExpressionType.

The SuppressionSettings parameter allows some expression matches to be suppressed, depending on how many times they occur. This parameter is a complex type that consists of three elements:

Element Type Overridable Description

MatchCount

Integer

False

Required element. Indicates how many positive matches the expression filter requires before outputting a data item. A value of 1 or 0 here defaults to the original behavior of the Expression Filter which is to output on all matches.

SampleCount

Integer

False

Optional element. Indicates how many total samples (both positive and negative) to store while calculating matches. This value must be greater or equal to the match count. If it is not, or if it is missing, the sample count is set equal to the match count (that is, only consecutive matching samples will trigger output).

WithinSeconds

Integer

False

Optional element. Indicates the time period during which a match increments a repeat count from the current item. This means that there need to be MatchCount matches of the expression within WithinSeconds in order for the Expression Filter to produce a data item.  If this parameter is missing, set to zero, or SampleCount is non-zero, it defaults to the MatchCount/SampleCount behavior.

These parameters cannot be overridden. If you want to allow the user to override the suppression settings, use System.ExpressionFilter.EventSuppression or System.ExpressionFilter.IntervalSuppression.

Composition

The System.ExpressionFilter module is a native module.

Module Type Usage

System.ExpressionFilter.EventSuppression

Filtering module with suppression settings specific to a time period.

System.ExpressionFilter.IntervalSuppression

Filtering module with suppression settings specific to number of matches.

External Module References

The System.ExpressionFilter module is used in many other modules that require a filtering condition detection module.

Samples

The following XML sample shows how the System.ExpressionFilter module is used in a DataSourceModuleType element definition. The expression is passed in through the configuration parameter of the data source module type. Using the configuration parameter to pass in the evaluation expression is commonplace with this module. If the expression equates to true, then the data is passed on to the next module in the workflow. The suppression settings parameters are not used in this example.

<DataSourceModuleType ID="Microsoft.Windows.EventProvider" Accessibility="Public" Batching="false">
  <Configuration>
    <IncludeSchemaTypes>
      <SchemaType>System!System.ExpressionEvaluatorSchema</SchemaType>
      <SchemaType>Microsoft.Windows.ComputerNameSchema</SchemaType>
    </IncludeSchemaTypes>
    <xsd:element name="ComputerName" type="ComputerNameType" minOccurs="0" maxOccurs="1" xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
    <xsd:element name="LogName" type="xsd:string" xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
    <xsd:element name="AllowProxying" type="xsd:boolean" minOccurs="0" maxOccurs="1" xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
    <xsd:element name="Expression" type="ExpressionType" xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
  </Configuration>
  <ModuleImplementation Isolation="Any">
    <Composite>
      <MemberModules>
        <DataSource ID="Provider" TypeID="Microsoft.Windows.BaseEventProvider">
          <ComputerName>$Config/ComputerName$</ComputerName>
          <LogName>$Config/LogName$</LogName>
          <AllowProxying>$Config/AllowProxying$</AllowProxying>
        </DataSource>
        <ConditionDetection ID="Filter" TypeID="System!System.ExpressionFilter">
          <Expression>$Config/Expression$</Expression>
        </ConditionDetection>
      </MemberModules>
      <Composition>
        <Node ID="Filter">
          <Node ID="Provider" />
        </Node>
      </Composition>
    </Composite>
  </ModuleImplementation>
  <OutputType>Microsoft.Windows.EventData</OutputType>
</DataSourceModuleType>

The following XML sample shows a UnitMonitorType that uses the System.ExpressionFilter module to explicitly filter the data from an SNMP data provider. In this case, two System.ExpressionFilter modules are used with regular detection: one to indicate whether the device is up (ErrorCode equal to 1), and one to indicate whether the device is down (ErrorCode equal to 2).

<UnitMonitorType ID="Microsoft.SystemCenter.NetworkDevice.CheckDeviceState" Accessibility="Public">
  <MonitorTypeStates>
    <MonitorTypeState ID="DeviceUp" NoDetection="false" />
    <MonitorTypeState ID="DeviceDown" NoDetection="false" />
  </MonitorTypeStates>
  <Configuration>
    <xsd:element name="Interval" type="xsd:integer" xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
    <xsd:element name="IsWriteAction" type="xsd:boolean" xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
    <xsd:element name="IP" type="xsd:string" xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
    <xsd:element name="CommunityString" type="xsd:string" xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
    <xsd:element minOccurs="0" maxOccurs="1" name="Version" type="xsd:string" xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
    <xsd:element name="SnmpVarBinds" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <xsd:complexType>
        <xsd:sequence>
          <xsd:element minOccurs="1" maxOccurs="unbounded" name="SnmpVarBind">
            <xsd:complexType>
              <xsd:sequence>
                <xsd:element name="OID" type="xsd:string" />
                <xsd:element name="Syntax" type="xsd:integer" />
                <xsd:element name="Value">
                  <xsd:complexType>
                    <xsd:simpleContent>
                      <xsd:extension base="xsd:string">
                        <xsd:attribute name="VariantType" type="xsd:integer" use="optional" />
                      </xsd:extension>
                    </xsd:simpleContent>
                  </xsd:complexType>
                </xsd:element>
              </xsd:sequence>
            </xsd:complexType>
          </xsd:element>
        </xsd:sequence>
      </xsd:complexType>
    </xsd:element>
  </Configuration>
  <MonitorImplementation>
    <MemberModules>
      <DataSource ID="ProbeDS" TypeID="Snmp!System.SnmpQueryProvider">
        <Interval>$Config/Interval$</Interval>
        <IsWriteAction>$Config/IsWriteAction$</IsWriteAction>
        <IP>$Config/IP$</IP>
        <CommunityString>$Config/CommunityString$</CommunityString>
        <Version>$Config/Version$</Version>
        <SnmpVarBinds>
          <SnmpVarBind>
            <OID>.1.3.6.1.2.1.1.5.0</OID>
            <Syntax>1</Syntax>
            <Value VariantType="8" />
          </SnmpVarBind>
        </SnmpVarBinds>
      </DataSource>
      <ConditionDetection ID="DeviceUpCondition" TypeID="System!System.ExpressionFilter">
        <Expression>
          <SimpleExpression>
            <ValueExpression>
              <XPathQuery Type="String">ErrorCode</XPathQuery>
            </ValueExpression>
            <Operator>Equal</Operator>
            <ValueExpression>
              <Value Type="UnsignedInteger">1</Value>
            </ValueExpression>
          </SimpleExpression>
        </Expression>
      </ConditionDetection>
      <ConditionDetection ID="DeviceDownCondition" TypeID="System!System.ExpressionFilter">
        <Expression>
          <SimpleExpression>
            <ValueExpression>
              <XPathQuery Type="String">ErrorCode</XPathQuery>
            </ValueExpression>
            <Operator>NotEqual</Operator>
            <ValueExpression>
              <Value Type="UnsignedInteger">1</Value>
            </ValueExpression>
          </SimpleExpression>
        </Expression>
      </ConditionDetection>
    </MemberModules>
    <RegularDetections>
      <RegularDetection MonitorTypeStateID="DeviceUp">
        <Node ID="DeviceUpCondition">
          <Node ID="ProbeDS" />
        </Node>
      </RegularDetection>
      <RegularDetection MonitorTypeStateID="DeviceDown">
        <Node ID="DeviceDownCondition">
          <Node ID="ProbeDS" />
        </Node>
      </RegularDetection>
    </RegularDetections>
  </MonitorImplementation>
</UnitMonitorType>

The following example shows a simple rule that runs a script that returns a random integer value between 0 and 1,000. Any value over 500 is considered “above the threshold,” and could potentially trigger an alert. However, the suppression settings are configured such that an alert will only be triggered if the random number is over 500 five times out of ten samples. Therefore, this rule uses the <SampleCount> parameter to track the number of matches in a given number of samples. This number could be adjusted lower or higher depending on the sensitivity you want for the threshold.

<TypeDefinitions>
  <ModuleTypes>
    <DataSourceModuleType ID="MPAuthor.ExpressionFilter.ScheduledProbeDS" Accessibility="Public" Batching="false">
      <Configuration>
        <xsd:element minOccurs="1" name="Interval" type="xsd:integer" xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
        <xsd:element minOccurs="0" name="SyncTime" type="xsd:string" xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
      </Configuration>
      <OverrideableParameters>
        <OverrideableParameter ID="Interval" Selector="$Config/Interval$" ParameterType="int" />
        <OverrideableParameter ID="SyncTime" Selector="$Config/SyncTime$" ParameterType="string" />
      </OverrideableParameters>
      <ModuleImplementation Isolation="Any">
        <Composite>
          <MemberModules>
            <DataSource ID="Scheduler" TypeID="System!System.Scheduler">
              <Scheduler>
                <SimpleReccuringSchedule>
                  <Interval>$Config/Interval$</Interval>
                  <SyncTime>$Config/SyncTime$</SyncTime>
                </SimpleReccuringSchedule>
                <ExcludeDates />
              </Scheduler>
            </DataSource>
            <ProbeAction ID="Script" TypeID="Windows!Microsoft.Windows.PowerShellPropertyBagProbe">
              <ScriptName>NetworkSpeed.ps1</ScriptName>
              <ScriptBody>
                
$api = new-object -comObject "MOM.ScriptAPI"
$bag = $api.CreatePropertyBag()
$randomValue = Get-Random -minimum 1 -maximum 1001
$bag.AddValue("value",$randomValue)
$bag
 

              </ScriptBody>
              <TimeoutSeconds>300</TimeoutSeconds>
            </ProbeAction>
          </MemberModules>
          <Composition>
            <Node ID="Script">
              <Node ID="Scheduler" />
            </Node>
          </Composition>
        </Composite>
      </ModuleImplementation>
      <OutputType>System!System.PropertyBagData</OutputType>
    </DataSourceModuleType>
  </ModuleTypes>
</TypeDefinitions>
<Monitoring>
  <Rules>
    <Rule ID="MPAuthor.ExpressionFilter.RandomNumberAlertRule" Enabled="true" Target="Windows!Microsoft.Windows.Computer" ConfirmDelivery="false" Remotable="true" Priority="Normal" DiscardLevel="100">
      <Category>Alert</Category>
      <DataSources>
        <DataSource ID="DS" TypeID="MPAuthor.ExpressionFilter.ScheduledProbeDS">
          <Interval>300</Interval>
          <SyncTime />
        </DataSource>
      </DataSources>
      <ConditionDetection ID="CD" TypeID="System!System.ExpressionFilter">
        <Expression>
          <SimpleExpression>
            <ValueExpression>
              <XPathQuery Type="Integer">Property[@Name='value']</XPathQuery>
            </ValueExpression>
            <Operator>Greater</Operator>
            <ValueExpression>
              <Value Type="Integer">500</Value>
            </ValueExpression>
          </SimpleExpression>
        </Expression>
        <SuppressionSettings>
          <MatchCount>5</MatchCount>
          <SampleCount>10</SampleCount>
        </SuppressionSettings>
      </ConditionDetection>
      <WriteActions>
        <WriteAction ID="Alert" TypeID="Health!System.Health.GenerateAlert">
          <Priority>1</Priority>
          <Severity>2</Severity>
          <AlertMessageId>$MPElement[Name="MPAuthor.ExpressionFilter.RandomNumberAlertRule.AlertMessage"]$</AlertMessageId>
        </WriteAction>
      </WriteActions>
    </Rule>
  </Rules>
</Monitoring>

The following example is similar to the previous one, but instead of counting the number of matches in a given number of samples, it counts the number of matches in a given period of time (30 minutes, in this case). Therefore, this sample uses the <WithinSeconds> parameter instead of <SampleCount>.

<TypeDefinitions>
  <ModuleTypes>
    <DataSourceModuleType ID="MPAuthor.ExpressionFilter.ScheduledProbeDS" Accessibility="Public" Batching="false">
      <Configuration>
        <xsd:element minOccurs="1" name="Interval" type="xsd:integer" xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
        <xsd:element minOccurs="0" name="SyncTime" type="xsd:string" xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
      </Configuration>
      <OverrideableParameters>
        <OverrideableParameter ID="Interval" Selector="$Config/Interval$" ParameterType="int" />
        <OverrideableParameter ID="SyncTime" Selector="$Config/SyncTime$" ParameterType="string" />
      </OverrideableParameters>
      <ModuleImplementation Isolation="Any">
        <Composite>
          <MemberModules>
            <DataSource ID="Scheduler" TypeID="System!System.Scheduler">
              <Scheduler>
                <SimpleReccuringSchedule>
                  <Interval>$Config/Interval$</Interval>
                  <SyncTime>$Config/SyncTime$</SyncTime>
                </SimpleReccuringSchedule>
                <ExcludeDates />
              </Scheduler>
            </DataSource>
            <ProbeAction ID="Script" TypeID="Windows!Microsoft.Windows.PowerShellPropertyBagProbe">
              <ScriptName>NetworkSpeed.ps1</ScriptName>
              <ScriptBody>
                
$api = new-object -comObject "MOM.ScriptAPI"
$bag = $api.CreatePropertyBag()
$randomValue = Get-Random -minimum 1 -maximum 1001
$bag.AddValue("value",$randomValue)
$bag
 

              </ScriptBody>
              <TimeoutSeconds>300</TimeoutSeconds>
            </ProbeAction>
          </MemberModules>
          <Composition>
            <Node ID="Script">
              <Node ID="Scheduler" />
            </Node>
          </Composition>
        </Composite>
      </ModuleImplementation>
      <OutputType>System!System.PropertyBagData</OutputType>
    </DataSourceModuleType>
  </ModuleTypes>
</TypeDefinitions>
<Monitoring>
  <Rules>
    <Rule ID="MPAuthor.ExpressionFilter.RandomNumberAlertRule" Enabled="true" Target="Windows!Microsoft.Windows.Computer" ConfirmDelivery="false" Remotable="true" Priority="Normal" DiscardLevel="100">
      <Category>Alert</Category>
      <DataSources>
        <DataSource ID="DS" TypeID="MPAuthor.ExpressionFilter.ScheduledProbeDS">
          <Interval>120</Interval>
          <SyncTime />
        </DataSource>
      </DataSources>
      <ConditionDetection ID="CD" TypeID="System!System.ExpressionFilter">
        <Expression>
          <SimpleExpression>
            <ValueExpression>
              <XPathQuery Type="Integer">Property[@Name='value']</XPathQuery>
            </ValueExpression>
            <Operator>Greater</Operator>
            <ValueExpression>
              <Value Type="Integer">500</Value>
            </ValueExpression>
          </SimpleExpression>
        </Expression>
        <SuppressionSettings>
          <MatchCount>5</MatchCount>
          <WithinSeconds>1800</WithinSeconds>
        </SuppressionSettings>
      </ConditionDetection>
      <WriteActions>
        <WriteAction ID="Alert" TypeID="Health!System.Health.GenerateAlert">
          <Priority>1</Priority>
          <Severity>2</Severity>
          <AlertMessageId>$MPElement[Name="MPAuthor.ExpressionFilter.RandomNumberAlertRule.AlertMessage"]$</AlertMessageId>
        </WriteAction>
      </WriteActions>
    </Rule>
  </Rules>
</Monitoring>

Information

   

Module Type

ConditionDetectionModuleType

Input Type

System.BaseData

Output Type

System.Event.Data

Implementation

Native

Library

System.Library