Schema structure

This section provides an overview of the Knox Service Plugin (KSP) schema structure and general best practices.

The following image shows the high level categories of policies and common configurations. It has four main components:

1. Basic elements — General operational controls for KSP. For example, turn on debug mode or input a KPE license key.

2. Device-wide policies section — Device Owner (DO) policy controls. These are of global scope.

3. Work profile policies section — Profile Owner (PO) policy controls. These apply to only the .

4. Configurations — Specific configuration properties that are used in conjunction with policy controls. For example, VPN profile settings, APN settings, or DeX customization settings. These can be used on either device-wide policies or work profile policies.

Schema breakdown

Common configurations

Each version of Knox Service Plugin includes a few common options. The features available within these options depend upon your Knox Service Plugin deployment mode, Knox Platform for Enterprise license status — whether you have a Standard or a Premium license — as well as the features available on your UEM console.

These common options are as follows:

1. Profile name — A unique nickname you provide for a set of policy configurations. You can create many different profile names for various sets of configurations. Later, you can use the name for tracking and debugging purposes. We recommend using a name less than 50 characters in length, for example, MyEnterprise Profile.

2. KPE Premium License key — This is useful for consoles that do not have Knox Premium License activation built in as a native feature. When this field is used, KSP can activate the license for you when you push the configuration. If your UEM console has already activated a Knox Premium License on your device, there is no need to activate a license using this field. The following image is an example of this field.

   

   You only need to input a license if you are using a premium policy. If you do not provide a license key and use a premium policy — or the key provided does not have necessary privileges — the KSP policy fails and produces an error message.

3. Debug modes — When you turn on debug mode, you can view policy results and errors on the device through an app menu. We recommend enabling this mode only during test phases and not during final deployment. If you run into any KSP deployment issues, check this box to enable debug mode and try to perform the action again. You can also export the message and reach out to Knox Support for help to diagnose and fix your issue.

4. DO and PO policies — Depending upon your deployment mode, you need to enable device-wide or Work profile-wide policy controls. Do as follows:

   • Device-wide policies — To enable or disable device-wide policies, use the Enable device policy controls field. Enable this option before using any of the Device-wide policies. If this option is disabled, KSP does not apply any policies in default user (User 0).

   • Work profile-wide policies — To enable or disable Work profile-wide policies, use the Enable work profile policy controls field. Enable this option before using any of the Device-wide policies. If this setting is disabled, KSP does not apply any policy changes inside the Work Profile.

Group policy control flag

Every group has a control that enables or disables that policy group. By default every policy group is disabled. You must enable this control before setting any policy in the group. For example, before using any policy in the device-wide policy section, turn on the Enable device-wide policies control first. Further more, to use any device restrictions within the device-wide policy section, turn on Enable device restriction controls and then activate individual policies, such as Allow microphone, Allow Wi-Fi and so on.

The following image illustrates a control group.

Profile Configurations

You can save a group of configurations using a Profile Name. Once you save a group of configurations, you can reuse these configurations for as many deployments as you need.

For example, in the following image, we have set the DeX profile name as DeX profile 1. Any configurations set are saved under the name DeX profile 1. When setting policies later, you can reference DeX profile 1 to quickly set up devices with your saved configurations.

Recommended practices

• Auto-install — Turn this feature on if your UEM supports it. This feature ensures all devices install KSP automatically when prompted.

• Auto-update — Turn this feature on if your UEM supports it. This feature ensures that the KSP app is up to date on deployed devices. KSP is designed to be backward compatible. For example, a newer version of the app can handle older schema data, but older app versions can’t handle new schema data.

• Native console policies — Use your UEM console for any policy that is supported natively and use KSP to bridge any gaps.

• Test in small batches — Always test your KSP schema changes with a limited set of devices, debug the issues (if any) by enabling debug mode, then roll out to wider deployment.

Special cases

List applications

Some fields allow you to specify more than one app to target. For example: when you select apps to allowlist for a proxy. To list out apps, use a comma-separated list of packages. For example com.samsung.android.email.provider, com.sec.android.app.sbrowser. To find a package name, look at the Google Play store URL or contact the app vendor.

Uploading files

Some Knox policies, such as DeX customization, require you to provide bulk data, such as an image file. However, OEMConfig specifications do not currently support file upload.

If you need to upload a file you can use one of the following two methods:

• Web URL — Upload the file to a cloud server and provide the web URL as an input string to KSP. Ensure that the URL is publicly accessible.

  Some UEMs have a limitation on the number of characters you can enter in a string field. In such cases, you cannot use this approach to upload files.

• Push the image file to the local storage — Use the UEM console to push the image file to the local storage on the device and provide the file path on the device as the input string to KSP. Contact your UEM vendor to find out if they support this feature.

  Push the image to your device before you install KSP and it attempts to apply any policies to the device.