Outermost Dictionary

The outermost dictionary contains manifest keys that describe the preference manifest file in general. Some manifest keys are only valid in the outermost dictionary.

The outermost dictionary typically contains the following manifest keys:

• a pfm_description key that provides a general description of the preference manifest file.

• a pfm_title key that provides a name that will be shown in Workgroup Manager’s Preference Manifest Editor as the name for the application’s preferences as a whole

• a pfm_format_version key that specifies the preference manifest format version the file uses; this key is only valid in the outermost dictionary

• a pfm_version key that specifies the version number for this preference manifest file so that it can be distinguished from other versions that might be released; this key is only valid in the outermost dictionary

• a pfm_domain key specifying the application domain for this preference manifest file, such as com.apple.myapp, where myapp is the typically name of the application’s bundle ID, which is specified in the application’s info.plist and is the name that the application uses to retrieve preferences through the CPPreferences or NSUserDefaults API calls.

• a pfm_subkeys key indicating that an array of dictionaries follows, with each dictionary using keys to describe a preference

Here is an example of an outermost dictionary for an application named myapp:

<dict>

    <key>pfm_description</key>

    <string>Configurable preferences for MyApp.</string>

    <key>pfm_title</key>

    <string>myapp</string>

    <key>pfm_format_version</key>

    <real>1.0</real>

    <key>pfm_version</key>

    <real>0.9</real>

    <key>pfm_domain</key>

    <string>com.apple.myapp</string>

    <key>pfm_subkeys</key>

Inner Dictionaries

The outermost dictionary is followed by a series of inner dictionaries that can contain other dictionaries.

Here is an example of an inner dictionary that might follow the pfm_subkeys key in the sample outermost dictionary:

        <array>

            <dict>

                <key>pfm_name</key>

                <string>autohide</string>

                <key>pfm_title</key>

                <key>Hiding</key>

                <key>pfm_type</key>

                <string>boolean</string>

                <key>pfm_default</key>

                <false/>

                <key>pfm_description</key>

                <string>True to turn hiding on.</string>

                <key>pfm_targets</key>

                <array>

                    <string>user</string>

                    <string>user-managed</string>

                </array>

            </dict>

            // Other dictionaries containing manifest keys that  describe

            // preference keys.

        </array> // End of the array of dictionaries.

    </dict> // End of the preference manifest file.

In the example of an inner dictionary,

• the pfm_name key defines the name (autohide) of the preference key.

• the pfm_title key specifies the user-visible name shown in the Workgroup Manager’s Preference Manifest Editor.

• the pfm_type key defines boolean as the data type of this preference key.

• the pfm_default key defines the default value of this preference key as false.

• the pfm_description key provides, in this case, a reminder that to enable this preference key, it’s value should be set to true. You can use the pfm_description key to provide any instructions or information needed for the proper setting of this preference key.

• the pfm_targets key specifies when and where this preference key should be used by OS X client management software to properly manage a user or computer. In this example, user specifies that the key may be set in a user’s preferences (at ~/Library/Preferences/com.apple.myapp.plist) and user-managed specifies that the key may be set in a user’s managed preferences (at /Library/Managed Preferences/username/com.apple.myapp.plist, where username is the logged in user’s short name).

Default Values

If a manifest key is not defined for a preference key, Workgroup Manager uses context and usage to determine a default value for the undefined key. If a default value cannot be determined, the preference key or the entire preference manifest file may be ignored.

Using the pfm_domain Key

The recommended approach is for each preference manifest file to specify just one domain. When a preference manifest file specifies one domain, the pfm_domain manifest key does not have to be specified for each preference key. When the pfm_domain is not specified for a preference key, the Workgroup Manager gets the domain for the preference key from the pfm_domain key in the outermost dictionary. Here is an example:

<key>pfm_format_version</key>

<real>1.0</real>

<key>pfm_version</key>

<real>1.0</real>

<key>pfm_domain</key>

<string>com.apple.myapp</string>

<key>pfm_subkeys</key>

<array>

    <dict>

        <key>pfm_name</key>

        <string>Preference One</string>

        // Additional information for “Preference One”

        <key>pfm_name</key>

        <string>Preference Two</key>

        // Additional information for “Preference Two”

    </dict>

</array>

In this example, the domain for Preference One and Preference Two is com.apple.myapp as specified by the pfm_domain key in the outmost dictionary.

Although doing so is not recommended, it is possible to specify more than one domain in a preference manifest file. Here is an example:

<key>pfm_format_version</key>

<real>1.0</real>

<key>pfm_version</key>

<real>1.0</real>

<key>pfm_subkeys</key>

<array>

    <dict>

        <key>pfm_name</key>

        <string>Preference One</string>

        // Additional information for “Preference One”

        <key>pfm_domain</key>

        <string>com.apple.myapp1</string>

        <key>pfm_name</key>

        <string>Preference Two</string>

        // Additional information for “Preference Two”

        <key>pfm_domain</key>

        <string>com,apple.myapp2</string>

    <dict>

</array>

Values for the pfm_targets Key

