Manage Cloud PC mappings

By default, when your Windows 365 Cloud PCs register with Citrix®, they are placed into machine catalogs, delivery groups, and zones that use system-generated names. Cloud PC mappings let you replace this default grouping with your own rules, so that each Cloud PC is automatically organized into the Citrix objects you choose.

How it works

A mapping rule matches a Cloud PC by an Entra ID extension attribute set on the device. You can create separate rules for each Citrix object type, so the same attribute value can place a Cloud PC into a custom machine catalog, a custom delivery group, and a custom zone at the same time:

• When you create a delivery group rule, a delivery group and a Citrix policy with the same name are created automatically. The policy controls session behavior for the delivery group.
• When you create a zone rule, a zone and a Citrix host connection with the same name are created automatically. The host connection is the channel Cloud PCs use to register into the zone.
• When you create a machine catalog rule, only the machine catalog is created automatically.

When a Cloud PC’s attribute value matches a rule, it is grouped into the named object:

• If the named object doesn’t exist yet, it’s created automatically.

  Note:

  For Frontline Cloud PCs, the created object names include a -Frontline suffix. For Entra hybrid joined Cloud PCs, the created object names include a -Hybrid suffix.

• If an object with that name already exists, the Cloud PC joins it instead. Cloud PCs that share the same attribute value are grouped into the same object. For example, three Cloud PCs with the same value are placed into one machine catalog, not three.

Note:

Mapping rules apply when a Cloud PC next registers with Citrix. Changing or adding rules doesn’t move Cloud PCs that are already registered until they register again. For steps to apply your rules, see Apply mapping rules.

Create a mapping

1. Sign in to Web Studio and go to Quick Deploy > Windows 365 in the left pane.

2. Select Cloud PC mappings.

3. (Multiple tenants only) Select the tenant that you want to configure from the tenant list.

4. Select Create mapping.

5. Select the Property (an extension attribute from 1 through 15) and enter the Value to match.

6. Select a Citrix object from the Machine catalog, Delivery group, and Zone options, and enter the Object name to use.

   The object name must meet the following requirements:

   • Up to 55 characters.
   • Can’t end with a backslash (\).
   • Can’t contain the following characters: / ; : # . * ? = < > | [ ] ( ) " ' ` ~

7. (Optional) To confirm a Cloud PC matches this rule, enter a user’s UPN and select Validate. A green result confirms a match.

8. Select Create mapping.

For steps to apply the rules you created, see Apply mapping rules.

Apply mapping rules

Mapping rules take effect only when a Cloud PC registers with Citrix. Follow the steps for your situation.

Cloud PCs not yet registered with Citrix

Create your rules before the Cloud PCs register so they are applied during the first registration.

1. In Entra ID, set the extension attribute on each Cloud PC device.
2. In Web Studio, create your rules on the Cloud PC mappings page.
3. Go to Quick Deploy > Windows 365 > License assignments and assign the Citrix license to the users.

When each Cloud PC registers, it is automatically placed into the machine catalog, delivery group, and zone specified by the matching rule.

Cloud PCs already registered with Citrix

Already-registered Cloud PCs keep their current grouping until they re-register. To apply new or updated rules, remove and then reassign the Citrix license to trigger a new registration.

1. Go to Quick Deploy > Windows 365 > License assignments.
2. Remove the Citrix license from the affected users.
3. Wait until each Cloud PC is removed from its machine catalog and delivery group. The Cloud PC isn’t deleted, and existing machine catalogs, delivery groups, and zones remain even if they become empty.
4. Reassign the Citrix license to the same users. Each Cloud PC registers again, and the new rules are applied.

Note:

Don’t reprovision a Cloud PC to apply mapping rules. Reprovisioning recreates the Cloud PC, and its extension attribute might not be retained, which prevents the rules from matching.

Check which rules apply to a user

Use Check mapping to see which rules a specific user’s Cloud PC matches.

1. On the Cloud PC mappings page, select Check mapping.

2. Enter the user’s UPN and select Run check.

3. Review the results table, which lists each matching machine catalog, delivery group, and zone.

Edit a mapping

1. Select a single mapping in the list, then select Edit.

2. Update the Citrix object or Object name. You cannot update the Property and Value.

3. Select Save, then confirm the change.

Note:

Changes apply the next time a Cloud PC registers. To apply changes to Cloud PCs that are already registered, see Apply mapping rules.

Delete a mapping

1. Select one or more mappings in the list.

2. Select Delete, then confirm.

Note:

Before you can disconnect a Windows 365 tenant, you must delete all of its mappings.