Getting Started

What is a profile manifest?

A profile manifest is a configuration file that describes the available keys, their types, and different restrictions they must conform to for a specific preference domain.

There are two levels of configuration in a profile manifest:

• Root Level
• Key Level

Root Level

The settings at this level define things like the preference domain, payload title and description, the availability for a specific platform or scope etc.

Key Level

At the key level you configure the individual preference keys available for the domain.

Each preference key is defined in a dictionary where it must set the key name, type and then all other settings to make it easier for the user to enter a correct value like a title, description, limit available values etc.

The key level are all settings in the pfm_subkeys array that must exist at the root of the manifest.

Key Reference

All available keys used to configure payload manifests are described on the Manifest Format page.

How to create a profile manifest

1. Download the manifest template

Start by downloading the manifest template that includes all required keys for a valid manifest:

Manifest Template Link

Name your manifest with the domain you are working with and place it in this folder:

~/Library/Application Support/ProfilePayloads/Manifests/ManagedPreferencesApplications

2. Enable the Developer Menu

1. Launch ProfileCreator.
2. Open Preferences.
3. Click Advanced and enable "Show Developer menu in menu bar".

Verify that you see a menu item called "Developer" in the menu bar that contains the menu item: "Reload Payload Manifest".

3. Verify that the manifest template shows up in ProfileCreator

1. Launch ProfileCreator.
2. Create a new Profile.
3. Click the Application manifests icon in the manifest library.

Verify that you see a payload without an icon called "Example Application".

4. Edit the manifest root keys

Open the manifest in your favorite text editor, preferably with support for XML highlighting like VSCodium, Atom or BBEdit to name a few.

The root of the manifest means all keys contained within the first <dict> tag except the pfm_subkeys key.

The following keys are required at the root of the manifest for it to be loaded by the framework:

• pfm_description
• pfm_domain
• pfm_format_version
• pfm_last_modified
• pfm_title
• pfm_unique
• pfm_version
• pfm_subkeys

You can read more about each key on the manifest format page, or in the comments in the manifest template.

Update each key with the values for your payload, following the comments in the manifest template.

5. Edit the required manifest subkeys

Once you have edited your information in the manifest root you should configure the default values of the following required manifest subkeys:

• PayloadDescription
• PayloadDisplayName
• PayloadIdentifier
• PayloadType

The lines you should update are marked with the comment <!-- CHANGE THIS VALUE -->

The following keys must also be included, but you should NOT modify them:

• PayloadUUID
• PayloadVersion
• PayloadOrganization

Below the comment <!-- *..* APPLICATION KEYS *..* --> is where you should put every key this manifest domain can configure.

In the manifest template you downloaded there are a number of example keys to show how to configure different value types and settings.

You should remove all example keys in your final manifest, but during the development you can use them as a base to understand how to configure the keys you want.

6. Install & Enable pre-commit

Pre-commit is an easy way of catching common errors and helping to ensure standardization within a code project. Whether or not you are a regular open source contributor, installing this is really important in this project for ensuring we don't inadvertently break things.

1. Install pre-commit via your preferred method.
2. Once, installed open a Terminal window and navigate to your ProfileManifests fork.
3. Enable pre-commit by running: pre-commit install.

7. Development Cycle

Whenever you make changes to the manifest plist, you can use the developer menu you enabled to reload the manifests to show your changes.

Use that to quickly test and verify the changes you made so the application displayed each key the way you intended.

The developer menu also holds another menu item called "Show Payload Manifest" that will show you the current XML it is using for the selected payload.

That can be used to verify your changes made it to the app, or if you want to look at how a key in another payload was defined.

How to create more complex rules and nested keys is not covered in this getting started guide. That will be added later to the wiki.

Need additional help?

If you have questions or need any help whatsoever in contributing to this repository, join the #profilemanifests channel in the MacAdmins Slack.