Windows Server 2008 and Windows Vista : Migrating .adm Templates to ADMX Files

Companies and administrators that have spent time creating custom .adm templates have two options for using those files in a Windows Server 2008 or Windows Vista environment. Because .adm templates are supported, they can be placed in the GPT of the GPO, and nothing else needs to be done. However, if you want to eliminate all .adm templates from the GPT of each GPO and still make the settings available to all administrators, the .adm templates and their settings must be migrated to an ADMX file.

Depending on the complexity of the .adm templates and the settings contained within them, the migration can either be very simple or quite complex. If only a few settings exist in an .adm template, it might be advantageous to manually migrate it to an ADMX file. However, if the .adm templates contain numerous settings that offer a complex array of setting options within the GPME, migrating them using the ADMX Migrator might be a better option.

Direct from the Source: Automatically Importing .adm Files into Windows Server 2008 and Windows Vista

If you copy your custom .adm file into the %windir%\inf directory, the GPME will automatically import into any GPO that is edited, relieving you of having to manually add the file to each GPO in which you want to use the custom settings. The disadvantage is that all GPOs that you edit will have the extra files added to the GPT.

Judith Herman, Programming Writer, Microsoft

File Syntax Conversion for .adm Template to ADMX Files

The syntax for an .adm template is similar to that of an ADMX file, but there are differences that need to be tracked and understood. Because both files create the interface within the GPME and define the registry information that will be updated, the settings will be a near duplication between the two formats. However, the two file formats use different syntax names, as defined in Table 1.

Table 1. File Syntax Conversion for .adm Template to ADMX

