Create a provisioning package with multivariant settings

In your organization, you might have different configuration requirements for devices that you manage. You can create separate provisioning packages for each group of devices in your organization that have different requirements. Or, you can create a multivariant provisioning package, a single provisioning package that can work for multiple conditions. For example, in a single provisioning package, you can define one set of customization settings that apply to devices set up for French and a different set of customization settings for devices set up for Japanese.

To provision multivariant settings, you use Windows Configuration Designer to create a provisioning package that contains all of the customization settings that you want to apply to any of your devices. Next, you manually edit the .XML file for that project to define each set of devices (a Target). For each Target, you specify at least one Condition with a value, which identifies the devices to receive the configuration. Finally, for each Target, you provide the customization settings to be applied to those devices.

Let's begin by learning how to define a Target.

In the XML file, you provide an Id, or friendly name, for each Target. Each Target is defined by at least one TargetState which contains at least one Condition. A Condition element defines the matching type between the condition and the specified value.

A Target can have more than one TargetState, and a TargetState can have more than one Condition.

The following information describes the logic for the target definition:

• When all Condition elements are TRUE, TargetState is TRUE:

  

• If any of the TargetState elements is TRUE, Target is TRUE, and the ID can be used for setting customizations:

  

The following table shows the conditions supported in Windows client provisioning for a TargetState:

The matching types supported in Windows client are:

You can define more than one TargetState within a provisioning package to apply settings to devices that match device conditions. When the provisioning engine evaluates each TargetState, more than one TargetState may fit current device conditions. To determine the order in which the settings are applied, the system assigns a priority to every TargetState.

A setting that matches a TargetState with a lower priority is applied before the setting that matches a TargetState with a higher priority. This means that a setting for the TargetState with the higher priority can overwrite a setting for the TargetState with the lower priority.

Settings that match more than one TargetState with equal priority are applied according to the order that each TargetState is defined in the provisioning package.

The TargetState priority is assigned based on the condition's priority (see the Conditions table for priorities). The priority evaluation rules are as followed:

1. A TargetState with P0 conditions is higher than a TargetState without P0 conditions.
2. A TargetState with both P0 and P1 conditions is higher than a TargetState with only P0 conditions.
3. A TargetState with a greater number of matched P0 conditions is higher than TargetState with fewer matched P0 conditions, regardless of the number of P1 conditions matched.
4. If the number of P0 conditions matched is equivalent, then the TargetState with the most matched P1 conditions has higher priority.
5. If both P0 and P1 conditions are equally matched, then the TargetState with the greatest total number of matched conditions has highest priority.

Follow these steps to create a provisioning package with multivariant capabilities.

1. Build a provisioning package and configure the customizations you want to apply during certain conditions. For more information, see Create a provisioning package.

2. After you configure the settings, save the project.

3. Open the project folder and copy the customizations.xml file to any local location.

4. Use an XML or text editor to open the customizations.xml file.

   The customizations.xml file holds the package metadata (including the package owner and rank) and the settings that you configured when you created your provisioning package. The Customizations node of the file contains a Common section, which contains the customization settings.

   The following example shows the contents of a sample customizations.xml file.

   <?xml version="1.0" encoding="utf-8"?>
   <WindowsCustomizations>
    <PackageConfig xmlns="urn:schemas-Microsoft-com:Windows-ICD-Package-Config.v1.0">
      <ID>{6aaa4dfa-00d7-4aaa-8adf-73c6a7e2501e}</ID>
      <Name>My Provisioning Package</Name>
      <Version>1.0</Version>
      <OwnerType>OEM</OwnerType>
      <Rank>50</Rank>
    </PackageConfig>
    <Settings xmlns="urn:schemas-microsoft-com:windows-provisioning">
      <Customizations>
        <Common>
          <Policies>
            <AllowBrowser>0</AllowBrowser>
            <AllowCamera>0</AllowCamera>
            <AllowBluetooth>0</AllowBluetooth>
          </Policies>
          <HotSpot>
            <Enabled>0</Enabled>
          </HotSpot>
        </Common>
      </Customizations>
    </Settings>
   </WindowsCustomizations>
   
   

