Authoring Service Modeling Language Models Step-by-Step Guide

  • Article

The purpose of this document is to introduce authoring Service Modeling Language (SML) models that can be used with the SML runtime library and discovery providers. This document uses a specific “best practice” scenario to demonstrate authoring the components of an SML model.

Service Modeling Language authoring prerequisites

Service Modeling Language (SML) is an extension to the XML schema-based modeling language based on W3C and ISO standards. SML provides a way to capture knowledge of complex IT services and systems in machine-interpretable models. For more information about the W3C and ISO standards, see the World Wide Web Consortium (https://go.microsoft.com/fwlink/?LinkId=5933).

Examples of information that may be included in an SML model are configuration, deployment, monitoring, policy, health, capacity planning, and service level agreements.

SML provides:

  • A model of a system's or service's structure.
  • Relationships between IT system components.
  • Relationships between IT system components and other services.
  • Constraints placed on IT services and systems.

Because SML uses XML and XSLT standards, you should have some basic understanding of the XML, XSLT, and XPath language structure and syntax. At a minimum you should understand:

  • The definition of a well-formed XML document.
  • XML elements.
  • XML attributes.
  • XML namespaces.
  • Case sensitivity of XML, XSLT, and XPath notation. You must enter all elements and attributes in the same case as presented in this reference.
  • XML schemas.
  • XSLT transforms.
  • XPath notation.

Key terms and concepts

The following terms and concepts are essential to understanding SML authoring.

  • best practice
    A process that has been defined by system experts as the right way to do something, given a range of valid options. Configurations that are not compliant with a best practice, even critical ones, are not necessarily wrong. They indicate practices that may result in undesirable consequences (for example, poor performance, lax security, poor reliability, or unexpected functional problems).
  • discovery providers
    A library of XSLT extension functions provided by the SML run-time library. The XSLT extension functions are used to discover data from various data stores. For example, the “registry discovery provider” can be used to discover data from the Windows registry.
  • discovery transform
    An XSLT style sheet used for discovering the required data, via discovery providers, and constructing instance documents conforming to the SML schema.
  • instance document
    An XML document produced as the output of a discovery process. It conforms to the predefined SML schema and contains the data discovered after applying the discovery transform.
  • Schematron rules
    User-defined constraints on an SML schema. An example of a constraint is when a registry key must contain a specific value.
  • SML schema
    An extension to the XML schema representation of system or service configuration data to be validated.

Core files of SML models

An SML model includes three core files:

  1. An .xsd file defining the SML schema of the system or service on which the data needs to be validated.
  2. A .sch file defining a set of Schematron rules to be applied to the SML schema.
  3. An .xsl file defining the discovery transform to discover the required data and validate the defined Schematron rules.

Note

The description of these core files assumes that you have determined the data you need to collect and validate on the local computer to which the SML model is applied. You must know this information in order to create an SML model. This prerequisite step can sometimes be very time consuming. For these reasons, we discuss determining this information as a prerequisite step to authoring an SML model.

Scenario: Authoring a Service Modeling Language model, based on antivirus best practice requirements

This scenario demonstrates authoring an SML model. This is a very basic scenario that walks you through the steps to develop an SML model that can be used to validate that a computer system is in compliance with antivirus best.

Authoring a Service Modeling Language model based on antivirus best practice requirements procedure

  1. Prerequisite step: Determine the expected configuration for the antivirus best practice

  2. Step 1: Create the SML schema based on the antivirus best practice configuration requirements

  3. Step 2: Create the Schematron rules based on the anitivirus constraints

  4. Step 3: Create the discovery transform file based on the antivirus best practice configuration requirements and constraints

Prerequisite step: Determine the expected configuration for the antivirus best practice

Before we can author an SML model based on the antivirus best practice, we must first define what we mean by "antivirus best practice." The antivirus best practice would be information about the system or services configuration, policies to be enforced, relationships to be managed and any other information that would help our antivirus efforts create computers that are protected from computer viruses.

One good way to start would be to ask two simple questions:

  1. With what rules or constraints does your system or service need to comply?
  2. Where can we find the data required for evaluating these rules or constraints?

Answering the first question is crucial to creating good SML models. In most IT environments this knowledge is the collective expertise of an entire group of contributors. The end goal is to have a comprehensive set of rules and constraints that need to be evaluated. For the antivirus scenario, we identify two basic rules that when followed dramatically decrease the incidence of computer viruses.

  • The antivirus application installed on the computer system must be configured to scan the computer hard drive’s boot sector for viruses.
  • Automatic Updates must be configured to automatically download updates and install them at a scheduled time.

Based on the two rules determined when answering the first question, we can investigate what data must be imported from a variety of common sources corresponding to the two rules. Examples of a few common sources include registry settings, data retrieved using WQL queries to the WMI service, file and directory information, and network-based resources. For a full listing of sources of information provided with SML, see the Service Modeling Language Technical Reference (https://go.microsoft.com/fwlink/?LinkId=95309).

In our scenario, we will evaluate two registry subkeys to determine if our antivirus application and Automatic Updates are configured correctly to meet the constraints identified earlier in this section. Knowledge about correct configuration comes from the documentation about our antivirus application and the documentation about Automatic Updates.

  • For our scenario, we have generalized the antivirus application as coming from Contoso Corporation. The fictitious antivirus application is configured using a registry subkey: HKLM\SOFTWARE\Contoso\CurrentVersion\Local Scanner\Scan BootSector. From the documentation, we know the subkey must be configured to the value of 1 to represent scanning the boot sector.
  • For our scenario, we know from Automatic Updates documentation that the registry subkey, HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\WindowsUpdate\Auto Update\AUOptions set to a value of 4. represents configuring Automatic Updates to download updates and install them at a scheduled time.

We have now determined the rules and the data that must be verified in order to determine if a computer complies with the basic antivirus best practice detailed for our scenario. We can use the rules and data to author an SML model in the following steps.

Step 1: Create the SML schema based on the antivirus best practice configuration requirements

Building on our example we now define the SML schema definition of a computer system configuration focusing on just two aspects: the antivirus setting and automatic updates. There are many ways to create the SML schema definition. Here is one way to create the schema definition for our “best practice” scenario.

We start by defining the type for the antivirus application. Here we define a new complex type called AntiVirusType. It contains an element of type string whose name is ScanBootSector.

<xs:complexType name="AntiVirusType">
      <xs:sequence>
          <xs:element name="ScanBootSector" type="xs:string" />
      </xs:sequence>
</xs:complexType>

Next we define the type for the Automatic Updates configuration. Here we define a new complex type called WindowsUpdateType. It contains a single string type element called AutoUpdateStatus.

<xs:complexType name="WindowsUpdateType">
  <xs:sequence>
    <xs:element name="AutoUpdateStatus" type="xs:string" />
  </xs:sequence>
</xs:complexType>

Now we can define the element that is of the type for the computer system configuration called MyMachineConfigurationType. MyMachineConfigurationType contains two elements, AntiVirus and WindowsUpdate, whose type was defined in the earlier steps.

  <xs:element name="MyMachineConfiguration"
              type="tns:MyMachineConfigurationType"/>
…
<xs:complexType name="MyMachineConfigurationType">
  <xs:sequence>
    <xs:element name="AntiVirus" type="AntiVirusType" />
    <xs:element name="WindowsUpdate" type="WindowsUpdateType" />
  </xs:sequence>
</xs:complexType>

We complete the schema definition by adding the required XSD tags and namespace information to make this a fully qualified schema file. The full SML schema file for this scenario will be called "SampleBestPractice.xsd".

<?xml version="1.0" encoding="utf-8" ?> 
<xs:schema targetNamespace="urn:SampleBestPractice"
           elementFormDefault="qualified"
           xmlns:tns="urn:SampleBestPractice"
           xmlns:xs="https://www.w3.org/2001/XMLSchema">
  <xs:element name="MyMachineConfiguration" type="tns:MyMachineConfigurationType"/>
  <xs:complexType name="AntiVirusType">
        <xs:sequence>
            <xs:element name="ScanBootSector" type="xs:string" />
        </xs:sequence>
  </xs:complexType>

  <xs:complexType name="WindowsUpdateType">
        <xs:sequence>
            <xs:element name="AutoUpdateStatus" type="xs:string" />
        </xs:sequence>
  </xs:complexType>

  <xs:complexType name="MyMachineConfigurationType">        
        <xs:sequence>
            <xs:element name="AntiVirus" type="tns:AntiVirusType" />
            <xs:element name="WindowsUpdate" type="tns:WindowsUpdateType" />        
 </xs:sequence>
  </xs:complexType>
</xs:schema>

This completes our schema definition for the antivirus best practice configuration structure of our computer.

Additional considerations

An important thing to notice in this schema definition is that we decided to create separate types for the AntiVirus and WindowsUpdate elements. We could easily have defined them directly as elements of MyMachineConfigurationType and reduced the lines of code.

Why define the types separately? There are powerful advantages for defining the types separately:

  • It encourages reuse. The types can now be used to compose other aggregate types.
  • It reduces complexity. Specific information about the particular application configuration (the antivirus application in the example) is encapsulated within the type. The aggregate type or dependent types do not need to know about the antivirus application.
  • It promotes interoperability. Different schema authors can refer to same types and can author schemas which can be dependent on each other. The individual types form the foundation of a type library.

Step 2: Create the Schematron rules file based on the anitivirus constraints

We will now create a Schematron rules file, "SampleBestPractice.sch" to match the schema file created in Step 1: Create the SML schema based on the antivirus best practice configuration requirements. In Step 1 we defined two separate types, AntiVirusType and WindowsUpdateType. These two types have elements, ScanBootSector and AutoUpdateStatus.

From our prerequisite step, we found that ScanBootSector element must be set to a value of 1 to represent scanning the boot sector of the disk. As a result, we need to know when we violate our antivirus best practice. We can write a Schematron assertion to output a message when the ScanBootSector element is not set to the value 1.

<sch:assert id="ScanBootSector"   
   test="tns:AntiVirus/tns:ScanBootSector = '1'">
Antivirus scanner must be configured to scan boot sector.
</sch:assert>

We can use the same reasoning for the AutoUpdateStatus element. From our prerequisite step, we found that AutoUpdateStatus must be set to a value of 4 to represent configuring Automatic Updates to download updates and install them at a scheduled time. As a result, we need to know when we violate our antivirus best practice. We can write a Schematron assertion to output a message when the AutoUpdateStatus is not set to the value 4.

<sch:assert id="ScheduledWindowsUpdate"    
     test="tns:WindowsUpdate/tns:AutoUpdateStatus = '4'">
Windows Update must be configured for automatic scheduled installation.
</sch:assert>

We now have a Schematron rule file, "SampleBestPractice.sch". It contains one pattern with a single rule containing two assertions representing our antivirus best practice. The context of the rule has been set to the MyMachineConfigurationType which we defined in Step 1: Create the SML schema based on the antivirus best practice configuration requirements.

<schema
  xmlns="https://purl.oclc.org/dsdl/schematron"
  xmlns:sdmbpa="https://schemas.microsoft.com/sml/bpa/2007/03"
  xmlns:sdm="https://schemas.microsoft.com/sdm/2005/09">
  <ns prefix="tns" uri="urn:SampleBestPractice" />
  <pattern>
    <rule context="/MyMachineConfigurationType">
      <assert id="ScheduledWindowsUpdate"
                  test="tns:WindowsUpdate/tns:AutoUpdateStatus = '4'">
        Windows Update must be configured for automatic scheduled installation.
      </assert>
      <assert id="ScanBootSector"
                 test="tns:AntiVirus/tns:ScanBootSector = '1'">
        Antivirus scanner must be configured to scan boot sector.
      </assert>
    </rule>
  </pattern>
</schema>

Step 3: Create the discovery transform file based on the antivirus best practice configuration requirements and constraints

The final step in authoring an SML model is writing the SML discovery transform file, "SampleBestPractice.xsl". In this example, the Automatic Update configuration and antivirus configuration data that needs to be discovered resides in the Windows registry. For a full listing of sources of information provided with SML, see the Service Modeling Language Technical Reference (https://go.microsoft.com/fwlink/?LinkId=95309).

The exact registry subkeys were defined in the prerequisite step, which we will repeat here.

  • For our scenario, we have generalized the antivirus application as coming from Contoso Corporation. The fictitious antivirus application is configured using a registry subkey: HKLM\SOFTWARE\Contoso\CurrentVersion\Local Scanner\Scan BootSector. From the documentation we know the subkey must be configured to the value of 1 to represent scanning the boot sector.
  • For our scenario, we know from Automatic Updates documentation that the registry subkey HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\WindowsUpdate\Auto Update\AUOptions must be set to a value of 4. This represents configuring Automatic Updates to download updates and install them at a scheduled time.

The SML discovery provider library contains a “Registry Provider.” It provides the functionality to collect data from the registry. For more information about SML discovery providers, see the Service Modeling Language Technical Reference (https://go.microsoft.com/fwlink/?LinkId=95309).

There are many ways to create the SML discovery transform. Here is one way to create the discovery transform for our best practice scenario.

We start by creating the discovery template for the AntiVirusType schema.

<xsl:template name="DiscoverAntiVirus">
  <tns:AntiVirus>
    <tns:ScanBootSector>
      <xsl:value-of select="reg:keyValue('HKLM\SOFTWARE\ Contoso\CurrentVersion\Local Scanner\Scan BootSector')" />
    </tns:ScanBootSector>
  </tns:AntiVirus>
</xsl:template>

This template has been named DiscoverAntiVirus. The elements AntiVirus and ScanBootSector are provided, so the XML instance to be created conforms to the AntiVirusType schema. The registry discovery provider's keyValue function as part of the select attribute.

string keyValue(string keyName, string valueName)

where

Parameter Description

keyName

The key name, in the format [\\server\]hive[\keyPath].

valueName

The name of the value to retrieve. May be empty, in which case the "(Default)" registry value is retrieved.

Returns

The registry value as a string or an empty string if the key or the named value is not found.

This explains the two parameters being passed to the function and that the value returned is a string.

We next create the discovery template for creating an instance of WindowsUpdateType using the same registry discovery provider and calling the keyValue function, as part of the select attribute.

<xsl:template name="DiscoverWindowsUpdate">
  <tns:WindowsUpdate>
    <tns:AutoUpdateStatus>
      <xsl:value-of select="reg:keyValue('HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\WindowsUpdate\Auto Update', 'AUOptions')" />
    </tns:AutoUpdateStatus>
  </tns:WindowsUpdate>
</xsl:template>

We now create the discovery template for MyMachineConfigurationType. The MyMachineConfigurationType is an aggregate of the DiscoverAntiVirus and WindowsUpdateType templates to generate an instance of MyMachineConfigurationType.

<xsl:template name="DiscoverMyMachineConfiguration">
  <tns:MyMachineConfiguration>
    <xsl:call-template name="DiscoverAntiVirus" />
    <xsl:call-template name="DiscoverWindowsUpdate" />
  </tns:MyMachineConfiguration>
</xsl:template>

The last step is to create a parent XSLT style sheet to incorporate the above templates and initiate the transformation process. Each style sheet must contain a template that matches "/", which forms the root of the output document. The XSLT-based transformation process starts from this root.

<xsl:template match="/">
  <xsl:call-template name="DiscoverMyMachineConfiguration" />
</xsl:template>

We then combine all these portions of the discover transform into a complete file called "SampleBestPractice.xsl".

<?xml version="1.0" encoding="utf-8" ?>
<xsl:stylesheet version="1.0"                            xmlns:reg="https://schemas.microsoft.com/sml/xsl/registry/2007/03"
xmlns:tns="urn:SampleBestPractice">
  <xsl:template match="/">
    <xsl:call-template name="DiscoverMyMachineConfiguration" />
  </xsl:template>
  
  <xsl:template name="DiscoverAntiVirus">
    <tns:AntiVirus>
      <tns:ScanBootSector>
        <xsl:value-of select="reg:keyValue('HKLM\SOFTWARE\ComputerAssociates\eTrustAntivirus\CurrentVersion\Local Scanner', 'Scan BootSector')" />
      </tns:ScanBootSector>
    </tns:AntiVirus>
  </xsl:template>

  <xsl:template name="DiscoverWindowsUpdate">
   <tns:WindowsUpdate>
     <tns:AutoUpdateStatus>
       <xsl:value-of select="reg:keyValue('HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\WindowsUpdate\Auto Update', 'AUOptions')" />
     </tns:AutoUpdateStatus>
   </tns:WindowsUpdate>
  </xsl:template>

  <xsl:template name="DiscoverMyMachineConfiguration">
    <tns:MyMachineConfiguration>
      <xsl:call-template name="DiscoverAntiVirus" />
      <xsl:call-template name="DiscoverWindowsUpdate" />
    </tns:MyMachineConfiguration>
  </xsl:template>
</xsl:stylesheet>

Authoring SML models summary

We have now completed authoring our SML model. Our model consists of three files:

  1. A schema definition file (SampleBestPractice.xsd)
  2. A Schematron rule file (SampleBestPractice.sch)
  3. A discovery transform file (SampleBestPractice.xsl)

Next steps

These files are now ready to be used by administrators to check for compliance with their defined models and take action on non-compliance results. The Configuration Manager 2007 desired configuration management feature provides a set of tools and resources that can help assess and track configuration compliance of client computers in the enterprise. For more information about this tool, see Desired Configuration Management in Configuration Manager (https://go.microsoft.com/fwlink/?LinkId=95435).

Additional References