The value of the pfm_targets key is an array consisting of any combination of user, user-managed, and system-managed. These values tell the MCX client when (before or after login) to process the preference keys for a particular application domain.

The value of the pfm_targets key works in conjunction with settings made by the administrator that indicate when an application preference should be processed:

• Always — This is an application preference that is set and cannot be changed.

• Once — This is an application preference that is set but can be permanently changed.

• Often— This is an application preference that is set and can be temporarily changed. When the user logs back in the preference is set to its original value.

It is up to the application to conform to these settings and display the correct user interface.

When user is a value of the pfm_targets key, any application preferences set by the administrator to Once and Often are processed just after authentication and before any user applications run. The key may be set in a user’s preferences at ~/Library/Preferences/com.apple.myapp.plist.

When user-managed is a value of the pfm_targets key, any application preferences set by the administrator to Always are processed just after authentication and before any user applications run. The key may be set in a user’s managed preferences at ~/Library/Managed Preferences/username/com.apple.myapp.plist. where username is the short name of the logged-in user.

When system-managed is a value of the pfm_targets key, any application preferences set by the system administrator to Always are processed at startup time and after every user logout. For example, the preference that controls whether to show loginwindow with a list of users or with a field in which the user’s name is entered has to processed before any user logs in. The key will be set in a property list file (.plist) in /Library/Managed Preferences/.

In actual practice, an application preference can be set anytime before the application runs. Log in is a convenient time because no user applications or processes have run yet. In this release, an application preference can activate at any time, such as waking from sleep, the computer is plugged into the network, or after a certain amount of time has elapsed. The preferences take effect immediately, but an application may not notice newly activated preferences until the applications are relaunched.

Defining a Preference Key of Type Alias

A preference key whose pfm_type is alias causes the Workgroup Manager’s Preference Manifest Editor to allow you to specify an alias to a file or folder. The data corresponding to the alias record is stored in the preference data as a data plist type.

Here is a sample definition for a preference key whose pfm_type is alias:

<key>pfm_name</key>

<string>backupVolume</string>

<key>pfm_type</key>

<string>alias</string>

<key>pfm_title</key>

<string>Backup Volume</string>

<key>pfm_description</key>

<string>Alias to the backup volume</string>

<key>pfm_targets</key>

<array>

    <string>user</string>

    <string>user-managed</string>

</array>

Defining a Preference Key of Type Array

Here is a sample definition for a preference key whose pfm_type is array:

<key>pfm_name</key>

<string>OptionCheckboxStringsTemp</string>

<key>pfm_type</key>

<string>array</string>

<key>pfm_default</key>

<array>

    <string>antialias</string>

    <string>fullcolor</string>

</array>

<key>pfm_title</key>

<string>Checkbox Strings</string>

<key>pfm_description</key>

<string>One array element for each visible checkbox containing  the internal name of  that checkbox.</string>

<key>pfm_targets</key>

<array>

    <string>user</string>

    <string>user-managed</string>

</array>

<key>pfm_subkeys</key>

<array>

    <dict>

        <key>pfm_description</key>

        <string>Checkbox string values.</string>

        <key>pfm_name</key>

        <string>checkboxnames</string>

        <key>pfm_rangelist</string>

        <array>

            <string>antialias</string>

            <string>fullcolor</string>

            <string>invertcolor</string>

        </array>

        <key>pfm_repetition_max</key>

        <integer>3</integer>

        <key>pfm_repetition_min</key>

        <integer>0</integer>

        <key>pfm_title</key>

        <string>Checkbox name</string>

        <key>pfm_type</key>

        <string>string</string>

    </dict>

</array>

Defining a Preference Key of Type Boolean

Here is a sample definition for a preference key whose pfm_type is boolean.

<key>pfm_name</key>

<string>reverseHilite</string>

<key>pfm_type</key>

<string>boolean</string>

<key>pfm_default</key>

<false/>

<key>pfm_title</key>

<string>Reverse Highlighting</string>

<key>pfm_description</key>

<string>Set to true for black on white highlighting.</string>

<key>pfm_targets</key>

<array>

    <string>user</string>

    <string>user-managed</string>

</array>

Defining a Preference Key of Type Date

Here is a sample definition for a preference key whose pfm_type is date.

<key>pf_domain</key>

<string>com.apple.myapp</string>

<key>pfm_name</key>

<string>database creation time</string>

<key>pfm_type</key>

<string>date</string>

<key>pfm_title</key>

<string>Database Creation Date</string>

<key>pfm_description</key>

<string>Date when the main database was created.</string>

<key>pfm_targets</key>

<array>

    <string>user</string>

    <string>user-managed</string>

</array>

Defining a Preference Key of Type Data

Here is a sample definition for a preference key whose pfm_type is data.

<key>pfm_name</key>

<string>preference data</string>

<key>pfm_type</key>

<string>data</string>

<key>pfm_title</key>

<string>Database Bit Flags</string>

<key>pfm_description</key>

<string>Database Bit Flags. 10 bytes long.</string>

<key>pfm_targets</key>

