Workspace Environment Management

Actions

Workspace Environment Management (WEM) streamlines the workspace configuration process by providing you with easy-to-use actions. You can use assignments to make actions available to users. WEM also provides you with filters to contextualize your assignments.

Group Policy settings

Important:

  • Workspace Environment Management (WEM) currently supports adding and editing only Group Policy settings associated with the HKEY_LOCAL_MACHINE and the HKEY_CURRENT_USER registry hives.

Rather than relying on an Active Directory administrator to use the Group Policy Management console to manage Group Policy Objects (GPOs), you can deploy GPOs through WEM.

Before you start, add or import your Group Policy settings. You then deploy your settings by assigning them to your users in the form of GPOs. You can manage the assignments for each GPO by specifying the targets you want to assign it to.

When the feature is enabled:

  • You can configure your settings.
  • The WEM agent can process Group Policy settings.

When the feature is disabled:

  • You cannot configure Group Policy settings.
  • The WEM agent does not process Group Policy settings even if they are already assigned to users or user groups.

Note:

For WEM agents to process and apply Group Policy settings properly, verify that Citrix WEM User Logon Service is enabled on them.

Registry-based settings

Use this tab to configure settings for Windows by configuring registry operations.

In Actions > Group Policy Settings > Registry-based under a configuration set, you can perform the following operations:

  • Import registry-based Group Policy settings into WEM.
  • Create a GPO.
  • Refresh the GPO list.
  • Edit a GPO.
  • Manage assignments for a GPO.
  • Clone a GPO.
  • Delete a GPO.

Warning:

Editing, adding, and deleting registry-based settings incorrectly can prevent the settings from taking effect in the user environment.

Import Group Policy settings

You can import GPOs from a zip file containing your GPO backups or exported registry files.

When importing settings from registry files, you can convert registry values that you export using the Windows Registry Editor into GPOs for management and assignment. Before you start, be aware of the following:

  • When importing settings from a zip file, the file can contain one or more registry files.

  • Each .reg file will be converted into a GPO. You can treat each converted GPO as a set of registry settings.

  • The name of each converted GPO is generated based on the name of the corresponding .reg file. Example: If the name of the .reg file is test1.reg, the name of the converted GPO is test1.

  • The feature supports converting delete operations associated with registry keys and values that you define in .reg files. For information about deleting registry keys and values by using a .reg file, see https://support.microsoft.com/en-us/topic/how-to-add-modify-or-delete-registry-subkeys-and-values-by-using-a-reg-file-9c7f37cf-a5e9-e1cd-c4fa-2a26218a1a23.

  • Descriptions of converted GPOs are empty.

To import your Group Policy settings, complete the following steps:

  1. In the action bar, click Import.

  2. Select the file type.

    • GPO backup file. Select this option if you want to import settings from GPO backup files. For information on how to back up Group Policy settings, see Back up Group Policy settings.

    • Exported registry file. Select this option if you want to import settings from registry files you export using the Windows Registry Editor.

  3. Click Browse to navigate to your zip file.

    Note:

    You can upload only files whose size doesn’t exceed 10 MB.

  4. Choose whether to overwrite existing GPOs with the same name.

  5. Click Import to start the import process.

After the import completes successfully, imported GPOs appear on the Registry-based tab.

Create a GPO

To create a GPO, complete the following steps:

  1. In the action bar, click Create GPO.

  2. Specify a name for the GPO.

  3. Optionally, specify additional information to help you identify the GPO.

  4. Click Add to add registry operations. The following settings become available:

    • Action. Lets you specify the type of action for the registry key.

      • Set value. Lets you set a value for the registry key.
      • Delete value. Lets you delete a value for the registry key.
      • Create key. Lets you create the key as specified by the combination of the root key and the subpath.
      • Delete key. Lets you delete a key under the registry key.
      • Delete all values. Lets you delete all values under the registry key.
    • Root Key. Supported values: HKEY_LOCAL_MACHINE and HKEY_CURRENT_USER.

    • Subpath. The full path of the registry key without the root key. For example, if HKEY_LOCAL_MACHINE\Software\Microsoft\Windows is the full path of the registry key, Software\Microsoft\Windows is the subpath.

    • Name. Lets you specify a name for the registry value. The highlighted item in the following diagram as a whole is a registry value.

      Registry value in the registry editor

    • Type. Lets you specify the data type for the value.

      • REG_SZ. This type is a standard string used to represent human readable text values.
      • REG_EXPAND_SZ. This type is an expandable data string that contains a variable to be replaced when called by an application. For example, for the following value, the string “%SystemRoot%” will be replaced by the actual location of the folder in an operating system.
      • REG_BINARY. Binary data in any form.
      • REG_DWORD. A 32-bit number. This type is commonly used for Boolean values. For example, “0” means disabled and “1” means enabled.
      • REG_DWORD_LITTLE_ENDIAN. A 32-bit number in little-endian format.
      • REG_QWORD. A 64-bit number.
      • REG_QWORD_LITTLE_ENDIAN. A 64-bit number in little-endian format.
      • REG_MULTI_SZ. This type is a multistring used to represent values that contain lists or multiple values. Each entry is separated by a null character.
    • Data. Lets you type data corresponding to the registry value. For different data types, you might need to type different data in different formats.

  5. After you finish, click Done.

