Managing CSPs Using VMware Policy Builder

Managing CSPs Using VMware Policy Builder


In this exercise, learn the benefits of modern policy management, and walk-through the process of migrating from traditional to modern policy management.

Benefits of Modern Management

Traditional Windows management for domain joined devices relies on centrally managed Group Policies (GPOs), and distributed Local Policies (LGPOs) for non-domain joined machines. This approach works well for devices tethered to physical office locations with domain-joined, always-on corporate network systems.

However, when it comes to the mobile workforce, which includes Windows 10, traditional management exhibits some limitations:

  • Too Inflexible - To receive GPO updates, devices must log into the domain network.
  • Difficult to Control - No centralized management makes LGPOs  difficult to control.

In contrast, modern management uses interfaces, known as Configuration Service Providers (CSPs), to push registry and file system settings to devices over-the-air. This approach effectively addresses the primary limitations of traditional management:

Traditional Modern
Too Inflexible Over-the-air management  allows devices to receive updates in real time without logging into the domain network
Difficult to Control Workspace ONE UEM provides centralized management capabilities

Modern Management with Workspace ONE UEM

Workspace ONE UEM delivers policies to devices through profiles. Many policies are available for direct configuration within the console's UI.

If a policy is not available in the UI, use the Custom Settings profile. This profile allows you to upload XML to configure the CSP and publish its settings to devices.

To save time and effort creating the XML, use the VMware Policy Builder tool to:

  • Generate or modify XML using the form-based UI
  • Only push policies supported by the device OS
  • Configure or modify multiple CSPs
  • Dynamically generate SyncML
  • Filter through options

The following video explains how VMware Policy Builder works in more detail:


Logging In To VMware Policy Builder

2. Log In to VMware Policy Builder

If you have a My VMware account do the following to log in.

  1. Enter the email address you use for My VMware
  2. Enter the password for your My VMware account
  3. Click the Login button to log into the Policy Builder


Reviewing VMware Policy Builder Features

Most of the steps in this exercise use the VMware Policy Builder. This section walks through the VMware Policy Builder's UI and its key features.  

  1. This link takes you back to the list of Configuration Service Providers which can be configured via the tool.
  2. One a CSP is selected, this link allows you to enter configuration parameters and have the SyncML generated automatically.
  3. When this link is clicked, you are taken to a page which allows you to paste in existing SyncML which can be modified graphically.
  4. This link allows you to generate a unique GUID and copy it to the clipboard.  Some CSP configurations require a GUID to be passed in.  
  5. This is the list of supported Windows 10 operating systems.  The CSPs are unique and specific to the OS version you are targeting.  
  6. This is the list of CSPs and associated DDF files.  Device Description Framework (DDF) files contain the configuration details of a CSP in XML format.

Creating a Custom Desktop Background CSP

In this section, use VMware Policy Builder to create a desktop background custom policy for a Windows 10 device - something that is routinely done through traditional group policy management.  

1. Open Personalization CSP Settings

  1. Set the CSP Baseline to Windows 10, 1709 - the operating system of the device used in this exercise.
  2. Type person in the filter box, to quickly find the Personalization CSP..
  3. Select the Personalization check-box.
  4. Click the Configure button to begin creating a custom policy.

2. Configure the Personalization CSP

  1. Enter c:\hol\vmware.jpg in the Desktop Image Url section.
  2. Notice the SyncML is generated for you dynamically including the configuration data you entered.
  3. Click the Copy button to copy the SyncML.  

Note: Keep track of the copied SyncML, because its required to for the Workspace ONE UEM configuration.

Creating a Desktop Background Custom Settings Profile

In this section, create a Custom Settings profile for Windows 10 that contains the SyncML generated in the policy builder. Then, use Workspace ONE UEM to push the desktop background policy to a Windows 10 device, and verify the setting applied.  

2. Select Platform

Select the Windows icon.

Note: Make sure that you select Windows and not Windows Rugged.

3. Select Device Type

Select Windows Desktop.

4. Select Context

Select Device Profile.

5. Configure General Settings

  1. Enter Background Image as the Name.
  2. Under Assigned Groups, select All Devices

6. Open Custom Settings

  1. Scroll down to the bottom on the left pane, and select Custom Settings.
  2. Click Configure.

7. Configure Custom Settings

  1. Paste the SyncML you copied earlier into the textbox next to Custom Settings, leave all other defaults.
  2. Click Save & Publish

8. Confirm Device Assignment and Publish

  1. Verify the profile is assigned to the correct device.
  2. Click Publish to push the CSP down to your Windows 10 device.

9. Verify the Desktop Background Changed

In this section, log out and then log back in to the Windows 10 machine and verify the desktop image changed.  

  1. Right-Click the start button.
  2. Choose Shut down or sign out.
  3. Select Sign out.
  4. Reconnect to the Windows 10 device.

Notice that the desktop background is now set to a VMware logo.   This was done via the Personalization CSP and pushed to your Windows 10 machine with Workspace ONE.  