.adm Template Language Reference	.admx File Language Reference	.adml File Language Reference	Conversion Comments
Adm File Language Versions (#If Version)	revision	revision	Unlike ADM files, the ADMX file has versioning built in and is not tied to an operating system version.
comments (;)	Annotation <!-- -->	Annotation <!-- -->	For ADM files, all text following the “;” is considered a comment. For ADMX files, neither the Annotation element or the XML comments will not be processed by Group Policy tools.
Strings reference (!!)	string		In .adm templates, precede text with “!!” to reference a string.
<Strings> section of the .adm file		stringTable
CLASS	class		ADMX files provide the ability to classify the policy definition as being for user, machine, or both. The “both” classification allows you to create a single policy definition that applies to the machine and user registry keys.
CATEGORY	categories category parentCategory		ADM files assume categories are nested within the definitions. ADMX files specify a parentCategory element for each policy element defined in the ADMX file. An individual category is defined within the categories element.
Duplicate Category Sections allowed in different ADM files	Duplicate category sections are not allowed in different ADMX files.		If one .adm file includes a duplicate CATEGORY entry used in a different existing .adm file, the policy settings will be merged when the Group Policy object Editor processes the ADM files. ADMX files have unique namespaces. Defining the same category element names in two different ADMX files will cause the category to be displayed twice. For ADMX files, you must define the category element name once and then reference the category element name with the using element.
SUPPORTED	supportedOn
POLICY	policies policy		In the ADMX file, the policies element contains individual policy elements that correspond to a policy setting.
PART	elements	presentation	In ADM files, the PART statement specifies various policy setting options, such as drop-down list boxes, text boxes, and text in the lower pane of the Group Policy snap-in. ADMX files aggregate policy setting options for one policy setting into the elements element in the ADMX file and the presentation element in the ADML file.
CHECKBOX	boolean	checkbox
TEXT		text	The text element in the .adml file provides the string used as the parameter text prompt.
EDITTEXT	text	textBox
NUMERIC	decimal	decimalTextBox
COMBOBOX	text	comboBox
DROPDOWNLIST	enum item	dropdownList
LISTBOX	list	listBox
VALUEON	enabledValue
VALUEOFF	disabledValue
ACTIONLISTON	enabledList
ACTIONLISTOFF	disabledList
KEYNAME	key
EXPLAIN	explainText
VALUENAME	valueName
CLIENTEXT	clientExtension
END			XML syntax includes termination of all its elements. There is no need to use special syntax to terminate an element.
DEFCHECKED		defaultChecked
Line Breaks \n or \n\n		Use link breaks or blank lines within the string definitions.
Maximum string length for EXPLAIN text		Limited by available memory only.
Maximum string length for CATEGORY EXPLAIN text		Limited by available memory only.
Maximum string length for EDITTEXT string		Maximum string length for EDITTEXT string = 1023 characters.

ADMX Migrator

The migration of .adm templates into ADMX files is not a simple task. The preceding information provides all of the details needed to migrate an .adm template to an ADMX file. However, as you can see, the process would not be simple because the structure, syntax, and formatting for each of the files is completely different.

One solution is to use ADMX Migrator, developed by FullArmor Corporation. At the time of publication, the tool is in version 1.2. It can be downloaded from the Microsoft Download Center at http://www.microsoft.com/downloads/details.aspx?FamilyID=0f1eec3d-10c4-4b5f-9625-97c2f731090c&DisplayLang=en.

The tool comes with two solutions, which provide two major functions:

• ADMX Editor

  • Edit ADMX files

  • Convert .adm templates to ADMX files

• ADMX Migrator Command Options

The ADMX Editor is an excellent interface for viewing and updating your ADMX files. It breaks down the ADMX file into the different areas of the XML formatted file. Figure 1 illustrates one of the default ADMX files viewed in the ADMX Editor, showing the areas of the file on the tabs.

Figure 1. The ADMX Editor allows you to view and modify the contents of any AMDX file.

The ADMX Editor also allows you to migrate .adm templates to ADMX files. This process is quite simple: When you click the ADMX Editor node within the tool, the Generate ADMX From ADM option allows you to perform the conversion. Figure 2 shows the migration option, as well as the result of an .adm template that has been migrated to an ADMX file.

Figure 2. The ADMX Editor also provides support for migrating .adm templates to ADMX files.

Note that some conversion issues could arise. The most common issues are related to the areas listed in Table 2.

Table 2. ADMX Migrator Common Issues and Solutions

Migration Issue	Solution
Duplicate policy name	Edit the .adm template to ensure that POLICY names are unique from one another.
Missing SUPPORTED on values	Edit the .adm template and add the SUPPORTED on value with information for each POLICY entry.
Unresolved strings	Edit the .adm template and ensure that each string reference (!! syntax) has an associated string entry in the file.

Finally, ADMX Migrator provides you with a full suite of command-line tools and switches to migrate .adm templates to ADMX files. The tool allows you to control nearly every aspect of the migration. Table 3 lists the switches that can be used with the ADMX Migrator command-line feature.

Table 3. ADMX Migrator Command-Line Options

Switch	Function
Source	Specifies the name of the ADM template that you want to convert.
Targetpath	Specifies the target folder where you want to save the converted ADMX template. If you do not specify a target path, ADMX Migrator saves the converted ADMX template in the \Documents\UserName\Local Settings\Temp folder, where UserName is the name of the user who is logged on to the computer on which you installed ADMX Migrator.
/X	Specifies ADMX as the type of the target file.
/L	Specifies ADML as the type of the target file.
/N:name	Specifies the display name XML element in the ADML file.
/D:description	Specifies the description XML element in the ADML file.
/R:revision	Specifies the revision number of the ADMX file. The Group Policy Object Editor checks this number when loading ADMX templates. The Group Policy Object Editor will not load ADMX templates with revision numbers that do not meet the requirements of the version of Group Policy Object Editor installed on the computer.
/P:prefix	Specifies the target element prefix used in the ADMX file.
/S:namespace	Specifies the namespace XML element in the ADMX file.
/U:prefix	Specifies the using element prefix used in the ADMX file.
/C:namespace	Specifies the namespace XML element in the ADMX file.