Edit a GPO

To edit a GPO, complete the following steps:

  1. Select the GPO and then click Edit in the action bar.

  2. Edit the name and description

  3. Do the following as needed:

    • Click Add to add a registry operation.

    • Select a registry operation and then edit it.

    • Delete a registry operation and then delete it.

    • Move a registry operation down or up. Alternatively, select a registry operation, click the six-dot icon, and then drag it to the desired position.

  4. After you finish, click Done.

Note:

If a GPO is already assigned to users, editing it will impact those users.

Manage assignments for a GPO

Note:

When assigning GPOs to machines, make sure that the machines reside in relevant security groups.

You can assign a GPO to different AD groups. A group can contain users and machines. Machine-level settings take effect if the related machine belongs to the group. User-level settings take effect if the current user belongs to the group.

Tip:

For machine-level settings to take effect immediately, restart the Citrix WEM Agent Host Service. For user-level settings to take effect immediately, users must log off and log back on.

To manage assignment for a GPO, complete the following steps:

  1. Select the GPO and then click Manage assignments in the action bar.

  2. Select assignment targets (users and groups) to assign the GPO to.

  3. Use filters to contextualize the assignment and then set the priority of the GPO for each target.

    Tip:

    For information about adding filters, see Filters. Group Policy settings comprise user and machine settings. Some filter conditions apply only to user settings. If you apply those conditions to machine settings, the WEM agent skips them when evaluating the filter before assigning the settings. For a complete list of conditions that do not apply to machine settings, see Conditions not applicable to machine settings.

  4. Click the ellipsis icon on each tile and do the following as needed:

    • Copy configuration. Lets you copy the configuration of the GPO.

    • Paste configuration. Lets you paste the configuration you copied from other configuration.

    • Apply this configuration to all targets. Lets you apply the configuration of the GPO to all targets.

  5. After you finish, click Save.

Clone a GPO

To clone a GPO, complete the following steps:

  1. Select the GPO and then click Clone in the action bar.

  2. Edit the name and description.

  3. Select the configuration set you want to clone the GPO to.

  4. Click Clone to start the clone process.

Delete a GPO

To delete a GPO, select it and then click Delete in the action bar.

Note:

If a GPO is already assigned to users, deleting it will impact those users.

Template-based settings

Use this tab to configure settings for Windows by using Group Policy Administrative Templates. You can configure GPOs at a machine and user level.

In Actions > Group Policy Settings > Template-based under a configuration set, you can perform the following operations:

  • Create a GPO with a template.
  • Manage templates.
  • Import templates.
  • Refresh the GPO list.
  • Edit a GPO.
  • Manage assignments for a GPO.
  • Clone a GPO.
  • Delete a GPO.

Create a GPO with a template

To create a GPO with a template, complete the following steps:

  1. In the action bar, click Create GPO.

  2. In Basic information:

    • Specify a name for the GPO.
    • Optionally, specify additional information to help you identify the GPO.
  3. In Computer configuration, configure policies that you want to apply to machines (regardless of who logs on to them).

  4. In User configuration, configure policies that you want to apply to users (regardless of which machine they log on to).

  5. In Summary, review the changes you made.

  6. After you finish, click Done.

In Computer configuration and User configuration, select a setting to configure it. You can show policies in tree view and list view. In list view, policies are sorted alphabetically, and you can search for desired policies.

To configure a setting, you first enable it. A setting might have multiple items that can be configured. Depending on the type of input needed, the setting can be a check box, input box (text or number as input), selection, list, or a combination.

For information about the settings, download a GPO reference sheet from Microsoft.

Manage templates

To manage templates, complete the following steps:

  1. In the action bar, click Manage template.

  2. In the Manage template wizard:

  • Select Computer configuration to configure policies that you want to apply to machines (regardless of who logs on to them).
  • Select User configuration to configure policies that you want to apply to users (regardless of which machine they log on to).
  1. After you finish, click Done.