Updating an Existing Cortana CSP

In this exercise, use VMware Policy Builder to update existing SyncML and disable Cortana.

1. Copy Existing SyncML

      <Format xmlns="syncml:metinf">int</Format>

Select all of the SyncML above from <Replace> to </Replace> and copy it.  

2. Paste the SyncML text

  1. Click the Modify button.
  2. Paste the copied SyncML into the SyncML pane.  

3. View the Allow Cortana Setting

  1. Expand Policy.
  2. Expand Device.
  3. Expand Config.
  4. Scroll down and expand Experience.
  5. Notice Allow Cortana is set to 1.  That means Cortana is currently enabled.  

4. Disable Allow Cortana and copy SyncML

  1. Enter 0 under Allow Cortana
  2. Notice the SyncML dynamically updated, and it now shows a 0 for Data
  3. Click the Copy button to copy the SyncML

Creating a Disable Cortana Custom Settings Profile

2. Select the Platform

Select the Windows icon.

3. Select the Device Type

Select Windows Desktop.

4. Select Context

Select Context

Click Device Profile.

5. Define the General Settings

  1. Select General if it is not already selected.
  2. Enter a profile name, such as Disable Cortana, in the Name text box.
  3. Scroll down to Assigned Groups, click the field, and select All Devices from the list that populates.

Note: Do not click Save & Publish at this point. This interface allows you to move around to different payload configuration screens before saving.

6. Open the Custom Settings Payload

  1. Select the Custom Settings payload from the menu on the left.
  2. Click the Configure button to begin configuring payload settings.

7. Configure Custom Settings

  1. Paste the copied "disable Cortana" SyncML to into Custom Settings text box.
  2. Click Save & Publish.

8. Review Assignment & Publish

  1. Review the device assignment.  It should be your Windows 10 desktop which you recently enrolled into Workspace ONE.
  2. Click the Publish button to push the CSP down to your Windows 10 device.

9. Restart the Device

In order to immediately see the disable Cortana policy apply on the Windows 10 device, log out and then back in.  

  1. Right-click the start menu.
  2. Choose Shut down or sign out.
  3. Select Sign out.
  4. Reconnect to the Windows 10 device.

10. Verify the Profile Applied

Click the search bar, located to the right of the start menu, and notice that Cortana is disabled.  

Configuring Custom Settings to Use Pre-released Configuration Service Providers (CSP)

The Custom Settings payload provides a way to use newly released Windows functionality in Workspace ONE UEM. When you want to use the new features supported on Windows Insider builds, you can use the Custom Settings payload and SyncML (XML) code to enable or disable certain settings manually.

1. Requirements

SyncML code must be generated to leverage the Custom Settings payload. Use one of the following methods to generate your SyncML:

Microsoft publishes a Configuration Service Provider (CSP) reference site available on their web site.

The Custom Settings profile appends the appropriate SyncML Atomic tags to the beginning and the end of the code. You must generate the appropriate code between any <Add>, <Replace>, <Delete>, or <Exec> tags. Optionally, to condense the size of the code, you can remove all whitespace and linearize the SyncML code.

1.1. Example SyncML without Atomic Tags

The following text is an example of SyncML without atomic tags.

<Replace><CmdID>2</CmdID><Item><Target><LocURI>./Device/Vendor/MSFT/AssignedAccess/KioskModeApp</LocURI></Target><Meta><Format xmlns="syncml:metinf">chr</Format></Meta><Data>

2. Configure Custom Payload

2.1. Add a Profile

Add a Profile

In the upper-right corner of Workspace ONE UEM Console:

  1. Select Add.
  2. Select Profile.

2.2. Add a Windows Profile

Add a Windows Profile

Select the Windows icon.

2.3. Add a Windows Desktop Profile

Add a Windows Desktop Profile

Select Windows Desktop.

2.4. Select Context – Device Profile

Select Context - Device Profile

Select User Profile or Device Profile.

Note: Refer to the LocURI to determine the correct User/Device context needed. In the SyncML example notice the LocURI begins with ./Device/ therefore we would apply to the device Device. However, if it were ./User/ then we would only apply  to that User.

Note: Policy scope is the level at which a policy can be configured. For more information, see the Microsoft Policy CSP article.

2.5. Define the General Settings

General settings determine how the profile is deployed and who receives it. For more information on General settings, see Add General Profile Settings in the VMware AirWatch Mobile Device Management Guide.

2.6. Select Custom Settings Payload

  1. Select the Custom Settings payload.
  2. Click Configure.
  1. Paste the SyncML you generated in the text box. The SyncML code you paste must contain the complete block of code, from <[characteristic]> to </[characteristic]>; where characteristic can be Add, Delete, Replace, or Exec. Do not include anything before or after these tags.
  2. Click Save & Publish.

3. Making Updates/Deleting Custom Settings Profiles

