2.2.3.4 Rules Schema Formatting

This section describes the XML format of the IDataManager Rules property. The PLA Protocol provides an XML language of rules for defining well-known patterns in data as well as a means for adding content to the final report, which alerts the user to the presence of these patterns. After the Data Manager runs during the Report phase, control is passed to the PLA Rules Manager. The PLA Rules Manager loads the document specified by the RuleTargetFileName property of the Data Manager, or, if absent, the file report.xml applies a set of rules that inspect the data collected for patterns. When these patterns are found, certain actions can be taken, including raising an ETW event or injecting XML into the report that display as warnings when the XML is rendered as HTML. The set of rules applied by the PLA Rules Manager is specified by an XML document. This XML document is stored as a property of the Data Manager.

The Rules node denotes the beginning of the XML document that is passed to the PLA Rules Manager. The Logging element is used to enable PLA Rules Manager debug logging. By default, the logging level is 0, which provides no debug logging. The logging level is controlled by the level attribute of the Logging element. The file attribute of the Logging element sets the name of the file where the debug information is written. By default, the file name is rules.log.

By default, the output of the PLA Rules Manager is an HTML file called report.html. This name can be controlled by the ReportFileName property of the Data Manager. After the PLA Rules Manager executes, PLA applies an XSLT transformation on the XML output to convert it to HTML. The content of this rule target file is HTML regardless of the extension of the file specified by ReportFileName. Also, the .html extension will not be added to the file, if absent.

The root Rules node of the rules XML is a series of rule Group elements paired with StringTable elements. The StringTable element is defined in a similar manner as the StringTable element from the Report Schema, as specified in section 2.2.3.3. The following XML snippet focuses on the syntax of the Group element.

 <Group name="$(GroupDisk)" enabled="true|false">
   <Rule>...</Rule>
 </Group>
  

The following table describes the Group attributes.

Each Group can define one or more Rule child elements. The following XML snippet illustrates the generic syntax of the Rule element.

 <Rule name="$(RuleCheckQueueLength)" enabled="true|false">
   <Step>...</Step>
 </Rule>
  

The following table describes the name attribute of the Rule element.

Each Rule defines one or more Step child elements. The following XML snippet illustrates the generic syntax of the Step element.

 <Step select="XPath expression" fatal="true|false" sortType="all|min|max" sortDataType="string|number" sortNode="XPath expression" enabled="true|false">
   <Variable>...</Variable>
   <Exists>
     <When></When>
     <Otherwise></Otherwise>
   </Exists>
   <Otherwise>...</Otherwise>
  </Step>
  

The following table describes the Step attributes.

The purpose of a Step is to set a context for evaluating expressions that look for patterns in the collected data. The context is specified by the select attribute that is an XPath expression. If the context the Step is selecting exists, the flow of control enters the Exists block. If the context does not exist, the flow of control enters the Otherwise block. Both the Exists and Otherwise elements are optional children of the Step element.

The context created by the Step element can either be a single XML node or a set of nodes. This depends on the use of the sortType attribute and the related sortDataType/sortNode attributes. The semantics of these attributes are described in the table above.

After selecting the context for the Step, and prior to executing the Exists or Otherwise block, one can use the Variable action to set a variable. See the definition of the Variable element.

If no XML block is evaluated after the Step context is created, the step is said to have failed. This includes failing to find an Otherwise block when all the When conditions evaluate to false. If a step declared as fatal fails, the execution of the whole rule is aborted at this point.

The primary child elements of the Step element consists of the Exists/Otherwise block. The following XML snippet illustrates the generic syntax of this set of elements.

 <Exists>
   <When expression="XPath expression" >
     <!-- Action -->
   </When>
   <Otherwise>
     <!-- Action -->
   </Otherwise>
 </Exists>
 <Otherwise>
   <!-- Action -->
 </Otherwise>
  

The following table describes the attributes of the When element.

The When/Otherwise block within the Exists element acts like a giant case statement. Each When element defines a condition under which its child elements is evaluated. The child elements are considered to be Actions. The actions useful to most content developers are: Set Variable, Insert Node, Insert Attribute, Delete, and Insert Warning. Each is described in turn in the following sections.