In Computer configuration and User configuration, select a setting to configure it. You can show policies in tree view and list view. In list view, policies are sorted alphabetically, and you can search for desired policies.

To configure a setting, you first enable it. A setting might have multiple items that can be configured. Depending on the type of input needed, the setting can be a check box, input box (text or number as input), selection, list, or a combination.

For information about the settings, download a GPO reference sheet from Microsoft.

Import templates

You can import ADMX files to WEM for use as templates. You then create GPOs with those templates. To import templates, complete the following steps:

  1. In the action bar, click Manage template.

  2. In the Manage template wizard, click Import.

  3. Browse to the zip file that contains your ADMX files and decide what to do if the file contains a template with the same name as an existing template:

    • Do not import. Cancels the import.
    • Skip the template and import the rest.
    • Overwrite the existing template. Overwriting might change associated settings originating from existing templates. Existing GPOs created with the templates are not affected. However, when you edit those GPOs, associated settings are lost.
  4. Click Start import to start the import process.

  5. After you finish, click Done to return to the Manage template wizard.

  6. Manage templates there or click Done to exit.

For information on how to manage your imported template files, see Files. When managing them there, consider the following:

  • Deleting GPO administrative template files will remove the associated settings from your current template. Existing GPOs created with the templates are not affected. However, when you edit those GPOs, associated settings are lost.

Edit a GPO

To edit a GPO, complete the following steps:

  1. Select the GPO and then click Edit in the action bar.

  2. In Basic information, edit the name and description.

  3. In Computer configuration, edit machine policies.

  4. In User configuration, edit user policies.

  5. In Summary, review the changes you made.

  6. After you finish, click Save.

Note:

If a GPO is already assigned to users, editing it will impact those users.

Manage assignments for a GPO

You can manage assignments for GPOs created using templates, just like you do for registry-based GPOs. For more information, see Manage assignments for a GPO.

Clone a GPO

To clone a GPO, complete the following steps:

  1. Select the GPO and then click Clone in the action bar.

  2. Decide whether to clone the GPO as a registry-based GPO or a template-based GPO.

    Note:

    When cloned as registry-based, the GPO is converted to registry values and appears on the Registry-based tab. You can treat each converted GPO as a set of registry settings.

  3. Edit the name and description.

  4. Select the configuration set you want to clone the GPO to.

  5. Click Clone to start the clone process.

Delete a GPO

To delete a GPO, select it and then click Delete in the action bar.

Note:

If a GPO is already assigned to users, deleting it will impact those users.

External tasks (preview)

Tip:

External tasks work at a user session level. To run tasks at a machine level, use Scripted Tasks instead.

This feature lets you create external tasks to assign to your users. External tasks work at a user session level and can be scripts or applications. Make sure that the target agent machines have the necessary programs to run them. Commonly used scripts include: .vbs and .cmd scripts.

You can specify when to run an external task so that you can manage your user environments precisely and effectively.

Tip:

You can use dynamic tokens to extend WEM actions to make them more powerful.

You can perform the following operations:

  • Create an external task.
  • Refresh the external task list.
  • Edit an external task.
  • Manage assignments for an external task.
  • Clone an external task.
  • Delete an external task.

Tip:

You can quickly enable or disable an external task by using the toggle in the State column. To enable a task, configure at least 1 trigger for it.

Create an external task

To create a task, complete the following steps:

  1. In External Tasks, click Create external task.

  2. On the Task tab, configure the following settings.

    • Name. Specify a name to help you identify the task.

    • Description. Specify additional information about the task.

    • Enable this task. Controls whether the task is enabled or disabled. When disabled, the agent does not process the task even if the task is assigned to users.

    • Task details

      • Path. Enter the path to the task or browse to the task. The path resolves in the user environment. Make sure that:

        • The path you specified here is consistent with the target agent machine.
        • The target agent machine has the corresponding program to run the task.
      • Arguments. Specify launch parameters or arguments. You can type a string. The string contains arguments to pass to the target script or application. For examples about using the Path and Arguments fields, see External task examples.

    • Task settings

      • Run hidden. If selected, the task runs in the background and is not visible to users.
      • Run once. If selected, WEM runs the task only once regardless of which options you select in Triggers and regardless of whether agents restart.
      • Execution order. Use this option when you have multiple tasks assigned to users and some tasks rely on others to run successfully. Tasks with an execution order value of 0 (zero) run first, then those with a value of 1, then those with a value of 2, and so on.
      • Wait for task to complete. Specify how long the agent waits for the task to complete. By default, the Wait timeout value is 30 seconds.
  3. On the Triggers tab, select triggers that you want to associate with the task.

    Note:

    Not all triggers can be associated with external tasks. See Considerations.

    • Create new trigger. See Create a trigger.

    • Show only triggers that apply to this task. Filter out triggers that do not apply to the task.

  4. When you finish, click Done to save and exit.