<array>

    <string>user</string>

    <string>user-managed</string>

</array>

Defining a Preference Key of Type Dictionary

Here is a sample definition for a preference key whose pfm_type is dictionary.

<key>pfm_name</key>

<string>document objects</string>

<key>pfm_type</key>

<string>dictionary</string>

<key>pfm_title</key>

<string>Document Object Dictionary</string>

<key>pfm_description</key>

<string>Dictionary of document objects.</string>

<key>pfm_targets</key>

<array>

    <string>user</string>

    <string>user-managed</string>

</array>

<key>pfm_subkeys</key>

<array>

    <dict>

        <key>pfm_name</key>

        <string>Preference One</string>

        // Other keys describing this preference.

    </dict>

    <dict>

        <key>pfm_name</key>

        <string>Preference Two</string>

        // Other keys describing this preference.

    </dict>

</array>

Defining a Preference Key of Type Integer

Here is a sample definition for a preference key whose pfm_type is integer.

<key>pfm_name</key>

<string>zoom factor</string>

<key>pfm_type</key>

<string>integer</string>

<key>pfm_default</key>

<integer>100</integer>

<key>pfm_range_max</key>

<integer>1000</integer>

<key>pfm_range_min</key>

<integer>0</integer>

<key>pfm_title</key>

<string>Zoom Factor</string>

<key>pfm_description</key>

<string>Document zoom factor. Only multiples of 10 are valid.</string>

<key>pfm_targets</key>

<array>

    <string>user</string>

    <string>user-managed</string>

</array>

Defining a Preference Key of Type Real

Here is a sample definition for a preference key whose pfm_type is real. In this example, pfm_range_max is not specified, so the Workgroup Manager would use the default, +<infinity>. The pfm_description key is not specified, so the preference key has no description.

<key>pfm_name</key>

<string>scaling</string>

<key>pfm_type</key>

<string>real</string>

<key>pfm_default</key>

<real>1.0</real>

<key>pfm_range_min</key>

<real>0.01</real>

<key>pfm_title</key>

<string>Scaling Factor</string>

<key>pfm_targets</key>

<array>

    <string>user</string>

    <string>user-managed</strings>

</array>

Defining a Preference Key of Type String

Here is a sample definition for a preference key whose pfm_type is string.

<key>pfm_name</key>

<string>input source</string>

<key>pfm_type</key>

<string>string</string>

<key>pfm_default</key>

<string>file</string>

<key>pfm_range_list</key>

<array>

    <string>file</string>

    <string>network</string>

</array>

<key>pfm_title</key>

<string>Input Source</string>

<key>pfm_description</key>

<string>Input can be taken from a file or the network.</string>

<key>pfm_targets</key>

<array>

    <string>user</string>

    <string>user-managed</string>

</array>

Defining a Preference Key of Type Union Policy

Union policy keys provide a way to specify behavior when two or more preference keys come into play as the result of a single event. Consider the case of what application tiles should appear in the application dock. For example, the following could be specified:

• that all computers show “Calculator” in the dock

• that Workgroup “MyWorkGroup” shows “DVD Player” in the dock

• that user “Jimmy” shows “TextEdit” in the dock

When “Jimmy” (who belongs to workgroup “MyWorkGroup”) logs in, what should appear in his dock? Just “TextEdit” or should “Calculator,” “DVD Player,” and “TextEdit” be in his dock?

Union policy keys set up rules so that array or dictionary keys found in user, group, or computer list records can be merged into a single array or dictionary in the resulting preference file.

The following example specifies a union policy for application tiles in:

<key>pfm_description</key>

<string>Application tiles union policy keys for user domain</string>

<key>pfm_name</key>

<string>appTilesUPKUser</string>

<key>pfm_remove_duplicates</key>

<true/>

<key>pfm_targets</key>

<array>

    <string>user</string>

</array>

<key>pfm_title</key>

<string>Application Tiles Union Policy - User</string>

<key>pfm_type</key>

<string>union policy</string>

<key>pfm_upk_input_keys</key>

<array>

    <string>AppItems-Raw</string>

</array>

<key>pfm_upk_output_name</key>

<string>persistent-apps</string>

<key>pfm_upk_output_type</key>

<string>array</string>

Defining a Preference Key of Type URL

A preference key whose pfm_type is url causes the Workgroup Manager’s Preference Manifest Editor to allow you to choose a file or folder. If you choose a .webloc file, the URL contained within the .webloc file is extracted and stored as a string type in the preference data. If you choose a file that is not a .webloc file, a file://-based URL is created to the selected file and this URL is stored as a string in the preference data.

Here is a sample definition for a preference key whose pfm_type is url.

<key>pfm_name</key>

<string>help source</string>

<key>pfm_type</key>

<string>url</string>

<key>pfm_default</key>

<string>http://help.apple.com</string>

<key>pfm_title</key>

<string>Web Help URL</string>

<key>pfm_description</key>

<string>Web-based help url.</string>

<key>pfm_targets</key>

<array>

    <string>user</string>

    <string>user-managed</string>

</array>