Customisation
Preferences
If you are looking to customise the JSON Schema in Jamf Pro or iMazing for other MDMs, you can use this guide to understand the purpose of each preference key.
Preference Structure
The JSON schema profile is comprised of three main preference dictionaries; the General Options, the Scheduled Update Options and the Forced Update Options.
The scheduled and forced update options have identical preference keys that serve the same purpose for the scheduled and forced update mechanisms respectively, although the forced update options require fewer preferences.This is partly because deferrals and grace periods for forced updates are configured on a per-app basis when you mark apps for forced updates, and partly because there is slightly less functionality required in the forced update feature.Schema Preference Key Guide
General Options
Activation Token
Activation Token
This key is required to activate and use Zappl.
Public Key
Public Key
This key is required to activate and use Zappl.
Allow Hourly Attempt Updates
Allow Hourly Attempt Updates
This key is set to
true by default.Allow Recurring Update Prompts
Allow Recurring Update Prompts
This key is set to
true by default.Automatic Self Updates
Automatic Self Updates
This key is set to
true by default.Allowed Installs
Allowed Installs
By default, all Apps within the Zappl App Catalog are available for installs. If you prefer to limit which Apps can be installed by Zappl, specify the Apps you wish to allow in this array.You can specify as many unique identifiers as you wish, using the App Catalog unique identifiers for each App.
If you wish to allow installs for all Apps within the catalog with the exception of a select few Apps, skip configuring this setting and use the Excluded Installs setting. If you specify an App in this list which is also in the Excluded Installs list, the exclusion will override this setting.
Example | Only Zoom, Google Chrome and Microsoft Excel are allowed installs and any other App installs will not be allowed via Zappl.
Excluded Installs
Excluded Installs
By default, all Apps within the Zappl App Catalog are available for installs. If you wish to allow installs for all Apps in the catalog with the exception of only a few Apps, specify the Apps you wish to exclude in this array.You can specify as many unique App identifiers as you wish, using the App Catalog unique identifiers for each App.
If you wish to only allow installs for some specific Apps within our catalog, skip this setting and instead use the Allowed Installs setting to create your allowed installations list. If you specify an App exclusion which is also in the Allowed Installs list, only the exclusion will be respected.
Example | All Apps in the catalog can be installed by Zappl with the exception of WhatsApp and Facebook Messenger.
Allowed Updates
Allowed Updates
By default, all Apps within the Zappl App Catalog will be updated if installed. If you prefer to limit which Apps can be updated by Zappl, specify the Apps you wish to allow in this array.You can specify as many unique identifiers as you wish, using the App Catalog unique identifiers for each App.
If you wish to allow updates for all Apps within the catalog with the exception of a select few Apps, skip configuring this setting and use the [Excluded Updates](/customise/preferences#excluded-updates] setting. If you specify an App in this list which is also in the [Excluded Updates](/customise/preferences#excluded-updates] list, the exclusion will override this setting.
Example | Zappl will only update Zoom, Google Chrome and Microsoft Excel and all other Apps will be ignored.
Excluded Updates
Excluded Updates
By default, all Apps within the Zappl App Catalog will be updated if installed. If you wish to allow updates for all Apps in the catalog with the exception of only a few Apps, specify the Apps you wish to allow in this array.You can specify as many unique App identifiers as you wish, using the App Catalog unique identifiers for each App.
If you wish to only allow updates for some specific Apps within our catalog, skip this setting and instead use the Allowed Updates setting to create your allowed update list. If you specify an exclusion App which is also in the Allowed Updates list, only the exclusion will be respected.
Example | All Apps within the App Catalog will be updated by Zappl if installed, with the exception of Jamf Connect and Cato Client.
ONLY Scheduled Options
Run Frequency Options
Run Frequency Options
Although the scheduled cached update check is run on a frequent basis every day, the preferences in the Run Frequency Options dictionary ensure that users are only prompted to install updates on a specified frequency, e.g. once every week.First, use the Run Frequency Option dropdown to define a method of frequently prompting users to update.
Specify Patch Frequency
Select this option if you prefer not to tie the updates to a specified weekday and instead run updates on a recurring frequency, e.g. once every day, once every week etc.
Specify Recurring Patch Day
Select this option if you want to specify a day of each week to prompt users if they have pending updates, e.g. every Tuesday.When you select one of these two options, preferences that relate to each option automatically populate.
Specific Patch Frequency Preferences
Specific Patch Frequency Preferences
Frequency to Prompt Users
Use this dropdown to select how often you want to prompt users to update.
Frequency Elapsed Behaviour
This dropdown determines how Zappl should behave if the user defers the update. Selecting the Single Prompt Mode option will ensure that if the user defers the update, they will not get prompted to update again until the configured frequency has elapsed again, e.g. one week later.
Alternatively, select Recurring Prompt Mode if you prefer to prompt the user on a recurring basis after deferring until the update is installed.
When selecting 
Recurring Prompt Mode, the Recurring Prompt Mode Deferral Window (Patch Frequency) field appears and allows you to define a minimum deferral period in minutes.
Specific Patch Day Preferences
Specific Patch Day Preferences
Patch Day
Use this dropdown to select a day of the week to prompt users to update when updates are pending.
Missed Update Prompts
Selecting this option ensures that if a computer is offline on the defined weekly patch day, the user can be prompted to update at the next available opportunity as opposed to waiting until the next patch day. Leave this unchecked if you prefer to ensure that prompts are only ever displayed on the configured patch day.
Patch Day Prompt Frequency
This dropdown helps you determine how frequently users are prompted to update on the configured patch day when they defer an update.Selecting the
Single Prompt Mode option ensures that when a user defers the update, they won’t get prompted to update until the following week on the configured patch day.If you prefer to prompt the user to update on a recurring basis on the configured patch day, select the
Recurring Prompt Mode option.
When selecting 
Recurring Prompt Mode, the Recurring Prompt Mode Deferral Window (Patch Day) field appears and allows you to define a minimum deferral period in minutes.
If Zappl finds no preferences configuration profile, the default behaviour is to prompt users to update once every week with single prompt mode enabled.
Deferral Options
Deferral Options
Use this preference dictionary to configure your desired deferral behaviour.
This preference is unique to the Scheduled Update Options dictionary. Deferral options for Forced Updates are configured when marking Apps for Forced Updates.
Specify Deferral Limit
Configuring a deferral limit for updates ensures that users cannot defer the update indefinitely. The deferral limit you configure here is how many times the user will be allowed to defer the update before being forced to install the update. Use the Deferral Limit field to specify your desired deferral limit.
Disable Deferral Limit
Selecting this option will allow users to defer the update indefinitely. We recommend only using this option if you plan to create a workflow which utilises forcing the update on demand.
Disable Deferrals
Selecting this option will mean that users will not be given any opportunity to defer and will instead be given a Grace Period to save any work before the updates are automatically installed.
Grace Period
Grace Period
This preference is unique to the Scheduled Update Options dictionary. Deferral options for Forced Updates are configured when marking Apps for Forced Updates.
By default this value is
15 minutes, therefore you only need to configure this preference if you wish to decrease or increase the default grace period.
Custom Multiple Apps Title
Custom Multiple Apps Title
This preference is only present in the Scheduled Update Options dictionary. This is because Forced Updates are always performed on a per-App basis, therefore all forced update prompts relate to a single App.
Custom Self Service Skip Button
Custom Self Service Skip Button
This preference is only present in the Scheduled Update Options dictionary. This is because the key is referring specifically to a self-initiated update check via Self Service.
App List Type
App List Type
This preference is only present in the Scheduled Update Options dictionary. This is because Forced Updates are performed on a per-App basis and therefore do not contain App lists.
Vertical List
This is the default setting.
Horizontal List
Select this option if you prefer to display Apps in a basic comma separated list.
Scheduled AND Forced Options
Run Limitation Options
Run Limitation Options
You can use the Run Limitation Options dictionary to apply exclusions to the frequency options you previously configured for Scheduled Updates. The same options are also available in the Forced Updates dictionary to allow you to limit when Zappl is permitted to prompt users to update any Apps that have been marked for forced updates.
A checkbox is available and by default ticked for each day of the week. If there is a particular day of the week you want to ensure update prompts are never displayed to the user, simply uncheck the box next to the day. This is useful when using the Specify Patch Frequency option, or when specifying a patch day with the Missed Update Prompts option checked.
Each day also offers the option to define an allowed update time window. Selecting an allowed time window means that whenever Zappl runs outside of that window, update prompts will be skipped and Zappl will exit with no further action.
By default, the start time is
If you want to define an exclusion time window, e.g. do not prompt between 
A checkbox is available and by default ticked for each day of the week. If there is a particular day of the week you want to ensure update prompts are never displayed to the user, simply uncheck the box next to the day. This is useful when using the Specify Patch Frequency option, or when specifying a patch day with the Missed Update Prompts option checked.
If you have specified a weekly patch day, and that patch day is then unchecked in the run limitation options, the run limitation for that day will be ignored and the user will still be prompted to update on the configured patch day.
By default, the start time is
12.00am and the end time is 11.59pm, but you can easily change this on a per-day basis by modifying the values in the fields.
If you want to define an exclusion time window, e.g. do not prompt between 2pm and 4pm but allow prompts for the rest of the day, simply reverse the timestamps as shown below.
Custom Icon
Custom Icon
By default, the icon displayed on the left hand side of the update prompts is your Jamf Self Service icon for scheduled updates, and the App icon for forced updates.
If you wish to change this to a different image, specify the path of an image to use in this field.
If you wish to change this to a different image, specify the path of an image to use in this field.
Initial Prompt Icon Overlay
Initial Prompt Icon Overlay
Configuring this option allows you to overlay a second icon on the bottom right corner of the main icon.By default, no icon overlay is configured, but you can specify a valid 
.png, .jpg or .icns file here to add one. To use the Jamf Self Service icon as the overlayed icon, type in selfService.
Here we're using this feature with a custom App Store icon.
Custom Prompt Sizes
Custom Prompt Sizes
The following prompt sizes can be customised via unique preference keys.
The prompt shown when deferrals are available (Available in the Scheduled and Forced Updates dictionaries).
The prompt shown when deferrals are not available or not configured (Available in the Scheduled and Forced Updates dictionaries).
The prompt shown when a user initiated the Self Service Updates policy (Available in the Scheduled Update options dictionary).The default size of the update prompts is set to provide enough space for the default text. If you change the text, the prompt size might become too small or too large. If it’s too large, you’ll see a lot of white space. If it’s too small, you’ll need to scroll to read all the text.
To remediate this, use the custom prompt size preferences listed above to adjust the size of various prompts displayed to users.
Custom Initial Prompt Size
The prompt shown when deferrals are available (Available in the Scheduled and Forced Updates dictionaries).Custom Grace Period Prompt Size
The prompt shown when deferrals are not available or not configured (Available in the Scheduled and Forced Updates dictionaries).Custom Self Service Prompt Size
The prompt shown when a user initiated the Self Service Updates policy (Available in the Scheduled Update options dictionary).The default size of the update prompts is set to provide enough space for the default text. If you change the text, the prompt size might become too small or too large. If it’s too large, you’ll see a lot of white space. If it’s too small, you’ll need to scroll to read all the text.To remediate this, use the custom prompt size preferences listed above to adjust the size of various prompts displayed to users.
When using
Vertical List as the app list option, Zappl automatically adds on the required prompt height to your custom prompt height to allow enough space for the App list to be shown beneath the prompt message. When configuring your custom prompt size, first switch the App List Type to the Horizontal List option, and ensure your prompt message fits perfectly into the custom prompt size. Once you are happy with the size, change the App list type back to Vertical List mode.Custom Single App Title
Custom Single App Title
Use this preference to customise the default title shown on any update prompt when there is 1 pending App update. You can define the name of the App using the 
appName variable.
In the Forced Update options dictionary, this preference is labelled
Custom Title. This is because forced updates are always performed on a per-App basis, so all forced update prompts relate to a single App.Custom Prompt Messages
Custom Prompt Messages
If you choose to customise the default text displayed on the update prompts, there are a number of different prompts which relate to different scenarios that can be modified.
When customising prompt text, ensure that you customise the text on the keys outlined below.
This message will be displayed on the prompt shown when there is 1 pending App update and deferrals are available.
This message will be displayed on the prompt shown when there are multiple App updates pending and deferrals are available.
This message will be displayed on the prompt shown when a user initiates the Self Service Application Updates policy and there is 1 pending App update which requires a quit.
This message will be displayed on the prompt shown when a user initiates the Self Service Application Updates policy and there are multiple pending App updates which require a quit.
This message will be displayed on the prompt shown when there is 1 pending App update and deferrals are either not available or not configured.
This message will be displayed on the prompt shown when there are multiple App updates pending and deferrals are either not available or not configured.
When customising the text for update prompts, variables can be utilised to include information such as deferral information, App names, button labels etc. For all variables available, see Custom Message Variables.
When customising prompt text, ensure that you customise the text on the keys outlined below.
Single App Initial Quit Prompt Message
This message will be displayed on the prompt shown when there is 1 pending App update and deferrals are available.Multiple Apps Initial Quit Prompt Message
This message will be displayed on the prompt shown when there are multiple App updates pending and deferrals are available.Single App Self Service Quit Prompt Message
This message will be displayed on the prompt shown when a user initiates the Self Service Application Updates policy and there is 1 pending App update which requires a quit.Multiple App Self Service Quit Prompt Message
This message will be displayed on the prompt shown when a user initiates the Self Service Application Updates policy and there are multiple pending App updates which require a quit.Single App Grace Period Quit Prompt Message
This message will be displayed on the prompt shown when there is 1 pending App update and deferrals are either not available or not configured.Multiple Apps Grace Period Quit Prompt Message
This message will be displayed on the prompt shown when there are multiple App updates pending and deferrals are either not available or not configured.When customising the text for update prompts, variables can be utilised to include information such as deferral information, App names, button labels etc. For all variables available, see Custom Message Variables.When configuring custom Forced Update messages, the single and multiple App options are not present. This is because forced updates are run on an individual App basis, so the prompts are always single App prompts.
Custom Defer Button
Custom Defer Button
Use this preference to change the label on the button used to defer updates.
Custom Update Button
Custom Update Button
Use this preference to change the label on the button used to run updates.
Prompt Refresh Interval
Prompt Refresh Interval
This is the length of time in seconds that the update prompts pull focus. Without the prompts regularly pulling focus, it is easy for the user to swipe away and ignore the update prompt without choosing to either defer or update.The default value is 
20 seconds. If you find this too aggressive, you can change the value to suit your needs. The minimum allowed value is 10 seconds.
Do Not Disturb Applications
Do Not Disturb Applications
Use this preference to define any Apps which if detected as being in the foreground will cause the update prompt to skip.
It is recommended that you configure this preference and add any video conferencing or presentation software used across your estate. This will ensure that users don’t get prompted to update whilst on a conference call or when presenting.
To define an App, you must first get the bundle identifier of the App. To do so, paste the below command into Terminal on a macOS computer that has the App installed (replacingCopy the resulting bundle identifier to your clipboard and paste it into the 
It is recommended that you configure this preference and add any video conferencing or presentation software used across your estate. This will ensure that users don’t get prompted to update whilst on a conference call or when presenting.
To define an App, you must first get the bundle identifier of the App. To do so, paste the below command into Terminal on a macOS computer that has the App installed (replacing
zoom.us.app with the name of the App you want to define). Alternatively, if it’s an app supported in our App Catalog you can find the Bundle Identifier there.Do Not Disturb Application Bundle ID preference. You can add as many App bundle identifiers as you require by clicking the Add Do Not Disturb Application Bundle ID button.
Do Not Disturb Application Assertions
Do Not Disturb Application Assertions
An application assertion is when an app actively declares that it needs to use a specific system resource, like the microphone, camera, or location services.
This is useful in scenarios where a user may be in a meeting using a web-based client like Google Meets without a camera on, as the assertion used by the web browser would prevent the update from interrupting the meeting.
You can add as many assertion apps as you wish, ensuring to use the correct assertion name format. To get the required assertion name format, run
/usr/bin/pmset -g assertions in Terminal while the application is running and using assertions.
Respect Do Not Disturb Mode
Respect Do Not Disturb Mode
Use this preference to ensure that if macOS Do Not Disturb mode is enabled, update prompts are skipped.
Setting this as
Setting this as
true will skip the update prompts, setting as false will prompt users while Do Not Disturb mode is detected.Do Not Disturb Camera Usage
Do Not Disturb Camera Usage
Use this preference to ensure that if the camera is detected as being actively in use, the update will be skipped.
We recommend setting this as
We recommend setting this as
true to ensure that users are not interrupted whilst on conference calls.Do Not Disturb Screen Sharing
Do Not Disturb Screen Sharing
Use this preference to ensure that if screen sharing is detected as being actively in use, the update will be skipped.
We recommend setting this as true to ensure that users are not interrupted whilst sharing their screen on conference calls or whilst recording their screen.
We recommend setting this as true to ensure that users are not interrupted whilst sharing their screen on conference calls or whilst recording their screen.
Update Progress Prompt Position
Update Progress Prompt Position
The update progress prompt is the small prompt that contains an update progress bar and information around the update whilst the update is running.
The default position of this prompt is the 
The default position of this prompt is the top right corner of the screen. This position can be modified using the dropdown within this preference.
Update Progress Prompt Behaviour
Update Progress Prompt Behaviour
This dropdown determines whether to display an update progress prompt during updates, and if so, determines whether the update progress prompt takes focus over other Apps whilst updates are running.
This option shows an update progress prompt during updates, but ensures that other Apps can pull focus over the prompt.
This option ensures that the update progress prompt always stays visible on top of any apps the user is using during updates.
This option ensures no update progress prompt is displayed. With this configured, a reminder prompt will be displayed to the user if they attempt to open an app which is being updated.
Prompt without focus
This is the default value.
Prompt with focus
This option ensures that the update progress prompt always stays visible on top of any apps the user is using during updates.Don't show a prompt
This option ensures no update progress prompt is displayed. With this configured, a reminder prompt will be displayed to the user if they attempt to open an app which is being updated.Update Progress Prompt Overlay Icon
Update Progress Prompt Overlay Icon
Use this preference to add an overlay icon to the update progress prompts. When updates are running, the main icon displayed is the icon for the App currently being updated. The overlay icon will be displayed on the bottom right corner of the App icon.
You can specify either a path to a valid
You can specify either a path to a valid
.png, .jpg or .icns file, or use the selfService variable for the Jamf Self Service icon.
Automatically Relaunch Apps
Automatically Relaunch Apps
With this set as
Set this as
true, Zappl silently relaunches the app as soon as the update completes providing that the app was in use prior to the update.Set this as
false to skip relaunching apps.Display Complete Message
Display Complete Message
Use this preference to determine whether a prompt should be displayed to the user to inform them that all updates have finished being installed.
The complete message prompt is the same size as the update progress prompt and inherits the same screen position.
To ensure this prompt is displayed to the user when updates are complete, set this as 
The complete message prompt is the same size as the update progress prompt and inherits the same screen position.
To ensure this prompt is displayed to the user when updates are complete, set this as true, or alternatively to disable the prompt set this as false.