Considerations

External tasks work at a session level. You can associate only the following triggers with external tasks. For more information, see Supportability matrix for triggers.

  • Built-in triggers:

    • Agent refresh
    • Reconnect
    • Logon
    • Logoff
    • Disconnect
    • Lock
    • Unlock
    • Scheduled
  • User process triggers:

    • Process started
    • Process ended

When using the Reconnect built-in trigger, consider the following:

  • If the WEM agent is installed on a physical Windows device, this option is not applicable.

When using the Disconnect, Lock, and Unlock triggers, consider the following:

  • The implementation of disconnect, lock, and unlock is based on Windows events. In some environments, these options might not work as expected. For example, in desktops running on Windows 10 or Windows 11 single-session VDAs, the disconnect option does not work. Instead, use the lock option. (In this scenario, the action we receive is “lock.”)

  • We recommend that you use these triggers with the UI agent. Two reasons:

    • When you use them with the CMD agent, the agent starts in the user environment each time the corresponding event occurs, to check whether the external task runs.
    • The CMD agent might not work optimally in concurrent task scenarios.

With user process triggers, you can define external tasks to supply resources only when certain processes are running and to revoke those resources when the processes end. Using processes as triggers for external tasks lets you manage your user environments more precisely compared with processing external tasks on logon or logoff. Before using user process triggers, verify that the following prerequisites are met:

  • The WEM agent launches and runs in UI mode.
  • The specified processes run in the same user session as the logged-on user.
  • To keep the configured external tasks up to date, be sure to select Enable Automatic Refresh on the Advanced Settings > Configuration > Advanced Options tab.

Edit an external task

To edit a task, perform the following steps:

  1. In External Tasks, select the task. If needed, use the search box to quickly find the task.

  2. Click Edit in the action bar.

  3. On the Task and Triggers tabs, make changes as needed.

  4. After you finish, click Done.

Manage assignments for an external task

To manage assignments for an external task, complete the following steps:

  1. Select the task and then select Manage assignments in the action bar.

  2. Select assignment targets (users and groups) to assign the task to.

  3. Use filters to contextualize the assignment.

    • For information about adding filters, see Filters.
  4. After you finish, click Done.

Clone an external task

Note:

Trigger associations and assignments are not cloned.

To clone a task, complete the following steps:

  1. Select the task and then select Clone in the action bar.

  2. Edit the name and description.

  3. Select the configuration set you want to clone the task to.

  4. Click Clone to start the clone process.

Delete an external task

To delete a task, select it and then select Delete in the action bar.

Note:

If an external task is already assigned to users, deleting it will impact those users.

More information

Back up Group Policy settings

To back up your Group Policy settings, complete the following steps on your domain controller:

  1. Open the Group Policy Management Console.
  2. In the Group Policy Management window, right-click the GPO you want to back up and then select Back Up.
  3. In the Back Up Group Policy Object window, specify the location where you want to save the backup. Optionally, you can give the backup a description.
  4. Click Back Up to start the backup and then click OK.
  5. Navigate to the backup folder and then compress it into a zip file.

Note:

WEM supports importing zip files that contain multiple GPO backup folders.

Configure FSLogix Profile Container using WEM GPO

For an example of how to configure settings for Windows by using Group Policy Administrative Templates, see Configure FSLogix Profile Container using WEM GPO.

External task examples

For a script (for example, PowerShell script):

  • If neither the folder path nor the script name contains blank spaces:
    • In the Path field, type the following: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe.
    • In the Arguments field, type the following: C:\<folder path>\<script name>.ps1.

    Alternatively, you can type the path to the script file directly in the Path field. For example: C:\<folder path>\<script name>.ps1. In the Arguments field, specify arguments if needed. However, whether the script file runs or opens with a different program depends on file type associations configured in the user environment. For information about file type associations, see File Associations.

  • If the folder path or the script name contains blank spaces:
    • In the Path field, type the following: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe.
    • In the Arguments field, type the following: -file C:\<folder path>\<script name>.ps1.

For an application (for example, iexplore.exe):

  • In the Path field, type the following: C:\Program Files\"Internet Explorer"\iexplore.exe.
  • In the Arguments field, type the URL of the website to open: https://docs.citrix.com/.