Workspace ONE UEM automatically has built-in logic when using fully integrated payloads; for instance, when removing a profile, Workspace ONE UEM sends a Delete action to remove the profile payload’s configurations. When using Custom Settings, if you want to update settings you must use the Replace tag and to remove settings you must use the Delete tag. When removing settings, do not include the Data tags; only the LocURI is needed.

3.1. Sample Removing Kiosk (Assigned Access) Configuration


4. Using Samples from VMware Sample Exchange

Workspace ONE UEM provides a seamless experience when using custom settings for Windows 10 devices. You can find fully tested and validated samples at the VMware Code Sample Exchange. Pay attention to the support Windows 10 Edition as some samples apply only to Surface Hub devices (Team) or require Enterprise or Education editions. For more information and to access the samples, see VMware Sample Exchange.

5. Using Existing Profiles to Create Custom Settings

Many organizations who deploy on-premises or dedicated SaaS environments cannot use the latest feature updates to keep up with Windows 10 releases. You can use your user acceptance testing (UAT) environment to create the profile and then export the generated SyncML, and paste it into your production environment. This allows you to take advantages of newly released capabilities between the time it is released and your production environment is upgraded to support these features.

5.1. Create a Windows Profile

Create a Windows profile from the Workspace ONE UEM Console using the required payloads.

5.2. Edit the Profile

  1. Select the radio button next to your new profile.
  2. Click </>XML.

5.3. Copy the SyncML

Copy the SyncML.

Remove the lines of text at the beginning and at the end; keep only the lines from <[characteristic]> to </[characteristic]>; where characteristic can be Add, Delete, Replace, or Exec. Do not include anything before or after these tags.
For example, <Atomic><CmdID>{CmdID}</CmdID> at the beginning and </Atomic> at the end.

5.4. Paste SyncML into Text Editor

Paste SyncML into a text editor and ensure all of the whitespace is removed. You may also want to linearize the SyncML.

5.5. Copy Newly Generated SyncML and Paste into Production Console

Copy your newly generated SyncML from the text editor. In your production console, create your Custom Settings profile by pasting the SyncML and publishing the profile.

6. Using Configuration Service Provider (CSP) Development Suite to Create Custom Settings

The latest Configuration Service Provider (CSP) release by Microsoft might not always be visually available in Workspace ONE UEM to configure. In this case, an admin can use Device Description Framework (DDF) to create custom settings to distribute through Workspace ONE UEM.

The DDF files are like the explanations (schemas) of how to use the CSP to leverage modern management. DDF files can be downloaded directly from Microsoft. Ensure you download the correct DDF version that correlates to the Windows 10 build version you are using.

6.1. Launch CSP Development Suite and Select Tool

If required, download CSP Development Suite.

Launch CSPDevelopmentSuite and select the SyncML Generator as the tool to be used. Note the other tools in the Development Suite. 

6.2. Import DDF

Select File > Import Ddf.

6.3. Select a DDF File

Select one of the DDF files. You can download DDF files from CSP DDF Files Download.

6.4. Expand Tree

Expand the tree on the left to see the various options. For more information about the CSP you are working with, see the Microsoft article Configuration service provider reference.

6.5. Enter Node Name

Click the [Enter node name] section and enter 0AA79349-F334-4859-96E8-B4AB43E9FEA0. Node name specifies a unique identifier that represents the ID of the Microsoft Office product to install.

6.6. Select Node to Configure

Select the node you want to configure. In this example, we select Install. From here, you can select Access and input our Access Data. For supported Access types and expected Data, see the Microsoft Configuration service provider reference article.

6.7. Generate Custom XML

The Access Data for the Office CSP expects the Office Configuration XML in serialized format. Use your pre-created XML or use the Office Click-to-Run Configuration XML Editor to quickly generate your customized XML. Copy the contents of your XML and XML Escape (xml to text) using Notepad++ (with XML Tools) or any online tool like Free Formatter.

Note: Notepad++ with XML Tools allows you to quickly edit your SyncML without a third-party site.

6.8. Remove Whitespace and Character Returns

The CSP Development Suite only supports linearized content, meaning all the whitespaces and character returns must be removed. In Notepad++, you can choose Plugins > XML Tools > Linarize XML.

6.9. Paste Formatted Data into Access Data

Copy your formatted data and paste into the Access Data field. In most cases Access Data will content a value of 0, 1, or a simple text value. Then click Insert to build your SyncML. Copy the body of your SyncML, from <Exec> to </Exec> in this case. You can also select File > Export SyncML to save your file and edit at a later stage, or send to someone.

6.10. Create Windows User Profile

In the Workspace ONE UEM Console, you create a custom settings profile by selecting Windows > Windows Desktop > User Profile (because our LocURI is ./User/ in this example).

6.11. Configure Custom Settings

  1. Select Custom Settings, then Configure.
  2. For Target, select OMA-DM Client because this is supported natively by the device.
  3. In this example, we deselect Make Commands Atomic. Exec commands do not require Atomic, but in most use cases you keep this setting checked.
  4. Paste your copied content into the Custom Settings field.
  5. Click Save & Publish.