5. Edit the customizations.xml file to create a Targets section to describe the conditions that handle your multivariant settings.

   The following example shows the customizations.xml, which is modified to include several conditions including ProcessorName, ProcessorType, MCC, and MNC.

   <?xml version="1.0" encoding="utf-8"?>
   <WindowsCustomizations>
    <PackageConfig xmlns="urn:schemas-Microsoft-com:Windows-ICD-Package-Config.v1.0">
      <ID>{6aaa4dfa-00d7-4aaa-8adf-73c6a7e2501e}</ID>
      <Name>My Provisioning Package</Name>
      <Version>1.0</Version>
      <OwnerType>OEM</OwnerType>
      <Rank>50</Rank>
    </PackageConfig>
    <Settings xmlns="urn:schemas-microsoft-com:windows-provisioning">
      <Customizations>
        <Common>
          <Policies>
            <AllowBrowser>0</AllowBrowser>
            <AllowCamera>0</AllowCamera>
            <AllowBluetooth>0</AllowBluetooth>
          </Policies>
          <HotSpot>
            <Enabled>0</Enabled>
          </HotSpot>
        </Common>
        <Targets>
          <Target Id="Unique target identifier for desktop">
            <TargetState>
              <Condition Name="ProcessorName" Value="Pattern:.*Celeron.*" />
              <Condition Name="ProcessorType" Value="Pattern:.*(I|i)ntel.*" />
            </TargetState>
            <TargetState>
              <Condition Name="ProcessorName" Value="Barton" />
              <Condition Name="ProcessorType" Value="Athlon MP" />
            </TargetState>
          </Target>
          <Target Id="Mobile target">
            <TargetState>
              <Condition Name="MCC" Value="Range:310, 320" />
              <Condition Name="MNC" Value="!Range:400, 550" />
            </TargetState>
          </Target>
        </Targets>
      </Customizations>
    </Settings>
   </WindowsCustomizations>
   
   

6. In the customizations.xml file, create a Variant section for the settings you need to customize. To do this:

   a. Define a child TargetRefs element. b. Within the TargetRefs element, define a TargetRef element. You can define multiple TargetRef elements for each Id that you need to apply to customized settings. c. Move compliant settings from the Common section to the Variant section.

   If any of the TargetRef elements matches the Target, all settings in the Variant are applied.

   Note

   You can define multiple Variant sections. Settings that reside in the Common section are applied unconditionally on every triggering event.

   The following example shows the customizations.xml updated to include a Variant section and the moved settings that are applied if the conditions for the variant are met.

   <?xml version="1.0" encoding="utf-8"?>
   <WindowsCustomizations>
    <PackageConfig xmlns="urn:schemas-Microsoft-com:Windows-ICD-Package-Config.v1.0">
      <ID>{6aaa4dfa-00d7-4aaa-8adf-73c6a7e2501e}</ID>
      <Name>My Provisioning Package</Name>
      <Version>1.0</Version>
      <OwnerType>OEM</OwnerType>
      <Rank>50</Rank>
    </PackageConfig>
    <Settings xmlns="urn:schemas-microsoft-com:windows-provisioning">
      <Customizations>
        <Common>
        </Common>
        <Targets>
          <Target Id="Unique target identifier for desktop">
            <TargetState>
              <Condition Name="ProcessorName" Value="Pattern:.*Celeron.*" />
              <Condition Name="ProcessorType" Value="Pattern:.*(I|i)ntel.*" />
            </TargetState>
            <TargetState>
              <Condition Name="ProcessorName" Value="Barton" />
              <Condition Name="ProcessorType" Value="Athlon MP" />
            </TargetState>
          </Target>
          <Target Id="Mobile target">
            <TargetState>
              <Condition Name="MCC" Value="Range:310, 320" />
              <Condition Name="MNC" Value="!Range:400, 550" />
            </TargetState>
          </Target>
        </Targets>
        <Variant>
          <TargetRefs>
            <TargetRef Id="Unique target identifier for desktop" />
            <TargetRef Id="Mobile target" />
          </TargetRefs>
          <Settings>
            <Policies>
              <AllowBrowser>1</AllowBrowser>
              <AllowCamera>1</AllowCamera>
              <AllowBluetooth>1</AllowBluetooth>
            </Policies>
            <HotSpot>
              <Enabled>1</Enabled>
            </HotSpot>
          </Settings>
        </Variant>
      </Customizations>
    </Settings>
   </WindowsCustomizations>
   

7. Save the updated customizations.xml file and note the path to this updated file. You'll need the path as one of the values for the next step.

8. Use the Windows Configuration Designer command-line interface to create a provisioning package using the updated customizations.xml.

   For example:

   icd.exe /Build-ProvisioningPackage /CustomizationXML:"C:\CustomProject\customizations.xml" /PackagePath:"C:\CustomProject\output.ppkg" /StoreFile:C:\Program Files (x86)\Windows Kits\10\Assessment and Deployment Kit\Imaging and Configuration Designer\x86\Microsoft-Common-Provisioning.dat"
   

In this example, the StoreFile corresponds to the location of the settings store that is used to create the package for the required Windows edition.

When you install the multivariant provisioning package on a Windows client device, the provisioning engine applies the matching condition settings at every event and triggers provisioning.

The following events trigger provisioning on Windows client devices: