Associating .admx and .adml Parameter Information

Applies To: Windows Server 2008

ADM files use the PART statement to define a single parameter for a policy setting. In the ADMX syntax, the elements controlling the presentation or localized display of a parameter, are defined in the .adml file. The information defining the datatype and value of a parameter are defined in the .admx file. This section will describe how the different elements from the two files, .admx and .adml, are used to create parameter definitions for policy settings.

We will use an example of creating two check box parameters for a single policy setting to illustrate how the .admx and .adml files work together to define parameters. This example is a fragment taken from the example2.admx and example2.adml sample files. For more information about downloading and importing the sample files into the Group Policy Object Editor, see Sample Files.

This XML fragment shows the policy setting from the .admx file that includes two check box parameters.

    <policy name="Sample_Checkbox" class="Machine"
            displayName="$(string.Sample_Checkbox)"
            explainText="$(string.Sample_Checkbox_Help)"
            presentation="$(presentation.Sample_Checkbox)"
            key="Software\Policies\Examples">
      <parentCategory ref="CHECKBOXTWOTYPES_CATEGORY" />
      <supportedOn ref="windows:SUPPORTED_ProductOnly" />
      <elements>
        <boolean id="Checkbox_1" valueName="Example2Checkbox1">
          <trueValue>
            <decimal value="1" />
          </trueValue>
          <falseValue>
            <decimal value="0" />
          </falseValue>
        </boolean>
        <boolean id="Checkbox_2" valueName="Example2Checkbox2">
          <trueValue>
            <decimal value="0" />
          </trueValue>
          <falseValue>
            <decimal value="1" />
          </falseValue>
        </boolean>
      </elements>
    </policy>

This XML fragment shows the corresponding presentation information from the .adml file.

      <presentation id="Sample_Checkbox">
        <checkBox refId="Checkbox_1">First check box parameter</checkBox>
        <checkBox refId="Checkbox_2" defaultChecked="true">Second check box parameter - checked by default</checkBox>
      </presentation>

These two XML fragments provide a starting point for looking at the coordination between parameter definitions in .admx and .adml files. We will look at two areas of coordination between the .admx and .adml files. The first is the top level referencing between the policy setting and its parameter display. The second is the referencing between datatype representation in the elements element and the parameter definition in the presentation element.

Referencing the presentation element

A policy setting defined through the policy element in an .admx file references a specific presentation element in the .adml file through the presentation attribute of the policy element. Using the example for the two check boxes, you can see the presentation attribute is defined as presentation="$(presentation.Sample_Checkbox)". The presentation.Sample_Checkbox text tells the Group Policy Object Editor to reference the .adml file presentationTable element using the id attribute set to Sample_Checkbox. The presentation element with this id attribute was provided above and is repeated here with this XML fragment.

      <presentation id="Sample_Checkbox">
        <checkBox refId="Checkbox_1">First check box parameter</checkBox>
        <checkBox refId="Checkbox_2" defaultChecked="true">Second check box parameter - checked by default</checkBox>
      </presentation>

You may wonder how the Group Policy Object Editor finds the correct .adml file to look up the presentation element. The answer is simple. The Group Policy Object Editor will search the .adml file with the same filename as the .admx file. The Group Policy Object Editor will display an error message if it cannot find a corresponding .adml file for each .admx file it reads.

The number of datatypes as well as the type of datatype (boolean, decimal, text, enum, item, and list) defined in the .admx elements element must match the number and type of the parameters defined in the .adml presentation element (checkBox, textBox, decimalTextBox, comboBox, dropdownList, and listBox). We will cover how to match the datatypes to the parameter definitions in the next section.

Referencing the parameter definition

You can match the number of datatypes defined in an elements element to the number of parameters identified in the presentation element, if you collapse the elements. In our example, the elements element contains two boolean elements:

      <elements>
        <boolean id="Checkbox_1" valueName="Example2Checkbox1">
           …
        </boolean>
        <boolean id="Checkbox_2" valueName="Example2Checkbox2">
          …
        </boolean>
      </elements>

The presentation element contains two checkBox elements:

      <presentation id="Sample_Checkbox">
        <checkBox refId="Checkbox_1">…</checkBox>
        <checkBox refId="Checkbox_2" defaultChecked="true">…</checkBox>
      </presentation>

The number of boolean elements (2) matches the number of checkBox elements (2). You use the id attribute of the boolean element to match the associated checkBox element referred to using the refId attribute.

The below table shows how to match the datatype in the .admx file, which is the boolean element in our example, with the parameter definition in the .adml file, which is the checkBox element in our example.