Share via

CommandExecuterEventPolicyType

  • Article

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

CommandExecuterEventPolicyType complex data type that contains an event policy.

Schema Definition

<xsd:complexType name="CommandExecuterEventPolicyType">
  <xsd:sequence>
    <xsd:element minOccurs="0" maxOccurs="1" name="Severity">
      <xsd:simpleType>
        <xsd:restriction base="xsd:integer">
          <xsd:minInclusive value="0"/>
          <xsd:maxInclusive value="2"/>
        </xsd:restriction>
      </xsd:simpleType>
    </xsd:element>
    <xsd:element minOccurs="0" maxOccurs="1" name="StdOutMatches" type="PolicyExpression"/>
    <xsd:element minOccurs="0" maxOccurs="1" name="StdErrMatches" type="PolicyExpression"/>
    <xsd:element minOccurs="0" maxOccurs="1" name="ExitCodeMatches" type="PolicyExpression"/>
  </xsd:sequence>
</xsd:complexType>

Remarks

A CommandExecuterEventPolicyType parameter defines the expected output and the behavior based on unexpected output from the script. For example, for the Microsoft.Windows.ScriptProbeAction module type, a System.CommandOutput data type is the expected output. This data type contains the standard output (StdOut), standard error (StdErr), and exit code of the script that ran.

The following code shows an example of the System.CommandOutput data item:

<DataItem type="System.CommandOutput" time="2008-10-10T12:48:57.0477521-07:00" sourceHealthServiceId="B0BE86FA-56AD-1F2E-EE87-8DF72FC53818">
  <StdOut>This is some output text</StdOut>
  <StdErr>This is some error text</StdErr>
  <ExitCode>0</ExitCode>
  <ProcessError></ProcessError>
</DataItem>

The event policy is used to determine the behavior, depending on the output provided by the script, and is only required to be configured if you want to override the default behavior.

The script module can return one of the following four states on execution:

  • Success

  • Warning

  • Data Loss

  • Fatal Error

If a module is used by a task, the default behavior is that all states, except fatal error, are marked as being successful task execution. This means that a script could fail during execution of a task, but Operations Manager would report the task as succeeding, which can be confusing to the user. Therefore, there are situations where it may be required to make the module return a fatal error even though the script might have executed and been completed. A CommandExecuterEventPolicyType parameter controls this behavior. A CommandExecuterEventPolicyType configuration parameter has four elements:

Parameter Type Description

Severity

Integer (0 to 2)

The state of the module to return based on matching StdOut, StdErr, and exit codes.

The possible severity values and their meaning are:

  • 0 - Warning

  • 1 – Data Loss

  • 2 – Fatal Error

StdOutMatches

PolicyExpression

Regular expression to match against data returned to standard out.

StdErrMatches

PolicyExpression

Regular expression to match against data returned to standard error.

ExitCodeMatches

PolicyExpression

Regular expression to match against the exit code from the script.

All script-based module types have a default event policy set that is applied if no specific event policy is passed as configuration. The Microsoft.Windows.ScriptProbeAction type has the following default policy:

<DefaultEventPolicy>
  <StdOutMatches/>
  <StdErrMatches>\a+</StdErrMatches>
  <ExitCodeMatches>[^0]+</ExitCodeMatches>
</DefaultEventPolicy>

This policy specifies that the default behavior of the module type is that any data in standard error or any non-zero exit code results in the module reporting execution as data loss (a severity of 1 is the default setting). Standard output is ignored.

This policy specifies that the default behavior of the module type is that any data in standard error or any non-zero exit code results in the module reporting execution as data loss (a severity of 1 is the default setting). Standard output is ignored.

When you specify an event policy setting, you are overriding the default policy. This is done per field. For example, if you override the severity only, then all other defaults will take effect.

To force the module to report a failure when standard out starts with the word “Error,” set the event policy as follows:

<EventPolicy>
  <Severity>2</Severity>
  <StdErrMatches>^Error</StdErrMatches>
</EventPolicy>

This policy forces a module failure and reports the full output of that failure back as task output.

To always return task success and report standard output, standard error, and exit code as task output, set the policy as follows:

<EventPolicy>
  <Severity>0</Severity>
  <StdErrMatches>\a+</StdErrMatches>
</EventPolicy>

In the case of a rule or monitor workflow where the Microsoft.Windows.ScriptProbeAction module is used, the following behavior occurs for each non-success state:

  • Warning – the workflow continues executing and uses the data item as output from the script module. Event 21413 is logged from the Health Service Modules source in the Operations Manager event log, giving full context to the warning.

  • Data Loss – the data item is dropped from the workflow and no subsequent modules execute. This means that monitor state is not set for a monitor. The workflow continues to execute and is not unloaded. Event 21413 is logged from the Health Service Modules source in the Operations Manager event log, giving full context to the failure.

  • Fatal Error – the module is failed, and the workflow that had the failure is unloaded and does not run again until new configuration is deployed or the agent is restarted. Event 21413 is logged, followed by Event 1103 from the HealthService source, indicating that the workflow was unloaded.

Note

The default settings for the standard error and standard output match are case insensitive and match regular expression.

There are two optional attributes that can be set on the StdOutMatches, StdErrMatches and ExitCodeMatches elements:

Attribute Type Description

Operator

PolicyOperatorType

This can be set to MatchesRegularExpression and DoesNotMatchRegularExpression. Matches is the default if this attribute is not specified.

CaseSensitve

Boolean

Indicates whether the match should be case-sensitive. A value of true indicates a case sensitive match only. A value of false is the default if this attribute is not specified.

The following code shows an example event policy configuration that uses an optional attribute:

<DefaultEventPolicy>
  <StdOutMatches Operator="DoesNotMatchRegularExpression"><![CDATA[<DataItem.+/DataItem\b*>}|{<DataItem.*/>}]]></StdOutMatches>
  <StdErrMatches>\a+</StdErrMatches>
  <ExitCodeMatches>[^0]+</ExitCodeMatches>
</DefaultEventPolicy>

Example

The example below defines a policy that causes the workflow to throw an error when the output does not contain a data item. The standard error contains any data, or the standard error contains the exit code if it is not zero.

<DefaultEventPolicy>
  <StdOutMatches Operator="DoesNotMatchRegularExpression"><![CDATA[{<DataItem.+/DataItem\b*>}|{<DataItem.*/>}]]></StdOutMatches>
  <StdErrMatches>\a+</StdErrMatches>
  <ExitCodeMatches>[^0]+</ExitCodeMatches>
</DefaultEventPolicy>

Information

   

Schema Type

System.CommandExecuterSchema

Library

System.Library