Skip to main content

​
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

This key is required to activate and use Zappl.
Enter your unique customer activation token. If you do not know this, please contact our Support team.
This key is required to activate and use Zappl.
Enter your unique customer public key. If you do not know this, please contact our Support team.
This key is set to true by default.
By default, Zappl attempts to install updates silently for Apps that are not in use once every hour. To disable these background update attempts, uncheck this option (not recommended).If you wish to disable all updates, this is the first of two settings that need to be unchecked, the second being the Allow Recurring Update Prompts option.
This key is set to true by default.
By default, Zappl prompts users to quit Apps that need to update on a regular recurring interval which can be configured in the Scheduled Update Options.If you wish to disable the recurring scheduled update prompts and only attempt to install updates silently when Apps are not in use, uncheck this option and check the Allow Hourly Attempt Updates option only.If you wish to disable all updates, this is the second of two settings that need to be unchecked along with the Allow Hourly Attempt Updates option.
This key is set to true by default.
By default, Zappl will update itself when new major and point releases are available.If you wish to disable this and either stay on a specific Zappl version, or push out updates for Zappl manually, uncheck this option.
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.
Allowed Updates

Example | Only Zoom, Google Chrome and Microsoft Excel are allowed installs and any other App installs will not be allowed via Zappl.

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.
Allowed Updates

Example | All Apps in the catalog can be installed by Zappl with the exception of WhatsApp and Facebook Messenger.

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 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.
Allowed Updates

Example | Zappl will only update Zoom, Google Chrome and Microsoft Excel and all other Apps will be ignored.

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.
Allowed Updates

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

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.Run Frequency OptionSpecify 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.Run Frequency Options

​
Frequency to Prompt Users

Use this dropdown to select how often you want to prompt users to update.Frequency to Prompt Users

​
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.Frequency Elapsed Behaviour
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. Recurring Prompt Mode Deferral Window - Patch Frequency

​
Patch Day

Use this dropdown to select a day of the week to prompt users to update when updates are pending.Patch Day

​
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.Missed Update Prompts

​
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. Patch Day Prompt Frequency
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. Patch Day Prompt Frequency (Recurring Prompt)
If Zappl finds no preferences configuration profile, the default behaviour is to prompt users to update once every week with single prompt mode enabled.
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.Specify 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 Deferral Limit

​
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.Disable Deferrals
This preference is unique to the Scheduled Update Options dictionary. Deferral options for Forced Updates are configured when marking Apps for Forced Updates.
This is the amount of time in minutes a user is given to save work before updates install automatically when deferrals are either not available or not configured.
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.Grace Period (Minutes)
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.
Use this preference to customise the default title shown on any update prompt when more than one App updates are pending.Custom Multiple Apps Title
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.
Use this preference to change the label on the button used to skip updates if a user decides to back out of the update after initiating the Self Service Updates policy.Custom Self Service Skip Button
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.
This preference determines how to list Apps that have pending updates on the update prompts displayed to the user.App List Type

​
Vertical List

This is the default setting.
When configured, Apps will be displayed at the bottom of the prompt in a vertical scrollable list along with their icon and the pending version that will be installed by the update.Vertical List UX

​
Horizontal List

Select this option if you prefer to display Apps in a basic comma separated list.Horizontal List UX

​
Scheduled AND Forced 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.Run Limitation Options
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.
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 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.Run Limitation - Allowed Update TimesIf 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.Run Limitation - Excluded Update Times
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.Custom IconIf you wish to change this to a different image, specify the path of an image to use in this field.Custom Icon Path
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.
Initial Prompt Icon Overlay PathInitial Prompt Icon Overlay UX

Here we're using this feature with a custom App Store icon.

The following prompt sizes can be customised via unique preference keys.

​
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 Prompt Size
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.Custom Single App Title
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.
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.

​
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.Custom Prompt MessagesWhen 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.
Use this preference to change the label on the button used to defer updates.Custom Defer Button
Use this preference to change the label on the button used to run updates.Custom Defer Button
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.Prompt Refresh Interval
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 (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.
defaults read /Applications/zoom.us.app/Contents/Info.plist CFBundleIdentifier
Copy the resulting bundle identifier to your clipboard and paste it into the 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.DND Applications
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.
Use this preference to ensure that updates are skipped if an application is using assertions. If an application is using the system microphone or playing audio, it should be marked as using assertions.
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.DND Application Assertions
Use this preference to ensure that if macOS Do Not Disturb mode is enabled, update prompts are skipped.
Setting this as true will skip the update prompts, setting as false will prompt users while Do Not Disturb mode is detected.Respect DND Mode
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 true to ensure that users are not interrupted whilst on conference calls.DND Camera Usage
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.DND Screen Sharing
The update progress prompt is the small prompt that contains an update progress bar and information around the update whilst the update is running.Update Progress Prompt UXThe 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 Options
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.

​
Prompt without focus

This is the default value.
This option shows an update progress prompt during updates, but ensures that other Apps can pull focus over the prompt.

​
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 Behaviour
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 .png, .jpg or .icns file, or use the selfService variable for the Jamf Self Service icon.Update Progress Prompt Overlay IconUpdate Progress Prompt Overlay Icon UX
With this set 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.Auto Relaunch Apps
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.Display Complete MessageTo 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.Display Complete Message
⌘I