Application & Custom Settings
Create a streamlined user experience for customizing macOS application settings and configurations
Overview
Beginning with Jamf Pro v10.19.0 administrators can customize their own JSON schema in the Application & Custom Settings payload of a computer configuration profile. This additional functionality allows administrators to enter a Jamf manifest in JSON schema format for an application that is not currently in the Jamf Repository. Jamf Technology Partners can leverage this functionality and provide custom manifest to make deployment of application settings in Jamf Pro easier for administrators. Continue reading to learn more about the technology, or contact your Technology Partner Manager to learn more about getting your application listed in the Jamf Repository.
Why use Application & Custom Settings
The Application & Custom Settings feature for macOS is akin to App Config for iOS. In addition to providing a defined process for apps to read data provided by MDM vendors, Jamf Pro includes a graphical user interface for administrators to customize the settings and values they're providing to supported apps. Previously this was done via the use of an uploaded plist file, which needed to be edited outside of Jamf Pro or entirely within the scope of the application with no customization available via the enterprise deployment solution.
Application Development
In order to leverage the Application & Custom Settings functionality in Jamf Pro, developers must configure their application to read settings from managed macOS devices. Settings should be stored in a preference domain where they will be accessible using the CFPreferences, NSUserDefaults or UserDefaults APIs.
Jamf also recommends disabling any end-user facing interfaces that are "forced". Settings that are "forced" are being applied via the managed settings and should not be accessible for users to interact with. For example, if your application includes a preference to configure a specific setting, when managed via Application & Custom Settings, users should not be presented with the option to configure this setting as the value is already "forced".
Level of the profile dictates which location the file is deployed to on managed devices.
Jamf Manifests
A properly structured Jamf manifest must be created in order for Jamf Pro to correctly deploy settings to macOS devices. The JSON schema consists of a header and multiple application properties. The header should include a title and description and can also include additional helpful information. Each application property will also contain a title and description in addition to a type field that defines the data type of the property. Various types will include additional fields relevant to the particular type. The following is a sample JSON schema that defines a variety of application properties for a sample application.
{
"title": "Disk Manager (com.company.diskmanager)",
"description": "Preference settings for the fictitious Disk Manager application. This manifest demonstrates different ways to format the appearance or value of properties as well as include useful options like infoText. Jamf Pro supports many but not all elements and options here: https://github.com/json-editor/json-editor.",
"properties": {
"askForPasswordDelay": {
"title": "Ask For Password Delay",
"description": "Disk Manager will wait the selected amount of time before requiring a password.",
"property_order": 5,
"type": "integer",
"options": {
"enum_titles": [
"immediately",
"5 seconds",
"1 Minute",
"5 Minutes",
"15 Minutes",
"1 Hour",
"4 hours",
"8 hours"
],
"infoText": "Keyword: askForPasswordDelay"
},
"links": [
{
"rel": "More information",
"href": "https://json-schema.org/understanding-json-schema/reference/type.html"
}
],
"enum": [
0,
5,
60,
300,
900,
3600,
14400,
28800
]
},
"diskCacheSize": {
"title": "Disk Cache Size",
"description": "Set disk cache size, in bytes.",
"default": 25600,
"property_order": 10,
"type": "integer",
"options": {
"infoText": "Keyword: diskCacheSize"
},
"links": [
{
"rel": "More information",
"href": "https://json-schema.org/understanding-json-schema/reference/type.html"
}
]
},
"primaryServer": {
"title": "Primary Server",
"description": "Disk Manager will default to this server.",
"property_order": 15,
"type": "string",
"options": {
"enum_titles": [
"Server 1",
"Server 2",
"Server 3"
],
"infoText": "Keyword: primaryServer"
},
"links": [
{
"rel": "More information",
"href": "https://json-schema.org/understanding-json-schema/reference/type.html"
}
],
"enum": [
"https://server1.company.com",
"https://server2.company.com",
"https://server3.company.com"
]
},
"downloadDirectory": {
"title": "Download Directory",
"description": "Choose the default location for downloading working files.",
"property_order": 20,
"type": "string",
"options": {
"infoText": "Keyword: downloadDirectory"
},
"links": [
{
"rel": "More information",
"href": "https://json-schema.org/understanding-json-schema/reference/type.html"
}
]
},
"askForPassword": {
"title": "Ask For Password",
"description": "Set Disk Manager application to require a password.",
"property_order": 25,
"type": "boolean",
"options": {
"infoText": "Keyword: askForPassword"
},
"links": [
{
"rel": "More information",
"href": "https://json-schema.org/understanding-json-schema/reference/type.html"
}
]
},
"disableOutput": {
"title": "Save Paper",
"description": "Set paper-saving mode.",
"property_order": 30,
"type": "boolean",
"options": {
"infoText": "Key name: disableOutput"
},
"links": [
{
"rel": "More information",
"href": "https://json-schema.org/understanding-json-schema/reference/type.html"
}
]
},
"powerSaver": {
"title": "Power Saver",
"description": "Enable energy saving features.",
"property_order": 32,
"type": "integer",
"options": {
"enum_titles": [
"On",
"Off"
],
"infoText": "Keyword: powerSaver"
},
"links": [
{
"rel": "More information",
"href": "https://json-schema.org/understanding-json-schema/reference/type.html"
}
],
"enum": [
1,
0
]
},
"allowedDomains": {
"title": "Allowed Domains",
"description": "Disk Manager will not filter these domains.",
"property_order": 35,
"type": "array",
"items": {
"type": "string",
"title": "Domain"
},
"options": {
"infoText": "Key name: allowedDomains"
},
"links": [
{
"rel": "More information",
"href": "https://json-schema.org/understanding-json-schema/reference/type.html"
}
]
},
"serverList": {
"title": "Server List",
"description": "Add servers to management list.",
"property_order": 40,
"type": "array",
"items": {
"title": "Server",
"type": "object",
"properties": {
"serverAddress": {
"title": "Hostname",
"type": "string"
},
"macAddress": {
"title": "MAC Address",
"type": "string"
},
"ipAddress": {
"title": "IP Address",
"type": "string"
}
}
},
"options": {
"infoText": "Key name: serverList"
},
"links": [
{
"rel": "More information",
"href": "https://json-schema.org/understanding-json-schema/reference/type.html"
}
]
},
"epochDate": {
"title": "Start Date",
"description": "Date (in YYYY-MM-DD format) of drive installation.",
"default": "2020-01-01",
"property_order": 45,
"type": "string",
"pattern": "^20[0-9]{2}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[0-1])$",
"options": {
"infoText": "Key name: startDate"
},
"links": [
{
"rel": "More information",
"href": "https://json-schema.org/understanding-json-schema/reference/type.html"
}
]
}
},
"required": ["powerSaver"]
}
The JSON above is merely a sample and does not encompass all of the capabilities provided by the JSON schema. For official documentation and more information, see JSON Schema.
Tips and Tricks
The JSON schema is comprehensive and it may be difficult to understand the relationship between Jamf Pro and the JSON schema you're building. Below you will find demonstrations of how various JSON schema keywords render within Jamf Pro, helping you enable Jamf Pro administrators to configure your applications.
The infoText keyword will provide a tooltip that appears when a user hovers over the info icon. Although this has many applications, many vendors have chosen to use it as an association to plist key names as seen below.
Jamf Pro's rendering of the "infoText" keyword.
The links keyword provides hyperlinked text which opens in a new tab.
Jamf Pro's rendering of the "links" keyword.
The pattern keyword uses a regular expression to enforce valid strings. This is especially useful for dates because JSON does not support a date keyword. This can be used to ensure values entered adhere to valid ISO dates or other common formats.
Jamf Pro's rendering of the "pattern" keyword.
Jamf recommends including the name of the preference domain within the header of the schema. This is a required field when importing the schema into Jamf Pro and also dictates the name of the file that's deployed to the managed device, which your application will be configured to read from.
Jamf Pro
The contents of a JSON schema manifest can be provided to Jamf Pro administrators to import into their Jamf Pro instance. This is done by configuring an External Application in the Application & Custom Settings payload of a macOS Configuration Profile. The administrator would select Custom Schema as the Source and enter in the Preference Domain that corresponds to the application's bundle identifier.
Specify the External Applications preference domain.
Add the schema and populate the JSON data.
Jamf Pro will validate the schema and then display a user-friendly interface that allows an administrator to easily configure settings for the application. The Configuration Profile can be scoped to the appropriate devices and will be deployed automatically.
GUI view of available settings, generated from provided JSON.
Updated 8 months ago