Custom Declarations

Declarations are a component of Apple's Declarative Device Management (DDM) protocol that are used for configuring devices. They can be used to apply configurations, assets, accounts, and even applications.

Currently, from an admin perspective, declarations work similar to configuration profiles in the SimpleMDM interface. 

Please note - this is advanced feature and if improperly used, it is possible for a device to end up in a bad state that could potentially require re-enrollment to resolve. Please test thoroughly before deploying to production devices.

Creating a custom declaration

To create a custom declaration in the SimpleMDM interface:

1. Navigate to the Configs > Profiles section.
2. Click "Create Profile".
3. Select "Custom Declaration".
4. Give the declaration a name.
5. In the "Type" field, enter the declaration type. For example, com.apple.configuration.safari.settings.

6. In the "Payload" field, either enter the JSON payload for the declaration into the text editor, or upload a JSON file containing the payload contents. Note: Only the contents of the payload need to be included - Type, Identifier, ServerToken, etc. will be included automatically. For example:

   {
    "NewTabStartPage": {
      "PageType": "Home",
      "HomepageURL": "https://www.wikipedia.org"
    }
   }

7. [Optional] Check the "Enable attribute support" box if you wish to use custom attributes in your declaration.
8. [Optional] Check the "Escape attributes" box if you need to escape special characters in the custom attribute values.
9. [Optional] Enter predicate syntax into the "Activation predicate" field if you wish to use a custom predicate.
10. Click 'Save' once you are done and assign the declaration to your devices like you would any other profile.

Resources for creating custom declarations:

• Apple MDM Developer documentation - Declarations
• Apple MDM Documentation Github Repo - Declarations

Custom Declarations API:

SimpleMDM supports the ability the create and manage custom declarations via API. Documentation for the Custom Declarations API is available here: https://api.simplemdm.com/v1#custom-declarations.

Predicates

Predicates are essentially conditional expressions that can be included in declarations. When a declaration is installed with a predicate, Apple operating systems that support DDM will evaluate the predicate to determine under what conditions the declaration should be activated. This allows admins to install a declaration ahead of time but only have it take affect once a device meets certain conditions.

Predicates allow admins to create powerful, complex workflows that automatically update as the device state changes. For example, an admin could create an email account configuration that only activates once the user has configured a passcode that meets the requirements of a passcode policy configuration.

Predicates use a specific syntax that looks like, for example:

(@status(device.model.family) == 'iPad')

This expression evaluates whether the status item reports the device model family as "iPad". If this expression evaluates to true, the declaration will be activated.

Further reading on activations, predicates, & predicate syntax:

• Apple MDM docs - Use activation declarations to apply logic to your configurations
• Apple Developer docs - Intro to predicates
• Apple Developer docs - Creating predicates