Citrix WEM Service
Citrix WEM Service
Citrix WEM Service
Management service
Contents
What’s new 10
Deprecation 56
Known issues 57
System requirements 81
Limits 83
Install agents 87
Upgrade 114
Migrate 116
Ribbon 126
Actions 131
Applications 150
Printers 158
Ports 164
Filters 178
Assignments 181
Security 210
Administration 247
Monitoring 252
Actions 263
Assignments 309
Triggers 320
Monitoring 379
Administration 380
Insights 391
Reports 394
Files 403
Enrollment 404
Invitation 406
Automatically back up configuration sets using WEM APIs and Windows PowerShell 434
Troubleshoot VDA registration and session launch issues using scripted tasks 479
Glossary 577
November 1, 2023
Note:
• The Workspace Environment Management service is available globally, with US‑based, EU‑
based, and Asia Pacific South based instances. We are working to enable Workspace Envi‑
ronment Management service instances in more regions.
• Workspace Environment Management service is also available in Citrix Cloud Japan, a cloud
that is isolated and separate from Citrix Cloud. Japanese customers can use the service in
a dedicated Citrix‑managed environment. For more information, see Citrix Cloud Japan.
• For information about Workspace Environment Management service customer data stor‑
age, retention, and control, see Customer data management.
Introduction
The Workspace Environment Management service uses intelligent resource management and Profile
Management technologies to deliver the best possible performance, desktop logon, and application
response times for the following deployments:
• Citrix DaaS (formerly Citrix Virtual Apps and Desktops service) and Citrix Virtual Apps and Desk‑
tops
• Azure Virtual Desktop
Important:
To manage Azure Virtual Desktop with the Workspace Environment Management service, you
must purchase the Citrix Optimization Pack.
– Uses Citrix Profile Management to manage user profiles across sessions and endpoints
– Delays unessential processes from the logon process to improve logon times
– Applies logon‑related configuration in the background, after a user logs on
– Eliminates most of the setup tasks that the on‑premises version of Workspace Environ‑
ment Management requires
Technical overview
The following components are hosted in Citrix Cloud and administered by Citrix as part of the ser‑
vice:
• Infrastructure services. The infrastructure services are installed on a multi‑session OS. They
synchronize various back‑end components (SQL Server and Active Directory) with front‑end
components (administration console and agent). We ensure that sufficient infrastructure ser‑
vices are provided on Citrix Cloud.
• Administration console. You use the administration console, available on the service’s Man‑
age tab, to manage your user environment using your web browser. The administration console
is hosted on a Citrix Cloud‑based Citrix virtual Apps server. The server provides a Citrix Work‑
space app for HTML5 connection to the administration console.
• Azure SQL Database. Workspace Environment Management service settings are stored in a
Microsoft Azure SQL Database service, deployed in an elastic pool. This component is managed
by Citrix.
The following components are installed and managed in each resource location by the customer/part‑
ner:
• Agent. The Workspace Environment Management service agent connects to the Workspace En‑
vironment Management infrastructure services and enforces the settings you configure in the
administration console. All communications are over HTTPS using the Citrix Cloud Messaging
Service. You can deploy the agent on a Virtual Delivery Agent (VDA). Doing so lets you manage
single‑session or multi‑session environments. You can also deploy the agent on a physical Win‑
dows endpoint.
All agents use local caching, ensuring that agents can continue using the latest settings if the
network connection is interrupted.
Note:
• Microsoft Active Directory Server. The Workspace Environment Management service requires
access to your Active Directory to push settings to your users. The infrastructure service com‑
municates with your Active Directory using the Citrix Cloud identity service.
• Cloud Connector. The Citrix Cloud Connector is required to allow machines in your resource
locations to communicate with Citrix Cloud. Install Citrix Cloud Connector on at least one ma‑
chine in every resource location that you are using. For continuous availability, install multiple
Cloud Connectors in each of your resource locations. We recommend at least two Cloud Connec‑
tors in each resource location to ensure high availability. If one Cloud Connector is unavailable
for any period of time, the other Cloud Connectors can maintain the connection.
Get started
What’s new
A goal of Citrix is to deliver new features and product updates to Workspace Environment Manage‑
ment (WEM) service customers when they are available. New releases provide more value, so there
is no reason to delay updates. Updates are rolled out to the service release approximately every four
weeks.
This process is transparent to you. Updates are applied to Citrix internal sites initially, and are then
applied to customer environments gradually. Delivering updates incrementally in waves helps ensure
product quality and maximize availability.
In general, updates to the documentation are made available before new features and product up‑
dates are accessible to all customers.
For information about the service level goal for the WEM service for cloud scale and service availability,
see Service Level Goals. To monitor service interruptions and scheduled maintenance, see the Service
Health Dashboard.
March 2024
WEM provides automatic backup of configuration sets. The automatic backup limit is now enhanced
to support storage of up to 25 backup files for each configuration set before overwriting the oldest
existing file. This enhancement reduces the operation effort, especially for large and complex envi‑
ronments. For more information, see Manage automatic backup.
• To support user level assignments, you can now apply the WEM action JSON files for the Win‑
dows 11 Start menu configuration. Using the new tool Start Menu Configurator for Windows
11 in the WEM Tool Hub, you can now select applications that you prefer to add to the Pinned
section of the Start menu and arrange the layout as needed. After customizing the layout, copy
the configuration data and paste the data in the web console, when you add a new JSON object
in the JSON Files page. For more details, see Customize the Start menu layout for Windows 11.
This tool is introduced in the WEM Tool Hub to help you create user stores. The user store is the central
network location for storing Citrix user profiles. This tool helps you to set up user stores by creating
file shares and setting appropriate permissions to them according to your specifications. This tool
simplifies the configuration process and reduces errors. You can choose to create the user store on
the current machine (running the tool) or on a different machine. For more details, see User store
creation tool.
Fixes
• Creating or duplicating Printers, Network drives, or User DSNs is very slow on the WEM web
console. [WEM‑32997]
• Upgrading the WEM database successively, results in the error The given key was not present
in the dictionary. [WEM‑34849]
• The Profile Management health column might show a question mark even when the Profile
Management is configured correctly. This issue occurs when the UpmConfigCheck.ps1
script used by the WEM agent does not work as expected. This issue affects the machines in‑
stalled with the Profile Management 2203 LTSR. [WEM‑34822, CVADHELP‑24723]
February 2024
This feature lets you group individual actions and manage their assignments in one place. Assign‑
ments are created per action rather than at the group level. You can now add actions to a group and
select assignment targets, create, edit, and delete assignment groups. Assignment details like filters
and options are maintained at the individual item level. For more details, see Assignment groups.
You can now gain a clearer and more detailed insight into the status of Profile Management through
Workspace Environment Management:
• Invalid: Indicates that Profile Management is either not found or not enabled.
• Error: Indicates configuration issues in Profile Management.
• Warning: Identifies a suboptimal state of Profile Management.
• Notice: Identities an acceptable state of Profile Management.
• Good: Identities Profile Management is in a healthy state.
For more details, see the description for Profile Management health column in Statistics.
• This enhancement provides a more detailed data analysis for User profile and Citrix Profile
Management. Group policy objects sub‑metric is now introduced with HDX connection sub‑
metric being enabled. For more details, see Windows Logon analysis.
You can now open the WEM standalone tool to check the status of the WEM components and trou‑
bleshoot. This tool can run on WEM agents or the infrastructure server providing results for different
selected (check) items respectively. After completing a check, a report is saved to their machine. You
can turn on the debug mode and retrieve the log files to the specified location. You can also fix some
configuration issues automatically. For more details, see WEM health check tool.
Fixes
• When the WEM agent runs on Windows Server 2022, the memory usage limit you apply to spe‑
cific processes might not work as expected. [WEM‑28773]
January 2024
Using the web console, you can now add user data source names (DSNs) and assign them to users.
For more details, see User DSN.
Ports
Using the web console, you can now add port mappings and assign them to users. For more details,
see Ports.
INI files
Using the web console, you can now add INI file operations and assign them to users. For more details,
see INI files.
This enhancement allows you to check the progress and results of tasks initiated in the last 24 hours.
You can see the task status for each of the target agents after you trigger a task. You can also view the
history of recent tasks and their statuses. For tasks with reports, you can access those reports directly
from the Reports tab. For more details, see Agents.
This enhancement lets you filter and add multiple values by separating each value with a semicolon
when you choose the Result summary condition, providing a flexible method for report management
that enables you to monitor and optimize the system.
Profile Management
Workspace Environment Management now supports all supported versions of Profile Management
through 2311. The following features are now available in the web console.
• User store selection method. Specifies the user store selection method when multiple user
stores are available. Options include:
– Configuration order. Lets Profile Management select the earliest configured store.
– Access performance. Lets Profile Management select the store with the best access per‑
formance.
The feature is available under each configuration set in Profiles > Profile Management Set‑
tings > Advanced settings > Replicate user stores. For more information, see Citrix Profile
Management Settings.
• Deduplicate files this size or larger (MB). Specifies the minimum size of files to deduplicate
from profile containers. The default size is 256 MB.
The feature is available under each configuration set in Profiles > Profile Management Set‑
tings > File deduplication > Enable file deduplication. For more information, see Citrix Profile
Management Settings.
• Log off users when profile container is not available during logon. Specifies whether to
force log‑off users when the profile container is unavailable during user logon.
The feature is available under each configuration set in Profiles > Profile Management Set‑
tings > Profile container > Enable profile container. For more information, see Citrix Profile
Management Settings.
• Set users and groups to access profile container. Specifies which AD domain users and
groups have Read & Execute permission on profile containers. By default, a profile
container is accessible only to its owner.
The feature is available under each configuration set in Profiles > Profile Management Set‑
tings > Profile container. For more information, see Citrix Profile Management Settings.
Fixes
• Using the Agent auto upgrade feature results in the upgrade failure on the x32 platform. [WEM‑
32783]
• Machine‑level GPOs assigned to the agent might fail when other AD objects have the same name
as the agent in the domain. [WEM‑32315, CVADHELP‑23868]
November 2023
The following enhancements are made to the automatic agent upgrade feature:
• You can select the desired agent package from the centralized SMB share package storage loca‑
tion, and schedule automatic upgrades for all agent machines in a configuration set.
• You can now specify the time period and schedule the day(s) of the week on which you want
WEM to automatically roll out the upgrade to all agent machines in a configuration set.
• You can now specify the device name and IP of agent machines in a configuration set for which
you want WEM to automatically roll out the upgrades. For more details, see App Package Deliv‑
ery.
• This feature is enhanced to extend the limitation set for the maximum value of the Memory Us‑
age Limit functionality from 4 GB to 32 GB in 64‑bit OS. This enhancement provides more flexi‑
bility based on real situations in the customer system environment.
This tool collects the logon duration data and generates reports about the recent logon duration data.
Each logon report is categorized further allowing you to identify potential issues and bottlenecks. For
more details, see Windows Logon analysis.
• Administrators can now review the Application security logs in the web console by enabling ap‑
plication security log collection per configuration set and get the corresponding reports. The
administrator can view the logs by subtype within the details of each report. For more details,
see Application Security logs under Reports and the description for Security logs in Monitor‑
ing preferences.
Fixes
October 2023
Registry Entries
Using the web console, you can now add registry entries as assignable actions, which let you create,
set, or delete registry values in the user environment. The feature has been enhanced to provide a bet‑
ter user experience. Additionally, you are now able to add tags to registry entries and assign multiple
registry entries at the same time. For more information, see Registry Entries.
Two new export options are introduced for agent reports, CSV (formatted) and JSON (formatted).
These options enhance the readability of extended data within the reports. For more information, see
Export reports.
This feature lets you reorganize your view of Profile Management settings. The three built‑in tags,
File‑based, Container‑based, and App access control act like filters, helping you concentrate on
the settings available to the selected tag. The latest selected tags are retained as your administrator
preference. For more information, see Profile Management Settings.
This feature lets you configure the list of excluded applications by providing the application names.
You can add, edit, and delete the excluded applications using the settings under Preferences. For
more information, see Excluded applications.
This feature lets the administrators create, manage FTAs, and assign them to the users. Administra‑
tors can also use the File Type Association Assistant tool in the WEM Tool Hub to easily get the
information they need for configuring FTAs in the web console. For more information, see File Type
Associations.
• A new setting Enable agent to use cached domain search results is added to the agent set‑
tings. When enabled, the agent uses the cache for domain query results to improve perfor‑
mance and resiliency. You can also update WEM group policies when the agent cannot contact
the domain. For more details, see Agent Settings.
This feature improves the user experience of configuring Profile Management through WEM. When you
follow the link on the Agent health check result page to Profile Management settings, you can see the
errors/warnings in the results with its corresponding setting highlighted in the Profile Management
configuration page on the web console. You can then modify the settings according to the results
displayed in the footer. For more information, see Reports.
A new version of WEM Tool Hub is now available: 2309.2.0.1. This version includes performance
enhancements, support for AAD/NDJ object selector support, and bug fixes. For more information,
see WEM Tool Hub.
Fixes
• The application disappeared at times, when the customer exported the application setting to
the file, saved the file to the ASCII encoding, and imported the modified file to WEM again. [WEM‑
31180]
• After the machine reboots, the WEM agent may lose previous SMB shares configured in Ad‑
vanced Settings > File Shares. [WEM‑30209]
September 2023
Support for the Windows 11 and Windows Server 2022 in Citrix Optimizer
• We added support for the Windows 11 version 21H2 (build 2009) and Windows Server 2022 21H2
(build 2009) in Citrix Optimizer. You can now use the WEM service to perform template‑based
system optimizations for Windows 11 2009 and Windows Server 2022 2009 machines. In addi‑
tion, we have updated all existing templates to reflect changes introduced in the latest stand‑
alone Citrix optimizer.
For information about using Citrix Optimizer, see Citrix Optimizer.
We have now enhanced the maximum manual export limit from 10 to 25 per account. For more infor‑
mation, see Back up a configuration set.
We have now enhanced the optimization insight application and usage insight application limit from
10 to 20. For more information, see Insights.
Using the web console, you can now add registry entries as assignable actions, which let you create,
set, or delete registry values in the user environment. The feature has been enhanced to provide a bet‑
ter user experience. Additionally, you are now able to add tags to registry entries and assign multiple
registry entries at the same time. For more information, see Registry Entries.
• You can now assign app access rules to AAD users/groups and NDJ machines in addition to AD
users/groups and domain‑joined machines that are currently supported. A tool AAD/NDJ ob‑
ject selector is now available on the web console, where you can get the object data and paste
them into the Rule Generator. For more information, see Assigning app access rules to AAD
users/groups and NDJ machines.
Administrators can create and manage file system operations and assign them to the users now using
the web console. For more information, see File System Operations.
This feature lets you configure Profile Management settings at the user level for customization and
precise control. Use this feature to apply specific Profile Management settings to individual users or
user groups, tailoring the profile experience as needed. For more information, see User‑level Profile
Management settings.
• Administrators can now review the privilege elevation logs in the web console by enabling secu‑
rity log collection per configuration set and get the corresponding reports. The administrator
can view the logs by subtype within the details of each report. For more information, see the
description for Security logs in Monitoring preferences.
Profile Management
• Workspace Environment Management now supports all supported versions of Profile Manage‑
ment through 2308. The following features are now available in the web console:
– Enable VHD auto‑expansion for profile container. If enabled, when the profile container
reaches 90% utilization, it automatically expands by 10 GB, with a maximum capacity of
80 GB. Depending on your needs, you can adjust the default auto‑expansion settings us‑
ing the following options: Auto‑expansion trigger threshold (%), Auto‑expansion in‑
crement (GB), Auto‑expansion limit (GB).
The feature is available under each configuration set in Profiles > Profile Management
Settings > Profile Container. For more information, see Citrix Profile Management Set‑
tings.
– Default capacity of VHD containers. Specifies the default storage capacity (in GB) of each
VHD container.
The feature is available under each configuration set in Profiles > Profile Management
Settings > Advanced settings. For more information, see Citrix Profile Management Set‑
tings.
– Enable exclusive access to profile container. If enabled, the profile container allows only
one access at a time.
The feature is available under each configuration set in Profiles > Profile Management
Settings > Advanced settings. For more information, see Citrix Profile Management Set‑
tings.
– Enable exclusive access to OneDrive container. If enabled, the OneDrive container al‑
lows only one access at a time.
The feature is available under each configuration set in Profiles > Profile Management
Settings > Advanced settings. For more information, see Citrix Profile Management Set‑
tings.
– Enable UWP app roaming. If enabled, UWP (Universal Windows Platform) apps roam with
users. As a result, users can access the same UWP apps from different computers.
The feature is available under each configuration set in Profiles > Profile Management
Settings > Advanced Settings. For more information, see Citrix Profile Management Set‑
tings.
A new option Configure task settings is introduced in the Scripted Tasks page that directs you to
the specifically chosen filtered task wizard in the Scripted Task Settings page. For more information,
see Configure task settings option.
A new version of WEM Tool Hub is now available: 2309.1.0.1. This version includes performance
enhancements, support for AAD/NDJ object selector support, and bug fixes. For more information,
see WEM Tool Hub.
Fixes
• The Profile Management health column might show errors even when Profile Management is
configured correctly. This issue occurs because the UpmConfigCheck.ps1 script used by
the WEM agent does not work as expected. This issue affects machines with Profile Management
setting, Path to log file enabled, with the path containing %SystemRoot% in it. [WEM‑29519]
• The WEM agent will now refresh the SMB connection every time the policy settings get refreshed
instead of waiting for the next refresh, which is every 15 minutes. [WEM‑29142, CVADHELP‑
21957]
July 2023
• This feature lets you configure Profile Management settings at the user level for customization
and precise control. Use this feature to apply specific Profile Management settings to individual
users or user groups, tailoring the profile experience as needed. For more information, see User‑
level Profile Management settings.
• To enable this feature, go to Home, click the preview features icon in the upper‑right corner,
and enable User‑level Profile Management settings. See Preview features.
We have made enhancements to WEM agent event logging, aiming at improving troubleshooting ca‑
pabilities. The enhancements include:
• Comprehensive event logs: We have provided comprehensive event logs, giving you a complete
picture of agent activities.
• Unique event IDs: Each event log now has a distinct ID, making it easier for you to filter and
identify specific events.
• The WEM Transformer now supports the latest version of the Microsoft Edge browser.
• You can now add JSON objects and assign them to create or modify JSON files. Using this fea‑
ture, you can apply personalized settings to applications with a JSON configuration file (for ex‑
ample, Microsoft Teams). This feature is available only in the web console. For more informa‑
tion, see Actions.
• This feature lets you add local applications to the WEM Tool Hub for quick access. The added
applications are considered your personal data and are retained when you switch machines
within the Profile Management environment. You can add and remove multiple applications at
a time. For more information, see Add local applications for quick access.
A new version of WEM Tool Hub is now available: 2307.1.0.1. The version includes performance
enhancements and bug fixes. For more information, see WEM Tool Hub.
Fixes
• Attempts to restore a configuration set might fail if it contains too many (for example, 10,000)
template‑based GPOs. [WEM‑28447]
June 2023
• This release introduces enhancements to the CPU spike protection feature, giving you more
granular control. The enhancements include the following changes:
– We have reorganized CPU spike protection options with intuitive logic for easier configu‑
ration.
– When customizing CPU spike protection, you can now configure the CPU usage limit using
non‑integer values.
– A new option Set limit relative to single CPU core, is now available, letting you set a limit
on CPU usage based on a single CPU core as a reference.
Environment variables
• Using the web console, you can now add environment variables as assignable actions. When
assigned, those environment variables are created or set in the user environment. The feature
has been enhanced to provide a better user experience. For more information, see Environment
variables.
• Minimum agent version required: 2306.1.0.1
You can now use dynamic tokens in Group Policy settings. This feature allows for more adaptable
policy configuration in different environments, reduces manual configuration, and simplifies policy
management. For more information, see Dynamic token support for Group Policy settings.
This release introduces the action processing results report feature. With this feature, you can now
view the results of every action assigned to a user in a consolidated report that updates every 4 hours.
The report includes information such as the name of the action, the assigned user, the filter used, and
the processing result. This feature is designed for all actions but currently supports only Group Policy
setting processing results. To use the feature, first enable result collection for Group Policy settings.
For more information, see Reports and Monitoring preferences.
• You can now add JSON objects and assign them to create or modify JSON files. Using this fea‑
ture, you can apply personalized settings to applications with a JSON configuration file (for ex‑
ample, Microsoft Teams). This feature is available only in the web console. For more informa‑
tion, see Actions.
• To enable this feature, go to Home, click the preview features icon in the upper‑right corner, and
enable JSON object assignment. See Preview features.
• Minimum agent version required: 2306.1.0.1
May 2023
• You can now back up and restore your Profile Management settings. For more information, see
Back up and restore. Plus, a quick setup feature is now available, letting you quickly set up
Profile Management, whether you want to start with a fresh template or restore from a backup.
For more information, see Quick setup.
Network drives
• Using the web console, you can now add network drives as assignable actions. When assigned,
those network drives are available for use within the user’s desktop. The feature has been en‑
hanced to provide a better user experience. For more information, see Actions.
Virtual drives
• Using the web console, you can now add virtual drives as assignable actions. When assigned,
those virtual drives are available for use within the user’s desktop. The feature has been en‑
hanced to provide a better user experience. For more information, see Actions.
Advanced settings have been migrated to the web console and are available in Advanced Settings
under each configuration set. We have reorganized the settings to provide a better user experience.
For more information, see Advanced Settings.
You can now set one of the following pages as your start page so that you land on it every time you
sign in to the web console:
• Agents
• Reports
• User Statistics
• Usage Insights
• Optimization Insights
• Profile Container Insights
If no start page is set, you land on the Home page instead. After setting your start page, you can access
it quickly by clicking the lightning icon ( ) on the left navigation of the console.
A new version of WEM Tool Hub is now available: 2304.2.0.1. The version includes performance en‑
hancements and bug fixes. For more information, see WEM Tool Hub.
Fixes
• The Profile Management health column might show errors even when Profile Management is
configured correctly. This issue occurs because the UpmConfigCheck.ps1 script used by
the WEM agent does not work as expected. This issue affects machines with only one system
volume. [WEM‑27498]
April 2023
• Using the web console, you can now add rules to control user access to items such as files, fold‑
ers, and registries. A typical use case is to apply rules to control user access to apps installed on
machines —whether to make apps invisible to relevant users. This feature can simplify appli‑
cation and image management. For example, using the feature, you can deliver identical ma‑
chines to different departments while meeting their different application needs, thus reducing
the number of images. For more information, see App access control.
Printers
• Using the web console, you can now add printers to assign to your users. When assigned, those
printers are available for use within the user’s desktop. The feature has been enhanced to pro‑
vide a better user experience. For more information, see Actions.
The following two tools are now available in WEM Tool Hub:
• Printer assistant. Use it to get a list of printers from your print server so that you can add them
as assignable actions in the management console.
• Rule generator for app access control. Use it to create rules to control user access to items
such as files, folders, and registries. The rules are implemented through Citrix Profile Manage‑
ment. A typical use case is to apply rules to control user access to apps installed on machines
—whether to make apps invisible to relevant users.
Profile Management
• Workspace Environment Management now supports all supported versions of Profile Manage‑
ment through 2303. The following features are now available in both the legacy console and
the web console.
– Enable active write back on session lock and disconnection. If enabled, profile files
and folders are written back only when a session is locked or disconnected. With both
this option and the Enable active write back registry option enabled, registry entries
are written back only when a session is locked or disconnected.
* In the web console, the feature is available under each configuration set in Profiles
> Profile Management Settings > Basic settings. For more information, see Citrix
Profile Management Setting.
* In the legacy console, the feature is available in Policies and Profiles > Citrix Pro‑
file Management Settings > Main Citrix Profile Management Settings. For more
information, see Citrix Profile Management Setting.
– Enable app access control. If enabled, Profile Management controls user access to items
(such as files, folders, and registries) based on the rules you provide.
* In the web console, the feature is available under each configuration set in Profiles
> Profile Management Settings > App access control. For more information, see
Citrix Profile Management Setting.
* In the legacy console, the feature is available in Policies and Profiles > Citrix Profile
Management Settings > App Access Control. For more information, see Citrix Profile
Management Setting.
– Enable VHD disk compaction. If enabled, VHD disks are automatically compacted on user
logoff when certain conditions are met. This option enables you to save the storage space
consumed by profile container, OneDrive container, and mirror folder container.
* In the web console, the feature is available under each configuration set in Profiles >
Profile Management Settings > Profile container. For more information, see Citrix
Profile Management Setting.
* In the legacy console, the feature is available in Policies and Profiles > Citrix Pro‑
file Management Settings > Profile Container Settings. For more information, see
Citrix Profile Management Setting.
– Set free space ratio to trigger VHD disk compaction, Set number of logoffs to trigger
VHD disk compaction, and Disable defragmentation for VHD disk compaction. If En‑
able VHD disk compaction is enabled, use these three policies to adjust the default VHD
compaction settings and behavior.
* In the web console, the feature is available under each configuration set in Profiles >
Profile Management Settings > Advanced settings. For more information, see Citrix
Profile Management Setting.
* In the legacy console, the feature is available in Policies and Profiles > Citrix Profile
Management Settings > Advanced Settings. For more information, see Citrix Profile
Management Setting.
February 2023
Applications
• Using the web console, you can now add applications to assign to your users. When assigned,
those applications have their shortcuts created on the desktop, Start menu, or taskbar, depend‑
ing on your configuration. The feature has been enhanced to provide a better user experience.
For more information, see Actions.
A tool set WEM Tool Hub, is now available for WEM administrators. It includes a collection of tools that
aims to simplify the configuration experience for administrators. To download it, go to Citrix Cloud >
WEM service > Utilities. For more information, see WEM Tool Hub.
When using external tasks in the web console, you can now directly configure when the agent
processes external tasks without going to Legacy Console > Advanced Settings for related settings.
This enhancement also provides detailed information on how to ensure that the agent processes ex‑
ternal tasks. For more information about external tasks, see Actions.
Fixes
• If you use the Studio policy, Citrix Cloud Connectors, to configure Cloud Connectors for Work‑
space Environment Management, the policy does not work as expected. [WEM‑25697]
• In the legacy console, when you click the State column heading to sort, items are not sorted as
expected. [WEM‑25978, WEMHELP‑274]
• In the legacy console, the Backup Actions button is not available when you use the backup wiz‑
ard to back up Group Policy settings even if the configuration set does not contain any resources
created using the web console. [WEM‑26240]
• The privilege elevation feature might fail to work as expected. The issue occurs because the cer‑
tificate used to sign the Citrix WEM software has expired. As a workaround, bypass the certificate
validity check by creating a DWORD registry value under HKEY_LOCAL_MACHINE\SYSTEM
\CurrentControlSet\Control\Norskale\Agent Host and setting the value to 1.
[WEM‑26420, WEMHELP‑284]
January 2023
• The automatic agent upgrade feature has been migrated to the web console and is available in
Advanced Settings > Agent Settings under each configuration set. The feature now provides
a better user experience and offers extra capabilities. In addition to scheduling automatic up‑
grades for the agents, you now have the flexibility to control whether to apply agent upgrades
to persistent or non‑persistent machines. For more information, see Advanced Settings.
• Minimum agent version required: 2301.1.0.1
• You can now set up binding rules for unbound non‑domain‑joined agents. Those rules dictate
which configuration set to bind the matching agents to. This feature simplifies the process of
adding non‑domain‑joined agents for WEM to manage. For more information, see Directory
Objects.
• Minimum agent version required: 2301.1.0.1
• Using the web console, you can now assign GPOs to organizational units. This eliminates the
need to change your Active Directory structure for use with WEM. For more information, see Add
an assignment target.
• Minimum agent version required: 2301.1.0.1
Fixes
• When running in offline mode, the agent can’t connect to the SMB shares you configured in Ad‑
vanced Settings > File Shares. This issue does not affect the functionality of the agent. [WEM‑
25318]
November 2022
External task
• Using the web console, you can now create external tasks to assign to your users. External tasks
can be scripts or applications. Specify when to run external tasks to manage your user environ‑
ment precisely and effectively. Also, the web console provides an extra capability for external
tasks —letting you associate the scheduled trigger with external tasks to schedule when to run.
For more information, see External tasks.
• Previously, WEM agents periodically connected to the WEM service to download configuration
data whether or not there was a configuration change. Agents now periodically check with the
service to see if any configuration changes were made:
This enhancement significantly reduces bandwidth consumption, especially if you have a large
deployment with many agents.
Fixes
• If you restore settings from a previous backup, you experience issues with user store‑related
credentials.
– In the legacy console, you can’t save changes made to the credentials.
– In the web console, the restored credentials fail to appear in Advanced Settings > File
Shares. [WEM‑23466]
• On Mozilla Firefox browsers, the built‑in scripted task Cloud Health Check fails to appear above
custom scripted tasks. [WEM‑24166]
• An application security rule fails to work when both of the following conditions are met:
• If a registry file contains a registry key without a registry value, the scan of the file for import to
Workspace Environment Management stops. Registry keys already scanned appear in the list.
[WEM‑24767]
Filter enhancements
• This feature lets you use the AND and OR operators to build filters. You can use the operators
to combine two or more conditions into a compound condition. This feature gives you more
flexibility to build filters for use with assignments and scripted tasks. For more information, see
Filters.
October 2022
• The following built‑in trigger types are now available when you create triggers:
• You can create triggers of these types and associate tasks with them. When activated, the trig‑
gers start those tasks in the user environment. The two additional trigger types give you more
flexibility to control when to run your scripted tasks. For more information, see Triggers.
• The following trigger types are now available when you create triggers
– Cloud Health Check result. Activates the trigger when Cloud Health Check returns speci‑
fied health statuses.
– Profile Management health check result. Activates the trigger when Profile Manage‑
ment health check returns specified health statuses.
– Custom scripted task result. Activates the trigger when scripted tasks return specified
results.
You can create triggers of these types and associate tasks with them. When activated, the trig‑
gers start those tasks in the user environment. These trigger types let you automatically manage
your user environments based on task execution results. For more information, see Triggers.
Profile Management
• Workspace Environment Management now supports all supported versions of Profile Manage‑
ment through 2209. The following feature is now available in both the legacy console and the
web console.
– File deduplication. If enabled, Profile Management removes duplicate files from the user
store and stores one copy of them in a central location. Doing so reduces the load on the
user store by avoiding file duplication, thus reducing your storage cost.
* In the web console, the feature is available under each configuration set in Profiles >
Profile Management Settings > File deduplication. For more information, see Citrix
Profile Management Setting.
* In the legacy console, the feature is available in Policies and Profiles > Citrix Profile
Management Settings > File Deduplication. For more information, see Citrix Profile
Management Setting.
In the web console, a tab, Registrations, is now available in Monitoring > Administration > Agents.
The tab lets you view the registration status of agents in your WEM deployment. With the information,
you can troubleshoot agent registration issues. For more information, see Administration.
You can now clone assignment targets (users and groups) from one configuration set to another, with‑
out the need to add them from scratch. For more information, see Assignment targets.
Fixes
• In the web console, when you use the filter, Last logon, to refine results in Monitoring > Ad‑
ministration > User Statistics, the filter might not work as expected. The issue occurs when
you leave the end date unspecified. As a workaround, specify an end date when using the filter.
[WEM‑23705]
• In Legacy Console > Policies and Profiles > Citrix Profile Management Settings, there is
no option to add user groups for which streamed profiles and cross‑platform profiles are used.
[WEM‑23874, CVADHELP‑20951, WEMHELP‑256]
September 2022
August 2022
• A new trigger type, Windows event, is now available when you create triggers. It lets you create
a Windows event‑based trigger. You can then associate tasks with it. When the Windows events
meet the defined criteria, the trigger is activated and starts the associated tasks. This trigger
type lets you automatically manage your user environments based on Windows events. For
more information, see Triggers.
• Minimum agent version required: 2208.1.0.1
• Previously, file downloads on the agent side always occurred through Citrix Cloud. You can
now let file downloads on the agent side occur through file shares. Doing so reduces network
resources needed for other critical operations. This feature reduces traffic on networks and
reduces the time to download files to agent machines. For more information, see File Shares.
• Minimum agent version required: 2208.1.0.1
• An option, Set a timeout value, is now available when you configure a scripted task. The option
lets you specify the time (in minutes) after which the task is forced to end. If you do not specify
a timeout, the task might keep running, thus preventing other tasks from running. For more
information, see Scripted Task Settings.
• Minimum agent version required: 2207.2.0.1
• A new node, Enrollment, is now available in the web console. The node contains two pages:
– Enrolled Agents. Lists all enrolled agents. You can manage them as needed.
– Invitation. Lets you send enrollment invitations to users. Each invitation includes an invi‑
tation code and the steps needed to complete the enrollment.
• An option, Filter, is now available in General when you configure a scripted task. The option
lets you use a filter to contextualize the task. As a result, the WEM agent runs the task only when
all conditions in the selected filter are met. For more information, see Configure a scripted task.
• Minimum agent version required: 2207.2.0.1
Fixes
When you add a scripted task larger than 10 MB, the following error message appears even if the task
is added successfully: Failed to add the scripted task. After you refresh the view, the
task appears. [WEM‑21241]
July 2022
Support for performing administrative tasks for non‑domain‑joined and enrolled agents
• You can now perform administrative tasks (such as refreshing the cache, resetting settings, and
retrieving agent information) for non‑domain‑joined and enrolled agents through the adminis‑
tration console, just like you do for other agents. Technically, this feature is a different imple‑
mentation. The target agents are not immediately notified of performing those tasks. The noti‑
fications are sent when the target agents or other agents on the same subnet connect to Citrix
Cloud to refresh settings. So, there might be a delay until the tasks run on the agent side. The
more agents you have on the same subnet, the shorter the delay.
• This feature is available in both the legacy console and the web console.
– In the web console, go to Monitoring > Administration > Agents. For more information,
see Administration.
– In the legacy console, go to Administration > Agents. For more information, see Admin‑
istration.
• In the web console, a tab, Template‑based, is now available in Actions > Group Policy Settings
under each configuration set. The tab lets you configure Windows GPOs by using Group Policy
Administrative Templates. You can configure GPOs at a machine and user level. After that, you
deploy them by assigning them to your users, just like you do for registry‑based GPOs. For more
information, see Group Policy Settings.
• The following new features are now available when you configure a scripted task:
– File path. A parameter type that lets you pass a file path as a parameter to the System.
IO.FileInfo class.
– Collect output even if runtime errors occur. An option that controls whether to collect
output file content and console output even if errors occur while running the task.
Fixes
• If you assign application security rules (AppLocker rules) to built‑in administrators, the rules
might not take effect on the agent machine even if the logged‑on user belongs to the adminis‑
trators group. [WEM‑21133, WEMHELP‑229]
• When you view the health status of Profile Management in the management console, you might
see errors even if Profile Management is configured correctly. The issue occurs when the local
system account under which the agent is running does not have permission to the user store.
[WEM‑21247, CVADHELP‑19963]
• In the web console, attempts to add or edit registry operations of the following types might
fail: REG_QWORD and REG_QWORD_LITTLE_ENDIAN. The issue occurs when you type
a decimal value that exceeds 9007199254740991 or a hexadecimal value that exceeds
1FFFFFFFFFFFFF. As a workaround, use the legacy console instead.
If you use the web console to edit registry operations of the two types whose value exceeds
the limit, you see the following error message: Invalid value or format. You can dismiss the
message. [WEM‑22217]
• In the web console, you can now manage Group Policy settings. The management takes the
form of configuring Windows Group Policy Objects (GPOs). After you add or import your set‑
tings, you deploy them by assigning them to your users. For more information, see Group Policy
Settings.
Profile Management
– Enable profile streaming for pending area. If enabled, files in the pending area are
fetched to the local profile only when they are requested. This ensures optimum logon
experience in concurrent session scenarios.
* In the web console, the option is available under each configuration set in Profiles >
Profile Management Settings > Streamed user profiles. For more information, see
Citrix Profile Management Setting.
* In the legacy console, the option is available in Policies and Profiles > Citrix Profile
Management Settings > Streamed user profiles. For more information, see Citrix
Profile Management Setting.
– Enable concurrent session support. Provides native Outlook search experience in con‑
current sessions. If enabled, each concurrent session uses a separate Outlook OST file.
You can specify the maximum number of VHDX disks for storing Outlook OST files.
Enable asynchronous processing for user Group Policy on logon. If enabled, Profile
Management roams with users a registry value that Windows uses to determine the pro‑
cessing mode for the next user logon —synchronous or asynchronous processing mode.
This ensures that the actual processing mode is applied each time users log on.
Enable OneDrive container. If enabled, Profile Management roams OneDrive folders with
users by storing the folders on a VHDX disk. The disk is attached during logons and de‑
tached during logoffs.
* In the web console, the three options are available under each configuration set in
Profiles > Profile Management Settings > Advanced settings. For more informa‑
tion, see Citrix Profile Management Setting.
* In the legacy console, the three options are available in Policies and Profiles > Citrix
Profile Management Settings > Advanced settings. For more information, see Citrix
Profile Management Setting.
Application launcher
tion console. Using the tool, users can launch all assigned applications in one place. For more
information, see Application launcher.
Fixes
• When you use VUEMRSAV.exe to view results about actions applied through an action group
for the current user, the Applied Actions tab might display the incorrect source of the actions.
Example: Two action groups (Group1 and Group 2) were assigned to the user and Group1
contains Application1. The Applied Actions tab might also show that Application1 is
from Group2 even if Group2 does not contain Application1. (By default, VUEMRSAV.exe is
located in the agent installation folder: %ProgramFiles%\Citrix\Workspace Environment Man‑
agement Agent\VUEMRSAV.exe.) [WEM‑20002]
May 2022
• Previously, you had to configure Cloud Connectors for WEM agents to manage them. You can
configure Cloud Connectors in two ways:
– Configure Cloud Connectors while installing the agent. For more information, see Install
the agent.
– Configure the Discover Citrix Cloud Connector from CVAD service policy. So, the agent
discovers Cloud Connector information from the relevant Citrix DaaS (formerly Citrix
Virtual Apps and Desktops service) deployment and then connects to the corresponding
Cloud Connector machines. For more information, see Configure group policies
(optional).
Starting with this release, you can enroll WEM agents without configuring Citrix Cloud Connec‑
tors. The enrollment applies to both domain‑joined and non‑domain‑joined machines. For
more information, see Enroll the agent.
– Support for bundling multiple files into a single zip file to upload. When adding a
scripted task, you can now bundle multiple files into a single zip file to upload. This feature
is useful when you want to run a scripted task that comprises multiple script files. After up‑
loading the zip file, you specify an entry point, indicating which file to run at the beginning
of the task. For more information, see Scripted Tasks.
– Include only regular expression matches in scripted task reports. A new option, In‑
clude only regular expression matches in reports, is now available in Output when you
configure a scripted task. The option controls whether to include the entire output content
in reports or only content that matches the regular expression. Enabling the option re‑
duces the amount of data transmitted to Citrix Cloud. For more information, see Scripted
Tasks.
– Ability to use tags to identify scripted tasks. You can now use tags to identify your
scripted tasks. Also, the tags act as filters, letting you rearrange your view of tasks de‑
pending on criteria that are important to you. For more information, see Scripted Tasks.
– More scheduling options available with scripted tasks. You now have additional op‑
tions to control when scripted tasks run. In addition to the hourly recurring pattern, you
can now set daily, weekly, and monthly recurrence patterns. You can also specify the date
and time at which you want scripted tasks to run, giving you more precise control. For
agents earlier than 2205.1.0.1, be aware of the considerations when using the feature. For
more information, see Configure a scripted task.
• This release includes the following enhancements to the Profile Management health check fea‑
ture:
* Added a section, Profile Management health check. The section lets you specify
which aspects to cover in Profile Management health check reports. For more infor‑
mation, see Advanced Settings.
Fixes
• When you import your AppLocker rules exported from the Microsoft AppLocker console into
WEM, rules of the hash type cannot be imported. [WEM‑20436]
• When using Legacy Console > Assignments > Modeling Wizard, you might not be able to view
the resultant actions for a user in a nested group. The issue occurs when the user does not
reside in the top group to which the actions or action groups are assigned. Example: The top
group is GroupA, GroupB is its member, and UserA is in GroupB. If you assign actions or
action groups to GroupA, you cannot view the resultant actions for UserA by using Modeling
Wizard. [WEM‑20842, WEMHELP‑225]
An option, Import Group Policy settings from Registry Files, is now available in Legacy Console
> Actions > Group Policy Settings. With the option, you can convert registry values that you export
using the Windows Registry Editor into GPOs for management and assignment. If you are familiar with
the Import registry files option available with Registry Entries, this feature:
• Lets you import registry values under both HKEY_LOCAL_MACHINE and HKEY_CURRENT_USER
.
• Lets you import registry values of the REG_BINARY and REG_MULTI_SZ types.
• Supports converting deletion operations associated with registry keys and values that you de‑
fine in .reg files.
In the web console, a new page, Filters, is now available within Assignments under each configura‑
tion set. Using that page, you can add filters for controlling when to assign actions to your users. For
Fixes
• With self‑elevation or privilege elevation disabled, the WEM agent might write the following
error to the Windows Event Log even if users experience no issues with their environment:
System.ArgumentException: Cannot delete a subkey tree because the
subkey does not exist. [WEM‑20441]
April 2022
• This release organizes existing options in the More menu in Web Console > Monitoring > Ad‑
ministration into the following groups: Agent, Profile, and Power management. The update
makes it easier for you to find what you need. The workflows for using the options remain the
same.
– Renaming Wake up agents to Wake and moving it to the Power management group
You can now clone an existing scripted task to use as a template for a new one, without the need to
create a similar task from scratch. For more information, see Scripted Tasks.
Fixes
• Attempts to restore self‑elevation rules to a different configuration set might fail. [WEM‑18602]
Citrix Optimization Pack for Azure Virtual Desktop is a new Citrix offering for optimizing Azure Virtual
Desktop workloads. The WEM service is the primary offering included in this Citrix Optimization Pack.
With the pack, you can use the WEM service to manage, optimize, and secure your native Azure Virtual
Desktop environments. For more information, see Citrix Optimization Pack for Azure Virtual Desk‑
top.
March 2022
In the web console, you can now use Citrix Profile Management to manage user profiles across ses‑
sions and desktops. For more information, see Profile Management Settings.
• Using the web console, you can now provide inputs as parameter variables in a scripted task
at runtime. Doing that lets you control how the scripted task behaves without changing the
underlying code. Also, WEM provides you with flexibility in what parameters you want to use
—parameters that accept only objects of a specific type (such as, string, integer, switch) and
named parameters (using the name of the parameter). For more information, see Scripted Task
Settings.
• You can now upgrade your WEM agents from the console on demand. The option is available in
both the legacy console and the web console. To use the feature:
– In the legacy console, go to Administration > Agents, right‑click an agent, and then select
Upgrade agent to latest version. For more information, see Administration.
– In the web console, go to Monitoring > Administration > Agents, select one or more
agents, click More, and then select Upgrade agent to latest version. For more informa‑
tion, see Administration.
• Home. Provides an overview of your WEM deployment along with information necessary for
you to get to know and get started with WEM quickly. The interface comprises the following
four parts:
• Directory Objects. Lets you add machines, groups, OUs, and more, that you want WEM to man‑
age. You can now do the following:
– Add machines, groups, Organizational Units (OUs), and more, that you want WEM to man‑
age.
– Apply settings to agents that are not bound to any configuration set. So, you can control
how unbound agents behave.
• Assignment Target. Lets you add users and groups (targets) so that you can assign actions and
security rules to them. For more information, see Assignments.
If your WEM service instance does not reside in your current region, you can now migrate the instance
to the current region yourself, without the need to contact Citrix Technical Support. Sign in to Citrix
Cloud, go to Workspace Environment Management > Utilities, select Start migration. After the mi‑
gration completes successfully, you will receive a notification. It can take up to two days to receive the
notification. We encourage you to migrate the instance to the current region for best performance.
January 2022
A new, web‑based Workspace Environment Management (WEM) console is now available. We are in
the process of migrating the full set of functionalities from the legacy console to the web console. The
web console generally responds faster than the legacy console. You can easily switch between the
web console and the legacy console from within the Manage tab to perform your configuration or
deployment management tasks. Click the down arrow next to Manage and select an option:
• Run scripted tasks. You can add scripted tasks that you customize to suit your unique environ‑
ment management needs. You can then automate those tasks with WEM by configuring them
in the applicable configuration set. For more information, see Scripted Tasks.
• Save a backup of a configuration set automatically. You can manage automatic backup for
your configuration sets. For more information, see Configuration Sets.
• Scan large files in profile containers. You can enable the WEM agent to run a scan of large files
on profile containers when container usage exceeds the specified threshold value. For more
information, see Advanced Settings.
• Prevent child processes from inheriting CPU priority. When you apply CPU spike protection,
the CPU priority of a process that triggers CPU spike protection is adjusted to a lower level. That
process’child process automatically inherits the lowered CPU priority. We added an option,
Prevent child processes from inheriting CPU priority, to the Configuration Sets > System
Optimization > CPU Management > Enable CPU spike protection tile. The option lets you
specify processes whose child processes you do not want to inherit the CPU priority. For more
information, see System Optimization.
• Language localization support for the web console. The web console is adapted for use in
languages other than English. The web console supports non‑English characters and keyboard
input even when the console itself is not localized in the preferred language of an administrator.
The supported languages are as follows: French, German, Spanish, and Japanese.
• You can now apply settings to agents that are not bound to any configuration set. The feature
lets you control how unbound agents behave. For more information, see Active Directory Ob‑
jects.
Support for managing non‑domain‑joined machines in Citrix Virtual Apps and Desktops
Standard for Azure deployments
• You can now use WEM service to manage non‑domain‑joined machines in Citrix Virtual Apps
and Desktops Standard for Azure deployments. This support enables you to assign policies and
settings to non‑domain‑joined machines as you do with domain‑joined machines. For more
information, see Manage non‑domain‑joined machines.
WEM service now supports enumerating Azure Active Directory (AD) users and groups. After connect‑
ing your Citrix Cloud account to your Azure AD, you can add Azure AD users and groups that you want
WEM to manage. For information about connecting your Citrix Cloud account to Azure AD, see Con‑
nect Azure Active Directory to Citrix Cloud.
External task
• This release includes enhancements to the external task feature. The feature now provides you
with three additional options to control when to run external tasks:
– Disconnect. Controls whether to run the external task when a user disconnects from a
machine where the agent is running.
– Lock. Controls whether to run the external task when a user locks a machine where the
agent is running.
– Unlock. Controls whether to run the external task when a user unlocks a machine where
the agent is running.
Profile Management
– Enable File Exclusions for Profile Container. Available on the Profile Container Set‑
tings tab, the option controls whether to exclude the listed files from the profile container.
– Enable File Inclusions for Profile Container. Available on the Profile Container Set‑
tings tab, the option controls whether to keep the listed files in the profile container when
their parent folders are excluded.
– Customize storage path for VHDX files. Available on the Advanced Settings tab, the
option controls whether to store VHDX files of different policies in different folders under
the specified storage path.
This release also adds wildcard support for Profile Management. When specifying files or fold‑
ers, you can now use wildcards. For more information, see Citrix Profile Management Settings.
Administrative access to WEM service based on Azure Active Directory (AD) group membership
You can now manage administrative access to WEM service based on Azure AD group membership.
Users (administrators) within the Azure AD group can directly onboard to Citrix Cloud and access WEM
service –you do not need to manually add them in Citrix Cloud. A general workflow to use the feature
is as follows:
Users can then sign in to Citrix Cloud by using their Azure AD credentials. For more information, see
Connect Azure Active Directory to Citrix Cloud.
Fixes
• On the Administration Console > Policies and Profiles > Microsoft USV Settings > Folder
Redirection tab, with both Redirect AppData (Roaming) and Delete Local Redirected Fold‑
ers enabled, the WEM agent fails to apply the following settings:
– Redirect Contacts
– Redirect Downloads
– Redirect Links
– Redirect Searches [WEM‑15016, CVADHELP‑18196]
• After you upgrade to 2103 or later, the WEM agent might write errors to the Windows Event
Log every five minutes even if users experience no issues with their environment. [WEM‑15466,
CVADHELP‑18352]
• When you use VUEMRSAV.exe to view results about excluded actions or excluded action groups
for the current user, the Excluded Actions tab fails to display Action Groups. (By default,
VUEMRSAV.exe is located in the agent installation folder: %ProgramFiles%\Citrix\Workspace
Environment Management Agent\VUEMRSAV.exe.) [WEM‑17075]
November 2021
If you use a service in another region, a message now appears when you sign in to the administra‑
tion console. The message reminds you to migrate your service instance to your current region. We
encourage you to do that for optimal performance. If necessary, contact Citrix Technical Support.
We added an option, Export statistics, to the migration tool. Use the option to control whether to
export agent and user statistics. For more information, see Migrate.
Fixes
• When you click Apply to save your environment settings, the administration console might exit
unexpectedly. The issue occurs because the Style setting of Environmental Settings > Start
Menu > Set Wallpaper is left empty. (If you previously set Style to Fill or Fit, the setting became
empty after you upgraded the administration console to version 2109.) Workaround: Do not
leave the Style setting empty. [WEM‑16351, WEMHELP‑159]
October 2021
• This release introduces self‑elevation for the privilege elevation feature. With self‑elevation,
you can automate privilege elevation for certain users without the need to provide the exact
executables beforehand. Those users can request self‑elevation for any applicable file simply
by right‑clicking the file and then selecting Run with administrator privileges in the context
menu. After that, a prompt appears, requesting that they provide a reason for the elevation.
The reason is for auditing purposes. If the criteria are met, the elevation is applied, and the files
run successfully with administrator privileges. In addition, self‑elevation gives you flexibility to
choose the best solution for your needs. You can create allow lists for the files you permit users
to self‑elevate or block lists for files you want to prevent users from self‑elevating. For more
information, see Self‑elevation.
You can now use the Full Configuration management interface of Citrix DaaS (formerly Citrix Virtual
Apps and Desktops service) to bind a catalog to a WEM configuration set. Doing so lets you use WEM
service to optimize the user experience based on your Citrix DaaS deployment. You can quickly deliver
the best possible workspace experience to your users by reusing an existing catalog setup. For more
information, see Create machine catalogs and Manage machine catalogs.
Workspace Environment Management service is now available in Citrix Cloud Japan, a cloud that is
isolated and separate from Citrix Cloud. Japanese customers can use the service in a dedicated Citrix‑
managed environment. The service requires Citrix Cloud Connector version 6.29.0.58841 or later.
For more information, see Citrix Cloud Japan.
Fixes
• The WEM agent can consume a significant amount of memory usage. Sometimes, its memory
consumption can increase to 3 GB per session. [WEM‑14682, WEMHELP‑133]
September 2021
• Previously, when you used the Apply to Child Processes setting in a rule, you applied the rule to
all child processes that the executable started. This release provides you with three additional
options, giving you more granular control over applying privilege elevation to child processes.
Fixes
• When you use the WEM PowerShell SDK module to export or import a WEM configuration set,
certain settings, such as application security (AppLocker) rules, are not included. [WEM‑12811,
CVADHELP‑18383]
• When you apply privilege elevation to a 32‑bit executable, the privilege of the executable can
be successfully elevated on machines running a 64‑bit Windows operating system. However, its
child processes automatically inherit the privilege whether or not the Apply to Child Processes
setting is selected in the executable rule. [WEM‑13592]
• When you use WEM to pin certain applications to the taskbar, they might not be pinned success‑
fully. The issue occurs with Windows multi‑session OS machines. [WEM‑14812]
• WEM fails to deploy registry keys if their path contains a forward slash (/). The issue occurs
because WEM incorrectly treats the forward slash as a separator. [WEM‑15561, WEMHELP‑146]
August 2021
The WEM service is available globally. Initially, it had only US‑based and EU‑based instances. In addi‑
tion, we now offer Asia Pacific South based instances.
July 2021
This release updates the email notification feature available on the Utilities tab. Previously, you could
decide whether to get notifications about upcoming upgrades to your WEM service. Starting with
this release, you will not receive notifications about upgrades to your WEM service. You can decide
whether to let us inform you that a new version of the Workspace Environment Management service
agent is available.
Fixes
• On a non‑English version of the Microsoft Windows operating system, the WEM agent during
logon writes errors to the Windows Event Log even if users experience no issues with their envi‑
ronment. [WEM‑12603, CVADHELP‑17381]
• The WEM agent writes errors to the Windows Event Log each time the Optimize Memory Usage
for Idle Processes feature comes into effect. The agent might also write errors to the Windows
Event Log when the feature fails to work. [WEM‑12934]
• If you use the [ADAttribute:objectSid] dynamic token to extract the objectsid at‑
tribute, the WEM agent fails to extract the attribute of the corresponding AD object. [WEM‑
13746]
• If you use the administration console to set desktop wallpaper, the WEM agent fails to fill, fit, or
tile the wallpaper. [WEM‑14408]
June 2021
• This release introduces parameter matching for the privilege elevation feature. Parameter
matching gives you more granular control by letting you restrict privilege elevation to executa‑
bles that match the specified parameter. A parameter works as a match criterion. To further
expand the criterion, you can use regular expressions. For more information, see Privilege
elevation.
• Starting with this release, you can apply privilege elevation to .msi and .msp Windows in‑
staller files. Using the feature, you elevate the privileges of non‑administrative users to an ad‑
ministrator level necessary for some Windows installer files. As a result, those users can run
those files as if they are members of the administrators group. For more information, see Privi‑
lege elevation.
Profile Management
– Replicate user stores. A new option that lets you replicate a user store to multiple paths
on each logon and logoff, in addition to the path that the Set path to user store option
specifies. To synchronize to the user stores files and folders modified during a session,
enable active write back. Enabling the option can increase system I/O and might prolong
logoffs. This feature does not currently support full container solutions.
– Accelerate folder mirroring. A new option that accelerates folder mirroring. Enabling the
option lets Profile Management stores mirrored folders on a VHDX‑based virtual disk. As a
result, Profile Management attaches the virtual disk during logons and detaches it during
logoffs, eliminating the need to copy the folders between the user store and local profiles.
– User Store Credentials. A new tab that lets you control whether to let Profile Management
impersonate the current user when accessing user stores. To allow Profile Management
to impersonate the current user, disable the setting. To prevent Profile Management from
impersonating the current user, enable the setting. As a result, Profile Management uses
the specified user store credentials to access the user stores on behalf of the user.
Fixes
• If you assign a printer to a user based on a filter and the assignment satisfies the filter criteria,
the WEM agent assigns the printer to the user. However, the agent still assigns the printer to the
user the next time the user logs on even when the assignment does not satisfy the filter criteria.
[WEM‑11680, CVADHELP‑16818]
• With the Windows PowerShell script execution policy set to Allow only signed scripts on the
agent host machine, WEM fails to perform Profile Management health checks. With the policy
set to Allow local scripts and remote signed scripts or Allow all scripts, WEM can perform Pro‑
file Management health checks but writes error information to the Windows Event Log. [WEM‑
11917]
• When you assign an action to a user or user group through an action group, the action still takes
effect even if it is set to Disabled in the administration console. [WEM‑12757, CVADHELP‑17406]
• The WEM agent installs VUEMRSAV.exe (Workspace Environment Management Resultant Ac‑
tions Viewer), a utility that lets users view the WEM configuration defined for them by admin‑
istrators. However, on the Agent Settings tab of the utility, users cannot see the setting that
is associated with the Use Cache to Accelerate Actions Processing option configured in the
administration console. [WEM‑12847]
May 2021
• This release includes enhancements to the external task feature. The feature now provides you
with two additional options to control when to run external tasks:
– Run when processes start. Controls whether to run the external task when specified
processes start.
– Run when processes end. Controls whether to run the external task when specified
processes end.
Using the two options, 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. For more information, see External Tasks.
• This release introduces enhancements to the process hierarchy control feature that improve
overall performance and stability. The enhancements include the following changes:
– The AppInfoViewer tool has been updated to include the following two options: Enable
Process Hierarchy Control and Disable Process Hierarchy Control. For the process hier‑
archy control feature to work, you must first use the tool on each agent machine to enable
the feature. Every time you use the tool to enable or disable the feature, a machine restart
is required.
– In certain scenarios, you must restart your agent machine after upgrading or uninstalling
the agent. See Considerations for details.
Fixes
• If you assign a file system operations action and update the action later, the files or folders that
were previously copied to the user environment might be deleted. The issue occurs because
the WEM agent reverts the assignment made earlier after you update the action. [WEM‑11924,
CVADHELP‑16916]
• With Agent Type set to CMD on the Advanced Settings > Configuration > Main Configuration
tab, the Monitoring > Daily Reports > Daily Login Report tab might fail to display a summary
of logon times across all users connected to the current configuration set. [WEM‑12226]
April 2021
• This release introduces the process hierarchy control feature. The feature lets you control
whether certain child processes can be started through their parent processes. You create a
rule by defining parent processes and then designating an allow list or a block list for their
child processes. You then assign the rule on a per user or per user group basis. The following
rule types are available:
– Path. Applies the rule to an executable according to the executable file path.
– Publisher. Applies the rule according to publisher information.
– Hash. Applies the rule to identical executables as specified.
This release adds two settings, Overwrite and Merge, to the Administration Console > Security >
Application Security tab. The settings let you determine how the agent processes application secu‑
rity rules.
• Select Overwrite if you want to overwrite existing rules. When selected, the rules that are
processed last overwrite rules that were processed earlier. We recommend that you apply this
setting only to single‑session machines.
• Select Merge if you want to merge rules with existing rules. When conflicts occur, the rules that
are processed last overwrite rules that were processed earlier.
Fixes
• The WEM agent might become unresponsive when processing applications, failing to process
them successfully. [WEM‑11435, CVADHELP‑16706]
• You might experience performance issues such as slow logon or slow session disconnect when
launching or disconnecting from published application sessions. The issue occurs with WEM
agent 2005 and later. [WEM‑11693]
March 2021
This release introduces a policy setting titled Discover Citrix Cloud Connector from CVAD service.
If you have not yet configured Cloud Connectors for the agent, use the setting to control whether
the agent discovers Cloud Connector information from the relevant Citrix Virtual Apps and Desk‑
tops (CVAD) service deployment. The agent then connects to the corresponding Cloud Connector
machines automatically. For more information, see Step 2: Configure group policies (optional).
We added support for the Windows 10 2009 (also known as 20H2) template introduced in Citrix opti‑
mizer. You can now use WEM service to perform template‑based system optimizations for Windows
10 2009 machines. In addition, we have updated all existing templates to reflect changes introduced
in the latest standalone Citrix optimizer. For information about using Citrix optimizer, see Citrix opti‑
mizer.
This release replaces the home page of the WEM administration console with a quick‑start page that
provides information necessary for you to get started with the WEM service. Follow the on‑screen
instructions to start configuring your WEM deployment. To reopen the quick‑start page, click Quick
Start (available in the ribbon) in the upper‑right corner of the console. For more information, see Get
started with your Workspace Environment Management service.
Profile Management
Workspace Environment Management service now supports all versions of Profile Management
through 2103. Also, the following new options are now available in the Administration Console >
Policies and Profiles > Citrix Profile Management Settings interface:
Fixes
• For logging level changes to take effect immediately, the WEM agent might access certain reg‑
istry keys very frequently, thus affecting performance. [WEM‑11217]
• With an action group assigned to multiple users or user groups, if you unassign it from a user
or user group, the assignment might not work as expected. For example, you assign an action
group to two user groups: Group A and Group B. If you unassign the action group from Group A,
the action group is unassigned from Group B rather than Group A. [WEM‑11459, WEMHELP‑75]
• When you configure an environment variable (Actions > Environment Variables), attempts to
use the $Split(string,[splitter],index)$ dynamic token might fail. The issue oc‑
curs because the dynamic token does not support multi‑line strings. [WEM‑11915]
January 2021
Microsoft Sync Framework 2.1 reached End of Life on January 12, 2021. WEM has removed the legacy
sync service based on that framework and instead uses a new sync framework, Dotmim.Sync, an open‑
source sync framework. How does this change impact you?
• If you use WEM agent version 1911 or later, this change does not require action on your part.
• If you use WEM agent version earlier than 1911, upgrade the agent to 1911.
WEM agent integration with the Citrix Virtual Apps and Desktops product software
The WEM agent is integrated with the Citrix Virtual Apps and Desktops product software, letting you
include the WEM agent when installing a Virtual Delivery Agent (VDA). This integration is reflected in
the Citrix Virtual Apps and Desktops 2012 product software and later. For more information, see Install
VDAs.
• Starting with this release, you can make Group Policy settings conditional by using a filter to
contextualize their assignments. A filter comprises a rule and multiple conditions. The WEM
agent applies the assigned Group Policy settings only when all conditions in the rule are met
in the user environment at runtime. Otherwise, the agent skips those settings when enforcing
filters. For more information, see Contextualize Group Policy settings.
Privilege elevation
• This release introduces the privilege elevation feature. The feature lets you elevate the privi‑
leges of non‑administrative users to an administrator level necessary for some executables. As
a result, those users can start those executables as if they are members of the administrators
group.
The feature enables you to implement rule‑based privilege elevation for specific executables.
The following rule types are available:
– Path. Applies the rule to an executable according to the executable file path.
– Publisher. Applies the rule according to publisher information.
– Hash. Applies the rule to identical executables as specified.
You can configure how a rule behaves according to the type of the operating system. You can
also configure whether a rule takes effect at a particular time or within a particular time range.
You assign a rule on a per user or per user group basis. For more information, see Privilege
elevation.
• Minimum agent version required: 2010.2.0.1
Fixes
• The privilege elevation feature might fail to work properly. The issue occurs with the follow‑
ing versions of the WEM agent: 2010.2.0.1, 2011.1.0.1, and 2101.1.0.1. The issue occurs be‑
cause the certificate used to sign the Citrix WEM software has expired. To work around the issue,
uninstall the relevant WEM agent, install the latest WEM agent, and then restart the agent host.
[WEM‑11918]
• While the WEM agent performs application processing during logon, Windows might display the
Problem with Shortcut dialog box, prompting end users to delete a shortcut that no longer
works properly. The issue occurs when the item to which the shortcut refers has been changed
or moved. [WEM‑10257, CVADHELP‑15968]
• When using the application security feature, you see a green checkmark next to a user or user
group in the Assigned column of the Assignments section in the Edit Rule or Add Rule window.
The green checkmark icon does not necessarily indicate that the rule is assigned to that user or
user group. Only a user or user group with a blue background is the one to which the rule is
assigned. [WEM‑10047]
Deprecation
April 8, 2021
This article gives you advanced notice of Workspace Environment Management (WEM) service features
that are being phased out so that you can make timely business decisions. Citrix monitors customer
use and feedback to determine when features are withdrawn. Announcements can change in subse‑
quent releases and might not include every deprecated feature or functionality.
For more information about product lifecycle support, see the Product Lifecycle Support Policy arti‑
cle.
The following table shows the WEM service features that are deprecated or removed.
Deprecated items are not removed immediately. Citrix continues to support them but they will be
removed in a future release.
Support for the legacy September 2020 January 2021 If you use WEM agent
agent cache sync version earlier than
service based on 1911, upgrade the
Microsoft Sync agent to 1911 or later.
Framework 2.1.
December 3, 2019
Workspace Environment Management might include third‑party software licensed under the terms
defined in the following document:
Known issues
• While creating Start menu shortcuts and pinning applications to the Start menu, shortcuts are
generated in the root folder of the Start menu instead of being created in the path specified.
This issue occurs only on Windows Server 2022/2019 but not on Windows Server 2016. [WEM‑
32923, CVADHELP‑24045]
For known issues related to the WEM service of earlier versions, see Known issues in previous re‑
leases.
• While creating Start menu shortcuts and pinning applications to the Start menu, shortcuts are
generated in the root folder of the Start menu instead of being created in the path specified.
This issue occurs only on Windows Server 2022/2019 but not on Windows Server 2016. [WEM‑
32923, CVADHELP‑24045]
• Certain applications of the “Citrix Workspace (StoreFront) resource”type, for example, SaaS ap‑
plications, might fail to start on the agent machine. [WEM‑26968]
• When the WEM agent runs on Windows Server 2022, the memory usage limit you apply to spe‑
cific processes might not work as expected. [WEM‑28773]
• Certain applications of the “Citrix Workspace (StoreFront) resource”type, for example, SaaS ap‑
plications, might fail to start on the agent machine. [WEM‑26968]
• When the WEM agent runs on Windows Server 2022, the memory usage limit you apply to spe‑
cific processes might not work as expected. [WEM‑28773]
• When the WEM agent fails to retrieve the policy settings during startup, the intended SMB con‑
nections (as configured by the SMB share settings) are not immediately accessible. In this sce‑
nario, you must wait for the next connection refresh, which occurs every 15 minutes. [WEM‑
29142]
• Certain applications of the “Citrix Workspace (StoreFront) resource”type, for example, SaaS ap‑
plications, might fail to start on the agent machine. [WEM‑26968]
• You might see the following error that appears intermittently in the Windows Event Log:
HostDirectoryServicesController.IsCurrentDomainReachable():
Checking domain status timed out. Each time WEM fails to check that the
domain is reachable, the error is written in the Windows Event Log. The checks are necessary
when WEM processes policies. This issue does not affect the functionality of the WEM agent.
[WEM‑27435, CVADHELP‑22396]
• Attempts to restore a configuration set may fail if it contains too many (for example, 10,000)
template‑based GPOs. [WEM‑28447]
• When the WEM agent runs on Windows Server 2022, the memory usage limit you apply to spe‑
cific processes might not work as expected. [WEM‑28773]
• Certain applications of the “Citrix Workspace (StoreFront) resource”type, for example, SaaS ap‑
plications, might fail to start on the agent machine. [WEM‑26968]
• Certain applications of the “Citrix Workspace (StoreFront) resource”type, for example, SaaS ap‑
plications, might fail to start on the agent machine. [WEM‑26968]
• Certain applications of the “Citrix Workspace (StoreFront) resource”type, for example, SaaS ap‑
plications, might fail to start on the agent machine. [WEM‑26968]
• In the legacy console, when you click the State column header to sort, items are not sorted as
expected. [WEM‑25978, WEMHELP‑274]
• In the legacy console, the Backup Actions button is not available when you use the backup
wizard to back up Group Policy settings. The issue occurs even if the configuration set does not
contain any resources created using the web console. [WEM‑26240]
• When running in offline mode, the agent can’t connect to the SMB shares you configured in Ad‑
vanced Settings > File Shares. This issue does not affect the functionality of the agent. [WEM‑
25318]
• If you restore settings from a previous backup, you experience issues with user store‑related
credentials.
– In the legacy console, you can’t save changes made to the credentials.
– In the web console, the restored credentials fail to appear in Advanced Settings > File
Shares. [WEM‑23466]
• On Mozilla Firefox browsers, the built‑in scripted task Cloud Health Check fails to appear above
custom scripted tasks. [WEM‑24166]
• An application security rule fails to work when both of the following conditions are met:
• If you restore settings from a previous backup, you experience issues with user store‑related
credentials.
– In the legacy console, you can’t save changes made to the credentials.
– In the web console, the restored credentials fail to appear in Advanced Settings > File
Shares. [WEM‑23466]
• On Mozilla Firefox browsers, the built‑in scripted task Cloud Health Check fails to appear above
custom scripted tasks. [WEM‑24166]
• In the web console, when you use the filter, Last logon, to refine results in Monitoring > Ad‑
ministration > User Statistics, the filter might not work as expected. The issue occurs when
you leave the end date unspecified. As a workaround, specify an end date when using the filter.
[WEM‑23705]
• In the web console, attempts to add or edit registry operations of the following types might
fail: REG_QWORD and REG_QWORD_LITTLE_ENDIAN. The issue occurs when you type
a decimal value that exceeds 9007199254740991 or a hexadecimal value that exceeds
1FFFFFFFFFFFFF. As a workaround, use the legacy console instead.
If you use the web console to edit registry operations of the two types whose value exceeds
the limit, you see the following error message: Invalid value or format. You can dismiss the
message. [WEM‑22217]
• When you use VUEMRSAV.exe to view results about actions applied through an action group
for the current user, the Applied Actions tab might display the incorrect source of the actions.
Example: Two action groups (Group1 and Group 2) were assigned to the user and Group1
contains Application1. The Applied Actions tab might also show that Application1 is
from Group2 even if Group2 does not contain Application1. (By default, VUEMRSAV.exe is
located in the agent installation folder: %ProgramFiles%\Citrix\Workspace Environment Man‑
agement Agent\VUEMRSAV.exe.) [WEM‑20002]
• When you use VUEMRSAV.exe to view results about actions applied through an action group
for the current user, the Applied Actions tab might display the incorrect source of the actions.
Example: Two action groups (Group1 and Group 2) were assigned to the user and Group1
contains Application1. The Applied Actions tab might also show that Application1 is
from Group2 even if Group2 does not contain Application1. (By default, VUEMRSAV.exe is
located in the agent installation folder: %ProgramFiles%\Citrix\Workspace Environment Man‑
agement Agent\VUEMRSAV.exe.) [WEM‑20002]
• When you import your AppLocker rules exported from the Microsoft AppLocker console into
WEM, rules of the hash type cannot be imported. [WEM‑20436]
• When using Legacy Console > Assignments > Modeling Wizard, you might not be able to view
the resultant actions for a user in a nested group. The issue occurs when the user does not
reside in the top group to which the actions or action groups are assigned. Example: The top
group is GroupA, GroupB is its member, and UserA is in GroupB. If you assign actions or
action groups to GroupA, you cannot view the resultant actions for UserA by using Modeling
Wizard. [WEM‑20842, WEMHELP‑225]
• When you import your AppLocker rules exported from the Microsoft AppLocker console into
WEM, rules of the hash type cannot be imported. [WEM‑20436]
• With self‑elevation or privilege elevation disabled, the WEM agent might write the following
error to the Windows Event Log even if users experience no issues with their environment:
System.ArgumentException: Cannot delete a subkey tree because the
subkey does not exist. [WEM‑20441]
• Attempts to restore self‑elevation rules to a different configuration set might fail. [WEM‑18602]
• On Windows 10 and Windows 11 machines, certain settings such as environment settings that
you configured in the administration console might not work. [WEM‑14193]
• Attempts to restore self‑elevation rules to a different configuration set might fail. [WEM‑18602]
• On Windows 10 and Windows 11 machines, certain settings such as environment settings that
you configured in the administration console might not work. [WEM‑14193]
• On Windows 10 and Windows 11 machines, certain settings such as environment settings that
you configured in the administration console might not work. [WEM‑14193]
• On the Administration Console > Policies and Profiles > Microsoft USV Settings > Folder
Redirection tab, with both Redirect AppData (Roaming) and Delete Local Redirected Fold‑
ers enabled, the WEM agent fails to apply the following settings:
– Redirect Contacts
– Redirect Downloads
– Redirect Links
– Redirect Searches [WEM‑15016, CVADHELP‑18196]
• After you upgrade to 2103 or later, the WEM agent might write errors to the Windows Event
Log every five minutes even if users experience no issues with their environment. [WEM‑15466,
CVADHELP‑18352]
• On Windows 10 and Windows 11 machines, certain settings such as environment settings that
you configured in the administration console might not work. [WEM‑14193]
• After Windows Update installs KB5005033 on an agent host, assigned printers do not work. The
issue occurs because the update prevents the automatic start of the Windows Print Spooler
service. As a workaround, start the service manually. [WEM‑15028]
• After you upgrade to Windows Server 2022, the WEM infrastructure service might fail to respond.
As a workaround, reinstall the infrastructure service and configure it to connect to the WEM
database. [WEM‑15353]
• After you upgrade to 2103 or later, the WEM agent might write errors to the Windows Event
Log every five minutes even if users experience no issues with their environment. [WEM‑15466,
CVADHELP‑18352]
• When you click Apply to save your environment settings, the administration console might exit
unexpectedly. The issue occurs because the Style setting of Environmental Settings > Start
Menu > Set Wallpaper is left empty. (If you previously set Style to Fill or Fit, the setting became
empty after you upgraded the administration console to version 2109.) Workaround: Do not
leave the Style setting empty. [WEM‑16351, WEMHELP‑159]
• On Windows 10 and Windows 11 machines, certain settings such as environment settings that
you configured in the administration console might not work. [WEM‑14193]
• After Windows Update installs KB5005033 on an agent host, assigned printers do not work. The
issue occurs because the update prevents the automatic start of the Windows Print Spooler
service. As a workaround, start the service manually. [WEM‑15028]
• After you upgrade to Windows Server 2022, the WEM infrastructure service might fail to respond.
As a workaround, reinstall the infrastructure service and configure it to connect to the WEM
database. [WEM‑15353]
• When you click Apply to save your environment settings, the administration console might exit
unexpectedly. The issue occurs because the Style setting of Environmental Settings > Start
Menu > Set Wallpaper is left empty. (If you previously set Style to Fill or Fit, the setting became
empty after you upgraded the administration console to version 2109.) Workaround: Do not
leave the Style setting empty. [WEM‑16351, WEMHELP‑159]
• When you apply privilege elevation to a 32‑bit executable, the privilege of the executable can
be successfully elevated on machines running a 64‑bit Windows operating system. However, its
child processes automatically inherit the privilege whether or not the Apply to Child Processes
setting is selected in the executable rule. [WEM‑13592]
• On Windows 10 machines, environment and certain other settings that you configured in the
administration console might not work. [WEM‑14193]
• If you use the [ADAttribute:objectSid] dynamic token to extract the objectsid at‑
tribute, the WEM agent fails to extract the attribute of the corresponding AD object. [WEM‑
13746]
• On Windows 10 machines, environment and certain other settings that you configured in the
administration console might not work. [WEM‑14193]
• On Windows 10 machines, environment and certain other settings that you configured in the
administration console might not work. [WEM‑14193]
• If you assign a printer to a user based on a filter and the assignment satisfies the filter criteria,
the WEM agent assigns the printer to the user. However, the agent still assigns the printer to the
user the next time the user logs on even when the assignment does not satisfy the filter criteria
at that time. [WEM‑11680, CVADHELP‑16818]
• When you assign an action to a user or user group through an action group, the action still takes
effect even if it is set to Disabled in the administration console. [WEM‑12757, CVADHELP‑17406]
• On Windows 10 machines, environment and certain other settings that you configured in the
administration console might not work. [WEM‑14193]
• If you assign a printer to a user based on a filter and the assignment satisfies the filter criteria,
the WEM agent assigns the printer to the user. However, the agent still assigns the printer to the
user the next time the user logs on even when the assignment does not satisfy the filter criteria
at that time. [WEM‑11680, CVADHELP‑16818]
• If you assign a file system operations action and update the action later, the files or folders that
were previously copied to the user environment might be deleted. The issue occurs because
the WEM agent reverts the assignment made earlier after you update the action. [WEM‑11924,
CVADHELP‑16916]
• With Agent Type set to CMD on the Advanced Settings > Configuration > Main Configuration
tab, the Monitoring > Daily Reports > Daily Login Report tab might fail to display a summary
of logon times across all users connected to the current configuration set. [WEM‑12226]
• On Windows 10 machines, environment and certain other settings that you configured in the
administration console might not work. [WEM‑14193]
• You might experience performance issues such as slow logon or slow session disconnect when
launching or disconnecting from published application sessions. The issue occurs with WEM
agent 2005 and later. [WEM‑11693]
• On Windows 10 machines, environment and certain other settings that you configured in the
administration console might not work. [WEM‑14193]
• For logging level changes to take effect immediately, the WEM agent might access certain reg‑
istry keys frequently, thus affecting performance. [WEM‑11217]
• With an action group assigned to multiple users or user groups, if you unassign it from a user
or user group, the assignment might not work as expected. For example, you assign an action
group to two user groups: Group A and Group B. If you unassign the action group from Group A,
the action group is unassigned from Group B rather than Group A. [WEM‑11459, WEMHELP‑75]
• On Windows 10 machines, environment and certain other settings that you configured in the
administration console might not work. [WEM‑14193]
• When using the application security feature, you see a green checkmark next to a user or user
group in the Assigned column of the Assignments section in the Edit Rule or Add Rule window.
The green checkmark icon does not necessarily indicate that the rule is assigned to that user or
user group. Only a user or user group with a blue background is the one to which the rule is
assigned. [WEM‑10047]
• The privilege elevation feature might fail to work properly. The issue occurs with the follow‑
ing versions of the WEM agent: 2010.2.0.1, 2011.1.0.1, and 2101.1.0.1. The issue occurs be‑
cause the certificate used to sign the Citrix WEM software has expired. To work around the issue,
uninstall the relevant WEM agent, install the latest WEM agent, and then restart the agent host.
[WEM‑11918]
• On Windows 10 machines, environment and certain other settings that you configured in the
administration console might not work. [WEM‑14193]
• When using the application security feature, you see a green checkmark next to a user or user
group in the Assigned column of the Assignments section in the Edit Rule or Add Rule window.
The green checkmark icon does not necessarily indicate that the rule is assigned to that user or
user group. Only a user or user group that has a blue highlight in the background is the one to
which the rule is assigned. [WEM‑10047]
• The privilege elevation feature might fail to work properly. The issue occurs with the following
versions of the WEM agent: 2010.2.0.1 and 2011.1.0.1. The issue occurs because the certifi‑
cate used to sign the Citrix WEM software has expired. To work around the issue, uninstall the
relevant WEM agent, install the latest WEM agent, and then restart the agent host. [WEM‑11918]
• On Windows 10 machines, environment and certain other settings that you configured in the
administration console might not work. [WEM‑14193]
• After you upgrade the WEM agent to version 1912, the memory consumption of Citrix WEM
Agent Host Service might exceed 2G. If debug mode is enabled, you can see that the follow‑
ing messages appear many times in the Citrix WEM Agent Host Service Debug.log file:
• After you upgrade the WEM agent to version 2005, Citrix WEM Agent Host Service might con‑
sume between 10% and 30% of the total CPU resources, affecting the user experience. [WEM‑
9902, WEMHELP‑47]
• When using the application security feature, you see a green checkmark next to a user or user
group in the Assigned column of the Assignments section in the Edit Rule or Add Rule window.
The green checkmark icon does not necessarily indicate that the rule is assigned to that user or
user group. Only a user or user group that has a blue highlight in the background is the one to
which the rule is assigned. [WEM‑10047]
• After you select a registry file in the Import from Registry File window, the Manage tab displays
a black screen if you press ESC to exit the window and then click Yes. [WEM‑10103]
• The privilege elevation feature might fail to work properly. The issue occurs with the WEM agent
version 2010.2.0.1. The issue occurs because the certificate used to sign the Citrix WEM software
has expired. To work around the issue, uninstall the relevant WEM agent, install the latest WEM
agent, and then restart the agent host. [WEM‑11918]
• On Windows 10 machines, environment and certain other settings that you configured in the
administration console might not work. [WEM‑14193]
• After you upgrade the WEM agent to version 1912, the memory consumption of Citrix WEM
Agent Host Service might exceed 2G. If debug mode is enabled, you can see that the follow‑
ing messages appear many times in the Citrix WEM Agent Host Service Debug.log file:
• After you upgrade the WEM agent to version 2005, Citrix WEM Agent Host Service might con‑
sume between 10% and 30% of the total CPU resources, affecting the user experience. [WEM‑
9902, WEMHELP‑47]
• When using the application security feature, you see a green checkmark next to a user or user
group in the Assigned column of the Assignments section in the Edit Rule or Add Rule window.
The green checkmark icon does not necessarily indicate that the rule is assigned to that user or
user group. Only a user or user group that has a blue highlight in the background is the one to
which the rule is assigned. [WEM‑10047]
• On Windows 10 machines, environment and certain other settings that you configured in the
administration console might not work. [WEM‑14193]
• After you upgrade the WEM agent to version 1912, the memory consumption of Citrix WEM
Agent Host Service might exceed 2G. If debug mode is enabled, you can see that the follow‑
ing messages appear many times in the Citrix WEM Agent Host Service Debug.log file:
• After you upgrade the WEM agent to version 2005, Citrix WEM Agent Host Service might con‑
sume between 10% and 30% of the total CPU resources, affecting the user experience. [WEM‑
9902, WEMHELP‑47]
• The WEM administration console might fail to display the changes you made to the working
directory for an installed application the next time you edit the application. [WEM‑10007,
CVADHELP‑15695]
• In non‑persistent environments, changes you make through the administration console might
fail to take effect on the agent hosts. The issue occurs because the agent cache file in the base
image might cause cache synchronization problems. As a workaround, users must first delete
the cache on their agent hosts and then refresh the cache manually to synchronize the cache
with the infrastructure services.
The recommended best practice is to use a persistent location for the agent cache. If the agent
cache resides in a non‑persistent location, take these steps before sealing the base image:
• The following options are not mutually exclusive. However, the administration console does
not allow you to configure them at the same time.
– Hide Specified Drives from Explorer and Restrict Specified Drives from Explorer
(on the Policies and Profiles > Environmental Settings > Windows Explorer tab)
[WEM‑10172, WEMHELP‑52]
• On Windows 10 machines, environment and certain other settings that you configured in the
administration console might not work. [WEM‑14193]
• On Windows 10 machines, environment and certain other settings that you configured in the
administration console might not work. [WEM‑14193]
• When editing a default packaged rule, you are prompted to provide valid values on the Pub‑
lisher tab of the Edit Rule window, with the OK button grayed out. However, the OK button
remains grayed out even if you provide valid values on the Publisher tab later. [WEM‑9498]
• On Windows 10 machines, environment and certain other settings that you configured in the
administration console might not work. [WEM‑14193]
• When you finish importing your Group Policy settings into WEM, the following message might
appear even if you are the only administrator that is using the administration console:
• On Windows 10 machines, environment and certain other settings that you configured in the
administration console might not work. [WEM‑14193]
• On Windows 10 machines, environment and certain other settings that you configured in the
administration console might not work. [WEM‑14193]
• On Windows 10 machines, environment and certain other settings that you configured in the
administration console might not work. [WEM‑14193]
• In Transformer (kiosk) mode, and with Enable Window Mode enabled, the WEM agent might
exit unexpectedly. [WEM‑8119]
• On Windows 10 machines, environment and certain other settings that you configured in the
administration console might not work. [WEM‑14193]
• Attempts to start an application from the My Applications icon list in the agent UI might fail.
The issue occurs with application shortcuts that are created using StoreFront URLs. [WEM‑7578,
CVADHELP‑14171]
• Agents might fail to synchronize with the WEM service in Citrix Cloud. The issue occurs when
you configure an HTTPS proxy to define how agents communicate with the service. [WEM‑7579,
CVADHELP‑14168]
• On Windows 10 machines, environment and certain other settings that you configured in the
administration console might not work. [WEM‑14193]
• On the agent host, attempts to start a published application as an application shortcut might
fail. The issue occurs with application shortcuts that are created using StoreFront URLs. [WEM‑
7348, CVADHELP‑14061]
• On Windows 10 machines, environment and certain other settings that you configured in the
administration console might not work. [WEM‑14193]
• Agent host machine names listed on the Active Directory Objects tab of the WEM service admin‑
istration console do not update automatically to reflect changes to machine names. To display
the new name of a machine in the Machines list, you must manually delete the machine from
the Machines list, and then add the machine again. [WEM‑1549]
• Registry entries might not take effect if you assign them to a user or user group through an
action group. However, they do take effect if you assign them directly. The issue occurs when
you assign registry entries to be created in one of the following locations:
– %ComputerName%\HKEY_CURRENT_USER\SOFTWARE\Policies
– %ComputerName%\HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies
[WEM‑5253]
• Workspace agent refreshes might take a long time to complete. The issue occurs when the cur‑
rent user belongs to many user groups and there are action groups or many actions for the agent
to process. [WEM‑6582]
• On Windows 10 machines, environment and certain other settings that you configured in the
administration console might not work. [WEM‑14193]
• Agent host machine names listed on the Active Directory Objects tab of the WEM service admin‑
istration console do not update automatically to reflect changes to machine names. To display
the new name of a machine in the Machines list, you must manually delete the machine from
the Machines list, and then add the machine again. [WEM‑1549]
• Registry entries might not take effect if you assign them to a user or user group through an
action group. However, they do take effect if you assign them directly. The issue occurs when
you assign registry entries to be created in one of the following locations:
– %ComputerName%\HKEY_CURRENT_USER\SOFTWARE\Policies
– %ComputerName%\HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies
[WEM‑5253]
• On Windows 10 machines, environment and certain other settings that you configured in the
administration console might not work. [WEM‑14193]
• Agent host machine names listed on the Active Directory Objects tab of the WEM service admin‑
istration console do not update automatically to reflect changes to machine names. To display
the new name of a machine in the Machines list, you must manually delete the machine from
the Machines list, and then add the machine again. [WEM‑1549]
• The Restore wizard might take a long time to load the Active Directory (AD) objects after you
select Machines as the type of AD objects you want to restore and click Next. The issue occurs
when there are many OUs (for example, 4,000). [WEM‑5169]
• Registry entries might not take effect if you assign them to a user or user group through an
action group. However, they do take effect if you assign them directly. The issue occurs when
you assign registry entries to be created in one of the following locations:
– %ComputerName%\HKEY_CURRENT_USER\SOFTWARE\Policies
– %ComputerName%\HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies
[WEM‑5253]
• The Use Cache Even When Online option on the Administration Console > Advanced Settings
> Configuration > Agent Options tab might not work. [WEM‑6118]
• On Windows 10 machines, environment and certain other settings that you configured in the
administration console might not work. [WEM‑14193]
• Agent host machine names listed on the Active Directory Objects tab of the WEM service admin‑
istration console do not update automatically to reflect changes to machine names. To display
the new name of a machine in the Machines list, you must manually delete the machine from
the Machines list, and then add the machine again. [WEM‑1549]
• After you migrate your on‑premises WEM database to the WEM service, you must reinstall the
WEM service agent even if the latest version is installed on your machine. This is necessary be‑
cause the agent cache cannot synchronize with the WEM service database unless you reinstall
the WEM service agent. [WEM‑2396]
• In Transformer (kiosk) mode, and with Log Off Screen Redirection enabled, WEM might fail to
redirect the user to the logon page after logging off. [WEM‑3133]
• The Restore wizard might take a long time to load the Active Directory (AD) objects after you
select Machines as the type of AD objects you want to restore and click Next. The issue occurs
when there are many OUs (for example, 4,000). [WEM‑5169]
• Registry entries might not take effect if you assign them to a user or user group through an
action group. However, they do take effect if you assign them directly. The issue occurs when
you assign registry entries to be created in one of the following locations:
– %ComputerName%\HKEY_CURRENT_USER\SOFTWARE\Policies
– %ComputerName%\HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies
[WEM‑5253]
• On Windows 10 machines, environment and certain other settings that you configured in the
administration console might not work. [WEM‑14193]
• Agent host machine names listed on the Active Directory Objects tab of the WEM service admin‑
istration console do not update automatically to reflect changes to machine names. To display
the new name of a machine in the Machines list, you must manually delete the machine from
the Machines list, and then add the machine again. [WEM‑1549]
• On the Active Directory Objects tab of the administration console, using Add Object and
Check Name to search and add objects allows only one object to be added at a time. You must
close and then reopen the Select Computers or Groups dialog to add another object. (The
on‑premises version of Workspace Environment Management allows multiple objects to be
identified and added without closing the dialog each time.) [WEM‑1620]
• After you migrate your on‑premises WEM database to the WEM service, you must reinstall the
WEM service agent even if the latest version is installed on your machine. This is necessary be‑
cause the agent cache cannot synchronize with the WEM service database unless you reinstall
the WEM service agent. [WEM‑2396]
• In Transformer (kiosk) mode, and with Log Off Screen Redirection enabled, WEM might fail to
redirect the user to the logon page after logging off. [WEM‑3133]
• The Restore wizard might take a long time to load the Active Directory (AD) objects after you
select Machines as the type of AD objects you want to restore and click Next. The issue occurs
when there are many OUs (for example, 4,000). [WEM‑5169]
• Registry entries might not take effect if you assign them to a user or user group through an
action group. However, they do take effect if you assign them directly. The issue occurs when
you assign registry entries to be created in one of the following locations:
– %ComputerName%\HKEY_CURRENT_USER\SOFTWARE\Policies
– %ComputerName%\HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies
[WEM‑5253]
• On Windows 10 machines, environment and certain other settings that you configured in the
administration console might not work. [WEM‑14193]
• Agent host machine names listed on the Active Directory Objects tab of the WEM service admin‑
istration console do not update automatically to reflect changes to machine names. To display
the new name of a machine in the Machines list, you must manually delete the machine from
the Machines list, and then add the machine again. [WEM‑1549]
• On the Active Directory Objects tab of the administration console, using Add Object and
Check Name to search and add objects allows only one object to be added at a time. You must
close and then reopen the Select Computers or Groups dialog to add another object. (The
on‑premises version of Workspace Environment Management allows multiple objects to be
identified and added without closing the dialog each time.) [WEM‑1620]
• After you migrate your on‑premises WEM database to the WEM service, you must reinstall the
WEM service agent even if the latest version is installed on your machine. This is necessary be‑
cause the agent cache cannot synchronize with the WEM service database unless you reinstall
the WEM service agent. [WEM‑2396]
• In Transformer (kiosk) mode, and with Log Off Screen Redirection enabled, WEM might fail to
redirect the user to the logon page after logging off. [WEM‑3133]
• On Windows 10 machines, environment and certain other settings that you configured in the
administration console might not work. [WEM‑14193]
• Instances of Adobe Reader installed on Windows Server 2012 R2 prevent Workspace Environ‑
ment Management from associating PDF files with other PDF reader applications. Users are
forced to select the PDF reader application each time they open a PDF. [WEM‑33]
• Agent host machine names listed on the Active Directory Objects tab of the WEM service admin‑
istration console do not update automatically to reflect changes to machine names. To display
the new name of a machine in the Machines list, you must manually delete the machine from
the Machines list, and then add the machine again. [WEM‑1549]
• On the Active Directory Objects tab of the administration console, using Add Object and
Check Name to search and add objects allows only one object to be added at a time. You must
close and then reopen the Select Computers or Groups dialog to add another object. (The
on‑premises version of Workspace Environment Management allows multiple objects to be
identified and added without closing the dialog each time.) [WEM‑1620]
• After you migrate your on‑premises WEM database to the WEM service, you must reinstall the
WEM service agent even if the latest version is installed on your machine. This is necessary be‑
cause the agent cache cannot synchronize with the WEM service database unless you reinstall
the WEM service agent. [WEM‑2396]
• In Transformer (kiosk) mode, and with Log Off Screen Redirection enabled, WEM might fail to
redirect the user to the logon page after logging off. [WEM‑3133]
• On Windows 10 machines, environment and certain other settings that you configured in the
administration console might not work. [WEM‑14193]
• Instances of Adobe Reader installed on Windows Server 2012 R2 prevent Workspace Environ‑
ment Management from associating PDF files with other PDF reader applications. Users are
forced to select the PDF reader application each time they open a PDF. [WEM‑33]
• Agent host machine names listed on the Active Directory Objects tab of the WEM service admin‑
istration console do not update automatically to reflect changes to machine names. To display
the new name of a machine in the Machines list, you must manually delete the machine from
the Machines list, and then add the machine again. [WEM‑1549]
• On the Active Directory Objects tab of the administration console, using Add Object and
Check Name to search and add objects allows only one object to be added at a time. You must
close and then reopen the Select Computers or Groups dialog to add another object. (The
on‑premises version of Workspace Environment Management allows multiple objects to be
identified and added without closing the dialog each time.) [WEM‑1620]
• After you migrate your on‑premises WEM database to the WEM service, you must reinstall the
WEM service agent even if the latest version is installed on your machine. This is necessary be‑
cause the agent cache cannot synchronize with the WEM service database unless you reinstall
the WEM service agent. [WEM‑2396]
• In Transformer (kiosk) mode, and with Log Off Screen Redirection enabled, WEM might fail to
redirect the user to the logon page after logging off. [WEM‑3133]
• On Windows 10 machines, environment and certain other settings that you configured in the
administration console might not work. [WEM‑14193]
• Instances of Adobe Reader installed on Windows Server 2012 R2 prevent Workspace Environ‑
ment Management from associating PDF files with other PDF reader applications. Users are
forced to select the PDF reader application each time they open a PDF. [WEM‑33]
• Agent host machine names listed on the Active Directory Objects tab of the WEM service admin‑
istration console do not update automatically to reflect changes to machine names. To display
the new name of a machine in the Machines list, you must manually delete the machine from
the Machines list, and then add the machine again. [WEM‑1549]
• On the Active Directory Objects tab of the administration console, using Add Object and
Check Name to search and add objects allows only one object to be added at a time. You must
close and then reopen the Select Computers or Groups dialog to add another object. (The
on‑premises version of Workspace Environment Management allows multiple objects to be
identified and added without closing the dialog each time.) [WEM‑1620]
• After you migrate your on‑premises WEM database to the WEM service, you must reinstall the
WEM service agent even if the latest version is installed on your machine. This is necessary be‑
cause the agent cache cannot synchronize with the WEM service database unless you reinstall
the WEM service agent. [WEM‑2396]
• In Transformer (kiosk) mode, and with Log Off Screen Redirection enabled, WEM might fail to
redirect the user to the logon page after logging off. [WEM‑3133]
• On Windows 10 machines, environment and certain other settings that you configured in the
administration console might not work. [WEM‑14193]
• Instances of Adobe Reader installed on Windows Server 2012 R2 prevent Workspace Environ‑
ment Management from associating PDF files with other PDF reader applications. Users are
forced to select the PDF reader application each time they open a PDF. [WEM‑33]
• Agent host machine names listed on the Active Directory Objects tab of the WEM service admin‑
istration console do not update automatically to reflect changes to machine names. To display
the new name of a machine in the Machines list, you must manually delete the machine from
the Machines list, and then add the machine again. [WEM‑1549]
• On the Active Directory Objects tab of the administration console, using Add Object and
Check Name to search and add objects allows only one object to be added at a time. You must
close and then reopen the Select Computers or Groups dialog to add another object. (The
on‑premises version of Workspace Environment Management allows multiple objects to be
identified and added without closing the dialog each time.) [WEM‑1620]
• After you migrate your on‑premises WEM database to the WEM service, you must reinstall the
WEM service agent even if the latest version is installed on your machine. This is necessary be‑
cause the agent cache cannot synchronize with the WEM service database unless you reinstall
the WEM service agent. [WEM‑2396]
• In Transformer (kiosk) mode, and with Log Off Screen Redirection enabled, WEM might fail to
redirect the user to the logon page after logging off. [WEM‑3133]
• When you click Apply Filter or Refresh Report on the Administration Console > Monitoring
> User Trends > Devices Types tab, you might not be able to view the report. Instead, you
are returned to the Administration Console > Actions > Applications > Application List tab.
[WEM‑3254]
• On Windows 10 version 1809 and Windows Server 2019, Workspace Environment Management
fails to pin the applications to the task bar. [WEM‑3257]
• After WEM upgrades to the latest version, if you still use the earlier versions of the agent, the
agent fails to work properly in offline mode. This issue occurs because of the scope changes of
the agent local cache file in the latest release. As a workaround, delete the old agent local cache
file, and then restart the WEM Agent Host Service (Norskale Agent Host service). [WEM‑3281]
• On the Security tab of the administration console, if you create an AppLocker rule for a file with
an .exe or a .dll extension using a file hash condition, the rule does not work. This issue occurs
because WEM calculates the hash code of that file incorrectly. [WEM‑3580]
• On the Security tab of the administration console, if you create an AppLocker rule for a file using
a publisher condition, the rule does not work. This issue occurs because WEM resolves the file
name incorrectly. [WEM‑3582]
• If you click Add OU on the administration console, WEM might not display anything on the Or‑
ganizational Units window. The issue occurs when a forest (current or trusted) contains many
OUs. As a workaround, you might need to click Cancel and then click Add OU multiple times.
[WEM‑3818, UCOHELP‑1211]
• The Application Security feature does not work on Windows servers that use non‑English Win‑
dows operating systems. This issue occurs because WEM fails to start the Application Identity
service in non‑English language environments. [WEM‑3957, LD1185]
• On Windows 10 machines, environment and certain other settings that you configured in the
administration console might not work. [WEM‑14193]
• Instances of Adobe Reader installed on Windows Server 2012 R2 prevent Workspace Environ‑
ment Management from associating PDF files with other PDF reader applications. Users are
forced to select the PDF reader application each time they open a PDF. [WEM‑33]
• Agent host machine names listed on the Active Directory Objects tab of the WEM service admin‑
istration console do not update automatically to reflect changes to machine names. To display
the new name of a machine in the Machines list, you must manually delete the machine from
the Machines list, and then add the machine again. [WEM‑1549]
• On the Active Directory Objects tab of the administration console, using Add Object and
Check Name to search and add objects allows only one object to be added at a time. You must
close and then reopen the Select Computers or Groups dialog to add another object. (The
on‑premises version of Workspace Environment Management allows multiple objects to be
identified and added without closing the dialog each time.) [WEM‑1620]
• After you migrate your on‑premises WEM database to the WEM service, you must reinstall the
WEM service agent even if the latest version is installed on your machine. This is necessary be‑
cause the agent cache cannot synchronize with the WEM service database unless you reinstall
the WEM service agent. [WEM‑2396]
• In Transformer (kiosk) mode, and with Log Off Screen Redirection enabled, WEM might fail to
redirect the user to the logon page after logging off. [WEM‑3133]
• When you click Apply Filter or Refresh Report on the Administration Console > Monitoring
> User Trends > Devices Types tab, you might not be able to view the report. Instead, you
are returned to the Administration Console > Actions > Applications > Application List tab.
[WEM‑3254]
• On Windows 10 version 1809 and Windows Server 2019, Workspace Environment Management
fails to pin the applications to the task bar. [WEM‑3257]
• After WEM upgrades to the latest version, if you still use the earlier versions of the agent, the
agent fails to work properly in offline mode. This issue occurs because of the scope changes of
the agent local cache file in the latest release. As a workaround, delete the old agent local cache
file, and then restart the WEM Agent Host Service (Norskale Agent Host service). [WEM‑3281]
• On the Security tab of the administration console, if you create an AppLocker rule for a file with
an .exe or a .dll extension using a file hash condition, the rule does not work. This issue occurs
because WEM calculates the hash code of that file incorrectly. [WEM‑3580]
• On the Security tab of the administration console, if you create an AppLocker rule for a file using
a publisher condition, the rule does not work. This issue occurs because WEM resolves the file
name incorrectly. [WEM‑3582]
• Attempts to map a network drive to users fail if you select the character # as the drive letter for
that network drive in the Assign Filter & Drive Letter window. This issue occurs because WEM
currently does not support assigning a random letter to a network drive by using “#.”[WEM‑3752,
LD1014]
• Attempts to migrate your WEM database into the WEM service can fail. The issue occurs when
the entries in the VUEMTasksHistory table of your on‑premises WEM database contain special
characters. As a workaround, delete those entries from your on‑premises WEM database, and
then restart the migration process. [WEM‑3817, UCOHELP‑1567]
• If you click Add OU on the administration console, WEM might not display anything on the Or‑
ganizational Units window. The issue occurs when a forest (current or trusted) contains many
OUs. As a workaround, you might need to click Cancel and then click Add OU multiple times.
[WEM‑3818, UCOHELP‑1211]
• The Application Security feature does not work on Windows servers that use non‑English Win‑
dows operating systems. This issue occurs because WEM fails to start the Application Identity
service in non‑English language environments. [WEM‑3957, LD1185]
• On Windows 10 machines, environment and certain other settings that you configured in the
administration console might not work. [WEM‑14193]
• Instances of Adobe Reader installed on Windows Server 2012 R2 prevent Workspace Environ‑
ment Management from associating PDF files with other PDF reader applications. Users are
forced to select the PDF reader application each time they open a PDF. [WEM‑33]
• If you open the Workspace Environment Management service administration console using In‑
ternet Explorer 11 (IE11) or Microsoft Edge, and open the Developer Tools pane (F12), when you
close the Developer Tools pane again the administration console does not redraw to full size.
If this happens, refresh the browser window to redraw the administration console correctly.
[WEM‑1377]
• Agent host machine names listed on the Active Directory Objects tab of the WEM service admin‑
istration console do not update automatically to reflect changes to machine names. To display
the new name of a machine in the Machines list, you must manually delete the machine from
the Machines list, and then add the machine again. [WEM‑1549]
• On the Active Directory Objects tab of the administration console, using Add Object and
Check Name to search and add objects allows only one object to be added at a time. You must
close and then reopen the Select Computers or Groups dialog to add another object. (The
on‑premises version of Workspace Environment Management allows multiple objects to be
identified and added without closing the dialog each time.) [WEM‑1620]
• After you migrate your on‑premises WEM database to the WEM service, you must reinstall the
WEM service agent even if the latest version is installed on your machine. This is necessary be‑
cause the agent cache cannot synchronize with the WEM service database unless you reinstall
the WEM service agent. [WEM‑2396]
• Attempts to access the administration console from the Workspace Environment Management
service Manage tab fail. As a workaround, refresh your browser window and try again. [WEM‑
2401]
• Attempts to run the UpmConfigCheck script on Windows 7 Service Pack 1, Windows 2008 R2
Service Pack 1, or Windows Server 2008 Service Pack 2 fail. To run the script on those operat‑
ing systems, you must manually install Windows Management Framework 3.0. If the UpmCon‑
figCheck still does not work after you install Windows Management Framework 3.0, restart your
WEM agent host service (Norskale Agent Host Service). [WEM‑2717]
• On Windows 10 machines, environment and certain other settings that you configured in the
administration console might not work. [WEM‑14193]
• On Windows Server 2012 R2, if Adobe Acrobat Reader is installed, it prevents Workspace Envi‑
ronment Management from associating PDF files with other PDF reader applications. Users are
forced to select the PDF reader application each time they open a PDF. [WEM‑33]
• On the Security tab, when you clear the option Process DLL Rules, the rule count reported next
to the “DLL Rules”collection is set to zero, regardless of the actual number in the WEM database.
[WEM‑425]
• If you open the Workspace Environment Management service administration console using In‑
ternet Explorer 11 (IE11) or Microsoft Edge, and open the Developer Tools pane (F12), when you
close the Developer Tools pane again the administration console does not redraw to full size.
If this happens, refresh the browser window to redraw the administration console correctly.
[WEM‑1377]
• Agent host machine names listed on the Active Directory Objects tab of the WEM service admin‑
istration console do not update automatically to reflect changes to machine names. To display
the new name of a machine in the Machines list, you must manually delete the machine from
the Machines list, and then add the machine again. [WEM‑1549]
• The on‑premises version of Workspace Environment Management (WEM) allows you to use Ac‑
tive Directory security groups as containers for WEM agents. However, the WEM service does
not support using Active Directory security groups as agent containers. The on‑premises infra‑
structure service also supports using direct and indirect OUs as agent containers. However, the
WEM service does not support indirect OUs. For example, suppose WEM agent AGENT1 belongs
to OU2, and OU2 belongs to OU1 (OU1>OU2>AGENT1). The on‑premises infrastructure service
recognizes AGENT1 as a member of both OU1 and OU2, but the WEM service only recognizes
AGENT1 as a member of OU2. [WEM‑1619]
• In the administration console Active Directory Objects tab, using Add Object and Check Name
to search and add objects allows only one object to be added at a time. You must close and
then reopen the Select Computers or Groups dialog to add another object. (The on‑premises
version of Workspace Environment Management allows multiple objects to be identified and
added without closing the dialog each time.) [WEM‑1620]
• On Windows 10 machines, environment and certain other settings that you configured in the
administration console might not work. [WEM‑14193]
System requirements
Software prerequisites
Citrix Cloud Connector. This component must be installed on at least one machine in every resource
location you are using before you install the Workspace Environment Management service agent. See
Cloud Connector Installation.
.NET Framework 4.7.1 or later. This component is necessary for the Workspace Environment Man‑
agement service agent. If not already installed, it is automatically installed during agent installa‑
tion.
Microsoft Visual C++. This component is necessary for the Workspace Environment Management
service agent. If not already installed, the Microsoft Visual C++ 2015–2019 Redistributable is automat‑
ically installed during agent installation.
Microsoft Edge WebView2 Runtime version 98 or later. This component is necessary for the Work‑
space Environment Management service agent. If not already installed, it is automatically installed
during agent installation.
Note:
Microsoft Active Directory. Workspace Environment Management service requires read access to
your Active Directory to push configured settings out to users.
Citrix DaaS (formerly Citrix Virtual Apps and Desktops service) or Citrix Virtual Apps and Desk‑
tops. Any supported version of Citrix Virtual Apps or desktops is required.
Citrix Workspace app for Windows. To connect to Citrix StoreFront store resources that have been
configured from the Workspace Environment Management service administration console, Citrix
Workspace app for Windows must be installed on the agent host machine. The following versions are
supported:
• Citrix Receiver for Windows versions: 4.4 LTSR CU5, 4.7, 4.9, 4.9 LTSR CU1, and 4.10
• Citrix Workspace app 1808 for Windows and later
For Transformer kiosk‑enabled machines, Citrix Workspace app for Windows must be installed with
single sign‑on enabled, and configured for pass‑through authentication. For more information, see
Citrix Workspace app.
Note:
The Workspace Environment Management agents are supported only on operating system ver‑
sions that are supported by their manufacturer. You might need to purchase extended support
from your operating system manufacturer.
Agent. The Workspace Environment Management agent is supported on the following operating sys‑
tems:
Note:
Hardware prerequisites
Agent: average RAM consumption is 10 MB, but we recommend that you provide 20 MB to be safe. 40
MB of available disk space (100 MB during installation).
Connectivity prerequisites
For the WEM service agent to operate, you must configure your firewall and proxy server to allow out‑
bound connections. For more information, see Internet connectivity requirements.
In enterprise networks, the WEM service also requires the Cloud Connector to communicate with the
WEM service agent. Therefore, check your firewall settings to ensure that the WEM service agent port
is configured correctly. For more information, see Port information.
Service dependencies
Netlogon. The agent service (“Citrix WEM Agent Host Service”) is added to the Net Logon Dependen‑
cies list to ensure that the agent service is running before logons can be made.
Antivirus exclusions
The Workspace Environment Management service agent is installed in the following default folder:
On‑access scanning must be disabled for the entire “Citrix”installation folder for the Workspace En‑
vironment Management agent. When this is not possible, the following processes must be excluded
from on‑access scanning:
• AgentCacheUtility.exe
• AgentGroupPolicyUtility.exe
• AppInfoViewer.exe
• Agent Log Parser.exe
• AppsMgmtUtil.exe
• Citrix.Wem.Agent.EnrollmentUtility.exe
• Citrix.Wem.Agent.Service.exe
• Citrix.Wem.Agent.LogonService.exe
• PrnsMgmtUtil.exe
• VUEMAppCmd.exe
• VUEMAppCmdDbg.exe
• VUEMAppHide.exe
• VUEMCmdAgent.exe
• VUEMMaintMsg.exe
• VUEMRSAV.exe
• VUEMUIAgent.exe
Limits
February 2, 2021
Workspace Environment Management (WEM) service is designed for large‑scale enterprise deploy‑
ments. On the server side, WEM service monitors the communication flow between front‑end and
back‑end components, and scales up or down dynamically based on data in transit.
When evaluating WEM service for sizing and scalability, consider the following limits. The values in
this article indicate the limits of a single WEM service instance.
Usage limits
Resource Limit
Important:
To ensure high availability, we recommend at least two Cloud Connectors in each resource lo‑
cation. The WEM agent balances the load among Cloud Connectors automatically. If the Citrix
Cloud Connectors in place are not for WEM service only, consider deploying additional Cloud
Connectors. For information about Cloud Connectors, see Citrix Cloud Connector.
November 1, 2022
If you are not familiar with the components used in a Workspace Environment Management (WEM)
service deployment, see Workspace Environment Management service.
If you are migrating from an on‑premises WEM deployment, see Migrate to cloud.
To set up your WEM deployment, complete the tasks summarized below. Links are provided to each
task’s details.
Review the entire process before starting the deployment, so you know what to expect. This article
also links to other helpful information sources.
See the Citrix Tech Zone documentation articles to help establish goals and define use cases and busi‑
ness objectives, and to get to know configuration considerations.
• To learn how WEM improves the overall experience and enhances the security of the deploy‑
ment, see Tech Brief: Workspace Environment Management.
• To learn the architecture and deployment considerations for this cloud‑based service, see Ref‑
erence Architecture: Workspace Environment Management.
• To learn how WEM optimizes resource utilization, logon times, and RAM usage, see Tech Insight:
Workspace Environment Management. Watch the videos there.
Sign up
Sign up for a Citrix account and request a WEM service trial. The onboarding steps are:
To sign up for a Citrix account and request a trial, contact your Citrix Sales Representative. When you
are ready to proceed, go to https://onboarding.cloud.com.
After you log on, in the WEM service tile, click Request Trial. The text changes to Trial Requested.
You will receive an email when your trial is available.
Note:
While waiting for the trial, you can review the information referenced in Where to go next. Al‑
though Citrix hosts and delivers your WEM service solution, you manage the machines that de‑
liver applications and desktops, plus the applications and users. You can spend this time setting
up the infrastructure to your corporate services, such as Active Directory.
Each machine that WEM manages must have a WEM agent installed on it. WEM agents connect to the
WEM service and enforce settings you configure in the administration console. Before you install the
agent, determine a setup method that suits your deployment needs.
There are three setup methods to connect the agent to the WEM service:
• Cloud Connector. Use this method if your machines are domain joined. This method requires
that you set up resource locations and install at least one Citrix Cloud Connector in each.
– For high availability, we recommend that you install two Cloud Connectors in each re‑
source location.
– Resource locations contain infrastructure services (such as Active Directory and Cloud Con‑
nectors) and the machines that deliver apps and desktops to users.
• Enrollment. Use this method to enroll WEM agents without configuring Cloud Connectors. This
method requires that you select Skip Configuration when installing the agent and applies only
to physical machines and persistent VMs.
The following provides general guidance to help you decide which method to use.
• For machines managed by Citrix DaaS. Use the same method to connect the agent to Citrix
Cloud as you do for the Virtual Delivery Agent (VDA) —through the Cloud Connector or the non‑
domain‑joined method.
• For machines not managed by Citrix DaaS. Use the Cloud Connector or the enrollment
method.
Each machine that WEM manages must have a WEM agent installed on it. See Install the agent.
After you complete the tasks above that set up your WEM deployment, start the WEM administration
console. There are two consoles available:
• Legacy console
• Web console
We are in the process of migrating features from the legacy console to the web console. The web
console responds faster than the legacy console and provides more functionalities. To see the features
available only in the web console, see What’s new.
More information
• REST APIs
Install agents
February 2, 2024
This article begins with a description of Workspace Environment Management (WEM) agents. The
remainder of the article describes the steps in the agent installation wizard. Additional information
related to agents is provided.
Introduction
Each machine that WEM manages must have a WEM agent installed on it. WEM agents connect to the
WEM service and enforce settings you configure in the administration console. All communications
are over HTTPS using the Citrix Cloud Messaging Service. All agents use local caching, ensuring that
they can continue using existing settings if network connection is interrupted.
• For domain‑joined machines, make sure that agent host machines belong to the same Active
Directory domain as the configured Cloud Connectors. Also, make sure that the agent host ma‑
chines in each resource location are joined correctly.
• The process of installing agents on machines that are non‑domain‑joined is similar to that of
domain‑joined machines. However, make sure that you satisfy all requirements and select the
correct options throughout the process. For more information, see Manage non‑domain‑joined
machines.
There are three methods to connect the agent to the WEM service:
• Cloud Connector
• Non‑domain‑joined
• Enrollment
For more information about the methods, see Determine which setup method to use.
Note:
To access resources published in Citrix Workspace as application shortcuts from the administra‑
tion console, ensure that Citrix Workspace app for Windows is installed on the agent machine.
For more information, see System requirements.
Important:
Skip this step if you choose to use the non‑domain‑joined or the enrollment method.
Optionally, you can choose to configure the group policies. The Agent Group Policies administrative
template, provided in the WEM agent package, adds the Agent Host Configuration policy.
1. Copy the Agent Group Policies folder provided with the WEM installation package to your WEM
domain controller.
4. In the Group Policy Management Editor window, go to Computer Configuration > Policies >
Administrative Templates > Citrix Components > Workspace Environment Management >
Agent Host Configuration and configure the following settings:
Agent proxy configuration. The WEM agent relies on internet connections to connect to the WEM
service in Citrix Cloud. The communication between the agent and the service serves the following
purposes:
Optionally, you can choose to configure an HTTPS proxy to define how the agent communicates with
the service. To do so, double‑click the Agent proxy configuration policy and then type a proxy server
address in this format: http://<FQDN or IP address>:<port number>. Example: http
://10.108.125.51:8080.
Note:
WEM service does not support proxy servers that require authentication.
Agent service port. Not required for WEM service. Leave state “Not configured.”
Cached data synchronization port. Not required for WEM service. Leave state “Not configured.”
Citrix Cloud Connectors. Configure at least one Citrix Cloud Connector. Agent host machines must
be in the same AD domain as the configured Cloud Connector machines.
Discover Citrix Cloud Connector from CVAD service. Lets you control whether the agent discovers
Cloud Connector information from the relevant Citrix DaaS (formerly Citrix Virtual Apps and Desktops
service) deployment if you have not yet configured Cloud Connectors for the agent. The agent then
connects to the corresponding Cloud Connector machines.
Note:
• This setting is designed for scenarios where the WEM agent is running in a Citrix DaaS de‑
ployment.
• This policy setting does not work if Cloud Connectors are configured during agent installa‑
tion or the Citrix Cloud Connectors policy setting is enabled.
Infrastructure server. Not required for WEM service. Leave state “Not configured.”
VUEMAppCmd extra sync delay. Specifies, in milliseconds, how long the agent application launcher
(VUEMAppCmd.exe) waits before published resources are started. This ensures that the necessary
agent work completes first. The recommended value is 100 through 200. The default value is 0.
Important:
Although the .NET Framework can be automatically installed during agent installation, we rec‑
ommend that you install it manually before you install the agent. Otherwise, you need to restart
your machine to continue with the agent installation, and it might take a long time to complete.
The agent setup program Citrix Workspace Environment Management Agent is provided in the agent
download. You can choose to install the agent interactively or using the command line. By default,
the agent installs into one of the following folders, depending on your operating system (OS):
2. Select “I agree to the license terms and conditions”and then click Install.
Note:
The Welcome page can take some time to appear. This happens when the required soft‑
ware is missing and is being installed in the background.
• By default, the destination folder field is automatically populated with the default folder
path. If you want to install the agent to another folder, click Change to navigate to the
folder and then click Next.
• If the WEM agent is already installed, the destination folder field is automatically popu‑
lated with the existing installation folder path.
5. On the Deployment Type page, select the applicable type of deployment and then click Next.
In this case, select Cloud Service Deployment.
6. On the Cloud Service Configuration page, specify the Citrix Cloud Connectors to which the agent
connects and then click Next.
• Configure Citrix Cloud Connectors. Configure the Citrix Cloud Connectors to which the
agent connects by typing a comma‑separated list of FQDNs or IP addresses of the Cloud
Connectors.
Note:
– Type the FQDN or IP address of each Citrix Cloud Connector. Make sure to sepa‑
rate the FQDNs or IP addresses with commas (,).
– In scenarios where multiple Cloud Connectors are configured, the WEM agent ran‑
domly selects from the list a Cloud Connector that is reachable. This design in‑
tends to distribute traffic across all Cloud Connectors.
7. On the Advanced Settings page, configure advanced settings for the agent and then click Next.
• Alternative Cache Location (Optional). Lets you specify an alternative location for the
agent cache. Click Browse to navigate to the applicable folder. Alternatively, you can do
that through the registry. To do that, first stop the Citrix WEM Agent Host Service and then
modify the following registry key.
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Norskale\Agent Host
Name: AgentCacheAlternateLocation
Type: REG_SZ
Value: Empty
By default, the value is empty. The default folder is: <WEM agent installation
folder path>\Local Databases Set. Specify a different folder path if necessary.
For the changes to take effect, restart the Citrix WEM Agent Host Service. If the change
takes effect, the following files appear in the folder: LocalAgentCache.db and LocalA‑
gentDatabase.db.
Caution:
Editing the registry incorrectly can cause serious problems that might require you
to reinstall your operating system. Citrix cannot guarantee that problems resulting
from the incorrect use of Registry Editor can be solved. Use Registry Editor at your
own risk. Be sure to back up the registry before you edit it.
• VUEMAppCmd Extra Sync Delay (Optional). Lets you specify how long the agent appli‑
cation launcher (VUEMAppCmd.exe) waits before published resources are started. This
ensures that the necessary agent work completes first. The default value is 0.
Note:
The value you type for the extra sync delay interval must be an integer greater than
or equal to zero.
Alternatively, you can choose a silent installation of the WEM agent using the command line. To do so,
use the following command line:
Tip:
• For agents running in a WEM service deployment, enter Cloud=1. For agents running in
an on‑premises WEM deployment, enter Cloud=0.
• You might want to consult the log files to troubleshoot the agent installation. By default,
log files recording all actions that occur during installation are created in %TEMP%. You
can use the /log log.txt command to designate a specific location for the log files to
be saved.
You can also use command‑line options to specify custom arguments. Doing so lets you customize
agent and system settings during the installation process. For more information, see Good to know.
After installation, the agent runs as the following services: Citrix WEM Agent Host Service and Citrix
WEM Agent User Logon Service. The agent runs as account LocalSystem. Changing this account is not
supported. The agent services require the “log on as a local system”permission.
1. On a machine where the agent is installed, open the system’s Control Panel.
2. Click Programs and Features.
3. Select Citrix Workspace Environment Management Agent and then click Uninstall in the
menu.
If you install the agent as an additional component when installing the VDA, use the WEM installer (MSI)
available with the VDA installer to uninstall the agent. The WEM installer citrix_wem_agent_core
.msi is present in <VDA installer path>\x64\Virtual Desktop Components. To
uninstall the agent that was installed as an additional component with the VDA, complete the
following steps:
After uninstalling the agent, you can use the VDA installer or the WEM installer to install it. Starting
with Citrix Virtual Apps and Desktops 2209, the WEM agent is no longer included as an additional
component in the VDA installation. To install it, use the full‑product installer on the Citrix Virtual
Apps and Desktops product ISO. For more information, see Install core components.
Where to go next
If you want to migrate your existing on‑premises WEM database into the WEM service, see Migrate to
cloud.
To directly get started with the WEM service, start the administration console and configure settings
there as needed. There are two consoles available:
• Legacy console
• Web console
We are in the process of migrating features from the legacy console to the web console. The web
console responds faster than the legacy console and provides more functionalities. To see the features
available only in the web console, see What’s new.
To ensure that the WEM agent works properly, be aware of the following prerequisites and recommen‑
dations:
Prerequisites
• The Windows service System Event Notification Service is configured to start automatically
on startup.
• The WEM agent services Citrix WEM Agent Host Service and Citrix WEM User Logon Service
are configured to start automatically on startup.
• The agent cache resides in a persistent location whenever possible. Using a non‑persistent
cache location can cause potential cache sync issues, excessive network data usage, perfor‑
mance issues, and so on.
Recommendations
• Do not manually operate Citrix WEM Agent Host Service, for example, using logon or startup
scripts. Operations such as stopping or restarting Citrix WEM Agent Host Service can stop the
Netlogon service from working, causing issues with other applications.
• Do not use logon scripts to launch UI‑mode or CMD‑mode agents. Otherwise, some functional‑
ities might fail to work.
• Citrix WEM Agent Host Service automatically reloads Cloud Connector settings configured
through Group Policy after the service starts.
• Citrix WEM Agent User Logon Service automatically starts Citrix WEM Agent Host Service
if the agent host service does not start during the first logon. This behavior ensures that user
configuration is processed properly.
• Citrix WEM Agent Host Service automatically performs checks on the following local database
files on startup: LocalAgentCache.db and LocalAgentDatabase.db. If the virtual ma‑
chine is provisioned and the local database files are from the base image, the database files are
automatically purged.
• When Citrix WEM Agent Host Service starts, it automatically verifies that the agent local cache
has been recently updated. If the cache has not been updated for more than two configured
cache synchronization time intervals, the cache is synchronized immediately. For example, sup‑
pose the default agent cache sync interval is 30 minutes. If the cache was not updated in the
past 60 minutes, it is synchronized immediately after Citrix WEM Agent Host Service starts.
• During installation, the WEM agent installer configures the Windows service System Event No‑
tification Service to start automatically.
• The WEM agent installer automatically starts the Netlogon service after the WEM agent upgrade
completes.
Citrix WEM Agent Host Service handles setting refresh and cache sync automatically. Use the agent
cache utility only in scenarios where there is a need to immediately refresh the settings and synchro‑
nize the cache.
Use the command line to run AgentCacheUtility.exe in the agent installation folder. The executable
accepts the following command‑line arguments:
See the following examples for details about how to use the command line:
– AgentCacheUtility.exe -RefreshSettings
Good to know
Agent settings
• AgentLocation. Lets you specify the agent installation location. Specify a valid folder path.
• CloudConnectorList. Lets you specify the FQDN or IP address of each Citrix Cloud Connector.
Make sure to separate FQDNs or IP addresses with commas (,).
• VUEMAppCmdDelay. Lets you specify how long the agent application launcher (VUEMAp‑
pCmd.exe) waits before Citrix Virtual Apps and Desktops published resources are started. The
default value is 0 (milliseconds). The value you type for the extra sync delay interval must be
an integer greater than or equal to zero.
• AgentCacheLocation. Lets you specify an alternative location for the agent cache. If config‑
ured, the agent local cache file is saved in the designated location instead of in the agent instal‑
lation folder.
• If the settings are configured through the command line, the WEM agent installer uses the con‑
figured settings.
• If the settings are not configured through the command line and there are previously configured
settings, the installer uses the settings that were previously configured.
• If the settings are not configured through the command line and there are no previously config‑
ured settings, the installer uses the default settings.
System settings
See below for the system settings associated with the agent host machine.
If Group Policy settings are processed in the background, Windows Shell (Windows Ex‑
plorer) might start before all policy settings are processed. Therefore, some settings might
not take effect the first time a user logs on. If you want all policy settings to be processed
the first time a user logs on, set the value to 1.
• WaitForNetwork. Lets you configure the value, in seconds, of the WaitForNetwork registry
key created during installation. This argument specifies how long the agent host waits for the
network to be completely initialized and available. The argument accepts any whole number in
the range of 0 (minimum) to 300 (maximum). By default, this value is 30.
• ServicesPipeTimeout. Lets you configure the value of the ServicesPipeTimeout registry key.
The key is created during installation under HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control.
This registry key adds a delay before the service control manager is allowed to report on the
state of the WEM agent service. The delay prevents the agent from failing by keeping the agent
service from launching before the network is initialized. This argument accepts any value, in
milliseconds. If not specified, a default value of 60000 (60 seconds) is used.
Note:
If the settings above are not configured using the command line, they are not processed
by the WEM agent installer during installation.
Examples
You can also configure the settings using the following command‑line format:
For example:
Enroll agents
November 8, 2022
Introduction
You can enroll Workspace Environment Management (WEM) agents without configuring Citrix Cloud
Connectors. Before you do that, consider the following:
• The enrollment applies to both domain‑joined and non‑domain‑joined machines but applies
only to physical machines and persistent VMs.
• For Citrix DaaS managed VMs, we recommend using the same method to connect the agent to
Citrix Cloud as you do for the VDA —through the Cloud Connector or the non‑domain‑joined
method. See Determine which setup method to use.
• To ensure that persistent VMs enroll properly:
This feature requires that you select Skip Configuration when installing the agent and that you do
not enable the Discover Citrix Cloud Connector from CVAD service policy.
Enroll agents
You have the flexibility to determine how to enroll your WEM agents. There are two ways:
• Enroll by invitation. This requires the web console. Users can be invited to participate in the
enrollment process.
• Enroll with the bearer token or API secure client. This doesn’t require the console and doesn’t
require users to participate in the enrollment process.
Enroll by invitation
To manage user devices remotely and securely, you enroll user devices in WEM.
1. In Manage > Web Console > Enrollment > Invitation, enable Enroll by invitation and then
generate an enrollment key.
2. On the agent machine, install the enrollment key using the enrollment tool.
b) Run the following command.(Replace <enrollment key> with the actual key.)
• Citrix.Wem.Agent.EnrollmentUtility.exe configenrollmentkey
-k <enrollment key>
Tip:
3. In Manage > Web Console > Enrollment > Invitation, send an enrollment invitation to users.
After users receive the invitation, they can enroll their devices using the invitation code. See Enroll
the agent with an invitation code.
After a device enrolls, it becomes managed and appears in Manage > Web Console > Enrollment >
Enrolled Agents. You can add it to a desired configuration set for precise management. See Manage
the enrolled agent.
Important:
1. Open your desktop Start menu and select Citrix > WEM Enrollment Registration Utility.
Tip:
If the utility is not available in the Start menu, go to the WEM agent installation folder and
open Citrix.Wem.Agent.Enrollment.RegUtility.exe.
2. In Enrollment Registration Utility, verify that the status of the enrollment key is Installed and
click Enroll Agent.
Note:
If the status of the enrollment key is not Installed, contact your administrator.
3. In the Enroll Agent window, paste the invitation code (copied from the invitation email) and
click Start Enrolling.
If the agent enrolls successfully, you see the following message: The agent was enrolled success‑
fully. You can click Close to return to Enrollment Registration Utility, which shows the following
information:
Note:
Enrolling with the bearer token or API secure client does not require the participation of the en‑
rollment key. If you use the Enrollment Registration Utility to check the enrollment status on
an agent machine enrolled with the bearer token or API secure client, the Enrollment key status
field appears as Not installed and the Enrollment status field appears as Enrolled.
1. Sign in to Citrix Cloud and get a bearer token or an API secure client for authentication to the
Citrix API service. For information about how to generate an API secure client and a bearer token,
see Get started with Citrix Cloud APIs.
• To enroll the agent with the bearer token, type the following command:
Tip:
When using a bearer token, be aware that the base URL is unique for each region.
For more information, see Base URLs. If unspecified, the URL for the US region
(api.wem.cloud.com) is used.
• To enroll the agent with the API secure client, type the following command:
Tip:
– When using a secure client, be aware that there are two URLs.
– The first URL is the authentication URL, which is unique for each region. For more
information, see Get started with Citrix Cloud APIs. If unspecified, the URL for the
US region (api‑us.cloud.com) is used.
– The second URL is the base URL, which is also unique for each region. For
more information, see Base URLs. If unspecified, the URL for the US region
(api.wem.cloud.com) is used.
Alternatively, in Step 3, create a configuration file in JSON format and use the file with the following
command:
Note:
We recommend that you delete the configuration file after the enrollment because the file con‑
tains sensitive information.
Tip:
When using a bearer token or secure client, you can leave the corresponding fields empty.
1 {
2
3
4 "CustomerId": The Citrix Cloud customer ID,
5
6 "ClientId": The secure client ID of the Citrix Cloud API client,
7
Example output:
After enrolling an agent, use the management console to bind it to a desired configuration set for
precise management.
• In the web console, go to Directory Objects and then add the agent machine to a configuration
set. See Directory Objects.
• In the legacy console, go to Active Directory Objects > Machines and then add the agent ma‑
chine to a configuration set. See Active Directory Objects.
• For information about adding non‑domain‑joined machines, see Manage non‑domain‑joined
machines.
Note:
• After you add an enrolled non‑domain‑joined machine, the agent first registers with the
Default Site configuration set or the Unbound Agents configuration set (if enabled). After
the agent is registered, you can add the machine to other configuration sets.
A service key is created in the cloud when an agent enrolls into WEM successfully. Consider the follow‑
ing rules:
• The key expires in 90 days. After it expires, the agent must connect to the WEM service to ro‑
tate the key. By default, the agent automatically connects to rotate the key 14 days before the
expiration.
• The expired key is kept for 180 days. The agent must rotate the key within 180 days. After that,
the key will be deleted.
• If the key is deleted, the agent using the key can no longer connect to the WEM service. The
agent must be reenrolled.
Note:
An identity change can cause a mismatch between the service key and the agent identity. An
identity change can occur, for example, when an agent machine joins or leaves a domain. In that
case, you must let the agent connect to the WEM service when the key is still valid so that the
agent can rotate the key.
Enrollment tool
Parameter Description
For example, to display agent enrollment status, type the following command:
• Citrix.Wem.Agent.EnrollmentUtility.exe status
Parameter Description
Parameter Description
Return codes
Code Description
0 No error
1 Invalid arguments
2 Insufficient permissions
3 Agent host service not ready
4 Error while calling remote APIs
100 Unhandled exception
1000 Agent not enrolled
1001 Agent currently enrolled. When enrolling the
agent, the operation is skipped unless the
– force option is specified.
2000 Enrollment key not installed
2001 Enrollment key installed
To unenroll the agent, use the agent installer when uninstalling the agent, with the following com‑
mand:
• HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\WEM\Agent\EnrollmentData
Introduction
Citrix Optimization Pack for Azure Virtual Desktop is a new Citrix offering for optimizing Azure Virtual
Desktop workloads. Currently, it includes the Workspace Environment Management service, a light‑
weight, scalable user environment management solution that simplifies IT administration and opti‑
mizes desktops for the best possible user experience.
With the Citrix Optimization Pack, you can use the Workspace Environment Management service to
manage, optimize, and secure your native Azure Virtual Desktop environments. Organizations can
realize the following benefits:
For information about other benefits, see the highlights of the Workspace Environment Management
service.
Important:
• To manage Azure Virtual Desktop with the Workspace Environment Management service,
you must purchase Citrix Optimization Pack.
• This product documentation, including other information sources this article links to, is not
specific to the Workspace Environment Management service. All information applies to Cit‑
rix Optimization Pack as well, unless otherwise stated. For a complete list of Workspace
Environment Management features that do not apply to Citrix Optimization Pack, see Fea‑
tures not applicable to Azure Virtual Desktop.
Prerequisites
• Machines and users are Active Directory or Azure Active Directory Domain Services joined
• Citrix Cloud Connectors are domain joined
System requirements
For information about system requirements of Citrix Optimization Pack, see System requirements.
Limits
Citrix Optimization Pack is designed for small and medium‑sized and large‑scale enterprise deploy‑
ments. On the server side, Citrix Optimization Pack monitors the communication flow between front‑
end and back‑end components and scales up or down dynamically based on data in transit.
When evaluating Citrix Optimization Pack for sizing and scalability, consider the limits. The values in
the article indicate the limits of a single Citrix Optimization Pack instance.
Get Started
Use the following sequence to set up your Citrix Optimization Pack deployment.
Tip:
For step‑by‑step instructions on deploying Azure Virtual Desktop, see the Microsoft documenta‑
tion at https://docs.microsoft.com/en‑au/azure/virtual‑desktop/overview.
Step 1: Onboarding
Sign up for a Citrix account and request a trial of Citrix Optimization Pack as described in Subscribe to
Citrix Optimization Pack for Azure Virtual Desktop. For information about the onboarding procedure,
see Sign up.
Resource locations contain infrastructure servers (such as Active Directory and Citrix Cloud Connec‑
tors). For more information, see the Cloud Connector method.
Each Azure Virtual Desktop that Citrix Optimization Pack manages must have a Workspace Environ‑
ment Management agent installed on it. Those machines must belong to the same Active Directory
domain or Azure Active Directory Domain Services domain as the configured Cloud Connectors. En‑
sure that the machines in each resource location are joined correctly.
For information about installing the agent, see Install agents.
To ensure that the agent works properly, review all the information in Prerequisites and recommen‑
dations.
More information
The Citrix Tech Zone documentation articles provide information that helps establish goals and define
use cases and business objectives and informs you of configuration considerations.
• To learn how Citrix Optimization Pack improves the overall experience and enhances the secu‑
rity of the deployment, see Tech Brief: Workspace Environment Management.
• To learn the architecture and deployment considerations for Citrix Optimization Pack, see Ref‑
erence Architecture: Workspace Environment Management.
• To learn how Citrix Optimization Pack optimizes resource utilization, logon times, and RAM us‑
age, see Tech Insight: Workspace Environment Management. Watch the videos there.
April 5, 2022
Introduction
You can subscribe to Citrix Optimization Pack for Azure Virtual Desktop through Citrix or through the
Azure Marketplace.
You can evaluate the pack by requesting a trial at Sign up. From a trial, you can convert to a paid
service subscription later.
You can order Citrix Optimization Pack for Azure Virtual Desktop through Citrix Cloud or through your
Citrix account representative or Citrix Partner.
• Follow the guidance in Sign up for Citrix Cloud to get a Citrix Cloud account and Organization
ID.
• You can request the Citrix Optimization Pack for Azure Virtual Desktop trial. In the Workspace
Environment Management service tile, click Request Trial. You’ll receive an email when your
trial is available.
You can order the Citrix Optimization Pack for Azure Virtual Desktop offerings through Azure Market‑
place:
If you have a Citrix Cloud account, but don’t know the Organization ID, look in the upper right corner
of the Citrix Cloud console. Or, look at the email you received when you created the account.
If you don’t have a Citrix Cloud account, follow the guidance in Sign up for Citrix Cloud.
Follow this procedure to order Citrix Optimization Pack for Azure Virtual Desktop through Azure Mar‑
ketplace.
8. On the Subscription in progress page, select Configure account now. (If the button is dis‑
abled, wait a moment.) You’re taken to a Citrix activation page.
• Use the Sign in link to sign in to Citrix Cloud. A successful sign‑in automatically populates
the Organization ID field.
• Quantity: Enter the number of users. (An initial order must be at least 25.) An estimated
price appears.
• Agree to the terms and conditions, and then select Activate Order.
Citrix sends you an email when your service is provisioned. Provisioning can take some time. If you
don’t receive the email by the following day, contact Citrix Technical Support. When you receive the
email from Citrix, you can begin using the service.
Important:
Do not delete the service resource in Azure. Deleting that resource cancels your subscription.
What’s next
After your order is fulfilled, continue with the next steps in Plan and build a deployment.
April 5, 2022
The following are the features that are available with the Workspace Environment Management ser‑
vice but do not apply to Citrix Optimization Pack for Azure Virtual Desktop.
This feature is only for Citrix DaaS (formerly Citrix Virtual Apps and Desktops service).
• Filter conditions
The following conditions are for Citrix DaaS and Citrix Virtual Apps and Desktops. They do not
apply to Citrix Optimization Pack for Azure Virtual Desktop.
This feature supports only applications published with Citrix DaaS and Citrix Virtual Apps and
Desktops.
• Transformer
This feature is for Citrix DaaS and Citrix Virtual Apps and Desktops. Currently, it’s available only
in the web console.
Upgrade
April 2, 2024
Note:
Starting with WEM agent 2211.1.0.1, agents download configuration data only when needed.
This enhancement can reduce bandwidth consumption by up to 50%. See What’s new. We rec‑
ommend that you upgrade your agents to 2211.1.0.1 or later so that you can reap the benefit.
Citrix maintains all Workspace Environment Management (WEM) service components in your deploy‑
ment except WEM service agents.
You can upgrade WEM service agents to a newer version without losing any of their existing configura‑
tions. This is called an in‑place upgrade.
By default, when new versions of the WEM service agent are released, you receive email notifications.
You can choose to unsubscribe if you do not want to receive such emails in the future. To do that, go
to the WEM service Utilities tab and then click Unsubscribe in the Notifications about new agent
versions section.
Important:
• Before upgrading a WEM service agent, ensure that no users are logged on. Doing that en‑
sures that files on agent machines can be changed during the upgrade process.
• We recommend that you upgrade the agent to the latest version so that you can use the
most recent features.
1. Download the latest WEM service agent package from the WEM service Utilities tab.
2. Deploy the new WEM service agent on each target machine as described in Install and configure.
Note:
If you use the automatic agent upgrade feature to roll out agent upgrades to non‑persistent ma‑
chines, the upgrades are reverted after the restart of the machines.
You can use the automatic agent upgrade feature to schedule automatic upgrades for the WEM agent.
The feature facilitates regular agent upgrades without the need to roll out agent upgrades manually.
The feature also provides flexibility in upgrading your WEM agents:
• You can specify a time period for which you want WEM to automatically roll out the upgrade to
all agent machines in a configuration set.
• Alternatively, you can choose to enable users to upgrade the agent manually.
You can upgrade your agents from the console on demand. The option is available in both the legacy
console and the web console. To use the feature:
• In the legacy console, go to Administration > Agents, right‑click an agent, and then select Up‑
grade agent to latest version. For more information, see Administration.
• In the web console, go to Monitoring > Administration > Agents, select one or more agents,
click More, and then select Upgrade agent to latest version. For more information, see Ad‑
ministration.
Migrate
June 2, 2022
Important:
• If you intend to migrate your existing on‑premises WEM database into the WEM service,
make sure that you use the latest version of the migration tool.
• To ensure that the migration tool works as expected, you might must upgrade the .NET
Framework. If you use WEM 1909 or earlier, upgrade to .NET Framework 4.7.1 or later on
the machine where you run the tool.
• We recommend that you run the migration tool on the machine where the infrastructure
service is installed. Doing so ensures that the infrastructure service can connect to the WEM
database and that the machine on which the infrastructure service is running has the nec‑
essary components.
We provide you with a toolkit to migrate your existing on‑premises Workspace Environment Manage‑
ment (WEM) database into the WEM service. The toolkit includes a wizard to generate an SQL file
containing the contents of your WEM database, and a simple way to upload the SQL file to the WEM
service Azure database. This article describes how to complete your on‑premises database migration.
Review the entire sequence before starting the migration process so that you know what to expect.
Before you migrate your WEM database, keep the following in mind:
• After your migration completes successfully, all data associated with your current WEM service
database will be lost.
• You can migrate your WEM database only after your WEM service is successfully provisioned.
• Before starting the migration process, Citrix recommends that you back up your on‑premises
WEM database.
• Before starting the migration process, Citrix recommends that you configure your database
maintenance on the Database Maintenance tab. Doing so reduces the size of your WEM data‑
base so that you have a better migration experience. For more information on database main‑
tenance, see Configure the infrastructure service.
• If you attempt to migrate your WEM database while the WEM service is upgrading, the following
error message appears in the notifications area in the top‑right corner of the Citrix Cloud user
interface: “The Workspace Environment Management database migration has failed because
the Workspace Environment Management service is upgrading. Please try again later.”When
this happens, try uploading the SQL file after your WEM service is upgraded successfully. Service
upgrades are also notified in the top‑right corner of the Citrix Cloud user interface.
System requirements
The toolkit supports the migration from WEM 4.7 and later. To migrate from an earlier version, upgrade
WEM 4.x to WEM 4.7 or later, and then migrate the database to the WEM service. For more information
on upgrading, see Upgrade a deployment.
Get started
Log on to your Citrix Cloud account. For more information, see What is a Citrix Cloud account.
Download the migration tool (WEM‑migration‑tool.zip) from the WEM service Utilities tab. Extract the
zip file to a convenient folder.
Note:
Citrix recommends that you run the migration tool on the machine where the infrastructure ser‑
vice is installed. Doing so ensures that the infrastructure service can connect to the WEM data‑
base and the machine on which the infrastructure service is running has the necessary compo‑
nents.
Run the Citrix WEM Migration Tool.exe contained in the zip file.
Server and instance name. Address of the SQL server instance that hosts the database. It must be
reachable from the infrastructure server exactly as typed here.
Use integrated connection (Windows credentials). If selected, allows the Database Migration Wiz‑
ard to use the Windows account of the identity it is running under to connect to the SQL server, and
then generate the SQL file containing the contents of your on‑premises WEM database. If this Win‑
dows account does not have sufficient permissions, run the Citrix WEM Migration Tool.exe using
a Windows account with sufficient privileges, or clear this option and provide an SQL account with
sufficient privileges instead.
Target. The desired folder for saving the SQL file containing the contents of your on‑premises WEM
database. Use the Browse button to navigate to the folder where you want to save the SQL file.
Export logs. Controls whether to export logs. The logs contain changes made to your WEM agents. If
enabled, the database file to be exported contains the logs. To speed up your migration, we recom‑
mend that you do not enable this option.
Export statistics. Controls whether to export agent and user statistics. If enabled, the database file
to be exported contains the statistics. By default, this option is disabled. To speed up your migration,
we recommend that you do not enable this option.
Note:
When saving as a file, your WEM database file is automatically renamed to “Your database
name_upload.7z.”
Click Export to start the database export process or click Cancel to exit the Database Migration Wiz‑
ard.
During the export process, the Database Migration Status window appears.
After the export process finishes, click Finish to close the window and to return to the Database Mi‑
gration Wizard.
Note:
• Depending on your database size, the export process can take from a few seconds to a few
minutes or even a few hours.
• If you close the Database Migration Status window when the database export is in
progress, you return to the Database Migration Wizard, but the Export button is disabled
because the database export process continues in the background. To stop the export
process completely, click Cancel.
If there are errors during export, check the Citrix WEM Migration Tool Debug Log file in the migration
tool folder that contains the Citrix WEM Migration Tool.exe.
Step 3: Upload the SQL file into your WEM service database
Important:
Do not close the Workspace Environment Management service page before the upload finishes.
Otherwise, your SQL file cannot be uploaded successfully.
1. On the WEM service Utilities tab, click Upload to start the upload process.
2. Click Choose File on the Upload SQL file page and then select the SQL file to be uploaded.
3. Click OK to start the upload and to return to the WEM service Utilities tab.
After you return to the WEM service Utilities tab, the progress message appears under Upload, which
updates as the upload progresses. After your SQL file is uploaded successfully, the migration process
starts automatically.
Note:
After your SQL file is uploaded successfully, you must wait 10 minutes before you can upload
again.
After migration
You receive a notification message a few hours later, communicating the result of the migration to
you. See notifications in the top‑right corner of the Citrix Cloud user interface. After the migration
completes successfully, perform the following steps on the Manage tab to view the data migrated
from your on‑premises WEM database.
Step 1: Load the migrated data into the WEM service console
5. Refresh your browser window to reconnect to the WEM service and to view the data migrated
from your on‑premises WEM database.
Use the agent switch feature to switch from on‑premises to service agent mode. For information about
the agent switch, see Agent Switch.
Important:
The agent switch feature is available in Workspace Environment Management 1909 and later. For
earlier versions, you must reinstall the agent or upgrade it to version 1909 or later before using
the agent switch.
Alternatively, you can download the agent from the service’s Utilities tab and then manually reinstall
the agent.
April 2, 2024
a) Download the agent from the Utilities tab of the WEM service.
b) Install the agent and configure Citrix Cloud Connectors during agent installation.
c) Restart the agent host to complete the installation.
a) In this console, select or create a configuration set to which you want to add the agent
host.
b) Navigate to Active Directory Objects > Users and then click Add to add a user or user
group.
c) Navigate to Active Directory Objects > Machines and then click Add OU or Add Object
to add the agent host.
Note:
If you have multiple configuration sets, you need to import recommended settings for each.
You can import Citrix‑recommended settings into your configuration set and then adjust and apply
them as needed. The recommended settings are provided with the WEM agent package. To download
the package, go to Citrix Cloud > WEM service > Utilities.
To import recommended settings, use Restore, available in the ribbon of the console. Before you start,
first upload default recommended settings into WEM. See Upload files.
1. Under the target configuration set, click Restore. The Restore wizard appears.
2. On the Select what to restore page, select Settings and then click Next.
5. On the Source page, select System Optimization Settings, Agent Configuration Settings,
and System Monitoring Settings, and then click Next.
Note:
The three options let you import all Citrix‑recommended settings. For example, the Sys‑
tem Optimization Settings option lets you apply basic system optimization settings to
the configuration set. Basic settings include CPU spike protection, auto‑preventing CPU
spikes, and intelligent CPU optimization.
6. On the Restore settings processing page, click Restore Settings to start the import.
8. Click Finish.
In addition to recommended settings, the WEM agent package also includes the following settings:
• Environment Lockdown Sample > VUEMEnvironmentalSettings. Use this file to import en‑
vironment settings. To do so, repeat the steps above, minding the following:
• Sample Applications > VUEMApplications. Use this file to import sample applications. To do
so, repeat the steps above, minding the following:
– On the Select what to restore page, select Actions and then click Next.
– On the Actions Selection page, select the actions you want to import.
– On the Restore actions processing page, click Restore Actions to start the import.
Ribbon
August 5, 2022
Configuration set. Switches from one Workspace Environment Management (WEM) site (configura‑
tion set) to another.
Site State. Toggles whether the site is Enabled or Disabled. When Disabled, WEM agents cannot con‑
nect to the site.
Edit. Opens the Edit configuration set window, with similar options to the Create configuration set
window.
Delete. Deletes the site. You cannot delete “Default site”because WEM relies on it to function. You
can, however, rename it.
Refresh. Refreshes the site list. The list does not refresh automatically when sites are created from
different administration consoles.
Backup. Opens the Backup wizard to save a backup copy of your current configuration to the WEM
administration console machine. You can back up actions, settings, security settings, and Active Di‑
rectory (AD) objects.
• Actions. Backs up selected WEM actions. Each type of action is exported as a separate XML file.
• Settings. Backs up selected WEM settings. Each type of setting is exported as a separate XML
file.
• Security Settings. Backs up all settings present on the Security tab. Each type of rule is ex‑
ported as a separate XML file. You can back up the following items associated with a configura‑
tion set:
• AD objects. Backs up the users, computers, groups, and organizational units that WEM man‑
ages. The Backup wizard lets you specify which type of AD objects to back up. There are two
types of AD objects:
Note:
You can name your backup copy, but you cannot specify the location where the backup
copy is saved. The backup copy is automatically saved to a default folder in Citrix Cloud.
• Configuration set. Backs up the WEM configuration set you selected. Each type of configura‑
tion set is exported as a separate XML file. You can back up only the current configuration set.
You can back up the following items associated with a configuration set:
– Actions
– AppLockers
– Assignments (related to actions and action groups)
– Filters
Restore. Opens the Restore wizard to revert to a previously backed up version of your WEM service
configuration. When prompted, select the applicable backup copy from the drop‑down list. Select a
Citrix Cloud folder containing the backup. You can also restore settings from a backup file.
• Security Settings. Restores all settings present on the Security tab. The settings in backup files
replace the existing settings in your current configuration set. When you switch to or refresh
the Security tab, invalid application security rules are detected. Those rules are automatically
deleted. Deleted rules are listed in a report that you can export if needed. The Restore wizard
lets you select what to restore:
In the Confirm Application Security Rule Assignment dialog, select Yes or No to indicate how
you want the Restore wizard to handle application security rule assignments:
– If you select Yes, restore attempts to restore rule assignments to users and user groups
in your current site. Reassignment succeeds only if the backed‑up users or groups are
present in your current site or AD. Any mismatched rules are restored but remain unas‑
signed, and they are listed in a report dialog which you can export in CSV format.
– If you select No, all rules in the backup are restored without being assigned to users and
user groups in your site.
• AD objects. Restores the backed‑up AD objects to the existing site. The Restore wizard gives
you granular control over AD objects to be imported. On the Select the AD objects you want
to restore page, you can specify which AD objects you want to restore and whether to overwrite
(replace) existing WEM AD objects.
• Configuration set. Restores the backed‑up configuration set to WEM. You can restore only one
configuration set at a time. It might take some time for the WEM administration console to re‑
flect the configuration set you restored. To view the restored configuration set, select it from the
Configuration set menu in the Ribbon. When restoring a configuration set, WEM automatically
renames it to <configuration set name>_1 if a configuration set with the same name
already exists.
Note:
Migrate. Opens the Migrate wizard to migrate a zip backup of your Group Policy Objects (GPOs) to
WEM.
Important:
• The Migrate wizard migrates only the settings (GPOs) that WEM supports.
• Citrix recommends that you back up your existing settings before you start the migration
process.
Citrix recommends that you perform the following steps to back up your GPOs:
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.
5. Navigate to the backup folder and then compress it into a zip file.
Note:
WEM also supports migrating zip files that contain multiple GPO backup folders.
After you back up your GPOs successfully, use Upload (available in the menu on the WEM service Man‑
age tab) to upload the zip file of your GPOs to the default folder in Citrix Cloud. After that completes
successfully, click Migrate. On the File to Migrate page, select the applicable file from the list. You
can also type the name of the file and then click Find to locate it.
• Overwrite. Overwrites existing WEM settings (GPOs) when there are conflicts.
• Convert. Converts your GPOs to XML files suitable for import to WEM. Select this option if you
want to have granular control over settings to be imported. After the conversion completes
successfully, use the Restore wizard to manually import the XML files.
Note:
You can name the output folder, but you cannot specify the names for the files to be saved.
Quick Start. Opens the quick‑start page that provides information necessary for you to get started
with the WEM service. Follow the on‑screen instructions to start configuring your WEM deployment.
Warning:
When you restore settings, the current settings in your Workspace Environment Management
service are overwritten.
The on‑premises Workspace Environment Management Backup wizard backs up the current config‑
uration set to a special XML format file. You can restore (apply) the settings in the file to the current
configuration set in your Workspace Environment Management service, using the following steps:
1. In the Workspace Environment Management service Manage tab, open the Citrix Workspace
app for the HTML5 session toolbar.
2. Use Upload to upload the XML backup file to a Citrix Cloud folder. The default folder is Default‑
UploadFolder.
3. Use the Workspace Environment Management service Restore wizard to restore from the Citrix
Cloud folder.
Actions
– Action Groups
– Group Policy Settings
– Applications
– Printers
– Network Drives
– Virtual Drives
– Registry Entries
– Environment Variables
– Ports
– Ini Files
– External Tasks
– File System Operations
– User DSN
– File Associations
• Filters
• Assignments
Action Groups
July 5, 2022
The action groups feature lets you first define a group of actions and then assign all the defined actions
in the action group to a user or user group in a single step. With this feature, you no longer have to
assign each action present in the Actions pane one by one. As a result, you can assign multiple actions
in a single step.
Tip:
You can use dynamic tokens to extend Workspace Environment Management actions to make
them more powerful.
Action groups
Displays a list of your existing action groups. Use Find to filter the list by name, display name, or
description.
Actions
Important:
• The action group includes only actions already present in each action category (applica‑
tions, printers, and network drives, and so on). For example, unless you have added appli‑
cations on the Application List tab, the action groups on the Action Group List tab do not
display any applications available for you to assign under Applications.
• If you configure the options for actions in an assigned action group (Action Group List >
Name > Configured), the configured options will not impact the users to which the action
group is assigned.
The Actions section displays the actions available to you. You can perform the following operations:
• Add. Lets you create an action group that contains all the actions you want to assign to a user
or user group.
• Edit. Lets you edit an existing action group.
• Copy. Lets you replicate an action group from an existing one.
• Delete. Lets you delete an existing action group.
1. On the Administration Console > Actions > Action Groups > Action Group List tab, click Add.
2. In the New Action Group window, type the required information, select the applicable option
from the dropdown, and then click OK.
To edit an action group, select the applicable group from the list and then click Edit.
To clone an action group, select the group you want to clone and then click Copy. Note that the clone
is automatically created after you click Copy. The clone inherits the name of the original and has a
suffix “‑Copy.”You can click Edit to change the name.
Note:
When you clone an action group, actions (if any) associated with the Network and Virtual Drives
are not cloned unless the Allow Drive Letter Reuse in assignment process option is enabled.
To enable that option, go to the Advanced Settings > Configuration > Console Settings tab.
To delete an action group, select the applicable group from the list and then click Delete.
Note:
If you delete or edit an action group that is already assigned, the changes you make will impact
all users to which the group is assigned.
Name. The display name of the action group, as it appears in the action group list.
Description. Lets you specify additional information about the action group.
Action Group State. Toggles the action group between enabled and disabled state. When disabled,
the agent does not process the actions included in the action group even if you assign that action
group to a user or user group.
Configuration
Lets you search for the specific action that you want to assign or you have configured. Use Find to
filter the option by name, display name, or description.
Available. These are the actions available to you to add to the action group you created.
Click the plus sign to expand the actions under the specific action category. Double‑click an action or
click the arrow buttons to assign or unassign it.
Note:
• If you add an action to an action group that is already assigned to users, the action will be
Configured. These are the actions already assigned to the action group you created. You can expand
individual actions to configure them. You can also configure the options for each specific action; for
example, application shortcut locations, default printers, drive letter, and so on.
Assignments
Important:
If you configure the options for actions in an assigned action group in the Assigned pane on the
Action Assignment tab, the configured options will automatically impact the users to which the
action group is assigned.
After you finish configuring the actions for the action group on the Actions > Action Groups > Action
Group List tab, you might want to assign the configured actions to the applicable user or user group.
To do so, go to the Assignments > Action Assignment > Action Assignment tab. On that tab, double‑
click a user or user group to see the Action Groups node in the Available pane that contains the action
groups you created. You can click the plus sign next to the Action Groups node to view the action
groups you created. Double‑click an action group or click the arrow buttons to assign or unassign it.
When you assign an action, you are prompted to select the rule you want to use to contextualize that
action.
When assigning action groups, there are several scenarios to be aware of:
Example scenario
For example, to use the action groups feature to assign two applications (iexplore.exe and calc.exe)
to a user at one time, follow the steps below.
1. Go to the Administration Console > Actions > Applications > Application List tab and then
add the applications (iexplore.exe and calc.exe).
2. Go to the Administration Console > Actions > Action Groups > Action Group List tab and then
click Add to create an action group.
3. On the Action Group List tab, double‑click the action group you created to display the action
list in the Available and Configured panes.
4. In the Available pane, double‑click each application to move it to the Configured pane. You
can also do so by selecting the application and then clicking the right arrow.
5. In the Configured pane, configure the options for each application. In this example, enable
Create Desktop and Pin To TaskBar.
6. Go to the Administration Console > Assignments > Action Assignment tab and then double‑
click the applicable user to display the action group in the Available and Assigned panes.
7. In the Available pane, double‑click the action group you created (in this example, Action group
1) to move it to the Assigned pane. You can also do so by selecting the action group and then
clicking the right arrow.
8. In the Assign Filter window, select Always True and then click OK.
9. Go to the Administration Console > Administration > Agents > Statistics tab and then click
Refresh.
10. Right‑click the agent and then select Refresh Workspace Agent(s) in the context menu.
11. On the machine where the agent is running (agent host), verify that the configured actions are
taking effect.
In this example, the two applications are successfully assigned to the agent host, and their shortcuts
are added to the desktop and pinned to the taskbar.
July 5, 2022
Important:
WEM service currently supports adding and editing only Group Policy settings associated with
the HKEY_LOCAL_MACHINE and the HKEY_CURRENT_USER registry hives.
In previous releases, you could migrate only Group Policy Preferences (GPP) into Workspace Environ‑
ment Management (WEM). For more information, see the description of the Migrate wizard in Ribbon.
You can now also import Group Policy settings (registry‑based settings) into WEM.
After importing the settings, you can have an itemized view of the settings associated with each GPO
before you decide which GPO to assign. You can assign the GPO to different AD groups, just like you
assign other actions. If you assign GPOs to an individual user directly, the settings do not take effect.
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.
Note:
For WEM agents to process Group Policy settings properly, verify that Citrix WEM User Logon Ser‑
vice is enabled on them.
Enable Group Policy Settings Processing. Controls whether to enable WEM to process Group Policy
settings. By default, this option is disabled. When disabled:
Displays a list of your existing GPOs. Use Find to filter the list by name or description.
Before importing Group Policy settings, back up your Group Policy settings on your domain
controller:
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.
5. Navigate to the backup folder and then compress it into a zip file.
Note:
WEM also supports importing zip files that contain multiple GPO backup folders.
1. Use Upload, available in the menu on the WEM service Manage tab, to upload the zip file of your
GPOs to the default folder in Citrix Cloud.
2. Navigate to the Administration Console > Actions > Group Policy Settings tab, select Enable
Group Policy Settings Processing, and then click Import to open the import wizard.
3. On the File to Import page of the import wizard, click Browse and then select the applicable
file from the list. You can also type the name of the file and then click Find to locate it.
5. After the import completes, click Finish. Imported GPOs appear on the Group Policy Settings
tab.
You can convert registry values that you export using the Windows Registry Editor into GPOs for man‑
agement and assignment. If you are familiar with the Import registry files option available with
Registry Entries, this feature:
• Lets you import registry values under both HKEY_LOCAL_MACHINE and HKEY_CURRENT_USER
.
• Lets you import registry values of the REG_BINARY and REG_MULTI_SZ types.
• 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.
• Import from a zip file. The zip file can contain one or more registry files. Make sure that the size
of the unzipped files is not greater than 30 M.
• 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.
• Descriptions of converted GPOs are empty. Their state defaults to enabled (check mark icon).
1. Use Upload to upload the zip backup of your registry files to the default folder in Citrix Cloud.
2. Go to Legacy Console > Actions > Group Policy Settings, select Enable Group Policy Settings
Processing, click the down arrow next to Import, and select Import Registry File.
3. In the wizard that appears, select the file from the list. You can also type the name of the file
and then click Find to locate it.
• Overwrite existing GPOs. Controls whether to overwrite existing GPOs when conflicts
occur.
5. After the import completes, click Finish. GPOs converted from the registry files appear in Group
Policy Settings.
Double‑click a GPO from the list for an itemized view of its settings and to edit the settings if needed.
To clone a GPO, right‑click the GPO and select Copy from the menu. The clone is automatically created
after you click Copy. The clone inherits the name of the original and has a suffix “‑Copy.”You can use
Edit to change the name.
The Edit Group Policy Object window appears after you click Edit.
Description. Lets you specify additional information about the GPO, which appears in the GPO list.
Warning:
Editing, adding, and deleting registry‑based settings incorrectly can prevent the settings from
taking effect in the user environment.
To add a registry key, click Add on the right‑hand side. The following settings become available:
• Order. Lets you specify the order of deployment for the registry key.
• 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.
• 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.
• Value. Lets you specify a name for the registry value. The highlighted item in the following
diagram as a whole is a registry value.
• 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 sys‑
tem.
– REG_BINARY. Binary data in any form.
– REG_DWORD. A 32‑bit number. This type is commonly used for Boolean values. For ex‑
ample, “0”means disabled and “1”means enabled.
– REG_DWORD_LITTLE_ENDIAN. A 32‑bit number in little‑endian format.
• Data. Lets you type data corresponding to the registry value. For different data types, you might
need to type different data in different formats.
Your changes might take some time to take effect. Keep the following in mind:
• Changes associated with the HKEY_LOCAL_MACHINE registry hive take effect when Citrix
WEM Agent Host Service starts or the specified SQL Settings Refresh Delay times out.
• Changes associated with the HKEY_CURRENT_USER registry hive take effect when users log
on.
You can make Group Policy settings conditional by using a filter to contextualize their assignments.
A filter comprises a rule and multiple conditions. The WEM agent applies the assigned Group Policy
settings only when all conditions in the rule are met in the user environment at runtime. Otherwise,
the agent skips those settings when enforcing filters.
1. In the administration console, navigate to Filters > Conditions and define your conditions. See
Conditions.
Important:
For a complete list of filter conditions available, see Filter conditions. Group Policy settings
comprise user and machine settings. Some filter conditions apply only to user settings.
If you apply those filter conditions to machine settings, the WEM agent ignores the filter
conditions and applies the machine settings. For a complete list of filter conditions that
do not apply to machine settings, see Filter conditions not applicable to machine settings.
2. Navigate to Filters > Rules and define your filter rule. You can include the conditions you de‑
fined in Step 1 into that rule. See Rules.
3. Navigate to Actions > Group Policy Settings and configure your Group Policy settings.
4. Navigate to Administration Console > Assignments > Action Assignment and complete the
following:
a) Double‑click the user or user group to which you want to assign the settings.
b) Select the application and click the right arrow (>) to assign them.
c) In the Assign Filter window, select the rule you defined in Step 2 and then click OK. The
settings move from the Available pane to the Assigned pane.
d) In the Assigned pane, configure priority for the settings. Type an integer to specify a
priority. The greater the value, the higher the priority. Settings with higher priority are
processed later, ensuring that they are in effect when there is a conflict or dependency.
ClientName Match No
Client IP Address Match No
Registry Value Match If you configure a registry value starting with
HKCU, the Registry Value Match filter does not
work if applied to machine settings.
User Country Match No
User UI Language Match No
User SBC Resource Type No
Active Directory Path Match No
Active Directory Attribute Match No
No ClientName Match No
No Client IP Address Match No
No Registry Value Match No
No User Country Match No
No User UI Language Match No
No Active Directory Path Match No
No Active Directory Attribute Match No
Client Remote OS Match No
No Client Remote OS Match No
Active Directory Group Match No
No Active Directory Group Match No
Published Resource Name No
Applications
April 2, 2024
Tip:
• You can use the Full Configuration management interface of Citrix DaaS to edit the appli‑
cation settings and then add an executable file path that points to VUEMAppCmd.exe.
VUEMAppCmd.exe ensures that the Workspace Environment Management agent finishes
processing an environment before Citrix DaaS (formerly Citrix Virtual Apps and Desktops
service) and Citrix Virtual Apps and Desktops published applications are started. For more
information, see Editing application settings using the Full Configuration management
interface.
• You can use dynamic tokens to extend Workspace Environment Management actions to
make them more powerful.
Application list
Displays a list of your existing application resources. You can use Find to filter the list by name or ID.
1. Go to the Administration Console > Actions > Applications > Application List tab, click Add.
Alternatively, right‑click the blank area and then select Add in the context menu. The New Ap‑
plication window appears.
a) On the General tab, type the required information and select an application type as
needed.
b) On the Options tab, add an icon for the application and configure settings as needed.
c) On the Advanced Settings tab, configure more options for the application.
a) Double‑click the user or user group to which you want to assign the application.
b) Select the application and click the right arrow (>) to assign it.
c) In the Assign Filter window, select Always True and then click OK. The application moves
from the Available pane to the Assigned pane.
d) In the Assigned pane, configure one or more of the following options for the application:
Create Desktop, Create Quick Launch, Create Start Menu, Pin To TaskBar, Pin To Start
Menu, and Auto Start.
The assignment might take some time to take effect, depending on the value you specified for SQL
Settings Refresh Delay on the Advanced Settings > Configuration > Service Options tab. Perform
the following steps for the assignment to take effect immediately if needed.
1. Go to the Administration Console > Administration > Agents > Statistics tab and then click
Refresh.
2. Right‑click the agent and then select Refresh Workspace Agent(s) in the context menu.
Name. The display name of the application shortcut, as it appears in the application list.
Application Type. The type of application the shortcut opens. The user interface differs depending
on your selection.
• Installed application. Lets you create a shortcut that opens an application installed on the
user’s machine. If selected, prompts you to complete the following:
– Command Line. Type the full path of the application that resides on the user’s machine.
Click Browse to see the listed applications and to understand the file path format.
– Working Directory. Type the full path to a folder on the user’s machine as a working folder
for the application. This field populates automatically after you type the full path in the
Command Line field.
– Parameters. Type launch parameters for the application if needed.
• File/Folder. Lets you create a shortcut that opens the target file or folder on the user’s machine
when a user clicks the shortcut icon. If selected, prompts you to complete the following:
Note:
While using a non‑domain‑joined agent, Application Type such as, File/Folder in WEM
might not work, if the Target is a network share.
• URL. Lets you add the URL of an application. If selected, prompts you to complete the following:
• StoreFront store. Lets you add an application that is based on a StoreFront store. If selected,
prompts you to complete the following:
– Store URL. Type the URL of a StoreFront store containing the resource you want to start
from the shortcut.
– Store Resource. Add the resource (available from the StoreFront store) that you want to
start from the shortcut. Click Browse to browse and select the resource.
Tip:
To add an application based on a StoreFront store, you must provide valid credentials. A
dialog appears the first time you click Browse to view store resources. The dialog prompts
you to type credentials that you use to log on to Citrix Workspace app for Windows. After
that, the Store Resources window appears, displaying a list of published applications re‑
trieved by Citrix Workspace app for Windows running on the WEM administration console
machine.
Start Menu Integration. Lets you specify where to create the application shortcut on the left side of
the Start menu. By default, a new shortcut is created in Programs. To create a custom folder for a
shortcut, perform these steps:
1. Click Select path to open the Start Menu Path Selection window.
2. In that window, right‑click Programs and click Add from the context menu. The Create New
Start Menu Folder window appears.
Icon File. Lets you add an icon for the application. Click Select Icon to type the full path for the icon
file you uploaded, select the path from the list, and then click Load. For more information, see To
select an icon. Icons are stored in the database as strings.
• High Resolution Icons Only. Displays only high‑definition icons in the list.
Application State. Controls whether the application shortcut is enabled. When disabled, the agent
does not process it even if it is assigned to a user.
• Maintenance Mode. When enabled, prevents users from running the application shortcut. The
shortcut icon contains a warning sign to indicate that the shortcut is unavailable. If users click
the shortcut, a message appears, notifying them that the application is unavailable. This op‑
tion lets you proactively manage scenarios where published applications are in maintenance
without disabling or deleting those application shortcuts.
Display Name. The name of the shortcut, as it appears in the user environment.
Hotkey. Lets you specify a hotkey for the user to launch the application with. Hotkeys are case sensi‑
tive and typed in the following format (for example): Ctrl + Alt + S.
Enable Automatic Self‑Healing. When selected, the agent automatically recreates application short‑
cuts on refresh if the user has moved or deleted them.
Enforce Icon Location. Lets you specify the exact location of the application shortcut on the user’s
desktop. Values are in pixels.
Windows Style. Controls whether the application opens in a minimized, normal, or maximized win‑
dow on the user’s machine.
Do Not Show in Self‑Services. Hides the application from the agent menu (self‑service interface)
accessible from the user’s machine. Users open the agent menu by right‑clicking the agent icon in
the taskbar when the session agent is running in UI mode. If selected, hides the application from both
the My Applications menu and the Manage Applications dialog.
Tip:
The Enable Application Shortcuts option controls whether the My Applications option is avail‑
able in the agent menu. The option is available from the Administration Console > Advanced
Settings > UI Agent Personalization > UI Agent Options tab. For more information, see UI
Agent Personalization.
Create Shortcut in User Favorites Folder. Creates an application shortcut in the user’s Favorites
folder.
Displays a tree view of your application shortcut resource locations in the Start menu.
Move. Opens up a wizard which allows you to select a location to move the application shortcut to.
Application launcher
Application launcher aggregates all applications you assigned to your users through the administra‑
tion console. Using the tool, users can launch all assigned applications in one place.
Tip:
Your users can directly open the application launcher tool (AppLauncherUtil.exe) in their environment.
The tool is available in the agent installation folder: %ProgramFiles%\Citrix\Workspace
Environment Management Agent\ AppLauncherUtil.exe. After opening the tool, users
see the following, reflecting the applications assigned to them:
• All apps. Shows all assigned applications. Available sorting options: Most recent, A‑Z, and Z‑A.
• Ellipsis icon. There is a Sign out option that lets users sign out of their sessions.
Make sure that the assigned applications are present on the agent machine. If an assigned application
is not installed on the agent machine, the application is shown but unavailable for launch.
For an example of how to use this feature, see Aggregate assigned applications in one place.
To select an icon
1. Hover the mouse cursor over the menu on the Manage tab of the WEM service.
3. Click the upload icon to upload the applicable icon file to a Citrix Cloud folder.
Note:
We do not retain the icon file for later use. We might delete the file when the file count limit
is reached. If necessary, save a local copy of the file. For more information about the file
count limit, see Upload files.
4. On the Administration Console > Actions > Applications > Application List tab, click Add.
5. In the New Application window, go to the Options tab and then click Select Icon.
6. In the Icon Selector window, type the full file path for the icon file you uploaded, se‑
lect the path from the drop‑down list, and then click Load. The default folder path is
C:\DefaultUploadFolder\. You must type the full file path in the following format:
C:\DefaultUploadFolder\iconname. For example:
• C:\DefaultUploadFolder\iconname.ico
• C:\DefaultUploadFolder\iconname.exe
7. In the Icon Selector window, select the applicable icon and then click OK.
Workspace Environment Management (WEM) provides you with client‑side tools to troubleshoot
issues you experience. The VUEMAppCMD tool (VUEMAppCmd.exe) ensures that the WEM agent fin‑
ishes processing an environment before published applications are started. It is located in the agent
installation folder: %ProgramFiles%\Citrix\Workspace Environment Management
Agent\VUEMAppCmd.exe.
Note:
You can use the Full Configuration management interface to edit the application settings and then add
an executable file path that points to VUEMAppCmd.exe. To do so, complete the following steps:
1. On the Application node, select the application, click Properties in the action bar, and then go
to the Location page.
2. In the Path to the executable file field, type the path for VUEMAppCmd.exe.
3. Type the path for the application to be launched in the command‑line argument field.
• Type the full path to the application that you want to launch through VUEMAppCmd.exe.
Make sure that you wrap the command line for the application in double quotes if the path
contains blank spaces.
• For example, suppose you want to launch iexplore.exe through VUEMAppCmd.exe.
You can do so by typing the following: "%ProgramFiles%\Internet Explorer\
iexplore.exe".
Printers
July 5, 2022
Tip:
You can use dynamic tokens to extend Workspace Environment Management actions to make
them more powerful.
A list of your existing printer resources, with unique IDs. You can use Find to filter your printers list by
name or ID.
Note:
• The WEM service currently does not support importing printers using Import Network
Print Server on the ribbon.
• After Windows Update installs KB5005033 on an agent machine, assigned printers do not
work. The issue occurs because the update prevents the automatic start of the Windows
Print Spooler service. As a workaround, start the service manually.
To add a printer
1. On the Network Printer List tab, click Add or right‑click the blank area and then select Add in
the context menu.
2. In the New Network Printer window, type the required information and then click OK.
Name. The display name of the printer, as it appears in the printer list.
Description. This field is only shown in the edition/creation wizard and allows you to specify addi‑
tional information about the resource.
Target Path. The path to the printer as it resolves in the user’s environment.
Printer State. Toggles whether the printer is enabled or disabled. When disabled, it is not processed
by the agent even if assigned to a user.
External Credentials. Allows you to state specific credentials with which to connect to the printer.
Self‑Healing. Toggles whether the printer is automatically recreated for users when the agent re‑
freshes.
Action Type. Describes what type of action this resource is. For Use Device Mapping Printers File,
specify Target Path as the absolute path to an XML printer list file (see XML printer list configuration).
When the agent refreshes it parses this XML file for printers to add to the action queue.
Network Drives
July 5, 2022
Tip:
You can use dynamic tokens to extend Workspace Environment Management actions to make
them more powerful.
A list of your existing network drives. You can use Find to filter the list by name or ID against a text
string.
Name. The display name of the drive, as it appears in the network drive list.
Description. This field is only shown in the edition/creation wizard and allows you to specify addi‑
tional information about the resource.
Target Path. The path to the network drive as it resolves in the user’s environment.
Network Drive State. Toggles whether the network drive is enabled or disabled. When disabled, it is
not processed by the agent even if assigned to a user.
External Credentials. Allows you to state specific credentials with which to connect to the network
drive.
Enable Automatic Self‑Healing. Toggles whether the network drive is automatically recreated for
your users when the agent refreshes.
Action Type. Describes what type of action this resource is. Defaults to Map Network Drive.
Virtual Drives
December 5, 2023
Controls the mapping of virtual drives. Virtual drives are Windows virtual drives or MS‑DOS device
names that map local file paths to drive letters.
Tip:
You can use dynamic tokens to extend Workspace Environment Management actions to make
them more powerful.
Displays a list of your existing virtual drives. You can use Find to filter the list by name or ID.
1. Go to the Administration Console > Actions > Virtual Drives > Virtual Drives List tab, click
Add. Alternatively, right‑click the blank area and then select Add in the context menu. The New
Virtual Drive window appears.
a) On the General tab, type the required information and select whether to set the virtual
drive as a home drive.
b) Click OK to save changes and to exit the New Virtual Drive window.
a) Double‑click the user or user group to which you want to assign the virtual drive.
b) Select the virtual drive and click the right arrow (>) to assign it.
c) In the Assign Filter & Driver Letter window, select Always True, select a driver letter,
and then click OK. (Select the asterisk (*) character instead of a specific letter if you want
to assign the next available drive letter to the virtual drive.) The virtual drive moves from
the Available pane to the Assigned pane.
The assignment might take some time to take effect, depending on the value you specified for SQL
Settings Refresh Delay on the Advanced Settings > Configuration > Service Options tab. Perform
the following steps for the assignment to take effect immediately if needed.
1. Go to the Administration Console > Administration > Agents > Statistics tab and then click
Refresh.
2. Right‑click the agent and then select Refresh Workspace Agent(s) in the context menu.
The General tab Name. The display name of the drive, as it appears in the virtual drive list.
Description. Lets you specify additional information about the virtual drive. The information appears
only in the edition or creation wizard.
Target Path. Type the path to the virtual drive as it resolves in the user’s environment.
Note:
While using a non‑domain‑joined agent, WEM might not work if the Target Path is a network
share.
Virtual Drive State. Toggles whether the virtual drive is enabled or disabled. When disabled, the
agent does not process it even if it is assigned to a user.
Set as Home Drive. Lets you choose whether to set it as a home drive.
The Options tab Action Type. Describes what type of action this resource is.
Registry Entries
July 5, 2022
Tip:
You can use dynamic tokens to extend Workspace Environment Management actions to make
them more powerful.
A list of your existing registry entries. You can use Find to filter the list by name or ID against a text
string.
Name. The display name of the registry entry, as it appears in the registry entry list.
Description. This field is only shown in the edition/creation wizard and allows you to specify addi‑
tional information about the resource.
Registry Value State. Toggles whether the registry entry is enabled or disabled. When disabled, it
will not be processed by the agent even if assigned to a user.
Target Path. The registry location in which the registry entry will be created. Workspace Environment
Management can only create Current User registry entries, so you do not need to preface your value
with %ComputerName%\HKEY_CURRENT_USER –this is done automatically.
Target Name. The name of your registry value as it appears in the registry (for example, NoNtSecu‑
rity).
Target Value. The value of the registry entry once created (for example, 0 or C:\Program Files)
Run Once. By default, Workspace Environment Management creates registry entries every time the
agent refreshes. Select this check box to make Workspace Environment Management create the reg‑
istry entry only once ‑ on the first refresh ‑ rather than on every refresh. This speeds up the agent
refresh process, especially if you have many registry entries assigned to your users.
You can convert your registry file into registry entries for assignment. This feature has the following
limitations:
• It supports only registry values under HKEY_CURRENT_USER. With the registry entries feature,
you can assign only registry settings under HKEY_CURRENT_USER.
• It does not support registry values of the REG_BINARY and REG_MULTI_SZ types.
To avoid the limitations, we recommend that you import your registry files to WEM by using the Im‑
port Registry File option in Group Policy Settings. For more information, see Import Group Policy
settings from registry files.
1. Use Upload to upload the registry file you want to import. The file appears in the default folder
in Citrix Cloud.
4. In the Import from Registry File window, select the desired registry file from the list. You can
also start typing the file name and then click Find to locate it.
5. Click Scan to start scanning the registry file. After the scan completes successfully, a list of reg‑
istry settings appears.
6. Select the registry settings that you want to import and then click Import Selected to start the
import process.
7. Click OK to exit.
Registry File Name. Populates automatically after you navigate to a .reg file and click Open. The
.reg file contains registry settings you want to import into WEM. The .reg file must be generated from
a clean environment to which only the registry settings you want to import are applied.
Scan. Scans the .reg file and then displays a list of registry settings that the file contains.
Registry Values List. Lists all registry values that the .reg file you want to import contains.
Enable Imported Items. If disabled, newly imported registry keys are disabled by default.
Prefix Imported Item Names. If selected, adds a prefix to the name of all registry items imported
through this wizard (for example, “XP ONLY”or “finance”). Doing so makes it easier to identify and
organize your registry entries.
Note:
The wizard cannot import registry entries with the same names. If your .reg file contains more
than one registry entry that has the same name (as displayed in the Registry Values List), select
one of those entries for import. If you want to import the others, rename them.
Environment Variables
You can use dynamic tokens to extend Workspace Environment Management actions to make
them more powerful.
A list of your existing environment variables. You can use Find to filter the list by name or ID against a
text string.
Name. The display name of the variable, as it appears in the environment variable list.
Description. This field is only shown in the edition/creation wizard and allows you to specify addi‑
tional information about the resource.
Environment Variable State. Toggles whether the environment variable is enabled or disabled.
When disabled, it is not processed by the agent even if assigned to a user.
Execution order.
Ports
The Ports feature allows client COM and LPT port mapping. You can also use Citrix Studio policies to
enable automatic connection of COM ports and LPT ports. For more information, see Port redirection
policy settings.
If you use the Ports feature to manually control the mapping of each port, remember to enable the
Client COM port redirection or the Client LPT port redirection policies in Citrix Studio. By default, COM
port redirection and LPT port redirection are prohibited.
Tip:
You can use dynamic tokens to extend Workspace Environment Management actions to make
them more powerful.
Ports list
A list of your existing ports. You can use Find to filter the list by name or ID.
To add a port
Name. The display name of the port, as it appears in the port list.
Description. Appears only in the edition/creation wizard and allows you to specify additional infor‑
mation about the resource.
Port State. Toggles whether the port is enabled or disabled. When disabled, it is not processed by
the agent even if assigned to a user.
Options tab Action Type. Describes what type of action this resource performs.
Ini Files
Controls the creation of .ini file operations, allowing you to modify .ini files.
Tip:
You can use dynamic tokens to extend Workspace Environment Management actions to make
them more powerful.
A list of your existing .ini file operations. You can use Find to filter the list by name or ID against a text
string.
Name. The display name of the .ini file operation, as it appears in the Ini File Operations list.
Description. This field is only shown in the edition/creation wizard and allows you to specify addi‑
tional information about the resource.
.ini File Operation State. Toggles whether the .ini file operation is enabled or disabled. When dis‑
abled, it is not processed by the agent even if assigned to a user.
Target Path. Specifies the location of the .ini file that will be modified as it resolves in the user’s
environment.
Note:
While using a non‑domain‑joined agent, WEM might not work if the Target Path is a network
share.
Target Section. Specifies which section of the .ini file this operation targets. If you specify a non‑
existent section, then it will be created.
Target Value Name. Specifies the name of the value that will be added.
Run Once. By default, Workspace Environment Management performs an .ini file operation every
time the agent refreshes. Select this checkbox to make the Workspace Environment Management
perform the operation only once, rather than at every refresh. This operation speeds up the agent
refresh process, especially if you have many .ini file operations assigned to your users.
External Tasks
December 5, 2023
Controls the execution of external tasks. External tasks include running scripts and applications as
long as the agent host has the corresponding programs to run them. Commonly used scripts include:
.vbs and .cmd scripts.
With the external tasks feature, you can specify when to run an external task. Doing so lets you more
effectively manage user environments.
Tip:
You can use dynamic tokens to extend Workspace Environment Management actions to make
them more powerful.
A list of your existing external tasks. You can use Find to filter the list.
Name. Lets you specify the display name of the external task, which appears in the external task list.
Description. Lets you specify additional information about the external task.
Path. Lets you specify the path to the external task. The path resolves in the user environment. Make
sure that:
• The path you specified here is consistent with the agent host.
• The agent host has the corresponding program to run the task.
Arguments. Lets you specify launch parameters or arguments. You can type a string. The string con‑
tains arguments to pass to the target script or application. For examples to use the Path and Argu‑
ments fields, see External task examples.
Note:
While using a non‑domain‑joined agent, WEM might not work if network share is used in Path or
Arguments.
External Task State. Controls whether the external task is enabled or disabled. When disabled, the
agent does not process the task even if the task is assigned to users.
Run Hidden. If selected, the task runs in the background and is not displayed to users.
Run Once. If selected, WEM runs the task only once regardless of which options you select on the
Triggers tab and regardless of whether agents restart. By default, this option is selected.
Execution Order. Lets you specify the running order of each task. The option can be useful when you
have multiple tasks assigned to users and some of those tasks rely on others to run successfully. By
default, the value is 0. 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 Completion. Lets you specify how long the agent waits for the task to complete. By
default, the Wait Timeout value is 30 seconds.
Action Type. Describes what type of action the external task is.
User session triggers. This feature lets you configure the following session activities as triggers for
external tasks:
• Refresh. Controls whether to run the external task when users refresh the agent. By default,
the option is selected.
• Reconnect. Controls whether to run the external task when a user reconnects to a machine on
which the agent is running. By default, the option is selected. If the WEM agent is installed on a
physical Windows device, this option is not applicable.
• Logon. Controls whether to run the external task when users log on. By default, the option is
selected.
• Logoff. Controls whether to run the external task when users log off. This option does not work
unless Citrix User Logon Service is running. By default, the option is not selected.
• Disconnect. Controls whether to run the external task when a user disconnects from a machine
on which the agent is running. By default, the option is not selected.
• Lock. Controls whether to run the external task when a user locks a machine on which the agent
is running. By default, the option is not selected.
• Unlock. Controls whether to run the external task when a user unlocks a machine on which the
agent is running. By default, the option is not selected.
When using disconnect, lock, and unlock options, consider the following constraints:
• The implementation of these options is based on Windows events. In some environments, these
options might not work as expected. For example, in desktops running on Windows 10 or Win‑
dows 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 options with the UI agent. Two reasons:
– When you use the options 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.
User process triggers. This feature lets you configure user processes as triggers for external tasks. Us‑
ing this feature, 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 exter‑
nal tasks lets you manage your user environments more precisely compared with processing external
tasks on logon or logoff.
• Before you use this feature, verify that the following prerequisites are met:
• Run when processes start. Controls whether to run the external task when specified processes
start.
• Run when processes end. Controls whether to run the external task when specified processes
end.
Troubleshooting
After you enable the feature, the WEM agent creates a log file named Citrix WEM Agent Logoff
.log the first time a user logs off. The log file is located in a user’s profile root folder. The WEM agent
writes information to the log file every time the user logs off. The information helps you monitor and
troubleshoot issues related to external tasks.
• If neither the folder path nor the script name contains blank spaces:
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 is run 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.
December 5, 2023
Controls the copying of folders and files into the user’s environment.
Tip:
You can use dynamic tokens to extend Workspace Environment Management actions to make
them more powerful.
A list of your existing file and folder operations. You can use Find to filter the list by name or ID against
a text string.
Name. The display name of the file or folder operation, as it appears in the list.
Description. Lets you specify additional information about the resource. This field appears only in
the edition or creation wizard.
Filesystem Operation State. Controls whether the file system operation is enabled or disabled.
When disabled, it is not processed by the agent even if assigned to a user.
Source Path. The path to the source file or folder that is copied.
Target Path. The destination path for the source file or folder that is copied.
Note:
While using a non‑domain‑joined agent, WEM might not work if network share is used in Source
Path or Target Path.
Overwrite Target if Existing. Controls whether the file or folder operation overwrites existing files or
folders with the same names in the target location. If cleared, and a file or folder with the same name
already exists at the target location, the affected files are not copied.
Run Once. By default, Workspace Environment Management runs a file system operation every time
the agent refreshes. Select this option to let Workspace Environment Management run the operation
only once, rather than on every refresh. This speeds up the agent refresh process, especially if you
have many file system operations assigned to your users.
Action Type. Describes what type of action this file or folder action is: Copy, Delete, Move,
Rename, or Symbolic Link operation. For symbolic link creation, you need to give users the
SeCreateSymbolicLinkPrivilege privilege for Windows to allow symbolic link creation.
Execution order. Determines the running order of operations, letting certain operations run before
others. Operations 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.
User DSN
You can use dynamic tokens to extend Workspace Environment Management actions to make
them more powerful.
A list of your existing user DSNs. You can use Find to filter the list by name or ID against a text string.
Name. The display name of the user DSN, as it appears in the user DSN list.
Description. This field is only shown in the edition/creation wizard and allows you to specify addi‑
tional information about the resource.
User DSN State. Toggles whether the user DSN is enabled or disabled. When disabled, it will not be
processed by the agent even if assigned to a user.
Driver. The DSN driver. At present, only SQL server DSNs are supported.
Server Name. The name of the SQL server to which the user DSN is connecting.
Database Name. The name of the SQL database to which the user DSN is connecting.
Connect Using Specific Credentials. Allows you to specify credentials with which to connect to the
server/database.
Run Once. By default, Workspace Environment Management will create a user DSN every time the
agent refreshes. Tick this box to make Workspace Environment Management only create the user
DSN once, rather than at every refresh. This speeds up the agent refresh process, especially if you
have many DSNs assigned to your users.
File Associations
Important:
File type associations that you configure become default associations automatically. However,
when you open an applicable file, the “How do you want to open this file?”window might still
appear, prompting you to select an application to open the file. Click OK to dismiss the window.
If you do not want to see a similar window again, do the following: Open the Group Policy Editor
and enable the Do not show the ‘new application installed’notification policy (Computer
Configuration > Administrative Templates > Windows Components > File Explorer).
Tip:
You can use dynamic tokens to extend Workspace Environment Management actions to make
them more powerful.
A list of your existing file associations. You can use Find to filter the list by name or ID.
Name. The display name of the file association, as it appears in the file association list.
Description. This field is only shown in the edition/creation wizard and allows you to specify addi‑
tional information about the resource.
File Association State. Toggles whether the file association is Enabled or Disabled. When disabled,
it is not processed by the agent even if assigned to a user.
File Extension. The extension used for this file type association. If you select a file name extension
from the list, the ProgID field automatically populates (if the file type is present on the machine where
the administration console is running). You can also type the extension directly. However, for browser
associations, you must type the extension directly. For more information, see Browser association.
ProgID. The programmatic identifier associated with an application (COM). This value automatically
populates when you select a file extension from the list. You can also type the ProgID directly. To
discover the ProgID of an installed application, you can use the OLE/COM Object Viewer (oleview.exe),
and look in Object Classes/Ole 1.0 Objects. For more information about ProgID, see Programmatic
identifier (ProgID).
Action. Lets you select the action type: open, edit, or print.
Target application. Lets you specify the executable used with this file name extension. Type the
full path of the executable. For example, for UltraEdit Text Editor: C:\Program Files\IDM
Computer Solutions\UltraEdit\uedit64.exe
Command. Lets you specify action types that you want to associate with the executable. For exam‑
ple:
Set as Default Action. Toggles whether the association is set as a default for that file name exten‑
sion.
Overwrite. Toggles whether this file association overwrites any existing associations for the specified
extension.
Run Once. By default, Workspace Environment Management (WEM) creates a file association every
time the agent refreshes. Select this option to create the file association once, rather than on every re‑
fresh. This speeds up the agent refresh process, especially if you have many file associations assigned
to your users.
For example, to add a new file type association for text (.txt) files for users to automatically open text
files with the program you selected (here, iexplore.exe), complete the following steps.
1. On the Administration Console > Actions > File Associations > File Association List tab, click
Add.
2. In the New File Association window, type the information and then click OK.
4. Double‑click the user or user group to which you want to assign the action.
5. Go to the Administration Console > Administration > Agents > Statistics tab and then click
Refresh.
6. Right‑click the agent and then select Refresh Workspace Agent(s) in the context menu.
7. Go to the machine on which the agent is running (user environment) to verify that the created
file type association works.
In this example, if you double‑click a file with a .txt extension in the end‑user environment, that file
automatically opens in Internet Explorer.
Good to know
Browser association
• Google Chrome
• Firefox
• Opera
• Internet Explorer (IE)
• Microsoft Edge
• Microsoft Edge Chromium
Note:
• To ensure that browser association for Google Chrome works, verify that the browser
on the agent host is installed by an administrator. Otherwise, log on to the machine
as an administrator and reinstall the browser. This is necessary because if the browser
is installed by a user (non‑administrator) the ProgID is ChromeHTML.<X> rather than
ChromeHTML. “X”denotes the Globally Unique Identifier (GUID) specific to the user, for
example JLKDKPPE7UYB4JTWJS73YQWTD4.
• Browser association for Microsoft Edge works only with the built‑in, default instance of Mi‑
crosoft Edge included in your particular version of the Windows 10 operating system. If you
upgrade the browser to a more recent version, the configured association does not take
effect. For a workaround, see Knowledge Center article CTX269675.
You no longer have to fill out the following fields: Action, Target application, and Command. You
can leave the fields empty as long as you can provide the correct ProgID. See below a list of ProgIDs
for popular applications:
However, you must fill out the fields (Action, Target application, and Command) if:
More information
For an example of how to configure file type associations, see Configure file type associations.
Filters
Rules
Rules are composed of multiple conditions. You use rules to define when an action is assigned to a
user.
A list of your existing rules. You can use Find to filter the list by name or ID against a text string
Name. The display name of the rule, as it appears in the rule list.
Description. This field is only shown in the edition/creation wizard and allows you to specify addi‑
tional information about the rule.
Filter Rule State. Toggles whether the rule is enabled or disabled. When disabled, the agent does
not process actions using this rule even if they are assigned.
Available Conditions. These are the filter conditions available to be added to the rule. Note. The
DateTime filter expects results in the format: YYYY/MM/DD HH:mm
Multiple values can be separated with semicolons (;) and ranges can be separated with hyphens. When
specifying a range between two times on the same date, the date should be included in both ends of
the range, e.g.: 1969/12/31 09:00‑1969/12/31 17:00
Configured Conditions. These are the conditions already added to the rule.
Note:
These conditions are AND statements, not OR statements. Adding multiple conditions requires
them all to trigger for the filter to be considered triggered.
Conditions
Conditions are specific triggers which allow you to configure the circumstances under which the agent
acts to assign a resource to a user.
A list of your existing conditions. You can use Find to filter the list by name or ID against a text string.
Name. The display name of the condition, as it appears in the condition list and in the rule cre‑
ation/edition wizard.
Description. This field is only shown in the edition/creation wizard and allows you to specify addi‑
tional information about the condition.
Filter Condition State. Toggles whether the filter is enabled or disabled. When disabled, it will not
appear in the rule creation/edition wizard.
Filter Condition Type. The type of filter condition type to use. See Filter conditions. Note: rules using
the Always True condition will always trigger.
Settings. These are the specific settings for individual conditions. See Filter conditions.
Note:
• When entering an IP address, you can either specify individual addresses or ranges.
• If you specify a range, both bounds must be specified in full. Use the dash character
(‑) to separate IP range bounds (e.g. 192.168.10.1‑192.168.10.5). Separate multiple
ranges or addresses using the semicolon character (;) . For example, 192.168.10.1‑
192.168.10.5;192.168.10.8‑192.168.10;192.168.10.17 is a valid value which includes
the ranges .1‑.5 and .8‑.10, plus the individual address .17.
Assignments
Tip:
Before assigning actions to users, perform the following steps in the order given:
Use assignments to make actions available to your users. This lets you replace a portion of your users’
logon scripts.
Action assignment
Users
This is your list of configured users and groups (see Users in Active Directory Objects). Double‑click a
user or group to populate the assignments menu. Use Find to filter the list by name or ID.
Tip:
To simplify assigning actions for all users in Active Directory, use the “Everyone”default group to
assign the actions. The actions that you assign to the “Everyone”default group do not appear on
the Resultant Actions tab in the Actions Modeling Wizard for an individual user. For example,
after you assign action1 to the “Everyone”default group, you might find that action1 does not
appear on the Resultant Actions tab.
Assignments
Lets you assign actions to the selected user or group. Use Find to filter the list by name or ID.
Available. Displays actions available for you to assign to this user or group.
Double‑click an action or click the arrow buttons to assign or unassign it. When you assign an action,
you are prompted to select a rule to contextualize it.
Note:
WEM supports automatically assigning the next available drive letter to a network drive. When
assigning a network drive, select the asterisk (*) character in the Assign Filter & Drive Letter win‑
dow to let WEM automatically assign the next available drive letter (whatever drive letter avail‑
able) to that network drive.
Assigned. Displays actions already assigned to this user or group. You can expand individual actions
to configure them (application shortcut locations, default printers, drive letter, and so on).
1. In the Users list, double‑click a user or group. This populates the Assignments lists.
2. In the Available list, select an action and click the right‑arrow (>) button.
3. In the Assign Filter dialog, select a Filter Rule and click OK.
4. In the Assigned list, use the Enable and Disable context actions to fine‑tune the behavior of
the assignment.
Note:
For the Pin To Start Menu option to work, make sure that the application shortcut exists in the
Start menu folder. If unsure, enable the Create Start Menu option as well.
For example, say you assign an action to start Notepad. In the Assigned list, the option “Autostart”is
provided and set to “Disabled”by default. If you use the Enable option to enable Autostart, Notepad
(local Notepad on the VDA) automatically launches when the user launches a published desktop ses‑
sion (local Notepad automatically starts when the desktop completes loading).
Modeling wizard
The Actions Modeling Wizard displays the resultant actions for a given user only (it does not work for
groups).
Actions Modeling Target User. The account name for the user you want to model.
Resultant Actions. The actions assigned to the user or to groups the user belongs to.
System Optimization
• CPU Management
• Memory Management
• I/O Management
• Fast Logoff
• Citrix Optimizer
• Multi‑session Optimization
These settings are designed to lower resource usage on the agent host. They help to ensure that freed‑
up resources are available for other applications. Doing so increases user density by supporting more
users on the same server.
While system optimization settings are machine‑based and apply to all user sessions, process opti‑
mization is user centric. This means that when a process triggers CPU Spike Protection in user A’s
session, the event is recorded only for user A. When user B starts the same process, process optimiza‑
tion behavior is determined only by process triggers in user B’s session.
CPU Management
Processes can run across all cores and can use up as much CPU as they want. In Workspace Environ‑
ment Management (WEM), CPU Management Settings lets you limit how much CPU capacity individ‑
ual processes can use. CPU spike protection is not designed to reduce overall CPU usage. It is designed
to reduce the impact on user experience by processes that consume an excessive percentage of CPU
Usage.
When CPU spike protection is enabled, if a process reaches a specified threshold, WEM automatically
lowers the priority of the process for a certain time. Then, when a new application is launched, it has
a higher priority than the lower‑priority process and the system will continue to run smoothly.
CPU spike protection examines each process in a quick “snapshot.”If the average load of a process
exceeds the specified usage limit for a specified sample time, its priority reduces immediately. After a
specified time, the process’CPU priority returns to its previous value. The process is not “throttled.”
Unlike in CPU Clamping, only its priority is reduced.
CPU spike protection is not triggered until at least one instance of an individual process exceeds the
threshold. In other words, even if total CPU consumption exceeds the specified threshold, CPU spike
protection is not triggered unless at least one process instance exceeds the threshold. But when that
process instance triggers CPU spike protection, new instances of the same process are (CPU) opti‑
mized when the option “Enable Intelligent CPU Optimization”is enabled.
Whenever a specific process triggers CPU spike protection, the event is recorded in the agent’s local
database. The agent records trigger events for each user separately. This means that CPU optimiza‑
tion for a specific process for user1 does not affect the behavior of the same process for user2.
For example, if Internet Explorer is sometimes consuming 50–60% of CPU, you can use CPU spike pro‑
tection to target only those iexplore.exe instances that are threatening VDA performance. (By contrast,
CPU clamping applies to all processes.)
We recommend that you experiment with the sample time to decide the optimal value for your envi‑
ronment that does not affect other users logged on to the same VDA.
Note:
• “CPU usage”in the following settings is based on “logical processors”in the physical or vir‑
tual machine. Each core in a CPU is considered as a logical processor, in the same way that
Windows does. For example, a physical machine with one 6‑core CPU is considered to have
12 logical processors (Hyper‑Threading Technology means that cores are doubled). A phys‑
ical machine with 8 x CPUs, each with 12 cores has 96 logical processors. A VM configured
with two 4‑core CPUs has 8 logical processors.
• The same applies to virtual machines. For example, suppose you have a physical machine
with 8 x CPUs, each with 12 cores (96 logical processors), supporting four multi‑session OS
VDA VMs. Each VM is configured with two 4‑cores CPUs (8 logical processors). To restrict
processes that trigger CPU spike protection on a VM, to use half of its cores, set Limit CPU
Core Usage to 4 (half of the VM’s logical processors), not to 48 (half of the physical machine’
s logical processors).
Enable CPU Spike Protection. Lowers the CPU priority of processes for a period of time (specified in
the Idle Priority Time field) if they exceed the specified percentage of CPU usage for a period of time
(specified in the Limit Sample Time field).
• Auto Prevent CPU Spikes. Use this option to automatically reduce the CPU priority of
processes that overload your CPU. This option automatically calculates the threshold value at
which to trigger CPU spike protection based on the number of logical processors (CPU cores).
For example, suppose there are 4 cores. With this option enabled, if the overall CPU usage
exceeds 23%, the CPU priority of processes that consume more than 15% of the overall CPU
resources reduces automatically. Similarly, in the case of 8 cores, if the overall CPU usage
exceeds 11%, the CPU priority of processes that consume more than 8% of the CPU resources
reduces automatically.
• Customize CPU Spike Protection. Lets you customize settings for CPU spike protection.
– CPU Usage Limit. The percentage of CPU usage that any process instance must reach to
trigger CPU spike protection. This limit is global across all logical processors in the server,
and is determined on an instance‑by‑process basis. Multiple instances of the same process
do not have their CPU usage percentages added when determining CPU spike protection
triggers. If a process instance never reaches this limit, CPU spike protection is not trig‑
gered. For example, on a Server VDA, in multiple concurrent sessions, suppose there are
many iexplore.exe instances. Each instance peaks at around 35% CPU usage for periods
of time, so that cumulatively, iexplore.exe is consistently consuming a high percentage of
CPU usage. However, CPU spike protection is never triggered unless you set CPU Usage
Limit at or below 35%.
– Limit Sample Time. The length of time for which a process must exceed the CPU usage
limit before its CPU priority is lowered.
– Idle Priority Time. The length of time for which the CPU priority of the process is lowered.
After that time, the priority returns to one of the following:
* The default level (Normal) if the process priority is not specified on the CPU Priority
tab and the Enable Intelligent CPU Optimization option is not selected.
* The specified level if the process priority is specified on the CPU Priority tab, regard‑
less of whether the Enable Intelligent CPU Optimization option is selected.
* A random level depending on the behavior of the process. This case occurs if the
process priority is not specified on the CPU Priority tab and the Enable Intelligent
CPU Optimization option is selected. The more frequent the process triggers CPU
spike protection, the lower its CPU priority is.
Enable CPU Core Usage Limit. Limits processes that trigger CPU spike protection to a specified num‑
ber of logical processors on the machine. Type an integer in the range of 1 through X, where X is the
total number of cores. If you type an integer greater than X, WEM limits the maximum consumption
of isolated processes to X by default.
• Limit CPU Core Usage. Specifies the number of logical processors to which processes that trig‑
ger CPU spike protection are limited. In the case of VMs, the value you type limits the processes
to the number of logical processors in the VMs rather than in the underlying physical hardware.
Enable Intelligent CPU Optimization. When enabled, the agent intelligently optimizes the CPU pri‑
ority of processes that trigger CPU spike protection. Processes that repeatedly trigger CPU spike pro‑
tection are assigned progressively lower CPU priority at launch than processes that behave correctly.
Note that WEM does not perform CPU optimization for the following system processes:
• Taskmgr
• System Idle Process
• System
• Svchost
• LSASS
• Wininit
• services
• csrss
• audiodg
• MsMpEng
• NisSrv
• mscorsvw
• vmwareresolutionset
Enable Intelligent I/O Optimization. When enabled, the agent intelligently optimizes the process
I/O priority of processes that trigger CPU spike protection. Processes that repeatedly trigger CPU
spike protection are assigned progressively lower I/O priority at launch than processes that behave
correctly.
Exclude Specified Processes. By default, WEM CPU management excludes all of the most com‑
mon Citrix and Windows core service processes. You can, however, use this option to Add or
Remove processes from an exclusion list for CPU spike protection by executable name (for example
notepad.exe). Typically, antivirus processes would be excluded.
Tip:
• To stop antivirus scanning taking over disk I/O in the session, you can also set a static I/O
Priority of Low for antivirus processes, see I/O Management.
• When processes trigger CPU spike protection, and process CPU priority is lowered, WEM
logs a warning each time it lowers the CPU priority of a process. In the Event Log, in Ap‑
plication and Services Logs, WEM Agent Service, looks for “Initializing process limitation
thread for process”.
CPU priority
These settings take effect if processes are competing for a resource. They let you optimize the CPU
priority level of specific processes, so that processes that are contending for CPU processor time do
not cause performance bottlenecks. When processes compete with each other, processes with lower
priority are served after other process with a higher priority. They are therefore less likely to consume
such a large share of the overall CPU consumption.
The process priority you set here establishes the “base priority”for all of the threads in the process.
The actual, or “current,”priority of a thread might be higher (but is never lower than the base). When
a number of processes are running on a computer, the processor time is shared between them based
on their CPU priority level. The higher the CPU priority level of a process is, the more the processor
time is assigned to it.
Note:
The overall CPU consumption does not necessarily decrease if you set lower CPU priority levels
on specific processes. There might be other processes (with higher CPU priority) still affecting
percentage CPU usage.
Enable Process Priority. When selected, lets you set CPU priority for processes manually.
To add a process
1. Click Add and type details in the Add Process CPU Priority dialog box.
3. Click Apply to apply the settings. Process CPU priorities you set here take effect when the agent
receives the new settings and the process is restarted.
Process Name. The process executable name without the extension. For example, for Windows
Explorer (explorer.exe) type “explorer”.
CPU Priority. The “base”priority of all threads in the process. The higher the priority level of
a process is, the more the processor time it gets. Select from Realtime, High, Above Normal,
Normal, Below Normal, and Low.
To edit a process
To remove a process
CPU affinity
Enable Process Affinity. When enabled, lets you define how many “logical processors”a process uses.
For example, you can restrict every instance of Notepad launched on the VDA to the number of cores
defined.
CPU clamping
CPU clamping prevents processes using more than a specified percentage of the CPU’s processing
power. WEM “throttles”(or “clamps”) that process when it reaches the specified CPU percentage you
set. This lets you prevent processes from consuming large amounts of CPU.
Note:
• CPU clamping is a brute force approach that is computationally expensive. To keep the CPU
usage of a troublesome process artificially low, it is better to use CPU spike protection, at
the same time as assigning static CPU priorities and CPU affinities to such processes. CPU
clamping is best reserved for controlling processes that are notoriously bad at resource
management, but that cannot stand to be dropped in priority.
• After you apply a percentage of the CPU’s processing power for a process and configure a
different percentage for the same process later, select Refresh Agent Host Settings for the
change to take effect.
The clamping percentage you configure is applied to the total power of any individual CPU in the
server, not to any individual core it contains. (In other words, 10% on a quad‑core CPU is 10% of the
entire CPU, not 10% of one core).
Tip:
• When WEM is clamping a process, it adds the process to its watchlist the WEM client initial‑
izes. You can verify that a process is clamped by viewing this.
• You can also verify that CPU clamping is working by looking at process monitor and con‑
firming that CPU consumption never rises above the clamping percentage.
Memory Management
April 8, 2024
These settings let you optimize application memory usage through Workspace Environment Manage‑
ment (WEM).
Memory management
If these settings are turned on, WEM calculates how much memory a process is using and the mini‑
mum amount of memory a process needs without losing stability. WEM considers the difference as
excess memory. When the process becomes idle, WEM releases the excess memory that the process
consumes to the page file, and optimizes the process for subsequent launches. Usually, an applica‑
tion becomes idle when it is minimized to the task bar.
When applications are restored from the task bar, they initially run in their optimized state but can
continue to consume additional memory as needed.
Similarly, WEM optimizes all applications that users are using during their desktop sessions. If there
are multiple processes over multiple user sessions, all memory that is freed up is available for other
processes. This behavior increases user density by supporting a greater number of users on the same
server.
Optimize Memory Usage for Idle Processes. Forces processes that remain idle for a specified time
to release excess memory until they are no longer idle.
Idle Sample Time (min). Lets you specify the length of time that a process is considered idle after
which it is forced to release excess memory. During this time, WEM calculates how much memory a
process is using, and the minimum amount of memory a process needs, without losing stability. The
default value is 120 minutes.
Idle State Limit (percent). Lets you specify the percentage of CPU usage below which a process is
considered idle. The default is 1%. We recommend that you do not use a value greater than 5%. Oth‑
erwise, a process being actively used can be mistaken for idle, causing its memory to be released.
Do Not Optimize When Total Available Memory Exceeds (MB). Lets you specify a threshold limit
below which WEM optimizes memory usage for idle applications.
Exclude Processes from Memory Usage Optimization. Lets you exclude processes from memory
usage optimization. Specify the process name, for example, notepad.exe.
WEM does not optimize application memory usage for the following system processes:
• rdpshell
• wfshell
• rdpclip
• wmiprvse
• dllhost
• audiodg
• msdtc
• mscorsvw
• spoolsv
• smss
• winlogon
• svchost
• taskmgr
• System Idle Process
• System
• LSASS
• wininit
• msiexec
• services
• csrss
• MsMpEng
• NisSrv
• Memory Compression
Enable Memory Usage Limit for Specific Processes. Lets you limit the RAM usage of a process by
setting an upper limit for the RAM, the process can consume.
Warning:
Applying memory usage limits to certain processes might have unintended effects, including
slow system responsiveness.
• Add. Allows you to add a process to which you want to apply a memory usage limit.
• Dynamic Limit. Allows you to apply a dynamic limit to the specified process. This setting dy‑
namically limits the amount of RAM allocated to the specified process. If applied, enforces mem‑
ory usage limits depending on the available memory. Therefore, the RAM that the specified
process consumes might exceed the specified amount.
• Static Limit. Allows you to apply a static limit to the specified process. This setting always limits
the amount of RAM allocated to the specified process. If applied, restricts the process from
consuming more than the specified amount of memory regardless of the amount of available
memory. As a result, the RAM that the specified process consumes is capped at the specified
amount.
To add a process:
1. On the Administration Console > System Optimization > Memory Management > Memory
Usage Limit tab, click Add.
2. In the Add Process window, type the name of the process you want to add (for example,
notepad.exe.), configure the memory usage limit, select a limit mode from the drop‑down
menu, and then click OK.
To apply a dynamic limit to an item, select the item and click Dynamic Limit.
To apply a static limit to an item, select the item and click Static Limit.
I/O Management
July 5, 2022
These settings allow you to optimize the I/O priority of specific processes, so that processes which are
contending for disk and network I/O access do not cause performance bottlenecks. For example, you
can use I/O Management settings to throttle back a disk‑bandwidth‑hungry application.
The process priority you set here establishes the “base priority”for all of the threads in the process.
The actual, or “current,”priority of a thread might be higher (but is never lower than the base). In
general, Windows give access to threads of higher priority before threads of lower priority.
I/O priority
Enable Process I/O Priority. Enables manual setting of process I/O priority.
1. Click Add and type details in the Add Process I/O Priority dialog.
2. Click OK to close the dialog.
3. Click Apply to apply the settings. Process I/O priorities you set here take effect when the agent
receives the new settings and the process is next restarted.
Process Name. The process executable name without the extension. For example, for Windows Ex‑
plorer (explorer.exe) type “explorer”.
I/O Priority. The “base”priority of all threads in the process. The higher the I/O priority of a process,
the sooner its threads get I/O access. Choose from High, Normal, Low, Very Low.
Fast Logoff
Fast Logoff ends the HDX connection to a remote session immediately, giving users the impression
that the session has immediately closed. However, the session itself continues through the session
logoff phases in the background on the VDA.
Note:
Fast Logoff supports Citrix virtual apps and RDS resources only.
Settings
Enable Fast Logoff. Enables fast logoff for all users in this configuration set. Users are logged out
immediately, while session logoff tasks continue in the background.
Exclude Specific Groups. Allows you to exclude specific groups of users from Fast Logoff.
Citrix Optimizer
Citrix optimizer optimizes user environments for better performance. It runs a quick scan of user en‑
vironments and then applies template‑based optimization recommendations. You can optimize user
environments in two ways:
• Use built‑in templates to perform optimizations. To do so, select a template applicable to the
operating system.
• Alternatively, create your own customized templates with specific optimizations you want and
then add the templates to Workspace Environment Management (WEM).
To get a template that you can customize, use either of the following approaches:
• Use the template builder feature that the standalone Citrix Optimizer offers. Download the
standalone Citrix Optimizer at https://support.citrix.com/article/CTX224676. The template
builder feature lets you build your own custom templates to be uploaded to WEM.
• On an agent host (machine where the WEM agent is installed), navigate to the <C:\Program
Files (x86)>\Citrix\Workspace Environment Management Agent\Citrix
Optimizer\Templates folder, select a default template file, and copy it to a convenient
folder. Customize the template file to reflect your specifics and then upload the custom
template to WEM.
Settings
Run Weekly. If selected, WEM runs optimizations on a weekly basis. If Run Weekly is not selected,
WEM behaves as follows:
• The first time you add a template to WEM, WEM runs the corresponding optimization. WEM runs
the optimization only once unless you make changes to that template later. Changes include
applying a different template to OS and moving optimization entries around between the Avail‑
able and Configured panes.
• Each time you make changes to a template, WEM runs the optimization once.
Note:
For a non‑persistent VDI environment, WEM follows the same behavior –all changes to the envi‑
ronment are lost when the machine restarts. In the case of Citrix Optimizer, WEM runs optimiza‑
tions each time the machine restarts.
Automatically Select Templates to Use. If you are unsure which template to use, use this option to
let WEM select the best match for each OS.
• Enable Automatic Selection of Templates Starting with Prefixes. Use this option if custom
templates with different name formats are available. Type a comma‑separated list of prefixes.
Custom template follows this name format:
The Citrix Optimizer tab displays a list of templates you can use to perform system optimizations.
The Actions section displays the actions available to you:
1. On the Administration Console > System Optimization > Citrix Optimizer > Citrix Optimizer
tab, click Add.
2. In the New Custom Template window, complete the following steps:
a) For Template Name, click Select an XML file and then select the applicable file from the
list.
Note:
The list displays the XML files you uploaded. To upload an XML file, see To upload a
custom template.
Important:
Citrix optimizer does not support exporting custom templates. Retain a local copy of your custom
template after you add it.
To edit a template, select the applicable template and then click Edit.
To remove a template, select the applicable template and then click Remove.
To view details of a template, select the applicable template and then click Preview.
Applicable OSs. A list of operating systems. Select one or more operating systems to which the tem‑
plate applies. You can add custom templates applicable to Windows 10 OSs that are not available on
the list. Add those OSs by typing their build numbers. Be sure to separate the OSs with semicolons (;).
For example, 2001;2004.
Important:
Groups. The Available pane displays a list of grouped optimization entries. The entries are grouped
by category. Double‑click a group or click the arrow buttons to move the group around.
State. Toggles the template between enabled and disabled states. If disabled, the agent does not
process the template, and WEM does not run optimizations associated with the template.
Changes to Citrix optimizer settings take some time to take effect, depending on the value that you
specified for the SQL Settings Refresh Delay option on the Advanced Settings > Configuration >
Service Options tab.
For the changes to take effect immediately, navigate to the context menu of the Administration >
Agents > Statistics tab and then select Process Citrix Optimizer.
Tip:
New changes might fail to take effect immediately. We recommend that you select Refresh
Agent Host Settings before you select Process Citrix Optimizer.
1. On the Manage tab, hover the mouse cursor over the hamburger menu.
3. Click the upload icon to upload the custom template (XML file) to the default folder in Citrix
Cloud.
Multi‑session Optimization
Multi‑session OS machines run multiple sessions from a single machine to deliver applications and
desktops to users. A disconnected session remains active and its applications continue to run. The
disconnected session can consume resources needed for connected desktops and applications that
run on the same machine. These settings let you optimize multi‑session OS machines with discon‑
nected sessions for better user experience with connected sessions.
Settings
Exclude Specified Groups. Lets you specify which groups to exclude from multi‑session optimization.
Specify at least one group.
Exclude Specified Processes. Lets you specify which processes to exclude from multi‑session opti‑
mization. Type the name of the process you want to exclude. Specify at least one process.
These settings let you replace user GPOs and configure user profiles.
• Environmental Settings
• Microsoft USV Settings
• Citrix Profile Management Settings
Environmental Settings
December 5, 2023
These options modify the user’s environmental settings. Some of the options are processed at logon,
while some others can be refreshed in session with the agent refresh feature.
Start menu
Process Environmental Settings. This check box toggles whether the agent processes environmen‑
tal settings. If it is cleared, no environmental settings are processed.
Exclude Administrators. If enabled, environmental settings are not processed for administrators,
even if the agent is launched.
User Interface: Start Menu. These settings control which Start menu functions are disabled by the
agent.
Important:
On operating systems other than Windows 7, the options under User Interface: Start Menu
might not work, except Hide System Clock and Hide Turnoff Computer.
User Interface: Appearance. These settings allow you to customize the user’s Windows theme and
desktop. Paths to resources must be entered as they are accessed from the user’s environment.
Note:
While using a non‑domain‑joined agent, WEM might not work if you use a network share.
Desktop
User Interface: Desktop. These settings control which desktop elements are disabled by the
agent.
User Interface: Edge UI. These settings allow you to disable aspects of the Windows 8.x Edge user
interface.
Windows Explorer
These settings control which Windows Explorer functionalities are disabled by the agent.
User Interface: Explorer. These options allow you to disable access to regedit or cmd, and hide
certain elements in Windows Explorer.
Hide Specified Drives from Explorer. If enabled, the listed drives are hidden from the user’s My
Computer menu. They are still accessible if browsed to directly.
Restrict Specified Drives from Explorer. If enabled, the listed drives are blocked. Neither the users
nor their applications can access them.
Control Panel
Hide Control Panel. This option is enabled by default to secure the user environment. If disabled,
the users have access to their Windows control panel.
Show only specified Control Panel Applets. If enabled, all control panel applets except the ones
listed here are hidden from the user. Additional applets are added using their canonical name.
Hide specified Control Panel Applets. If enabled, only the listed control panel applets are hidden.
Additional applets are added using their canonical name.
See Common Control Panel applets along with their canonical names.
Disable Specified Known Folders. Prevents the creation of the specified user profile known folders
at profile creation.
SBC/HVD tuning
User Environment: Advanced Tuning. These options allow you to optimize performance in SBC/HVD
environments.
These settings allow you to optimize Microsoft User State Virtualization (USV).
These settings allow you to configure the integration of Workspace Environment Management with
Microsoft roaming profiles.
Process User State Virtualization Configuration. Controls whether the agent processes USV set‑
tings. If disabled, no USV settings are processed.
Exclude Administrators. If enabled, USV settings you configure do not apply to administrators. When
using this option, consider the following:
• Settings on the Roaming Profiles Configuration and Roaming Profiles Advanced Configura‑
tion tabs are machine‑level and still apply regardless of whether the option is enabled.
• Settings on the Folder Redirections tabs are user‑level. The option controls whether the set‑
tings apply to administrators.
Set Windows Roaming Profile Path. Lets you specify the path to your Windows profiles.
Set RDS Roaming Profiles Path. Lets you specify the path to your RDS roaming profiles.
Set RDS Home Drive Path. Lets you specify the path to your RDS home drive and the drive letter that
it appears with in the user environment.
Enable Folder Exclusions. If enabled, the listed folders are not included in a user’s roaming profile.
This allows you to exclude specific folders known to contain large amounts of data which the user
does not need to have as part of their roaming profile. The list is pre‑populated with default Windows
7 exclusions, and can be pre‑populated with default Windows XP exclusions instead.
Delete Cached Copies of Roaming Profiles. If enabled, the agent deletes cached copies of the roam‑
ing profiles.
Add Administrators Security Group to Roaming User Profiles. If enabled, the Administrators group
is added as owner to roaming user profiles.
Do Not Check for User Ownership of Roaming Profiles Folders. If enabled, the agent does not check
to see if the user owns the roaming profiles folder before acting.
Do Not Detect Slow Network Connections. If enabled, connection speed detection is skipped.
Wait for Remote User Profile. If enabled, the agent waits for the remote user profile to be fully down‑
loaded before processing its settings.
Folder redirection
Process Folder Redirection Configuration. This check box toggles whether the agent processes
folder redirections. If it is cleared, no folder redirections are processed. Select the options to control
whether and where the user’s folders are redirected.
Delete Local Redirected Folders. If enabled, the agent deletes the local copies of the folders selected
for redirection.
Note:
Some options work only with specific versions of Profile Management. Consult the Profile Man‑
agement documentation for details.
Workspace Environment Management (WEM) service supports the features and operation of the cur‑
rent version of Citrix Profile Management. In the WEM administration console, the Citrix Profile Man‑
agement Settings (in Policies and Profiles) supports configuring all settings for the current version
of Citrix Profile Management.
In addition to using WEM to configure Citrix Profile Management features, you can use Active Directory
GPOs, Citrix Studio policies, or .ini files on the VDA. We recommend that you use the same method
consistently.
Get started with Profile Management by applying basic settings. Basic settings include processed
groups, excluded groups, user store, and more.
Enable Profile Management Configuration. When enabled, you can configure and apply your set‑
tings. Enabling this option creates Profile Management related registries in the user environment.
The option controls whether WEM deploys Profile Management settings you configure in the console
to the agent. If disabled, none of the Profile Management settings are deployed to the agent.
Enable Profile Management. Controls whether to enable the Profile Management service on the
agent machine. If disabled, the Profile Management service does not work.
You might want to disable Profile Management completely so that settings already deployed to the
agent will no longer be processed. To achieve the goal, do the following:
1. Clear the Enable Profile Management check box and wait for the change to apply automati‑
cally or apply the change manually for immediate effect.
Note:
The change takes some time to take effect, depending on the value you specified for SQL
Settings Refresh Delay in Advanced Settings. For the change to take effect immediately,
refresh agent host settings and then reset Profile Management settings for all related
agents. See Administration.
2. After the change takes effect, clear the Enable Profile Management Configuration check box.
Set processed groups. Lets you specify which groups are processed by Profile Management. Only
the specified groups have their Profile Management settings processed. If left empty, all groups are
processed.
Set excluded groups. Lets you specify which groups are excluded from Profile Management.
Process logons of local administrators. If enabled, local administrator logons are treated the same
as non‑administrator logons for Profile Management.
Set path to user store. Lets you specify the path to the user store folder.
Migrate user store. Lets you specify the path to the folder where the user settings (registry changes
and synchronized files) were saved. Type the user store path that you previously used. Use this option
along with the Set path to user store option.
Enable active write back. If enabled, profiles are written back to the user store during the user’s
session, preventing data loss.
Enable active write back registry. If enabled, registry entries are written back to the user store dur‑
ing the user’s session, preventing data loss.
Enable active write back on session lock and disconnection. With both this option and the Enable
active write back option enabled, profile files and folders are written back only when a session is
locked or disconnected. With both this option and the Enable active write back registry option
enabled, registry entries are written back only when a session is locked or disconnected.
Enable offline profile support. If enabled, profiles are cached locally for use while not connected.
Enable Profile Container. If enabled, Profile Management maps the listed folders to the profile disk
stored on the network, thus eliminating the need to save a copy of the folders to the local profile.
Specify at least one folder to include in the profile container.
Enable Folder Exclusions for Profile Container. If enabled, Profile Management excludes the listed
folders from the profile container. Specify at least one folder to exclude from the profile container.
Enable Folder Inclusions for Profile Container. If enabled, Profile Management keeps the listed
folders in the profile container when their parent folders are excluded. Folders on this list must be
subfolders of the excluded folders. This means that you must use this option in combination with the
Enable Folder Exclusions for Profile Container option. Specify at least one folder to include in the
profile container.
Enable File Exclusions for Profile Container. If enabled, Profile Management excludes the listed
files from the profile container. Specify at least one file to exclude from the profile container.
Enable File Inclusions for Profile Container. If enabled, Profile Management keeps the listed files in
the profile container when their parent folders are excluded. Files on this list must be contained in the
excluded folders. This means that you must use this option in combination with the Enable Folder
Exclusions for Profile Container option. Specify at least one file to include in the profile container.
Enable Local Cache for Profile Container. If enabled, each local profile serves as a local cache of
its profile container. If profile streaming is in use, locally cached files are created on demand. Other‑
wise, they are created during user logons. To use this setting, put an entire user profile in its profile
container. This setting applies only to Citrix Profile Management profile containers.
Tip:
When adding files or folders, you can use wildcards. For more information, see Wildcard support.
Enable VHD disk compaction. If enabled, VHD disks are automatically compacted on user logoff
when certain conditions are met. This option enables you to save the storage space consumed by
profile container, OneDrive container, and mirror folder container.
Depending on your needs and the resources available, you can adjust the default VHD compaction
settings and behavior using the Set free space ratio to trigger VHD disk compaction, Set number
of logoffs to trigger VHD disk compaction, and Disable defragmentation for VHD disk compaction
options in Advanced settings.
Profile handling
Delete local cached profiles on logoff. If enabled, locally cached profiles are deleted when the user
logs off.
Set delay before deleting cached profiles. Lets you specify a delay (in seconds) before cached pro‑
files are deleted on logoff.
Enable Migration of Existing Profiles. If enabled, existing Windows profiles are migrated to Profile
Management on logon.
Automatic migration of existing application profiles. If enabled, existing application profiles are
migrated automatically. Profile Management performs the migration when a user logs on and there
are no user profiles in the user store.
Enable local profile conflict handling. Configures how Citrix Workspace Environment Management
handles cases where Profile Management and Windows profiles conflict.
Enable template profile. If enabled, uses a template profile at the indicated location.
Template profile overrides local profile. If enabled, the template profile overrides local profiles.
Template profile overrides roaming profile. If enabled, the template profile overrides roaming pro‑
files.
Template profile used as Citrix mandatory profile for all logons. If enabled, the template profile
overrides all other profiles.
Advanced settings
Set number of retries when accessing locked files. Configures the number of times the Agent retries
accessing locked files.
Set directory of the MFT cache file. Lets you specify the MFT cache file directory. This option has
been deprecated and will be removed in the future.
Enable application profiler. If enabled, defines application‑based profile handling. Only the settings
defined in the definition file are synchronized. For more information about creating definition files,
see Create a definition file.
Process Internet cookie files on logoff. If enabled, stale cookies are deleted at logoff.
Log off user if a problem is encountered. If enabled, users are logged off rather than switched to a
temporary profile if a problem is encountered.
Customer experience improvement program. If enabled, Profile Management uses the Customer
Experience Improvement Program (CEIP) to help improve the quality and performance of Citrix prod‑
ucts by collecting anonymous statistics and usage information. For more information on the CEIP, see
About the Citrix Customer Experience Improvement Program (CEIP).
Enable multi‑session write‑back for profile containers. If enabled, Profile Management saves
changes in multi‑session scenarios for both FSLogix Profile Container and Citrix Profile Management
profile containers. If the same user launches multiple sessions on different machines, changes made
in each session are synchronized and saved to the user’s profile container disk.
Enable asynchronous processing for user Group Policy on logon. If enabled, Profile Management
roams with users a registry value that Windows uses to determine the processing mode for the next
user logon —synchronous or asynchronous processing mode. If the registry value does not exist, syn‑
chronous mode is applied. Enabling the option ensures that the actual processing mode is applied
each time users log on. If disabled, asynchronous mode can’t be applied as expected if users:
Disable defragmentation for VHD disk compaction. Applicable when Enable VHD disk compaction
is enabled. Lets you specify whether to disable file defragmentation for VHD disk compaction.
When VHD disk compaction is enabled, the VHD disk file is first automatically defragmented using
the Windows built‑in defrag tool, and then compacted. VHD disk defragmentation produces better
compaction results while disabling it can save system resources.
Set free space ratio to trigger VHD disk compaction. Applicable when Enable VHD disk compaction
is enabled. Lets you specify the free space ratio to trigger VHD disk compaction. When the free space
ratio exceeds the specified value on user logoff, disk compaction is triggered.
Free space ratio = (current VHD file size –required minimum VHD file size*) ÷ current VHD file size
* Obtained using the GetSupportedSize method of the MSFT_Partition class from the Microsoft
Windows operating system.
Set number of logoffs to trigger VHD disk compaction. Applicable when Enable VHD disk com‑
paction is enabled. Lets you specify the number of user logoffs to trigger VHD disk compaction.
When the number of logoffs since the last compaction reaches the specified value, disk compaction is
triggered again.
Replicate user stores. If enabled, Profile Management replicates a user store to multiple paths on
each logon and logoff, in addition to the path that the Set path to user store option specifies. To
synchronize to the user stores files and folders modified during a session, enable active write‑back.
Enabling the option can increase system I/O and might prolong logoffs.
Customize storage path for VHDX files. Lets you specify a separate path to store VHDX files. By de‑
fault, VHDX files are stored in the user store. Policies that use VHDX files include the following: Profile
container, Search index roaming for Outlook, and Accelerate folder mirroring. If enabled, VHDX files
of different policies are stored in different folders under the storage path.
Enable search index roaming for Microsoft Outlook users. If enabled, the user‑specific Microsoft
Outlook offline folder file (*.ost) and Microsoft search database are roamed along with the user profile.
This improves the user experience when searching mail in Microsoft Outlook.
• Outlook search index database –backup and restore. If enabled, Profile Management auto‑
matically saves a backup of the last known good copy of the search index database. When there
is a corruption, Profile Management reverts to that copy. As a result, you no longer need to
manually reindex the database when the search index database becomes corrupted.
• Enable concurrent session support for Outlook search data roaming. Provides native Out‑
look search experience in concurrent sessions. If enabled, each concurrent session uses a sep‑
arate Outlook OST file.
– Maximum number of VHDX disks for storing Outlook OST files. Lets you specify the
maximum number of VHDX disks for storing Outlook OST files. If unspecified, only two
VHDX disks can be used to store Outlook OST files (one file per disk). If more sessions start,
their Outlook OST files are stored in the local user profile. Supported values: 1–10.
Enable OneDrive container. If enabled, Profile Management roams OneDrive folders with users by
storing the folders on a VHDX disk. The disk is attached during logons and detached during logoffs.
Log settings
Configure Log Settings. Lets you specify which types of events to include in the logs.
Set Maximum Size of Log File. Lets you specify a maximum size in bytes for the log file.
Set Path to Log File. Lets you specify the location at which the log file is created.
Registry
NTUSER.DAT Backup. If selected, Profile Management maintains a last known good backup of the
NTUSER.DAT file. If Profile Management detects corruption, it uses the last known good backup copy
to recover the profile.
Enable Default Exclusion List. Default list of registry keys in the HKCU hive that are not synchronized
to the user’s profile. If selected, registry settings which are selected in this list are forcibly excluded
from Profile Management profiles.
Enable Registry Exclusions. Registry settings in this list are forcibly excluded from Profile Manage‑
ment profiles.
Enable Registry Inclusions. Registry settings in this list are forcibly included in Profile Management
profiles.
File system
Enable Logon Exclusion Check. If enabled, configures what Profile Management does when a user
logs on when a profile in the user store contains excluded files or folders. (If disabled, the default
behavior is Synchronize excluded files or folders). You can select one of the following behaviors in
the list:
Synchronize excluded files or folders (default). Profile Management synchronizes these excluded
files or folders from the user store to local profile when a user logs on.
Ignore excluded files or folders. Profile Management ignores the excluded files or folders in the user
store when a user logs on.
Delete excluded files or folder. Profile Management deletes the excluded files or folders in the user
store when a user logs on.
Enable Default Exclusion List ‑ Directories. Default list of directories ignored during synchroniza‑
tion. If selected, folders which are selected in this list are excluded from the Profile Management syn‑
chronization.
Enable File Exclusions. If enabled, the listed files are not included in a user’s profile. This setting
lets you exclude specific files containing a large amount of data that users do not need as part of their
profile. The list is pre‑populated with default Windows 7 exclusions, and can be pre‑populated with
default Windows XP exclusions instead.
Enable Folder Exclusions. If enabled, the listed folders are not included in a user’s profile. This set‑
ting lets you exclude specific folders containing a large amount of data that users do not need as part
of their profile. The list is pre‑populated with default Windows 7 exclusions, and can be pre‑populated
with default Windows XP exclusions instead.
Tip:
When adding files or folders, you can use wildcards. For more information, see Wildcard support.
Synchronization
Enable Directory Synchronization. If enabled, the listed folders are synchronized to the user
store.
Enable File Synchronization. If enabled, the listed files are synchronized to the user store, ensuring
that users always get the most up‑to‑date versions of the files. If files have been modified in more
than one session, the most up‑to‑date files are kept in the user store.
Tip:
When adding files or folders, you can use wildcards. For more information, see Wildcard support.
Enable Folder Mirroring. If enabled, the listed folders are mirrored to the user store on logoff, ensur‑
ing that files and subfolders in mirrored folders stored in the user store are exactly the same as the
local versions. See below for more information about how folder mirroring works.
Accelerate folder mirroring. By default, Profile Management copies necessary transactional folders
between the user store and local profiles. Mirroring ensures the integrity of those folders. This op‑
tion eliminates the need to copy them by using a container‑based solution, thus accelerating folder
mirroring. Profile Management attaches the virtual disk during logons and detaches it during logoffs,
eliminating the need to copy the folders between the user store and local profiles. Files in mirrored
folders will always overwrite files stored in the user store on session logoff, irrespective of whether
they are modified. If extra files or subfolders are present in the user store compared to the local ver‑
sions in mirrored folders, those extra files and subfolders are deleted from the user store on session
logoff.
• Add folders to mirror. By default, Profile Management copies necessary transactional folders
between the user store and local profiles. A transactional folder is a folder containing interde‑
pendent files, where one file references other files. You can add more as needed.
Enable Large File Handling. If enabled, large files are redirected to the user store, thus eliminating
the need to synchronize those files over the network.
Note:
Some applications do not allow concurrent file access. Citrix recommends that you take appli‑
cation behavior into consideration when you define your large file handling policy.
Enable Profile Streaming. If disabled, none of the settings in this section are processed.
Enable Profile Streaming for Folders. If enabled, folders are fetched only when they are being ac‑
cessed. This setting eliminates the need to traverse all folders during user logons, thus saving band‑
width and reducing the time to synchronize files.
Always cache. If enabled, files of the specified size (in MB) or larger will always be cached.
Set timeout for pending area lock files: Frees up files so they are written back to the user store from
the pending area after the specified time if the user store remains locked when a server becomes
unresponsive.
Set streamed user profile groups. This list determines which user groups streamed profiles are used
for.
Enable Profile Streaming Exclusion List ‑ Directories. If selected, Profile Management does not
stream folders in this list, and all the folders are fetched immediately from the user store to the local
computer when users log on.
Enable profile streaming for pending area. If enabled, files in the pending area are fetched to the
local profile only when they are requested. This ensures optimum logon experience in concurrent
session scenarios. The pending area is used to ensure profile consistency while profile streaming is
enabled. It temporarily stores profile files and folders changed in concurrent sessions. By default,
this option is disabled. All files and folders in the pending area are fetched to the local profile during
logon.
Cross‑platform settings
Enable cross‑platform settings. If disabled, none of the settings in this section are processed.
Set cross‑platform settings groups. Lets you specify the user groups for which cross‑platform pro‑
files are used.
Set path to cross‑platform definitions. Lets you specify the path to your cross‑platform definition
files.
Set path to cross‑platform setting store. Lets you specify the path to your cross‑platform setting
store.
Enable source for creating cross‑platform settings. Enables a source platform for cross‑platform
settings.
This option controls user access to files, folders, and registries. A typical use case is to apply rules to
control user access to apps installed on machines —whether to make apps visible to relevant users.
Enable app access control. If enabled, Profile Management controls user access to items (such as
files, folders, and registries) based on the rules you provide.
• GUI‑based tool ‑ WEM Tool Hub > Rule Generator for App Access Control
• PowerShell tool –available with the Profile Management installation package
Enable credential‑based access to user store. If disabled, Profile Management impersonates the
current user to access user stores. Therefore, make sure that the current user has permission to
directly access the user stores. Disabling this setting prevents all settings on this tab from being
processed. If enabled, Profile Management uses the specified user store credentials to access the user
stores on behalf of the user. Enabling this setting allows you to put user stores in storage repositories
(for example, Azure Files) that the current user has no permission to access.
Important:
Disabling this setting deletes all user store connections that the WEM agent previously estab‑
lished.
File deduplication
Identical files can exist among various user profiles. Separating those files from the user store and
storing them in a central location saves storage space by avoiding duplicates. You can specify files that
you want to include in the shared store on the server hosting the user store. Specify the file names
with paths relative to the user profile.
Enable File Inclusions. If enabled, Profile Management generates the shared store automatically. It
then centrally stores the specified files in the shared store rather than in each user profile in the user
store. Doing so reduces the load on the user store by avoiding file duplication, thus reducing your
storage cost.
Enable File Exclusions. If enabled, Profile Management excludes the specified files from the shared
store. You must use this option along with the Enable file inclusions option. Specify at least one file
to exclude from the shared store.
Tip:
When adding files or folders, you can use wildcards. For more information, see Wildcard support.
Wildcard support
When adding files or folders, you can use wildcards. Wildcards in file names are applied recursively
while wildcards in folder names are not. You can use the vertical bar (|) to restrict the policy only to
the current folder so that the policy does not apply to its subfolders.
Examples:
• AppData\*.tmp excludes all files with the extension .tmp in the folder AppData and its sub‑
folders.
• AppData\*.tmp| excludes all files with the extension .tmp in the folder AppData.
• Downloads\*\a.txt excludes a.txt in any immediate subfolder of the Downloads
folder. Remember: wildcards in folder names are not applied recursively.
• Downloads\* excludes all immediate subfolders of the Downloads folder.
Security
These settings let you control user activities within Workspace Environment Management (WEM).
Application security
Important:
To control which applications users can run, use the Windows AppLocker interface or WEM to
manage Windows AppLocker rules. You can switch between these approaches at any time. We
recommend that you do not use both approaches at the same time.
These settings let you control the applications that users are permitted to run by defining rules. This
functionality is similar to Windows AppLocker. When you use WEM to manage Windows AppLocker
rules, the agent converts Application Security tab rules into Windows AppLocker rules on the agent
host. If you stop the agent processing rules, they are preserved in the configuration set. AppLocker
continues running by using the last set of instructions processed by the agent.
Application security
This tab lists the application security rules in the current WEM configuration set. Use Find to filter the
list according to a text string.
When you select the top‑level item “Application Security”in the Security tab, the following options
become available:
• Process Application Security Rules. When selected, the Application Security tab controls are
enabled and the agent processes rules in the current configuration set, converting them into
AppLocker rules on the agent host. When not selected, the Application Security tab controls
are disabled and the agent does not convert rules into AppLocker rules. (In this case, AppLocker
rules are not updated.)
Note:
This option is not available if the WEM administration console is installed on Windows 7
SP1 or Windows Server 2008 R2 SP1 (or earlier versions).
• Process DLL Rules. When selected, the agent converts DLL rules in the current configuration
set into AppLocker DLL rules on the agent host. This option is available only when you select
Process Application Security Rules.
Important:
If you use DLL rules, you must create a DLL rule with “Allow”permission for each DLL that
is used by all the allowed apps.
Caution:
If you use DLL rules, users might experience sluggish performance. This issue happens
because AppLocker checks each DLL that an app loads before the app is allowed to run.
• The Overwrite and Merge settings let you determine how the agent processes application se‑
curity rules.
– Overwrite. Lets you overwrite existing rules. When selected, the rules that are processed
last overwrite rules that were processed earlier. We recommend that you apply this mode
only to single‑session machines.
– Merge. Lets you merge rules with existing rules. When conflicts occur, the rules that are
processed last overwrite rules that were processed earlier. If you need to modify the rule
enforcement setting during merging, use overwrite mode because merge mode will keep
the old value if it differs.
Rule collections
Rules belong to AppLocker rule collections. Each collection name indicates how many rules it con‑
tains, for example (12). Click a collection name to filter the rule list to one of the following collec‑
tions:
• Executable Rules. Rules that include files with the .exe and .com extensions associated with
an application.
• Windows Rules. Rules that include installer file formats (.msi, .msp, .mst) controlling the instal‑
lation of files on client computers and servers.
• Script Rules. Rules that include files of the following formats: .ps1, .bat, .cmd, .vbs, .js.
• Packaged Rules. Rules that include packaged apps, also known as Universal Windows apps. In
packaged apps, all files within the app package share the same identity. Therefore, one rule can
control the entire app. WEM supports only publisher rules for packaged apps.
• DLL Rules. Rules that include files of the following formats: .dll, .ocx.
When you filter the rule list to a collection, the Rule enforcement option is available to control how
AppLocker enforces all rules in that collection on the agent host. The following rule enforcement val‑
ues are possible:
Off (default). Rules are created and set to “off,”which means they are not applied.
On. Rules are created and set to “enforce,”which means they are active on the agent host.
Audit. Rules are created and set to “audit,”which means they are on the agent host in inactive state.
When a user runs an app that violates an AppLocker rule, the app is allowed to run and the information
about the app is added to the AppLocker event log.
You can import rules exported from AppLocker into Workspace Environment Management. Imported
Windows AppLocker settings are added to any existing rules in the Security tab. Any invalid applica‑
tion security rules are automatically deleted and listed in a report dialog.
2. Browse to the XML file exported from AppLocker containing your AppLocker rules.
3. Click Import.
To add a rule
1. Select a rule collection name in the sidebar. For example, to add an executable rule select the
“Executable Rules”collection.
• Name. The display name of the rule as it appears in the rule list.
5. In the Permissions section, select Allow or Deny. The selection controls whether to allow or
prohibit applications from running.
6. To assign this rule to users or user groups, in the Assignments pane, choose users or groups
to which you want to assign this rule. The “Assigned”column shows a “check”icon for assigned
users or groups.
Tip:
• You can use the usual Windows selection modifier keys to make multiple selections,
or use Select All to select all rows.
• Users must already be in the WEM Users list.
• You can assign rules after the rule is created.
7. Click Next.
8. Specify the criteria the rule matches, depending on the rule type you choose:
• Path. Type the path to the file or folder to which you want to apply the rule. The WEM
agent applies the rule to an executable according to the executable file path.
• Publisher. Fill out the following fields: Publisher, Product name, File name, and File
version. You cannot leave any of the fields empty, but you can type an asterisk (*) instead.
The WEM agent applies the rule according to publisher information. If applied, users can
run executables that share the same publisher information.
• Hash. Click Add to add a hash. In the Add Hash window, type the file name and the hash
value. You can use the AppInfoViewer tool to create a hash from a selected file or folder.
The WEM agent applies the rule to identical executables as specified. As a result, users can
run executables that are identical to the specified one.
9. Click Next.
10. Add any exceptions you require (optional). In Add exception, choose an exception type and
then click Add. (You can edit or remove exceptions if needed.)
Select one or more rules in the list and then click Edit in the toolbar or context menu. In the editor,
select the rows containing the users and user groups you want to assign the rule to and then click OK.
You can also unassign the selected rules from everyone using Select All to clear all selections.
Note: If you select multiple rules and click Edit, any rule assignment changes for those rules apply
to all users and user groups you select. In other words, existing rule assignments are merged across
those rules.
Click Add Default Rules. A set of AppLocker default rules is added to the list.
To edit rules
Select one or more rules in the list and then click Edit in the toolbar or context menu. The editor
appears, letting you adjust settings that apply to the selection you made.
To delete rules
Select one or more rules in the list and then click Delete in the toolbar or context menu.
You can back up all application security rules in your current configuration set. Rules are all exported
as a single XML file. You can use Restore to restore the rules to any configuration set.
In the ribbon, click Backup then select Security Settings.
You can restore application security rules from XML files created by the Workspace Environment Man‑
agement backup command. The restore process replaces the rules in the current configuration set
with those rules in the backup. When you switch to or refresh the Security tab, any invalid applica‑
tion security rules are detected. Invalid rules are automatically deleted and listed in a report dialog,
which you can export.
During the restore process, you can choose whether you want to restore rule assignments to users
and user groups in your current configuration set. Reassignment only succeeds if the backed‑up user‑
s/groups are present in your current configuration set/active directory. Any mismatched rules are
restored but remain unassigned. After restore, they are listed in a report dialog which you can export
in CSV format.
3. In Restore from folder, browse to the folder containing the backup file.
• Yes. Restores rules and reassigns them to the same users and user groups in your current
configuration set.
Process management
Process management
Enable Process Management. This option toggles whether process whitelists and blacklists are in
effect. If disabled, none of the settings on the Process BlackList and Process WhiteList tabs take
effect.
Note:
This option works only if the agent is running in the user’s session. To enable the agent to run
in the session, use the Advanced Settings > configuration > Main Configuration tab to enable
the Launch Agent options (at Logon / at Reconnect / for Admins) and set Agent Type to UI.
These options are described in Advanced Settings.
Process blackList
Enable Process Blacklist. This option enables process blacklisting. Add processes by using their
executable names (for example, cmd.exe).
Exclude Local Administrators. Excludes local administrator accounts from the process blacklist.
Exclude Specified Groups. Lets you exclude specific user groups from the process blacklist.
Process whiteList
These settings let you whitelist specific processes. Process blacklists and process whitelists are mutu‑
ally exclusive.
Enable Process Whitelist. This option enables process whitelisting. Add processes by using their
executable names (for example, cmd.exe).
Note:
If enabled, Enable Process Whitelist automatically blacklists all processes not in the whitelist.
Exclude Local Administrators. Excludes local administrator accounts from the process whitelist
(they can run all processes).
Exclude Specified Groups. Lets you exclude specific user groups from the process whitelist (they can
run all processes).
Privilege elevation
Note:
The privilege elevation feature lets you elevate the privileges of non‑administrative users to an admin‑
istrator level necessary for some executables. As a result, the users can start those executables as if
they are members of the administrators group.
Privilege elevation
When you select the Privilege Elevation pane in Security, the following options appear:
• Process Privilege Elevation Settings. Controls whether to enable the privilege elevation fea‑
ture. When selected, enables agents to process privilege elevation settings and other options
on the Privilege Elevation tab become available.
• Do Not Apply to Windows Server OSs. Controls whether to apply privilege elevation settings to
Windows Server operating systems. If selected, rules assigned to users do not work on Windows
Server machines. By default, this option is selected.
• Enforce RunAsInvoker. Controls whether to force all executables to run under the current Win‑
dows account. If selected, users are not prompted to run executables as administrators.
This tab also displays the complete list of rules that you have configured. Click Executable Rules or
Windows Installer Rules to filter the rule list to a specific rule type. You can use Find to filter the list.
The Assigned column displays a check mark icon for assigned users or user groups.
Supported rules
You can configure privilege elevation using two types of rules: executable rules and Windows installer
rules.
• Executable Rules. Rules that include files with .exe and .com extensions associated with an
application.
• Windows Installer Rules. Rules that include installer files with.msi and .msp extensions asso‑
ciated with an application. When you add Windows installer rules, keep the following scenario
in mind:
– Privilege elevation applies only to Microsoft’s msiexec.exe. Make sure that the tool you use
to deploy .msi and .msp Windows installer files is msiexec.exe.
– Suppose that a process matches a specified Windows installer rule and its parent process
matches a specified executable rule. The process cannot get elevated privileges unless the
Apply to Child Processes setting is enabled in the specified executable rule.
After you click the Executable Rules or the Windows Installer Rules tab, the Actions section displays
the following actions available to you:
To add a rule
1. Navigate to Executable Rules or Windows Installer Rules and click Add Rule. The Add Rule
window appears.
• Name. Type the display name of the rule. The name appears in the rule list.
• Description. Type additional information about the rule.
• Apply to Child Processes. If selected, applies the rule to all child processes that the exe‑
cutable starts. To manage privilege elevation at a more granular level, use the following
options:
– Apply only to executables in the same folder. If selected, applies the rule only to
executables that share the same folder.
– Apply only to signed executables. If selected, applies the rule only to executables
that are signed.
– Apply only to executables of the same publisher. If selected, applies the rule only
to executables that share the same publisher information. This setting does not work
with Universal Windows Platform (UWP) apps.
Note:
When you add Windows install rules, the Apply to Child Processes setting is enabled
by default and you cannot edit it.
• Start Time. Lets you specify a time for agents to start applying the rule. The time format
is HH:MM. The time is based on the agent time zone.
• End Time. Lets you specify a time for agents to stop applying the rule. The time format
is HH:MM. From the specified time onward, agents no longer apply the rule. The time is
based on the agent time zone.
• Add Parameter. Lets you restrict privilege elevation to executables that match the speci‑
fied parameter. The parameter works as a match criterion. Make sure that the parameter
you specify is correct. For an example of how to use this feature, see Executables running
with parameters. If this field is empty or contains only blank spaces, the agent applies
privilege elevation to relevant executables whether or not they run with parameters.
• Enable Regular Expressions. Lets you control whether to use regular expressions to fur‑
ther expand the criterion.
5. In the Assignments section, select users or user groups to which you want to assign the rule. If
you want to assign the rule to all users and user groups, select Select All.
Tip:
• You can use the usual Windows selection modifier keys to make multiple selections.
• Users or user groups must already be in the list displayed on the Administration >
Users tab.
• You can choose to assign the rule later (after the rule is created).
6. Click Next.
7. Do either of the following. Different actions are needed depending on the rule type you selected
in the preceding page.
Important:
WEM provides you with a tool named AppInfoViewer to obtain the following information
and more from executable files: publisher, path, and hash. For more information, see Tool
to obtain information for executable files.
• Path. Type the path to the file or folder to which you want to apply the rule. The WEM
agent applies the rule to an executable according to the
executable file path.
• Publisher. Fill out the following fields: Publisher, Product name, File name, and File
version. You cannot leave any of the fields empty, but you can type an asterisk (*) instead.
The WEM agent applies the rule according to publisher information. If applied, users can
run executables that share the same publisher information.
• Hash. Click Add to add a hash. In the Add Hash window, type the file name and the hash
value. You can use the AppInfoViewer tool to create a hash from a selected file or folder.
The WEM agent applies the rule to identical executables as specified. As a result, users can
run executables that are identical to the specified one.
Executables running with parameters You can restrict privilege elevation to executables that
match the specified parameter. The parameter works as a match criterion. To see parameters avail‑
able to an executable, use tools such as Process Explorer or Process Monitor. Apply the parameters
that appear in those tools.
Suppose you want to apply the rule to an executable (for example, cmd.exe) according to the exe‑
cutable file path. You want to apply privilege elevation only to test.bat. You can use Process Ex‑
plorer to get the parameters.
• /c ""C:\test.bat""
• C:\Windows\System32\cmd.exe
In this case, you elevate the privilege of the specified users to an administrator level only for test.
bat .
To assign rules to users Select one or more rules in the list and then click Edit in the Actions section.
In the Edit Rule window, select users or user groups to which you want to assign the rule and then
click OK.
To delete rules Select one or more rules in the list and then click Delete in the Actions section.
To back up privilege elevation rules You can back up all privilege elevation rules in your current
configuration set. All rules are exported as a single XML file. You can use Restore to restore the rules
to any configuration set.
To complete the backup, use the Backup wizard, available in the ribbon. For more information about
using the Backup wizard, see Ribbon.
To restore privilege elevation rules You can restore privilege elevation rules from XML files ex‑
ported through the Workspace Environment Management Backup wizard. The restore process re‑
places the rules in the current configuration set with those rules in the backup. When you switch to or
refresh the Security > Privilege Elevation pane, any invalid privilege elevation rules are detected. In‑
valid rules are automatically deleted and listed in a report that you can export. For more information
about using the Restore wizard, see Ribbon.
Self‑elevation
With self‑elevation, you can automate privilege elevation for certain users without the need to pro‑
vide the exact executables beforehand. Those users can request self‑elevation for any applicable file
simply by right‑clicking the file and then selecting Run with administrator privileges in the context
menu. After that, a prompt appears, requesting that they provide a reason for the elevation. The WEM
agent does not validate the reason. The reason for the elevation is saved to the database for auditing
purposes. If the criteria are met, the elevation is applied, and the files run successfully with adminis‑
trator privileges.
The feature also gives you flexibility to choose the best solution for your needs. You can create allow
lists for the files you permit users to self‑elevate or block lists for files you want to prevent users from
self‑elevating.
Self‑elevation applies to files of the following formats: .exe, .msi, .bat, .cmd, .ps1, and .vbs.
Note:
By default, certain applications are used to run some files. For example, cmd.exe is used to run
.cmd files and powershell.exe is used to run .ps1 files. In those scenarios, you cannot change the
default behavior.
When you select Security > Self‑elevation, the following options appear:
• Enable self‑elevation. Controls whether to enable the self‑elevation feature. Select the option
to:
• Permissions. Lets you create allow lists for the files you permit users to self‑elevate or block
lists for files you want to prevent users from self‑elevating.
– Allow. Creates allow lists for the files you permit users to self‑elevate.
– Deny. Creates block lists for files you want to prevent users from self‑elevating.
• Settings. Lets you configure additional settings that control how agents apply self‑elevation.
• Assignments. Lets you assign the self‑elevation condition to applicable users or user groups.
To assign the condition to all users and user groups, click Select All or select Everyone. The
Select All check box is useful in scenarios where you want to clear your selection and reselect
users and user groups.
WEM supports auditing activities related to privilege elevation. For more information, see Auditing
user activities.
The process hierarchy control feature controls whether certain child processes can be started from
their parent processes in parent‑child scenarios. You create a rule by defining parent processes and
then designating an allow list or a block list for their child processes. Review this entire section before
using the feature.
Note:
• A process is subject to only one rule. If you define multiple rules for the same process, only the
rule with the highest priority is enforced.
• The rule you defined is not restricted only to the original parent‑child hierarchy but also applies
to each level of that hierarchy. Rules applicable to a parent process prevail over rules applicable
to its child processes regardless of the priority of the rules. For example, you define the following
two rules:
With the two rules, you cannot open CMD from Notepad by first opening Word and then opening
Notepad from Word regardless of the priority of the rules.
This feature relies on certain process‑based parent‑child relationships to work. To visualize the parent‑
child relationships in a scenario, use the process tree feature of the Process Explorer tool. For more
information about Process Explorer, see https://docs.microsoft.com/en‑us/sysinternals/downloads/
procmon.
To avoid any potential issues, we recommend that you add an executable file path that points to
VUEMAppCmd.exe in the Full Configuration management interface. VUEMAppCmd.exe ensures that
the WEM agent finishes processing settings before published applications start. Complete the follow‑
ing steps:
1. On the Application node, select the application, click Properties in the action bar, and then go
to the Location page.
2. Type the path of the local application on the end‑user operating system.
• Under the Path to the executable file field, type the following: <%Program‑
Files%>\Citrix\Workspace Environment Management Agent\VUEMAppCmd.exe.
• Under the Command‑line argument field, type the full path to the application that you
want to launch through VUEMAppCmd.exe. Make sure that you wrap the command line
for the application in double quotes if the path contains blank spaces.
• For example, suppose you want to launch iexplore.exe through VUEMAppCmd.exe. You
can do so by typing the following: %ProgramFiles(x86)%\"Internet Explorer
"\iexplore.exe.
Considerations
For the feature to work, you need to use the AppInfoViewer tool on each agent machine to enable
the feature. Every time you use the tool to enable or disable the feature, a machine restart is required.
• You must restart the agent machine after upgrading or uninstalling the agent.
Note:
If you upgrade from or uninstall versions 2103.2.0.1 or 2104.1.0.1, no restart prompt ap‑
pears.
• The automatic agent upgrade feature does not work on agent version 2105.1.0.1 or later. To use
the automatic agent upgrade feature, use the AppInfoViewer tool to first disable the process
hierarchy control feature.
• If you upgrade from versions 2103.2.0.1 or 2104.1.0.1, you must restart the agent machine
after the automatic agent upgrade completes.
To verify that the process hierarchy control feature is enabled, open the Registry Editor on the agent
machine. The feature is enabled if the following registry entry exists:
• 32‑bit OS
– HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\CtxHook\AppInit_Dlls\WEM
Hook
• 64‑bit OS
– HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\CtxHook\AppInit_Dlls\WEM
Hook
– HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Citrix\CtxHook\AppInit_Dlls
\WEM Hook
Important:
On versions 2103.2.0.1 and 2104.1.0.1 of the agent, the process hierarchy control feature might
be automatically enabled. To verify that the process hierarchy control feature is enabled, open
the Registry Editor on the agent machine. If the feature is enabled, you must restart the agent
machine manually after upgrading or uninstalling the agent.
Prerequisites
To use the feature, make sure that the following prerequisites are met:
When you select Process Hierarchy Control in Security, the following options appear:
• Enable Process Hierarchy Control. Controls whether to enable the process hierarchy control
feature. When selected, other options on the Process Hierarchy Control tab become available
and configured settings there can take effect. You can use this feature only in a Citrix virtual
apps deployment.
• Hide Open With from Context Menu. Controls whether to show or hide the Open With op‑
tion from the Windows right‑click context menu. When enabled, the menu option is hidden
from the interface. When disabled, the option is visible and users can use it to start a process.
The process hierarchy control feature does not apply to processes started through the Open
With option. We recommend that you enable this setting to prevent applications from starting
processes through system services that are unrelated to the current application hierarchy.
The Process Hierarchy Control tab also displays the complete list of rules that you have configured.
You can use Find to filter the list. The Assigned column displays a check mark icon for assigned users
or user groups.
To add a rule
1. Navigate to Process Hierarchy Control and click Add Rule. The Add Rule window appears.
• Name. Type the display name of the rule. The name appears in the rule list.
• Description. Type additional information about the rule.
• Add Child Processes to Block List. If selected, lets you define a block list for applicable
child processes after configuring a rule for their parent processes. A block list prohibits
only the processes you specified from running and other processes are allowed to run.
• Add Child Processes to Allow List. If selected, lets you define an allow list for applicable
child processes after configuring a rule for their parent processes. An allow list allows only
the processes you specified to run and other processes are prohibited from running.
Note:
A process is subject to only one rule. If you define multiple rules for the same process, the
rules are enforced in order of priority.
5. In the Priority section, set the priority for the rule. When configuring the priority, consider the
following: The priority determines the order in which the rules you configured are processed.
The greater the value, the higher the priority. Type an integer. If there is a conflict, the rule with
the higher priority prevails.
6. In the Assignments section, select users or user groups to which you want to assign the rule. If
you want to assign the rule to all users and user groups, select Select All.
Note:
• You can use the usual Windows selection keys to make multiple selections.
• Users or user groups must already be in the list displayed on the Administration >
Users tab.
• You can choose to assign the rule later (after the rule is created).
7. Click Next.
8. Do either of the following to configure the rule for parent processes. Different actions are
needed depending on the rule type you selected on the preceding page.
Important:
WEM provides you with a tool named AppInfoViewer to obtain the following information
and more from executable files: publisher, path, and hash. For more information, see Tool
to obtain information for executable files.
• Path. Type the path to the file or folder to which you want to apply the rule for parent
processes. The WEM agent applies the rule to an executable according to the executable
file path. We do not recommend that you type only asterisk (*) in this field to indicate a
path match. Doing that might cause unintended performance issues.
• Publisher. Fill out the following fields: Publisher, Product name, File name, and File
version. You cannot leave any of the fields empty, but you can type an asterisk (*) instead.
The WEM agent applies the rule to parent processes according to publisher information. If
applied, users can run executables that share the same publisher information.
• Hash. Click Add to add a hash. In the Add Hash window, type the file name and the hash
value. You can use the AppInfoViewer tool to create a hash from a selected file or folder.
The WEM agent applies the rule to identical executables as specified. As a result, users can
run executables that are identical to the specified one.
10. Do either of the following to define an allow list or a block list for applicable child processes.
a) Select a rule type from the menu and then click Add. The Child Process window appears.
b) In the Child Process window, configure settings as needed. The user interface of the Child
Process window is different depending on the rule type you selected. For a child process,
the following rule types are available: Path, Publisher, and Hash.
c) Click OK to return to the Add Rule window. You can add more child processes or click
Create to save the rule and to exit the window.
To assign rules to users Select one rule in the list and then click Edit in the Actions section. In
the Edit Rule window, select users or user groups to which you want to assign the rule and then click
OK.
To delete rules Select one or more rules in the list and then click Delete in the Actions section.
To back up rules You can back up all process hierarchy control rules in your current configuration
set. All rules are exported as a single XML file. You can use Restore to restore the rules to any configu‑
ration set.
To complete the backup, use the Backup wizard, available in the ribbon. For more information about
using the Backup wizard, see Ribbon.
To restore rules You can restore process hierarchy control rules from XML files exported through the
Workspace Environment Management Backup wizard. The restore process replaces the rules in the
current configuration set with those rules in the backup. When you switch to or refresh the Security
> Process Hierarchy Control pane, any invalid rules are deleted and listed in a report that you can
export. For more information about using the Restore wizard, see Ribbon.
WEM supports auditing activities related to process hierarchy control. For more information, see Au‑
diting user activities.
WEM supports auditing activities related to privilege elevation and process hierarchy control. To view
the audits, go to the Administration > Logging > Agent tab. On the tab, configure logging settings,
select ElevationControl, Self‑elevation, or ProcessHierarchyControl in the Actions field, and then
click Apply Filter to narrow the logs to specific activities. You can view the entire history of privilege
elevation or process hierarchy control.
More information
For an example of how to configure process hierarchy control, see Protect Citrix Workspace environ‑
ments using process hierarchy control.
Use these pages to specify the users, computers, groups, and organizational units you want Work‑
space Environment Management (WEM) to manage.
Note:
Add users, computers, groups, and OUs to WEM so that the agent can manage them.
Users
A list of your existing users and groups. You can use Find to filter the list by name or ID against a text
string.
After connecting your Citrix Cloud account to your Azure Active Directory (AD), you can also add Azure
AD users and groups. Complete the following steps:
1. Click the down arrow next to Add. The Add Azure AD User window appears.
2. In the Add Azure AD User window, type information in the search bar and then click Search to
display matched users or groups.
3. Select applicable users or groups and then click OK.
For information about connecting Citrix Cloud to Azure AD, see Connect Azure Active Directory to Citrix
Cloud.
Name. The name of the user or group.
Description. Shown only in the Edit Item dialog, letting you specify additional information about the
user or group.
Item Priority. Lets you configure priority between different groups and user accounts. The priority
determines the order in which the actions you assign are processed. Type an integer to specify a pri‑
ority. The greater the value, the higher the priority. If there is a conflict (for example, when mapping
different network drives with the same drive letter), the group or user account with the higher priority
prevails.
Important:
When assigning Group Policy settings, the priority you configure here does not work. To set the
priority for them, use Administration console > Assignments. For more information, see Con‑
Item State. Lets you choose whether a user or group is enabled or disabled. If disabled, you cannot
assign actions to it.
Machines
A list of machines that have been added to the current configuration set. Only machines listed here
are managed by Workspace Environment Management. You can use Find to filter the list by name or
ID against a text string.
When agents on these machines register with the infrastructure service, the infrastructure service
sends them the necessary machine‑dependent settings related to the configuration set. To improve
the user experience, the infrastructure service caches data related to the configuration set for the
agents. Data caching allows the infrastructure service to retrieve data from AD less frequently. The
cache refreshes on an hourly basis. Changing agents to a different configuration set can take some
time to take effect.
Tip:
To check whether agents on these machines are correctly registered with the infrastructure
server, see Agents in the Administration section.
Advanced
Provides settings that control whether to apply settings to agents that are not bound to any configu‑
ration set.
The following settings apply to your entire WEM deployment. They are not associated with any config‑
uration sets. After you enable them, go to the “Unbound Agents”configuration set and then configure
settings there so that you can control how unbound agents behave.
• Apply settings to unbound agents. Lets you apply the settings of the “Unbound Agents”con‑
figuration set to agents that you have not yet added in Active Directory Objects.
– Include unbound non‑domain‑joined agents. Lets you control whether to apply the set‑
tings to unbound non‑domain‑joined agents.
Transformer Settings
General
General settings
These settings control the appearance and basic settings for Transformer.
Enable Transformer. If enabled, Agent Hosts connected to this site automatically goes into kiosk
mode. While in kiosk mode, the Agent Host becomes a web or application launcher that redirects the
user to the configured remote desktop interface. The user environment is locked down and the user
is only allowed to interact with the agent. If you disable this option, none of the settings in either the
General or Advanced pages are processed.
Web Interface URL. This URL is used as the web front end for the user’s virtual desktop. This is the
access URL for your Citrix DaaS (formerly Citrix Virtual Apps and Desktops service) and Citrix Virtual
Apps and Desktops environment.
Custom Title. If enabled, the Workspace Environment Management Agent kiosk window is given a
custom title‑bar.
Enable Window Mode. If enabled, the Workspace Environment Management Agent kiosk starts in
windowed mode. The user is still locked out of their Windows environment.
Allow Language Selection. If enabled, allows users to select what language the Transformer inter‑
face is in.
Show Navigation Buttons. If enabled, the “Forward”, “Back”, and “Home”web navigation buttons
appear in the Agent kiosk window. “Home”sends users back to the web interface URL defined
above.
Show 12 Hour Clock. If enabled, displays a 12‑hour clock (AM/PM). By default, the Transformer clock
is a 24‑hour clock.
Enable Application Panel. If enabled, displays a panel with the user’s applications as assigned in
Workspace Environment Management.
Auto‑Hide Application Panel. If enabled, the application panel auto‑hides itself when not in use.
Change Unlock Password. Allows you to specify the password that can be used to unlock the user’s
environment by pressing Ctrl+Alt+U. This is designed to allow administrators and to support agents
to troubleshoot the user environment without restrictions.
Site settings
Enable Site List. If enabled, adds a list of URLs to the kiosk interface.
Tool settings
Enable Tool List. If enabled, adds a list of tools to the kiosk interface.
Advanced
Process launcher
These options allow you to turn the Workspace Environment Management Agent kiosk mode into a
process launcher rather than presenting a web interface.
Enable Process Launcher. If enabled, puts the Workspace Environment Management agent into
process launcher mode. While in process launcher mode, the Workspace Environment Management
agent launches the process specified in Process Command Line. If terminated, the process is re‑
launched.
Process Command Line. Allows you to enter the command line for a specific process (for example,
the path to mstsc.exe to launch an RDP connection).
Process Arguments. Allows you to specify any arguments to the command line listed above (for ex‑
ample, in the case of mstsc.exe, the IP address of the machine to connect to).
Clear Last Username for VMware View. If enabled, clears the user name of the previous user on the
logon screen when you launch a VMware desktop session.
Enable VMware View Mode. If enabled, allows the process launcher to monitor the virtual appli‑
cations or desktops running on a user’s machine in VMware View mode and to run End of Session
Options when they are all closed.
Enable Microsoft RDS Mode. If enabled, allows the process launcher to monitor the virtual applica‑
tions or desktops running on a user’s machine in Microsoft Remote Desktop Services (RDS) mode and
to run End of Session Options when they are all closed.
Enable Citrix Mode. If enabled, allows the process launcher to monitor the virtual applications or
desktops running on a user’s machine in Citrix mode and to run End of Session Options when they
are all closed.
Fix Browser Rendering. If enabled, forces the kiosk window to run in a browser mode compatible
with the version of Internet Explorer (IE) that is currently installed on agent host machines. By default,
this forces the kiosk window to run in IE7 compatibility mode.
Note:
While configuring the transformer, ignore the Advanced & administration settings.
Log Off Screen Redirection. If enabled, automatically redirects the user to the logon page whenever
they land on the logoff page.
Hide Kiosk While in Citrix Session. If enabled, hides the Citrix Workspace Environment Management
Agent kiosk while the users are connected to their Citrix sessions.
Always Show Admin Menu. If enabled, always displays the kiosk admin menu –this gives all users
access to the kiosk admin menu.
Hide Taskbar & Start Button. If enabled, hides the user’s taskbar and start menu. Otherwise, the
user is still able to access their desktop.
Lock Alt‑Tab. If enabled, ignores alt tab commands, preventing the user from switching away from
the agent.
Fix Z‑Order. If enabled, adds a “hide”button to the kiosk interface that allows the user to push the
kiosk to the background.
Lock Citrix Desktop Viewer. If enabled, switches the desktop viewer to a locked down mode. This
is equivalent to the lockdown that happens when Citrix Workspace app for Windows Desktop Lock is
installed. This allows better integration with local applications. This option works only when all of
the following conditions are met:
• The user logging on to the agent host is not a member of the administrators group.
• The Enable Transformer option on the General Settings tab is enabled.
• The Enable Autologon Mode option on the Logon/Logoff & Power Settings tab is enabled.
Hide Display Settings. If enabled, hides Display under Settings in the Transformer UI.
Hide Keyboard Settings. If enabled, hides Keyboard under Settings in the Transformer UI.
Hide Mouse Settings. If enabled, hides Mouse under Settings in the Transformer UI.
Hide Volume Settings. If enabled, hides Volume under Settings in the Transformer UI.
Hide Client Details. If enabled, hides Client Details under the exclamation mark icon in the Trans‑
former UI. From Client Details, you can see information such as the version number.
Disable Progress Bar. If enabled, hides the embedded web browser progress bar.
Hide Windows Version. If enabled, hides Windows Version under the exclamation mark icon in the
Transformer UI.
Hide Home Button. If enabled, hides the Home icon in the menu in the Transformer UI.
Hide Printer Settings. If enabled, hides the Printer icon in the menu in the Transformer UI. Users are
not able to manage printers in the Transformer UI.
Prelaunch Receiver. If enabled, launches Citrix Workspace app and wait for it to load before bringing
up the kiosk mode window.
Disable Unlock. If enabled, the agent cannot be unlocked through the Ctrl+Alt+U unlock shortcut.
Hide Logoff Option. If enabled, hides Log Off under the shutdown icon in the Transformer UI.
Hide Restart Option. If enabled, hides Restart under the shutdown icon in the Transformer UI.
Hide Shutdown Option. If enabled, hides Shutdown under the shutdown icon in the Transformer
UI.
Ignore Last Language. The Transformer UI supports multiple languages. In the General pane, if the
Allow Language Selection option is enabled, users can select a language for the Transformer UI. The
agent remembers the selected language until this option is enabled.
Enable Autologon Mode. If enabled, users automatically log on to the desktop environment by the
agent, bypassing the Windows logon screen.
Log Off Web Portal When a session is launched. If enabled, the web front end specified in the Gen‑
eral Settings page is logged off when the user’s desktop session is launched.
End of Session Options. Allows you to specify which action the agent takes with the environment
that it is running in when the user ends their session.
Shut Down at Specified Time. If enabled, the agent automatically shuts off the environment that it
is running in at the specified local time.
Shut Down When Idle. If enabled, the agent automatically shuts off the environment that it is running
in after running idle (no user input) for the specified length of time.
Don’t Check Battery Status. In Transformer use cases, the agent checks battery status and alerts the
user if the battery is running low. If enabled, the agent does not perform this check.
Advanced Settings
November 1, 2023
These settings modify how and when the agent processes actions.
Configuration
Main configuration
Agent Actions. These settings determine whether the agent processes actions configured in the Ac‑
tions tab. These settings apply on logon, and on refresh ‑ automatic or manual refresh (user or admin‑
istrator triggered).
Process Network Drives. When selected, the agent processes network drives actions.
Process Virtual Drives. When selected, the agent processes virtual drive actions. (Virtual drives are
Windows virtual drives or MS‑DOS device names which map a local file path to a drive letter.)
Process Registry Values. When selected, the agent processes registry entry actions.
Process Environment Variables. When selected, the agent processes environment variable
actions.
Process Ini Files Operations. When selected, the agent processes .ini file actions.
Process External Tasks. When selected, the agent processes external task actions.
Process File System Operations. When selected, the agent processes file system operation
actions.
Process File Associations. When selected, the agent processes file association actions.
Process User DSNs. When selected, the agent processes user DSN actions.
Agent Service Actions. These settings control how the agent service behaves on endpoints.
Launch Agent on Reconnect. Controls whether the agent runs when a user reconnects to a machine
where the agent is running.
Launch Agent for Admins. Controls whether the agent runs when a user is an administrator.
Agent Type. Controls whether a user is presented with a user interface (UI) or a command‑line prompt
(CMD) when interacting with the agent.
Enable (Virtual) Desktop Compatibility. Ensures that the agent is compatible with desktops where
it is running. This setting is necessary for the agent to launch when the user logs on to a session. If
you have users on physical or VDI desktops, select this option.
Execute Only CMD Agent in Published Applications. If enabled, the agent launches in CMD mode
rather than in UI mode in published applications. CMD mode displays a command prompt instead of
an agent splash screen.
Cleanup actions
Options present on this tab control whether the agent deletes the shortcuts or other items (network
drives and printers) when the agent refreshes. If you assign actions to a user or user group, you might
find that you can also control the creation of the shortcuts or items. You can do so by configuring the
options for the actions in the Assigned pane of the Assignments > Action Assignment > Action As‑
signment tab. Workspace Environment Management processes these options according to a specific
priority:
For example, suppose you have enabled the Create Desktop option for the assigned application in
the Assigned pane, and the application shortcut is already created on the desktop. The shortcut is still
on the desktop when the agent refreshes, even though you enabled the Delete Desktop Shortcuts
option on the Cleanup Actions tab.
Shortcut Deletion at Startup. The agent deletes all shortcuts of the selected types when it
refreshes.
Delete Network Drives at Startup. If enabled, the agent deletes all network drives whenever it re‑
freshes.
Delete Network Printers at Startup. If enabled, the agent deletes all network printers whenever it
refreshes.
Preserve Auto‑created Printers. If enabled, the agent does not delete auto‑created printers.
Preserve Specific Printers. If enabled, the agent does not delete any of the printers in this list.
Agent options
Log File. The log file location. By default, this is the profile root of the logged‑in user.
Enable Offline Mode. If disabled, the agent does not fall back on its cache when it fails to connect to
the infrastructure service.
Use Cache Even When Online. If enabled, the agent always reads its settings and actions from its
cache (which is built whenever the agent service cycles).
Use Cache to Accelerate Actions Processing. If enabled, the agent processes actions by retrieving
relevant settings from the agent local cache instead of from the infrastructure services. Doing so
speeds up the processing of actions. By default, this option is enabled. Disable this option if you
want to revert to the previous behavior.
Important:
• The agent local cache is synchronized with the infrastructure services on a periodic basis.
Therefore, changes to action settings take some time to take effect, depending on the value
that you specified for the Agent Cache Refresh Delay option (on the Advanced Settings >
Configuration > Service Options tab).
• To reduce delays, specify a lower value. For the changes to take effect immediately, navi‑
gate to the Administration > Agents > Statistics tab, right‑click the applicable agent, and
then select Refresh Cache in the context menu.
• We recommend that you do not disable this setting. Otherwise, users might have a de‑
graded user experience in scenarios with poor network connectivity. If disabled, actions
you configured through the administration console might fail to be applied on the agent
hosts in scenarios where there is a high volume of traffic to the WEM service.
Refresh Environmental Settings. If enabled, the agent triggers a refresh of user environment set‑
tings when an agent refresh occurs. For information about environment settings, see Environmental
Settings.
Refresh System Settings. If enabled, the agent triggers a refresh of Windows system settings (for
example, Windows Explorer and Control Panel) when an agent refresh occurs.
Refresh When Environmental Settings Change. If enabled, the agent triggers a Windows refresh on
endpoints when any environment setting changes.
Refresh Desktop. If enabled, the agent triggers a refresh of desktop settings when an agent refresh
occurs. For information about desktop settings, see Desktop.
Refresh Appearance. If enabled, the agent triggers a refresh of Windows theme and desktop wallpa‑
per when an agent refresh occurs.
Asynchronous Printer Processing. If enabled, the agent processes printers asynchronously, without
awaiting the completion of the processing of other actions.
Asynchronous Network Drive Processing. If enabled, the agent processes network drives asynchro‑
nously, without awaiting the completion of the processing of other actions.
Initial Environment Cleanup. If enabled, the agent cleans up the user environment during the first
logon. Specifically, it deletes the following items:
– With Preserve Auto‑created Printers on the Cleanup Actions tab enabled, the agent
does not delete auto‑created printers.
– With Preserve Specific Printers on the Cleanup Actions tab enabled, the agent does not
delete any of the printers specified in the list.
• All network drives except the network drive that is the home drive.
• All non‑system desktop, Start menu, Quick Launch, and Start‑button‑context‑menu shortcuts.
• All taskbar and Start menu pinned shortcuts.
Initial Desktop UI Cleanup. If enabled, the agent cleans up the session desktop during the first logon.
Specifically, it deletes the following items:
• All non‑system desktop, Start menu, Quick Launch, and Start‑button‑context‑menu shortcuts.
• All taskbar and Start menu pinned shortcuts.
Check Application Existence. If enabled, the agent does not create a shortcut unless it confirms that
the application exists on the machine the user signs in to.
Expand App Variables. If enabled, variables are expanded by default (see Environment variables for
normal behavior when the agent encounters a variable).
Enable Cross‑Domain User Group Search. If enabled, the agent queries user groups in all Active
Directory domains. Note: This is a time‑intensive process. Select this option only if necessary.
Broker Service Timeout. The timeout value after which the agent switches to its own cache, when it
fails to connect to the infrastructure service. The default value is 15000 milliseconds.
Directory Services Timeout. The timeout value for directory services on the Agent Host machine,
after which the agent uses its own internal cache of user group associations. The default value is
15000 milliseconds.
Network Resources Timeout. The timeout value for resolving network resources (network drives or
file/folder resources located on the network), after which the agent considers the action has failed.
The default value is 500 milliseconds.
Agent Max Degree of Parallelism. The maximum number of threads the agent can use. Default value
is 0 (as many threads as physically allowed by the processor), 1 is single‑threaded, 2 is dual‑threaded,
and so on. Usually, this value does not need changing.
Enable Notifications. If enabled, the agent displays notification messages on the agent host when
the connection to the infrastructure service is lost or restored. Citrix recommends that you do not
enable this option on poor‑quality network connections. Otherwise, connection state change notifi‑
cations might appear frequently on the endpoint (agent host).
Advanced options
Enforce Execution of Agent Actions. If these settings are enabled, the Agent Host always refreshes
those actions, even if no changes have been made.
Revert Unassigned Actions. If these settings are enabled, the Agent Host deletes any unassigned
actions when it next refreshes.
Automatic Refresh. If enabled, the Agent Host refreshes automatically. By default, the refresh delay
is 30 minutes.
Reconnection actions
Action Processing on Reconnection. These settings control what actions the Agent Host processes
upon reconnection to the user environment.
Advanced processing
Filter Processing Enforcement. If enabled, these options force the Agent Host to reprocess filters at
every refresh.
Service options
Agent Cache Refresh Delay. This setting controls how long the Citrix WEM Agent Host Service waits
to refresh its cache. The refresh keeps the cache in sync with the WEM service database. The default
is 30 minutes. When using this option, keep the following in mind:
• The minimum interval at which the cache synchronizes with the WEM service database is 15
minutes. Type an integer that is equal to or greater than 15 minutes.
• The actual sync interval might vary. Based on the specified value, the WEM agent calculates
an interval in which a random value is selected as the actual sync interval each time the agent
cache refresh delay times out. For example, you set the value to 30 minutes. The agent selects
a random value from this interval: [(30 –30/2), (30 + 30/2)].
SQL Settings Refresh Delay. This setting controls how long the Citrix WEM Agent Host Service waits
to refresh its SQL connection settings. The default is 15 minutes. Type an integer that is equal to or
greater than 15 minutes.
Agent Extra Launch Delay. This setting controls how long the Citrix WEM Agent Host Service waits to
launch the agent host executable. The default is 0.
Tip:
In scenarios where you want the agent host to complete the necessary work first, you can specify
how long the agent application launcher (VUEMAppCmd.exe) waits. VUEMAppCmd.exe ensures
that the agent host finishes processing an environment before Citrix DaaS (formerly Citrix Vir‑
tual Apps and Desktops service) and Citrix Virtual Apps and Desktops published applications are
started. To specify the wait time, configure the VUEMAppCmd extra sync delay setting, available
in the Agent Host Configuration group policy. For more information, see Install and configure
the agent.
Enable Debug Mode. This enables verbose logging for all Agent Hosts connecting to this site.
Bypass ie4uinit Check. By default, the Citrix WEM Agent Host Service awaits ie4uinit to run before
launching the Agent Host executable. This setting forces the Agent Host service to not wait for
ie4uinit.
Agent Launch Exclusions. If enabled, the Citrix WEM Agent Host is not launched for any user belong‑
ing to the specified user groups.
Console settings
Forbidden Drives. Any drive letter added to this list is excluded from the drive letter selection when
assigning a drive resource.
Allow drive letter reuse in assignment process. If enabled, a drive letter used in an assignment is
still available for use by other assignments.
StoreFront
Use this tab to add a StoreFront store to Workspace Environment Management service. You can then
navigate to the Actions > Applications > Application List tab to add applications available in those
stores. Doing so lets you assign published applications as application shortcuts to endpoints. For
more information, see Applications. In Transformer (kiosk) mode, assigned StoreFront application
actions appear on the Applications tab. For more information about StoreFront stores, see StoreFront
documentation.
To add a store
1. Click Add.
2. Enter details in the Add Store dialog, then click OK. The store is saved in your configuration set.
Store URL. The URL of the store on which you want to access resources using Workspace Environment
Management. Specify the URL in this form: http[s]://hostname[:port]. The host name is the
FQDN of the store and the port is the port used for communication with the store if the default port
for the protocol is not available.
Important:
• The store URL you use must be directly accessible from external networks, and must not be
behind any solutions such as Citrix ADC.
• This feature does not work with StoreFront using multifactor authentication.
To edit a store Select a store in the list and click Edit to change the store URL or description.
To remove a store Select a store in the list and click Remove to remove a store from your configu‑
ration set.
To apply changes Click Apply to apply store settings immediately to your agents.
Wake on LAN
Use this tab to remotely turn on agent hosts. WEM automatically selects agents that reside on the
same subnet as the target agents and uses those agents as Wake on LAN messengers. This feature
requires hardware compatible with Wake on LAN. To use this feature, verify that the target machines
satisfy the hardware requirements and relevant BIOS settings are configured.
Enable Wake on LAN for Agents. Controls whether to configure settings on Windows operating sys‑
tems to enable Wake on LAN for the agent hosts. If selected, the agents configure the following system
settings:
After enabling this option, navigate to the Administration > Agents > Statistics tab, select one or
more agents from the list, and then click Wake Up Agents to wake up your selected agents.
UI agent personalization
These options let you personalize the look and feel of the agent in UI mode. These options determine
how the UI agent appears in the user environment.
Note:
These options apply only to the agent in UI mode. They do not apply to the agent in CMD mode.
UI agent options
These settings let you customize the appearance of the session agent (in UI mode only) in the user’s
environment.
Custom Background Image Path. If specified, displays a custom splash screen instead of the Citrix
Workspace Environment Management logo when the agent launches or refreshes. The image must
be accessible from the user environment. We recommend that you use a 400*200 px .bmp file.
Loading Circle Color. Lets you modify the color of the loading circle to fit your custom background.
Text Label Color. Lets you modify the color of the loading text to fit your custom background.
UI Agent Skin. Lets you select a preconfigured skin you want to use for dialogs that open from the
UI agent. For example, the Manage applications dialog and the Manage Printers dialog. Note: This
setting does not change the splash screen.
Hide Agent Splashscreen. If enabled, hides the splash screen when the agent is loading or refreshing.
This setting does not take effect the first time the agent refreshes.
Hide Agent Icon in Published Applications. If enabled, published applications do not display the
agent icon.
Hide Agent Splashscreen in Published Applications. If enabled, hides the agent splash screen for
published applications where the agent is running.
Only Admins Can Close Agent. If enabled, only administrators can exit the agent. As a result, the
Exit option in the agent menu is disabled on endpoints for non‑administrators.
Allow Users to Manage Printers. If enabled, the Manage Printers option in the agent menu is avail‑
able to users on endpoints. Users can click the option to open the Manage printers dialog to configure
a default printer and to modify print preferences. By default, the option is enabled.
Allow Users to Manage Applications. If enabled, the Manage Applications option in the agent menu
is available to users on endpoints. Users can click the option to open the Manage applications dialog
and configure the following options. By default, the option is enabled.
• Start Menu. Creates the application shortcut in the Start menu folder.
Prevent Admins From Closing Agent. If enabled, administrators cannot exit the agent.
Enable Applications Shortcuts. If enabled, controls whether to display the My Applications option
in the agent menu. Users can run applications from the My Applications menu. By default, the option
is enabled.
Disable Administrative Refresh Feedback. If enabled, this option does not display a notification
in the user environment when an administrator forces an agent refresh through the administration
console.
Allow Users to Reset Actions. Controls whether to display the Reset Actions option in the agent
menu. By default, the option is disabled. The Reset Actions option lets current users specify what
actions to reset in their environment. After a user selects Reset Actions, the Reset actions dialog
appears. In the dialog, the user can have granular control over what to reset. The user can select
applicable actions and then click Reset. Doing so purges the corresponding action‑related registry
entries.
Note:
• The following two options are always available in the agent menu: Refresh and About. The
Refresh option triggers an immediate update of the WEM agent settings. As a result, set‑
tings configured in the administration console take effect immediately. The About option
Helpdesk options
Help Link Action. Controls whether the Help option is available to users on endpoints and what
happens when a user clicks it. Type a website link through which users can ask for help.
Custom Link Action. Controls whether to display the Support option in the agent menu and what
happens when a user clicks it. Type a website link through which users can access support‑related
information.
Enable Screen Capture. Controls whether to display the Capture option in the agent menu. Users
can use the option to open a screen capture tool. The tool provides the following options:
Enable Send to Support Option. Controls whether to display the Send to support option in the
screen capture tool. If enabled, users can use the option to send screenshots and log files directly to
the specified support email address, in the specified format. This setting requires a working, config‑
ured email client.
Custom Subject. If enabled, lets you specify an email subject template that the screen capture tool
uses to send support emails.
Email Template. Lets you specify an email content template that the screen capture tool uses to send
support emails. This field cannot be empty.
Note:
For a list of hash‑tags that you can use in the email template, see Dynamic tokens.
Users are only presented with the option to enter a comment if the ##UserScreenCaptureCom‑
ment## hash‑tag is included in the email template.
Use SMTP to Send Email. If enabled, sends a support email using SMTP instead of MAPI.
Test SMTP. Tests the SMTP settings as typed above to verify that they are correct.
Power saving
Shut Down At Specified Time. If enabled, lets the agent automatically shuts down the machine
where it is running at the specified time. The time is based on the agent time zone.
Shut Down When Idle. If enabled, lets the agent automatically shut down the machine where it is
running after the machine remains idle (no user input) for the specified length of time.
Administration
Users
Statistics
This page displays a summary of users whose agent hosts have connected to the database.
Users Summary. Displays a count of total users who have reserved a WEM license, for both the current
site (configuration set) and all sites (configuration sets). Also displays a count of new users in the last
24 hours and in the last month.
Users History. This displays connection information for all the users associated with the current site
(configuration set), including the last connection time (in Coordinated Universal Time, UTC), the name
of the machine from which they last connected and the session agent type (UI or CMD) and version.
You can use Find to filter the list by name or ID against a text string.
Agents
This page displays statistics about the agents in your WEM deployment.
Statistics
This page displays a summary of the WEM agents recorded in the WEM database.
Agents Summary. Displays a count of total agents that have reserved a WEM license, for both the
current configuration set and all configuration sets. It also reports agents added in the last 24 hours
and in the last month.
Agents History. Displays connection information for all agents registered with the configuration set,
including the last connection time, the name of the device from which they last connected, and the
agent version. You can use Find to filter the list by name or ID.
In the Synchronization State column, the following icons indicate the result of the last synchroniza‑
tion of the agent cache with the WEM service.
• Successful (check mark icon). Indicates that the last synchronization was successful, with the
synchronization result reported to the administration console.
In the Profile Management Health Status column, you can view the health status of Profile Manage‑
ment on your deployment.
Profile Management health status performs automated status checks on your agent hosts to de‑
termine whether Profile Management is configured optimally. You can view the results of these
checks to identify specific issues from the output file on each agent host (%systemroot%\temp\
UpmConfigCheckOutput.xml). The feature performs status checks every day or each time the
WEM agent host service starts. To perform the status checks manually, right‑click the selected agent
in the administration console, and then select the Refresh Profile Management Configuration
Check in the context menu. Each status check returns a status. To view the most recent status, click
Refresh. The icon in the Profile Management Health Status column provides general information
about the health status of Profile Management:
• Good (check mark icon). Indicates that Profile Management is in good shape.
• Warning (triangle exclamation point icon). Informs about a suboptimal state of Profile Manage‑
ment. The suboptimal settings might affect the user experience with Profile Management in
your deployment. This status does not necessarily require action on your part.
• Error (X icon). Indicates that Profile Management is configured incorrectly, causing Profile Man‑
agement not to function properly.
• Unavailable (question mark icon). This icon appears when Profile Management is not found or
not enabled.
If the status checks do not reflect your experience or if they do not detect the issues you are having,
contact Citrix Technical Support.
In the Recently Connected column, the following icon indicates that the agent uploaded statistics to
the WEM service within a certain interval. The agent is online. A blank column field indicates that the
agent is offline.
Clear Expired Records. Lets you delete the expired records from the WEM service database. If a user’
s last logon time dates back more than 24 hours, the corresponding record expires.
To refresh agents When you refresh an agent it communicates with the infrastructure server. The
infrastructure server validates the agent host identity with the WEM database.
Options in the context menu When applying the options to non‑domain‑joined and enrolled
agents, consider the following:
Currently, applying these options to non‑domain‑joined and enrolled agents is not supported.
Refresh Cache. Triggers a refresh of the agent local cache (an agent‑side replica of the WEM config‑
uration database). Refreshing the cache synchronizes the agent local cache with the infrastructure
services.
Refresh Agent Host Settings. Applies the agent service settings. Those settings include advanced
settings, optimization settings, transformer settings, and other non‑user assigned settings.
Refresh Workspace Agents. Applies the user‑assigned actions to the WEM agents. Those actions
include network drives, printers, applications, and more.
Important:
• The Refresh Workspace Agents option works only with the agents in UI mode that are
automatically launched (not launched by end users or by using scripts). The option does
not work with the agents in CMD mode.
• Not all settings can be refreshed. Some settings (for example, environment settings and
group policy settings) are applied only on startup or logon.
If the settings are not applied to the agent after configuring Reset Profile Management Settings
from the WEM administration console, see CTX219086 for a workaround.
Reset Microsoft USV Settings. Clears the registry cache and updates the associated configuration
settings. If Microsoft USV Settings are not applied to your agent, click Reset Microsoft Usv Settings,
and then click Refresh.
Refresh Profile Management Configuration Check. Performs status checks on your agent hosts to
determine whether Profile Management is configured optimally.
Delete Record. Enables deletion of the agent record from the database. If the agent is still active, this
option is grayed out.
Reset Actions. Lets you reset all actions you assigned by purging all action‑related registry entries on
the applicable machine.
Process Citrix Optimizer. Applies the settings to the agents so that changes to Citrix optimizer set‑
tings take effect immediately.
The refresh operations described earlier in this section can also be performed on the agent side. How‑
ever, those operations behave differently depending on actual conditions. For more information, see
Agent‑side refresh operations.
Upgrade Agent to Latest Version. Lets you upgrade the agent to the last version. The time at which
you perform an agent upgrade determines the latest version of the agent. To see the latest agent
version, go to the WEM service Utilities tab.
Registrations
This page shows the registration status of the WEM agents recorded in the database.
Important:
WEM agents must register with the WEM service so that settings can be applied to them. An agent
can be bound only to one configuration set.
State. Registration status of agent on the agent host computer, indicated by icons and the following
description giving more information about registration success or failure:
Agent is not bound to any site. The infrastructure server cannot resolve any site (configuration set)
for this agent because the agent is not bound to any site (configuration set).
Agent is bound to one site. The infrastructure server is sending the necessary machine‑dependent
settings to the agent for that site (configuration set).
Agent is bound to multiple sites. The infrastructure server cannot resolve a site (configuration set)
for this agent because the agent is bound to more than one site (configuration set).
• edit the Active Directory hierarchy (relations between computers, computer groups, and OUs)
OR
• edit the WEM hierarchy (in the Active Directory Objects section of the administration console)
so that a computer binds to only one site (configuration set).
After making these changes, refresh agents with the infrastructure server.
Logging
Administrative
This tab displays a list of all changes made to the WEM settings in the database. By default, the log is
unpopulated until the log is refreshed manually.
Filtering Options. These options allow you to filter the log by site (configuration set), and date
range.
Clear Log. Clears the log for all configuration sets. This cannot be undone. Clearing the log adds one
event in the new log indicating this has been done. This option is only available to Global Full Access
administrators.
Agent
This tab lists all changes made to your WEM agents. The log is unpopulated until you click Refresh.
Filtering Options. These options allow you to filter the log by site (configuration set), and date
range.
Clear Log. Clears the log for all configuration sets. This cannot be undone. Clearing the log adds one
event in the new log indicating this has been done. This option is only available to Global Full Access
administrators.
Monitoring
July 3, 2023
These pages contain detailed user login and machine boot reports.
Daily reports
Daily Login Report. A daily summary of login times across all users connected to this site. You can
double‑click a category for a detailed view showing individual logon times for each user on each de‑
vice.
Daily Boot Report. A daily summary of boot times across all devices connected to this site. You can
double‑click a category for a detailed view showing individual boot times for each device.
User trends
Login Trends Report. This report displays overall login trends for each day over the selected period.
You can double‑click each category of each day for a detailed view.
Boot Trends Report. This report displays overall boot trends for each day over the selected period.
You can double‑click each category of each day for a detailed view.
Device Types. This report displays a daily count of the number of devices of each listed operating
system connecting to this site. You can double‑click each device type for a detailed view.
User Report. This report allows you to view login trends for a single user over the selected period.
You can double‑click each data point for a detailed view.
Device Report. This report allows you to view boot trends for a single device over the selected period.
You can double‑click each data point for a detailed view.
This feature monitors profile containers for Profile Management and FSLogix. It provides insights into
the basic usage data of the profile containers, the status of sessions using the profile containers, the
issues detected, and more. Use this feature to stay on top of space usage for profile containers and to
identify problems that prevent profile containers from working.
Summary
• Used Space. The chart on the left side shows the space usage of profile containers over the
specified time period.
• Session Status. The chart on the right side shows results of attaching profile containers for
sessions established over the specified time period.
After specifying the time period (for example, last 6 days), click Refresh to trigger a refresh of the
charts.
High when used space is more than (GB). Lets you type a threshold value above which to treat the
space usage of the profile containers as high. Type a positive integer.
Low when used space is less than (GB). Lets you type a threshold value below which to treat the
space usage of the profile containers as low. Type a positive integer.
Note:
• The high threshold value must be greater than the low threshold value.
• After specifying the high and the low threshold values, click Refresh to trigger a refresh of
the Used Space chart.
• After specifying the high and the low threshold values, space usage in between defaults to
Medium.
Displays a list of status records for profile containers over a specified time period. After specifying the
time period (for example, last 6 days), click the Refresh button to filter records.
You can trigger the collection of data for the container the selected record pertains to. Doing so brings
you up to date with the user’s container status. To achieve that, right‑click a status record and then
select Refresh. The refresh operation results in a sequence of tasks. First, a task is immediately sent
to the associated agent host. The agent receives the task and then collects status‑related data if the
container is in use on the agent host. Then, the latest attach record is updated with the collected data.
It might take a while for the status to be updated. Click the Refresh button for the up‑to‑date record
to appear.
The Status column displays information about status and error codes. For information about error
codes, see the Microsoft documentation at https://docs.microsoft.com/en‑us/fslogix/fslogix‑error‑
codes‑reference.
Configuration
Report options
These options allow you to control the reporting period and work days. You can also specify minimum
Boot Time and Login Time (in seconds) below which values are not reported.
March 2, 2022
Use Manage > Web Console to configure WEM settings. The console consists of two panes:
• The left‑hand pane (navigation pane), which displays quick navigation nodes. The following
nodes are available:
– Home. Provides an overview of your WEM deployment along with information necessary
for you to get to know and get started with WEM quickly.
– Configuration Sets. Displays a list of configuration sets.
– Directory objects. Lets you add machines, groups, OUs, and more, that you want WEM to
manage.
– Monitoring. Displays a dashboard to monitor and troubleshoot your WEM deployment
and lets you perform administrative tasks. Click the node to display more items.
– Files. Lets you manage all your files on your cloud storage in one place.
– Scripted Tasks. Lets you add scripted tasks that you customize to suit your unique envi‑
ronment management needs. You can then automate those tasks with WEM by configuring
them in the applicable configuration set.
• The right‑hand pane, which displays details related to the node you are on.
For information about the settings you can use with the web console, see user interface description
(web console).
Home page
This page provides an overview of your Workspace Environment Management (WEM) deployment
along with information necessary for you to get to know and get started with WEM quickly.
The interface comprises the following four parts:
• Overview
• Quick access
• Highlights
• Preview features
Overview
Provides an overview of your WEM deployments, which includes the following information:
To view agents in detail, click View agent statistics to go to Monitoring > Administration > Agents,
where you can view agent information and perform administrative tasks such as refreshing the cache,
customizing settings, and retrieving agent information. For more information, see WEM agents.
To view VDA health status in detail, click View under Normal to see reports about VDAs in normal state
or click View under Unusual to see reports about VDAs in unusual state. For more information, see
Reports.
Quick access
Provides quick access to a subset of the key features that WEM offers. The following features are avail‑
able in the web console:
• Optimize resource utilization. Lets you reduce user logon times and make applications more
responsive.
• Gain insights. Lets you gain insights into profile container and application behavior.
• Configure scripted tasks. Lets you customize scripted tasks to suit your unique environment
management needs.
Tip:
When you click the quick access link, a window appears, prompting you to select the ap‑
plicable configuration set. You are then directly taken to the feature page within the con‑
figuration set.
• Optimize profile management. Lets you provide a unified experience across all user desktops.
• Assign group policies. Lets you assign Group Policy Objects to different Active Directory groups,
just like you assign other actions.
• Enforce enterprise security. Lets you protect desktops by applying additional AppLocker
rules.
Highlights
Shows the key features that WEM offers. The following features are available in the web console:
• CPU management
• Scripted tasks
• Privilege elevation
• External tasks
Preview features
Shows features that are currently in preview. To see preview features, click the preview features icon in
the upper‑right corner of the console. A red dot appears each time new preview features are available.
You see the following tooltip when there are no preview features to show: No preview features
to show at the moment.
Preview features might not be fully localized and are recommended for use in non‑production envi‑
ronments. Issues found with preview features are not supported by Citrix Technical Support.
After you enable or disable preview features, refresh your browser window for the change to take ef‑
fect.
Configuration Sets
This page lets you manage your configuration sets. A configuration set is a logical container used to
organize a set of Workspace Environment Management (WEM) configurations. You can perform the
following operations:
Note:
• For Default Site, you cannot delete it. You can change its name and description if neces‑
sary.
• For Unbound Agents, you cannot delete or edit it. The Edit configuration set option is
unavailable.
You create a configuration set to apply settings to directory objects (users, machines, groups, and
OUs). To do so, perform the following steps:
3. Optionally, specify additional information to help you identify the configuration set.
4. Click Save.
2. Click the configuration set. The details view of the configuration set appears.
Note:
• System Optimization
• Advanced Settings
• Scripted Task Settings
The Backup and restore page displays a list of your existing backups. There are two types of back‑
ups: automatic backup and manual backup (configuration set and settings). You can differentiate
automatic backups from manual backups by the Content type column.
• Restore. Lets you restore a configuration from the backup. Restoring a configuration from
a backup replaces all settings related to the selected configuration set with those from the
backup.
Note:
– To restore Profile Management settings to a configuration set, you can also use the
quick setup feature on the Profiles > Profile Management Settings page under that
configuration set.
– When restoring Profile Management settings from a backup, the SMB shares selected
for relevant services to use are also restored.
• Download. Lets you save a copy of the backup to your local machine. The backup is saved to
the default download location of your browser. The backup file is in JSON format.
• Click the Refresh icon next to the Upload button to refresh the current page
You can upload a JSON file used to revert to a previous backup. A JSON file can contain a configuration
set or Profile Management settings. To upload a file, perform the following steps:
2. Click Browse, browse to the file you want to upload, select the file, and then click Open. You
are returned to the Upload backup file wizard.
Note:
You can save a backup of a configuration set automatically. The feature supports storing up to 25
backup files for each configuration set before starting to overwrite the oldest existing file. You cannot
back up the following items related to a configuration set:
• Directory objects related to machines (single machines, machine groups, and OUs)
• Process management
1. Click Manage automatic backup. The Manage automatic backup wizard appears.
3. Select one of the following three options for that configuration set.
Important:
We limit the number of manual backups to 25 per account. If you have reached the limit, delete
existing backups and try again.
You can save a backup copy of your configuration set and then use the backup for restore purposes.
You can back up the following items related to a configuration set:
• Actions
• Directory objects related to machines (single machines, machine groups, and OUs)
• Monitoring data (statistics and reports)
• Process management
• Agents registered with the configuration set
3. Select from the list the configuration set you want to back up.
5. Optionally, select Save a copy of the backup to your local machine to save the backup locally.
Note:
Important:
We limit the number of manual backups to 25 per account. If you have reached the limit, delete
existing backups and try again.
6. Optionally, select Save a copy of the backup to your local machine to save the backup locally.
Note:
Actions
Tip:
• You can use dynamic tokens to extend WEM actions to make them more powerful.
• To paste data copied from WEM Tool Hub into the web console, ensure that the browser
allows data copying. Example: For Microsoft Edge, be sure to have the Site permissions
> Clipboard > Ask when a site wants to see text and images copied to the clipboard
option enabled.
Workspace Environment Management (WEM) streamlines the workspace configuration process by pro‑
viding 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.
Important:
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.
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 do the fol‑
lowing operations:
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.
• 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 set‑
tings.
• Exported registry file. Select this option if you want to import settings from registry files
you export using the Windows Registry Editor.
Note:
You can upload only files whose size doesn’t exceed 10 MB.
After the import completes successfully, imported GPOs appear on the Registry‑based tab.
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.
• 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.
• 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 op‑
erating 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.
1. Select the GPO and then click Edit in the action bar.
• 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.
Note:
Manage assignments for a GPO 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.
1. Select the GPO and then click Manage assignments in the action bar.
2. Select assignment targets (users, groups, and OUs) to assign the GPO to.
Note:
When assigning GPOs to machines, make sure that the machines reside either in OUs or in
relevant security groups.
• To add a new target, click Add new target. For more information, see Add an assignment
target.
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 be‑
fore 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:
• Paste configuration. Lets you paste the configuration you copied from other configura‑
tion.
• Apply this configuration to all targets. Lets you apply the configuration of the assign‑
ment to all targets.
1. Select the GPO and then click Clone in the action bar.
3. Select the configuration set you want to clone the GPO to.
Delete a GPO To delete a GPO, select it and then click Delete in the action bar.
Note:
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 To create a GPO with a template, complete the following steps:
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.
• Select Computer configuration to configure policies that you want to apply to machines (re‑
gardless 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).
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
Important:
When importing ADMX files to WEM for use as templates, ensure that all .adml files in the zip file
are of the same language.
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:
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:
5. After you finish, click Done to return to the Manage template wizard.
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 cur‑
rent template. Existing GPOs created with the templates are not affected. However, when you
edit those GPOs, associated settings are lost.
1. Select the GPO and then click Edit in the action bar.
Note:
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.
1. Select the GPO and then click Clone in the action bar.
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.
4. Select the configuration set you want to clone the GPO to.
Delete a GPO To delete a GPO, select it and then click Delete in the action bar.
Note:
Applications
This feature lets you add applications to assign to your users. When assigned, those applications have
their shortcuts created on the desktop, Start menu, or taskbar, depending on your configuration.
Tip:
You can use the Full Configuration management console of Citrix DaaS to edit the application set‑
tings and then add an executable file path that points to VUEMAppCmd.exe. VUEMAppCmd.exe
ensures that the Workspace Environment Management agent finishes processing an environ‑
ment before Citrix DaaS and Citrix Virtual Apps and Desktops published applications are started.
For more information, see Editing application settings using the Full Configuration management
interface.
• Add an application.
• Refresh the application list.
• Edit an application to manage its properties.
• Manage assignments for an application.
• Clone an application.
• Delete an application.
• Switch to the Start menu view.
• Specify how the agent processes applications.
1. In the web console, go to the relevant configuration set, navigate to Actions > Applications,
and click Add application. See Add an application.
2. Select the application you added and click Manage assignments in the action bar. See Manage
assignments for an application.
The assignment takes some time to take effect, depending on the value you specified for SQL Settings
Refresh Delay in Advanced Settings. For the assignment to take effect immediately, complete the fol‑
lowing steps:
1. Go to Web Console > Monitoring > Administration > Agents > Statistics and select the agent.
2. Click More in the action bar and select Agent > Refresh agent host settings.
Important:
• For the agent to process actions, verify that the following settings are enabled:
– Launch agent on logon (for processing actions on logon)
– Launch agent on reconnection (for processing actions on reconnection)
– Enable desktop compatibility mode
• You can find these settings in Legacy Console > Advanced Settings > Configuration > Main
Configuration > Agent Service Actions.
Add an application
• State. Enable or disable the application or put it into maintenance mode. When in main‑
tenance mode, the application is unavailable for use. Its shortcut icon contains a warning
sign, indicating that it is unavailable.
• Application type. Specify the type of application the shortcut opens. The user interface
differs depending on your selection.
* Application path. Type the full path of the application that resides on the user’s
machine.
* Working folder. Type the full path to a folder on the user’s machine as a working
folder for the application. This field populates automatically after you type the
full path in the Application path field.
* Parameters. Type launch parameters for the application if needed.
• File or folder. Lets you create a shortcut that opens the target file or folder on the user’
s machine when a user clicks the shortcut icon. If selected, prompts you to complete the
following:
• URL. Lets you add the URL of an application. If selected, prompts you to complete the
following:
• Citrix Workspace resource. Lets you add an application from Citrix Workspace. If se‑
lected, prompts you to complete the following:
– Store URL. Type the URL of a StoreFront or Workspace store that contains the resource
you want to start from the application shortcut.
Note:
You can’t open SaaS apps or certain applications of the Citrix Workspace (Store‑
front) resource type on the agent machine.
– Resource. Use WEM Tool Hub > Application Assistant to browse to the target Work‑
space resource. Copy the resource information and paste it here by clicking Paste
resource info. Click Open Application Assistant to open the WEM Tool Hub (if in‑
stalled). To download the WEM Tool Hub, go to Citrix Cloud > WEM service > Utilities.
For more information, see WEM Tool Hub.
• Application icon. Click Change to select a different icon or add a new icon.
– To add a new icon, browse to an .ico file or paste the icon data copied from WEM Tool
Hub > Application Assistant. WEM supports saving up to 100 icons. For more infor‑
mation, see WEM Tool Hub.
• Set icon location on user’s desktop. Specify the target location of the application short‑
cut on the user’s desktop. Values are in pixels. If moved, the shortcut reverts to the speci‑
fied location on next logon.
• Display name. Specify the name of the shortcut. The name appears in the user environ‑
ment.
• Start menu integration. Click Change to specify where to create the application shortcut
on the left side of the Start menu. By default, a new shortcut is created in Programs. In
the Start menu integration window, you can do the following:
To delete custom folders, go to Start menu view in Applications. See Switch to the
Start menu view.
• Hotkey. To set a hotkey, click the input field and press the key combination. Or enter the
combination in the following format (for example): Ctrl + Alt + S
• Enable automatic restore. If enabled, the agent automatically recreates the shortcut (if
moved or deleted) on refresh.
• Hide application from agent menu. Specify whether to show or hide the application in
the agent menu accessible from the user’s machine.
Edit an application
1. In Applications, select the application. If needed, use the search box to quickly find the appli‑
cation.
1. Select the application and then select Manage assignments in the action bar.
2. Select assignment targets (users and groups) to assign the application to.
• To add a new target, click Add new target. For more information, see Add an assignment target.
• Configure a target to specify which filter to use and where to create the application shortcut:
Clone an application
Note:
1. Select the application and then select Clone in the action bar.
3. Select the configuration set you want to clone the application to.
Delete an application
To delete an application, select it and then select Delete in the action bar.
Note:
To switch to the Start menu view, click Start menu view. The view shows where each application
resides in the Start menu folder. You can do the following:
Processing:
StoreFront:
• Add a StoreFront URL and enter a description for it if needed. You need the URL when adding
an application of type “Citrix Workspace resource.”See Add an application.
External tasks
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 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.
• 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.
• Show only triggers that apply to this task. Filter out triggers that do not apply to the
task.
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
– Process started
– Process ended
• 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 en‑
vironments, 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:
1. In External Tasks, select the task. If needed, use the search box to quickly find the task.
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.
• To add a new target, click Add new target. For more information, see Add an assignment
target.
1. Select the task and then select Clone in the action bar.
3. Select the configuration set you want to clone the task to.
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.
Printers
This feature lets you add printers as assignable actions. When assigned, those printers are available
for use within the user’s desktop.
• Add a printer.
• Add printers from a print server.
• Refresh the printer list.
• Edit a printer.
• Manage assignments for a printer.
• Clone a printer.
• Delete a printer.
• Specify how the agent processes printers.
1. In the web console, go to the relevant configuration set, navigate to Actions > Printers, and
click Add printer. See Add a printer.
2. Select the printer you added and click Manage assignments in the action bar. See Manage
assignments for a printer.
The assignment takes some time to take effect. For immediate effect, see Make assignments take
effect immediately.
Add a printer
2. Specify the action type. The interface differs based on the selected action type.
To add printers from a network print server, look for desired printers in WEM Tool Hub > Printer As‑
sistant, copy their information, and then paste it. See WEM Tool Hub.
Edit a printer
1. In Printers, select the printer. If needed, use the search box to quickly find the printer.
2. Click Edit in the action bar.
3. Make changes as needed.
4. After you finish, click Save.
1. Select the printer and then select Manage assignments in the action bar.
2. Select assignment targets (users and groups) to assign the printer to.
• To add a new target, click Add new target. For more information, see Add an assignment
target.
• Configure a target to specify which filter to use and whether to set it as the default printer.
For information about adding filters, see Filters.
Clone a printer
Note:
1. Select the printer and then select Clone in the action bar.
2. Edit the name and description.
3. Select the configuration set you want to clone the printer to.
4. Click Clone to start the clone process.
Delete a printer
To delete a printer, select it and then select Delete in the action bar.
Note:
Processing options:
Network drives
This feature lets you add network drives as assignable actions. When assigned, those network drives
are available for use within the user’s desktop.
You can perform the following operations:
1. In the web console, go to the relevant configuration set, navigate to Actions > Network Drive,
and click Add network drive. See Add a network drive.
2. Select the network drive you added and click Manage assignments in the action bar. See Man‑
age assignments for a network drive.
The assignment takes some time to take effect. For immediate effect, see Make assignments take
effect immediately.
1. In Network Drives, select the network drive. If needed, use the search box to quickly find the
network drive.
1. Select the network drive and then select Manage assignments in the action bar.
2. Select assignment targets (users and groups) to assign the network drive to.
• To add a new target, click Add new target. For more information, see Add an assignment
target.
• Configure a target to specify which filter and drive letter to use. For information about
adding filters, see Filters.
1. Select the network drive and then select Clone in the action bar.
3. Select the configuration set you want to clone the network drive to.
To delete a network drive, select it and then select Delete in the action bar.
Note:
If a network drive is already assigned to users, deleting it will impact those users.
Processing options:
Drive letter:
• Drive letters not to be used for assignment. Any selected drive letter is excluded from the
drive letter selection when assigning a drive resource.
• Allow drive letter reuse in assignment. If enabled, a drive letter used in an assignment is still
available for use by other drives assigned to the same target.
Virtual drives
This feature lets you add virtual drives as assignable actions. When assigned, those virtual drives are
available for use within the user’s desktop.
1. In the web console, go to the relevant configuration set, navigate to Actions > Virtual Drive,
and click Add virtual drive. See Add a virtual drive.
2. Select the virtual drive you added and click Manage assignments in the action bar. See Manage
assignments for a virtual drive.
The assignment takes some time to take effect. For immediate effect, see Make assignments take
effect immediately.
• Set as home drive. If enabled, the network drive is set as the home drive.
1. In Virtual Drives, select the virtual drive. If needed, use the search box to quickly find the virtual
drive.
1. Select the virtual drive and then select Manage assignments in the action bar.
2. Select assignment targets (users and groups) to assign the virtual drive to.
• To add a new target, click Add new target. For more information, see Add an assignment
target.
• Configure a target to specify which filter and drive letter to use. For information about
adding filters, see Filters.
Important:
The Next available and No letter assigned options apply only to network drives.
1. Select the virtual drive and then select Clone in the action bar.
3. Select the configuration set you want to clone the virtual drive to.
To delete a virtual drive, select it and then select Delete in the action bar.
Note:
If a virtual drive is already assigned to users, deleting it will impact those users.
Processing options:
Drive letter:
• Drive letters not to be used for assignment. Any selected drive letter is excluded from the
drive letter selection when assigning a drive resource.
• Allow drive letter reuse in assignment. If enabled, a drive letter used in an assignment is still
available for use by other drives assigned to the same target.
Registry Entries
This feature lets you create, set, delete registry values, and assign them to create or modify registries.
You can add tags to registry entries and assign multiple registry entries at the same time.
1. In the web console, go to the relevant configuration set. Navigate to Actions > Registry entries,
and click Add registry entry. For more details, see Add a registry entry.
2. Select the registry entry that you added and click Manage assignments in the action bar. For
more details, see Manage assignments for a registry entry or multiple registry entries.
The assignment takes some time to take effect. For immediate effect, see Make assignments take
effect immediately.
1. In registry entries, select the registry entry or entries. If needed, use the search box or tag the
list to quickly find the registry entry.
To manage assignments for a registry entry or multiple registry entries, complete the following
steps:
1. Select the registry entry or registry entries and then select Manage assignments in the action
bar. If needed, use the search box or tag list to quickly find the registry entry or registry entries.
Note:
To manage assignments for multiple registry entries, review the registry entries list and then click
Next.
1. Select assignment targets (users and groups) to assign the registry entry.
• To add a new target, click Add new target. For more information, see Add an assignment
target.
• Configure a target to specify which filter to use. For information about adding filters, see
Filters.
Note:
1. Select the registry entry and then select Clone in the action bar.
3. Select the configuration set where you want to clone the registry entry.
You can convert your registry file into registry entries for an assignment. This feature has the following
limitations:
• It supports only registry values under HKEY_CURRENT_USER. With the registry entries feature,
you can assign only registry settings under HKEY_CURRENT_USER.
• It does not support registry values of the REG_BINARY and REG_MULTI_SZ types.
To avoid the limitations, we recommend that you import your registry files to WEM by using the Import
Group Policy settings in Group Policy Settings. For more information, see, Import Group Policy
settings.
To delete a registry entry, select the registry entry and then select Delete in the action bar.
Remove tags
1. Select the registry entries and then select Remove tags in the action bar.
Environment variables
This feature lets you add environment variables as assignable actions. When assigned, those environ‑
ment variables are created or set in the user environment.
1. In the web console, go to the relevant configuration set, navigate to Actions > Environment
Variable, and click Add environment variable. See Add an environment variable.
2. Select the environment variable that you added and click Manage assignments in the action
bar. See Manage assignments for an environment variable.
The assignment takes some time to take effect. For immediate effect, see Make assignments take
effect immediately.
1. In Environment Variables, select the environment variable. If needed, use the search box to
quickly find the environment variable.
2. Click Edit in the action bar.
3. Make changes as needed.
4. After you finish, click Save.
1. Select the environment variable and then select Manage assignments in the action bar.
2. Select assignment targets (users and groups) to assign the environment variable to.
• To add a new target, click Add new target. For more information, see Add an assignment
target.
• Configure a target to specify which filter to use. For information about adding filters, see
Filters.
1. Select the environment variable and then select Clone in the action bar.
2. Edit the name and description.
3. Select the configuration set you want to clone the environment variable to.
4. Click Clone to start the clone process.
To delete an environment variable, select it and then select Delete in the action bar.
Note:
• If an environment variable is already assigned to users, deleting it will impact those users.
Processing options:
More information
Typically, an assignment takes effect after the period of time that you specified for SQL Settings Re‑
fresh Delay in Advanced Settings. For the assignment to take effect immediately, complete the fol‑
lowing steps:
1. Go to Web Console > Monitoring > Administration > Agents > Statistics and select the agent.
2. Click More in the action bar and select Agent > Refresh agent host settings.
Important:
• For the agent to process actions, verify that the following settings are enabled:
– Launch agent on logon (for processing actions on logon)
– Launch agent on reconnection (for processing actions on reconnection)
– Enable desktop compatibility mode
• You can find these settings in Legacy Console > Advanced Settings > Configuration >
Main Configuration > Agent Service Actions.
To back up your Group Policy settings, complete the following steps on your domain controller:
Note:
WEM supports importing zip files that contain multiple GPO backup folders.
For an example of how to configure settings for Windows by using Group Policy Administrative Tem‑
plates, see Configure FSLogix Profile Container using WEM GPO.
Application launcher
Application launcher aggregates all applications you assigned to your users through the administra‑
tion console. Using the tool, users can launch all assigned applications in one place.
Tip:
Your users can directly open the application launcher tool (AppLauncherUtil.exe) in their environment.
The tool is available in the agent installation folder: %ProgramFiles%\Citrix\Workspace
Environment Management Agent\ AppLauncherUtil.exe. After opening the tool, users
see the following, reflecting the applications assigned to them:
• All apps. Shows all assigned applications. Available sorting options: Most recent, A‑Z, and Z‑A.
• Ellipsis icon. There is a Sign out option that lets users sign out of their sessions.
Make sure that the assigned applications are present on the agent machine. If an assigned application
is not installed on the agent machine, the application is shown but unavailable for launch.
For an example of how to use this feature, see Aggregate assigned applications in one place.
• If neither the folder path nor the script name contains blank spaces:
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.
Controls the copying of folders and files into the user’s environment.
Tip:
You can use dynamic tokens to extend Workspace Environment Management actions to make
them more powerful.
A list of your existing file and folder operations. You can use Find to filter the list by name or ID against
a text string.
Fields and controls Name. The display name of the file or folder operation, as it appears in the
list.
Description. Lets you specify additional information about the resource. This field appears only in
the edition or creation wizard.
Filesystem Operation State. Controls whether the file system operation is enabled or disabled.
When disabled, it is not processed by the agent even if assigned to a user.
Source Path. The path to the source file or folder that is copied.
Target Path. The destination path for the source file or folder that is copied.
Overwrite Target if Existing. Controls whether the file or folder operation overwrites existing files or
folders with the same names in the target location. If cleared, and a file or folder with the same name
already exists at the target location, the affected files are not copied.
Run Once. By default, Workspace Environment Management runs a file system operation every time
the agent refreshes. Select this option to let Workspace Environment Management run the operation
only once, rather than on every refresh. This speeds up the agent refresh process, especially if you
have many file system operations assigned to your users.
Action Type. Describes what type of action this file or folder action is: Copy, Delete, Move,
Rename or Symbolic Link operation. For symbolic link creation, you need to give users the
SeCreateSymbolicLinkPrivilege privilege for Windows to allow symbolic link creation.
Execution order. Determines the running order of operations, letting certain operations run before
others. Operations 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.
File type associations (FTAs) that you configure become default associations automatically. How‑
ever, when you open an applicable file, the “How do you want to open this file?”window might
still appear, prompting you to select an application to open the file. Click OK to dismiss the win‑
dow. If you do not want to see a similar window again, do the following: Open the Group Policy
Editor and enable the Do not show the ‘new application installed’notification policy (Com‑
puter Configuration > Administrative Templates > Windows Components > File Explorer).
You can use dynamic tokens to extend Workspace Environment Management actions to make
them more powerful.
• Add FTAs
• Refresh FTAs
• Edit FTAs
• Manage assignments
• Clone FTAs
• Delete FTAs
To add FTAs
Name. The display name of the file association, as it appears in the file association list.
Description. This field is only shown in the edition/creation wizard and allows you to specify addi‑
tional information about the resource.
File Association State. Toggles whether the file association is Enabled or Disabled. When disabled,
it is not processed by the agent even if assigned to a user.
File Extension. The extension used for this file type association. If you select a file name extension
from the list, the ProgID field automatically populates (if the file type is present on the machine where
the administration console is running). You can also type the extension directly. However, for browser
associations, you must type the extension directly. For more information, see Browser association.
ProgID. The programmatic identifier associated with an application (COM). This value automatically
populates when you select a file extension from the list. You can also type the ProgID directly. To
discover the ProgID of an installed application, you can use the OLE/COM Object Viewer (oleview.exe),
and look in Object Classes/Ole 1.0 Objects. For more information about ProgID, see Programmatic
identifier (ProgID).
Action. Lets you select the action type: open, edit, or print.
Target application. Lets you specify the executable used with this file name extension. Type the
full path of the executable. For example, for UltraEdit Text Editor: C:\Program Files\IDM
Computer Solutions\UltraEdit\uedit64.exe
Command. Lets you specify action types that you want to associate with the executable. For exam‑
ple:
Set as Default Action. Toggles whether the association is set as a default for that file name exten‑
sion.
Overwrite. Toggles whether this file association overwrites any existing associations for the specified
extension.
Run Once. By default, Workspace Environment Management (WEM) creates a file association every
time the agent refreshes. Select this option to create the file association once, rather than on every re‑
fresh. This speeds up the agent refresh process, especially if you have many file associations assigned
to your users.
Tip:
You can use File Type Association Assistant data to add them as assignable actions in the man‑
agement console.
1. In File Type Associations, select the required association. If needed, use the search box to
quickly find the required file type association.
Manage assignments
To manage assignments for a file type association, complete the following steps:
1. Select the file type association and then select Manage assignments in the action bar.
2. Select assignment targets (users and groups) to assign the association to.
• To add a new target, click Add new target. For more information, see Add an assignment target.
• Use filters to contextualize the assignment. If necessary, set the priority of the required associ‑
ation for each target.
• Click the three ellipses associated with the assignment to copy the configuration.
• You can also apply the copied configuration to all the targets by choosing the respective option
associated with the assignment.
1. Select the file type association and then select Clone in the action bar.
3. Select the configuration set you want to clone the file type association to.
To delete a file type association, select it and then select Delete in the action bar.
Processing options:
JSON files
This feature lets you add JSON objects and assign them to create or modify JSON files. Using this fea‑
ture, you can apply personalized settings to applications with a JSON configuration file (for example,
Microsoft Teams).
1. In the web console, go to the relevant configuration set, navigate to Actions > JSON object, and
click Add JSON object. See Add a JSON object.
2. Select the JSON object that you added and click Manage assignments in the action bar. See
Manage assignments for a JSON object.
The assignment takes some time to take effect. For immediate effect, see Make assignments take
effect immediately.
If you don’t want to enter the path and content manually, click Generate with template. The
Generate with template feature lets you generate JSON content with templates for configuring
specific applications. Currently, the feature applies only to Microsoft Teams.
generate‑with‑template
• Create file if it does not exist. This is a failsafe option ensuring that the object works as
expected. For example, in the case of Microsoft Teams, the “desktop‑config.json”file does
not exist until Microsoft Teams is launched for the first time.
• Back up the original file. When selected, the agent automatically saves a backup of the
target file in the same location. The backup inherits the name of the original and has a
suffix “‑WEMCopy.”
• Processing mode
– User‑level processing. Process the action when the user logs on or when the agent
refreshes.
– Machine‑level processing. Process the action when the machine starts or when the
agent refreshes its SQL connection settings.
• Run once. If selected, WEM runs the action only once.
JSON content merge example The following example illustrates how the specified content is
merged with the existing content in the target JSON file.
1 {
2
3 "value": "value1",
4 "array": ["test1", "test2"],
5 "object": {
6 "key1": "value1", "key2": "value2" }
7
8 }
9
10 <!--NeedCopy-->
1 {
2
3 "value": "value2",
4 "array": ["test2", "test3"],
5 "object": {
6 "key1": "changed", "key3": "value3", "key4": "value4" }
7 ,
8 "new": 1
9 }
10
11 <!--NeedCopy-->
1 {
2
3 "value": "value2",
4 "array": ["test1", "test2", "test3"],
5 "object": {
6 "key1": "changed", "key2": "value2", "key3": "value3", "key4": "value4
" }
7 ,
8 "new": 1
9 }
10
11 <!--NeedCopy-->
To add a JSON object to the Windows 11 Start menu layout, complete the following steps.
4. Click Done.
For more information, see Customize the Start menu layout for Windows 11.
1. In JSON objects, select the JSON object. If needed, use the search box to quickly find the JSON
object.
2. Click Edit in the action bar.
3. Make changes as needed.
4. After you finish, click Save.
1. Select the JSON object and then select Manage assignments in the action bar.
2. Select assignment targets (users and groups) to assign the JSON object to.
• To add a new target, click Add new target. For more information, see Add an assignment
target.
• Configure a target to specify which filter to use. For information about adding filters, see
Filters.
Note:
1. Select the JSON object and then select Clone in the action bar.
2. Edit the name and description.
3. Select the configuration set you want to clone the JSON object to.
4. Click Clone to start the clone process.
To delete a JSON object, select it and then select Delete in the action bar.
Note:
• If a JSON object is already assigned to users, deleting it will impact those users.
INI Files
Controls the creation of .ini file operations, allowing you to modify .ini files.
A list of your existing .ini file operations. You can use Find to filter the list by name or ID against a text
string.
Fields and controls Name. The display name of the .ini file operation, as it appears in the Ini File
Operations list.
Description. This field is only shown in the edition/creation wizard and allows you to specify addi‑
tional information about the resource.
.ini File Operation State. Toggles whether the .ini file operation is enabled or disabled. When dis‑
abled, it is not processed by the agent even if assigned to a user.
Target Path. Specifies the location of the .ini file that will be modified as it resolves in the user’s
environment.
Note:
While using a non‑domain‑joined agent, WEM might not work if the Target Path is a network
share.
Target Section. Specifies which section of the .ini file this operation targets. If you specify a non‑
existent section, then it will be created.
Target Value Name. Specifies the name of the value that will be added.
Run Once. By default, Workspace Environment Management performs an .ini file operation every
time the agent refreshes. Select this checkbox to make the Workspace Environment Management
perform the operation only once, rather than at every refresh. This operation speeds up the agent
refresh process, especially if you have many .ini file operations assigned to your users.
1. Select the INI file and then select Manage assignments in the action bar.
2. Select assignment targets (users and groups) to assign this INI file to.
3. Use filters to contextualize the assignment.
4. Set the priority of the selected INI file for each target.
5. After you finish, click Save.
1. Select the INI file and then select Clone in the action bar.
2. Edit the name and description.
3. Select the configuration set you need to clone.
4. Click Clone to start the clone process.
Delete INI file To delete an INI file, select it and then select Delete in the action bar.
Ports
Lets you add port mappings as assignable actions. The Ports feature allows client COM port mapping.
You can also use Citrix Studio policies to enable automatic connection of COM ports.
If you use the Ports feature to manually control the mapping of each port, remember to enable the
Client COM port redirection policies in Citrix Studio. By default, COM port redirection is prohibited.
Ports list
A list of your existing ports. You can use Find to filter the list by name or ID.
To add a port
Fields and controls Name. The display name of the port, as it appears in the port list.
Description. Appears only in the edition/creation wizard and allows you to specify additional infor‑
mation about the resource.
Port State. Toggles whether the port is enabled or disabled. When disabled, it is not processed by
the agent even if assigned to a user.
Options tab Action Type. Describes what type of action this resource performs.
Edit port mapping To edit port mapping, complete the following steps:
1. Select a port mapping and then select Manage assignments in the action bar.
2. Select assignment targets (users and groups) to assign this port to.
3. Use filters to contextualize the assignment.
4. Set the priority of the selected port mappings for each target.
5. After you finish, click Save.
1. Select the port and then select Clone in the action bar.
2. Edit the name and description.
3. Select the configuration set you need to clone.
4. Click Clone to start the clone process.
Delete port mapping To delete port mapping, select it and then select Delete in the action bar.
User DSNs
A list of your existing user DSNs. You can use Find to filter the list by name or ID against a text string.
Name. The display name of the user DSN, as it appears in the user DSN list.
Description. This field is only shown in the edition/creation wizard and allows you to specify addi‑
tional information about the resource.
User DSN State. Toggles whether the user DSN is enabled or disabled. When disabled, it will not be
processed by the agent even if assigned to a user.
Driver. The DSN driver. At present, only SQL server DSNs are supported.
Server Name. The name of the SQL server to which the user DSN is connecting.
Database Name. The name of the SQL database to which the user DSN is connecting.
Run Once. By default, Workspace Environment Management will create a user DSN every time the
agent refreshes. Tick this box to make Workspace Environment Management only create the user
DSN once, rather than at every refresh. This speeds up the agent refresh process, especially if you
have many DSNs assigned to your users.
Edit a user DSN To edit/modify a user DSN, complete the following steps:
Manage assignments for a user DSN To manage assignments for a user DSN, complete the follow‑
ing steps:
1. Select a user DSN and then select Manage assignments in the action bar.
2. Select assignment targets (users, groups, and OUs) to assign the user DSN to.
3. Use filters to contextualize the assignment.
4. Set the priority of the selected user DSN for each target.
5. After you finish, click Save.
Clone a user DSN To clone a user DSN, complete the following steps:
1. Select the user DSN and then select Clone in the action bar.
2. Edit the name and description.
3. Select the configuration set you need to clone.
4. Click Clone to start the clone process.
Delete a user DSN To delete a user DSN, select it and then select Delete in the action bar.
Assignments
Use assignments to make actions available to your users. This lets you replace a portion of your users’
logon scripts.
Assignment targets
The Assignment Targets page lets you add users and groups (targets) so that you can assign actions
and security rules to them. Select a target to manage its assignments.
Note:
Converting SIDs to target names can take some time. If the conversion is incorrect or fails, ver‑
ify that the Cloud Connectors are working properly by viewing their health status. If the issue
persists, contact Citrix Technical Support.
• Everyone. A built‑in group that contains all users, including anonymous users and guests. Mem‑
bership is controlled by the operating system.
• Administrators. A built‑in group that includes all members of the administrators group. After
the initial installation of the operating system, the only member of the group is the administra‑
tor account. When a computer joins a domain, the Domain Admins group is added to the ad‑
ministrators group. When a server becomes a domain controller, the Enterprise Admins group
is added to the administrators group.
• Edit. Lets you edit a target. You can change its description, priority, and enablement status.
When configuring the priority, consider the following: The priority determines the order in
which the actions you assign are processed. The greater the value, the higher the priority. Type
an integer. If there is a conflict, the target with the higher priority prevails.
• Delete. Lets you delete a target. Note: Built‑in targets will not be deleted.
Tip:
You can quickly enable or disable a target by using the toggle in the State column.
Note:
For Active Directory and Azure Active Directory, you can narrow your search to users or
security groups. For Active Directory, you can also choose organizational units. Keep in
mind that only Group Policy settings can be assigned to organizational units.
5. In the Search box, enter the name of the target you want to add. As you enter the name, matches
appear in the menu.
Note:
The search returns only the top 50 results. Refine your search if necessary.
6. Click the plus icon to add the target. (Targets you already added appear with a green check mark
icon.)
Tip:
If you want to add targets from a different identity provider, switch to a different identity
type to continue.
7. After you finish, click Add to add the targets and to exit the wizard.
1. On the Assignment Targets page, select the target. If needed, use the search box to quickly
find the target.
2. In the action bar, select Manage assignments. The Manage assignments window appears.
4. Click Review changes to verify that you made the changes as intended.
1. On the Assignment Targets page, select the target. If needed, use the search box to quickly
find the target.
2. In the action bar, select Clone. The Clone assignment target window appears.
3. Select the configuration set to clone the target to.
4. Click Clone.
Note:
Filters
Note:
The Filters page lets you add filters for controlling when to assign actions to your users. A filter can
comprise multiple conditions.
• Always true. If selected, the related actions are always assigned to target users. You cannot
edit or delete this built‑in filter.
• Add filter. Lets you add a filter so it is available for use when you assign actions.
• Refresh. Updates the list of filters. Using this option also refreshes the list of conditions in
Manage conditions.
• Edit. Lets you edit a filter. If you edit a filter that is bound to actions assigned to users, the
change will impact those users immediately.
Add a filter
3. In Conditions, build your filter by adding conditions. Click the operator to toggle between
Match all (AND operator) or Match any (OR operator). You can use both operators to combine
two or more conditions into a compound condition.
• Add condition. Select conditions from the list or create new ones.
• Add condition group. Add a condition group to group a series of conditions using the
same logical operator ‑ AND or OR. You can add condition groups within condition groups.
You can nest condition groups up to three levels.
Note:
• Conditions you create here are available for use with other filters.
• Use the Summary section for a deeper understanding of the criteria of compound
conditions.
• Filters containing OR operators are evaluated only on agents whose version is
2210.2.0.1 or later.
• Certain types of conditions apply only to user settings. If you apply them to machine
settings (for example, scripted tasks and GPOs), the agent skips them when evaluating
the filter. For a complete list of filter conditions that do not apply to machine settings,
see Conditions not applicable to machine settings.
Create a condition
You can create conditions when you add a filter or manage conditions. In the Create condition wizard
that appears, perform the following steps:
3. Select a condition type from the list and then configure settings accordingly.
Different condition types might have different settings. The following condition types are available:
Citrix Virtual Desktops farm name True or false depending on whether the farm
name matches the specified value.
Client IP address True or false depending on whether the IP
address matches the specified value.
Client name True or false depending on whether the client
name matches the specified values. Enter client
names, separated by semicolons (;). You can use
the asterisk (*) as a wildcard. You can also use
dynamic tokens.
Client OS True or false depending on whether the client OS
matches the specified value.
Client remote OS True or false depending on whether the client
remote OS matches the specified value.
Computer name True or false depending on whether the
computer name matches the specified values.
Enter computer names, separated by semicolons
(;). You can use the asterisk (*) as a wildcard.
Connection state True or false depending on whether the
connection state is Online or Offline.
Date and time True or false depending on whether the date and
time matches the specified values. Enter dates
or date ranges, separated by semicolons (;).
Enter dates in the format, mm/dd/yyyy. Enter
date ranges in the format (time optional), mm/
dd/yyyy HH:mm - mm/dd/yyyy HH:mm.
Day of week True or false depending on whether the day
matches the specified values.
Dynamic value True or false depending on whether the dynamic
value matches the specified values. Enter values
the dynamic expression resolves to, separated by
semicolons (;). Note: If you want the condition to
hold true regardless of the value of the dynamic
expression, enter a question mark (?).
When using “client”and “computer”related condition, be aware of the following two scenarios:
• If the agent is installed on a physical endpoint, conditions that contain “client”in the condition
names are not applicable.
More information
• Machine settings. Those settings apply only to machines regardless of who logs on to them.
Examples: Group Policy settings and scripted tasks.
• User settings. Those settings apply only to users regardless of which machine they log on to.
Example: User’s language settings.
The following conditions do not apply to machine settings. If a filter contains any of them, the agent
skips them when evaluating the filter.
ClientName Match No
Client IP Address Match No
Registry Value Match If you configure a registry value starting with
HKCU, the Registry Value Match filter does not
work if applied to machine settings.
User Country Match No
User UI Language Match No
User SBC Resource Type No
Active Directory Path Match No
Active Directory Attribute Match No
No ClientName Match No
No Client IP Address Match No
No Registry Value Match No
No User Country Match No
No User UI Language Match No
No Active Directory Path Match No
No Active Directory Attribute Match No
Client Remote OS Match No
No Client Remote OS Match No
Active Directory Group Match No
Assignment Groups
This feature lets you add actions, including GPO and JSON files to a group and select assignment
targets for deployment. Assignment details such as filters and options are managed at the individual
item level. You can now set a single filter for all assignments associated with a particular target. When
you add new items to the group, assignments for those items are generated automatically, letting you
review assignment details and make any necessary adjustments.
Note:
• If an item in the group is already assigned to a specified target from the dropdown list, the
selected target updates the assignment. You can further configure the assignment details
for each assignment target in the Assignment details page.
• If a group has been assigned to the organizational units, it cannot contain items other than
the Group Policy settings.
• To add virtual drives, you must select a drive letter manually.
• To view an assignment group, select it and then click View in the action bar.
• You can view the categories of items along with the items listed in the selected category of a
table on the Content tab.
• On the Assignments tab, you can list the assignment targets that the group is assigned to.
• To edit an assignment group, select it and then click Edit in the action bar.
• In the Content tab, edit the name, description, and content of the assignment group.
• In the Assignments tab, you can add or remove the assignment targets. You can also edit the
assignment details for each target.
To delete an assignment group, select the assignment and then click Delete in the action bar.
Triggers
Create triggers and associate tasks with them. When activated, the triggers start the associated tasks
in the user environment. To view the tasks associated with a trigger, click the trigger to expand its
row.
• Create a trigger
• Edit a trigger
• Clone a trigger
• Manage associations
• Delete a trigger
Tip:
You can quickly enable or disable a trigger by using the toggle in the State column.
• Session triggers:
Note:
Session triggers let you configure session activities as triggers and are currently available
only for external tasks.
• Machine triggers:
Note:
Create a trigger
Note:
If disabled, the agent does not evaluate and process the trigger.
5. Select a trigger type from the list and fill in the required information.
• Scheduled
• Process started
• Process ended
• Windows event
Tip:
• The information varies depending on the trigger type that you select. For details, see
Available trigger types.
• For an example of how to use Windows events as triggers, see Use Windows events as
triggers to detect VDA registration issues.
• Scheduled. Schedules when to activate the trigger. The following options are available:
Note:
User process triggers let you configure user processes as triggers and are currently avail‑
able only for external tasks.
• Windows event. Lets you define the criteria that Windows events must meet to activate the
trigger. The following options are available:
– Add criterion. Define the criteria that Windows events must meet to activate the trigger.
– Interval. Specify an interval, in minutes, for the trigger. After being activated, the trigger
will not be activated again until the specified interval elapses.
Note:
Only Windows classic event logs such as Application, System, or Security are supported.
• Cloud Health Check result. Activates the trigger when Cloud Health Check returns a specified
health status. The following options are available:
– VDA health status. Use VDA health status to activate the trigger. VDAs can be in normal or
unusual state, as shown in Home > Overview.
– Task data. Select data to pass to associated tasks, and specify the parameters in those
tasks to receive the data. If a parameter you specify here is the same as the one config‑
ured for associated tasks, the former takes precedence. We recommend using the default
parameter names. Update your script files if necessary. You can specify the following data:
* VDA health status (string). The health status that Cloud Health Check returns. Use
the parameter in associated tasks to receive the status.
* Health report (string). The VDA health check report that Cloud Health Check gener‑
ates. Use the parameter in associated tasks to receive the full path of the report. For
more information, see Heath check results.
• Profile Management health check result. Activates the trigger when Profile Management
health check returns a specified health status. The following options are available:
– Profile Management health status. Use the following Profile Management health sta‑
tuses to trigger associated tasks: Warning (suboptimal state of Profile Management) and
Error (Profile Management configured incorrectly).
– Task data. Select data to pass to associated tasks, and specify the parameters in those
tasks to receive the data. If a parameter you specify here is the same as the one config‑
ured for associated tasks, the former takes precedence. We recommend using the default
parameter names. Update your script files if necessary. You can specify the following data:
* Profile Management health status (string). The health status that the Profile Man‑
agement health check returns. Use the parameter in associated tasks to receive the
status. For more information, see Administration.
* Health report (string). The health check report that the Profile Management health
check generates. Use the parameter in associated tasks to receive the full path of the
report. For more information, see Reports.
• Custom scripted task result. Activates the trigger when scripted tasks return specified results.
You first specify custom scripted tasks and then define the criteria that the tasks must meet to
activate the trigger. The following options are available:
– Add criterion. Select one or more scripted tasks and then define the criteria that those
tasks must meet to activate the trigger.
– Task data. Select data to pass to associated tasks, and specify the parameters in those
tasks to receive the data. If a parameter you specify here is the same as the one config‑
ured for associated tasks, the former takes precedence. We recommend using the default
parameter names. Update your script files if necessary. You can specify the following data:
* Task name (string). The name of the scripted task that triggers the associated task.
Use the parameter in associated tasks to receive the name.
* Exit code (integer). The exit code value that the scripted task returns. Use the para‑
meter in associated tasks to receive the value.
* Console output (string). The console output that the scripted task writes. Use the
parameter in associated tasks to receive the full path of the output.
* File output (string). The file output that the scripted task generates. Use the para‑
meter in associated tasks to receive the full path of the output.
Edit a trigger
Clone a trigger
Manage associations
3. Select scripted tasks to associate them with the trigger or unselect scripted tasks to unassociate.
If needed, use the search box to quickly search for a task.
• To prevent endless looping, WEM supports up to 10 triggering times in a single loop chain. The
following is an example, in which Task A triggers Task B, Task B triggers Task C, …, and Task K
triggers Task L. Task K fails to trigger Task L —the loop terminates because the triggering times
in this single loop chain have exceeded 10.
Delete a trigger
Note:
If you delete a trigger with which scripted tasks are associated, it will no longer trigger those
tasks.
The following table lists which triggers are supported for which tasks.
Agent refresh X
Reconnect X
Logon X
Logoff X
Disconnect X
Lock X
Unlock X
Machine startup X
Machine shutdown X
Scheduled X X
Process started X
Process ended X
Windows event X
Cloud Health Check result X
Profile Management health X
check result
Custom scripted task X
System Optimization
Workspace Environment Management (WEM) system optimization consists of the following set‑
tings:
• CPU Management
• Memory Management
• I/O Management
• Fast Logoff
• Citrix Optimizer
• Multi‑session Optimization
These settings are designed to lower resource usage on the agent machine. They help to make sure
that freed‑up resources are available for other applications. Doing so increases user density by sup‑
porting more users per server.
System optimization settings are machine‑based and apply to all user sessions, but process optimiza‑
tion is user centric. This means that when a process triggers CPU spike protection in user A’s session,
the event is recorded only for user A. When user B starts the same process, process optimization be‑
havior is determined only by process triggers in user B’s session.
CPU management
Processes can run across all cores and can use up as much CPU as they want. In WEM, the CPU man‑
agement feature lets you limit how much CPU capacity individual processes can use. CPU spike pro‑
tection is not designed to reduce overall CPU usage. It is designed to reduce the impact on user expe‑
rience by processes that consume an excessive percentage of CPU usage.
When CPU spike protection is enabled, if a process reaches a specified threshold, WEM automatically
lowers the priority of the process for a certain time. Then, when a new application is launched, it has
a higher priority than the lower‑priority process and the system will continue to run smoothly.
CPU spike protection examines each process in a quick “snapshot.”If the average load of a process
exceeds the specified usage limit for a specified sample time, its priority reduces immediately. After a
specified time, the process’CPU priority returns to its previous value. The process is not “throttled.”
Unlike in CPU Clamping, only its priority is reduced.
CPU spike protection is not triggered until at least one instance of an individual process exceeds the
threshold. In other words, even if total CPU consumption exceeds the specified threshold, CPU spike
protection is not triggered unless at least one process instance exceeds the threshold. But when that
process instance triggers CPU spike protection, new instances of the same process are (CPU) opti‑
mized when the option Enable intelligent CPU optimization is enabled.
Whenever a specific process triggers CPU spike protection, the event is recorded in the agent’s local
database. The agent records trigger events for each user separately. This means that CPU optimiza‑
tion for a specific process for user1 does not affect the behavior of the same process for user2.
For example, if Internet Explorer is sometimes consuming 50–60% of CPU, you can use CPU spike pro‑
tection to target only those iexplore.exe instances that are threatening VDA performance. (By contrast,
CPU clamping applies to all processes.)
We recommend that you experiment with the sample time to decide the optimal value for your envi‑
ronment that does not affect other users logged on to the same VDA.
Note:
• “CPU usage”in the following settings is based on “logical processors”in the physical or vir‑
tual machine. Each core in a CPU is considered as a logical processor, in the same way that
Windows does. For example, a physical machine with one 6‑core CPU is considered to have
12 logical processors (Hyper‑Threading Technology means that cores are doubled). A phys‑
ical machine with 8 x CPUs, each with 12 cores has 96 logical processors. A VM configured
with two 4‑core CPUs has 8 logical processors.
• The same applies to virtual machines. For example, suppose you have a physical machine
with 8 x CPUs, each with 12 cores (96 logical processors), supporting four multi‑session OS
VDA VMs. Each VM is configured with two 4‑cores CPUs (8 logical processors). To restrict
processes that trigger CPU spike protection on a VM, to use half of its cores, set CPU core
usage limit to 4 (half of the VM’s logical processors), not to 48 (half of the physical machine’
s logical processors).
When enabled, lowers the CPU priority of processes for a period of time (specified in the Idle priority
time field) if they exceed the specified percentage of CPU usage for a period of time (specified in the
Sample time limit field).
Automatically prevent CPU spikes. This option automatically reduce the CPU priority of processes
that overload your CPU. This option automatically calculates the threshold value at which to trigger
CPU spike protection based on the number of logical processors (CPU cores). For example, suppose
that there are 4 cores. With this option enabled, if the overall CPU usage exceeds 23%, the CPU pri‑
ority of processes that consume more than 15% of the overall CPU resources reduces automatically.
Similarly, in the case of 8 cores, if the overall CPU usage exceeds 11%, the CPU priority of processes
that consume more than 8% of the CPU resources reduces automatically.
Customize CPU spike protection. Lets you customize settings for CPU spike protection.
• CPU usage limit. The percentage of CPU usage that any process instance must reach to trigger
CPU spike protection. This limit is global across all logical processors in the server, and is deter‑
mined on an instance‑by‑process basis. Multiple instances of the same process do not have their
CPU usage percentages added when determining CPU spike protection triggers. If a process in‑
stance never reaches this limit, CPU spike protection is not triggered. For example, on a Server
VDA, in multiple concurrent sessions, suppose that there are many iexplore.exe instances. Each
instance peaks at around 35% CPU usage for periods of time, so that cumulatively, iexplore.exe
is consistently consuming a high percentage of CPU usage. However, CPU spike protection is
never triggered unless you set CPU Usage Limit at or below 35%.
• Sample time limit. The length of time for which a process must exceed the CPU usage limit
before its CPU priority is lowered.
• Idle priority time. The length of time for which the CPU priority of the process is lowered. After
that time, the priority returns to one of the following:
– The default level (Normal) if the process priority is not specified in the CPU priority tile
and the Enable intelligent CPU optimization option is not selected.
– The specified level if the process priority is specified in the CPU priority tile, regardless of
whether the Enable intelligent CPU optimization option is selected.
– A random level depending on the behavior of the process. This case occurs if the process
priority is not specified in the CPU priority tile and the Enable intelligent CPU optimiza‑
tion option is selected. The more frequent the process triggers CPU spike protection, the
lower its CPU priority is.
Enable CPU core usage limit. Limits processes that trigger CPU spike protection to a specified num‑
ber of logical processors on the machine. Type an integer in the range of 1 through X, where X is the
total number of cores. If you type an integer greater than X, WEM limits the maximum consumption
of isolated processes to X by default.
• CPU core usage limit. Specifies the number of logical processors to which processes that trig‑
ger CPU spike protection are limited. In the case of VMs, the value you type limits the processes
to the number of logical processors in the VMs rather than in the underlying physical hardware.
Enable intelligent CPU optimization. When enabled, the agent intelligently optimizes the CPU pri‑
ority of processes that trigger CPU spike protection. Processes that repeatedly trigger CPU spike pro‑
tection are assigned progressively lower CPU priority at launch than processes that behave correctly.
Note that WEM does not perform CPU optimization for the following system processes:
• Taskmgr
• System Idle Process
• System
• Svchost
• LSASS
• Wininit
• services
• csrss
• audiodg
• MsMpEng
• NisSrv
• mscorsvw
• vmwareresolutionset
Enable intelligent I/O optimization. When enabled, the agent intelligently optimizes the process
I/O priority of processes that trigger CPU spike protection. Processes that repeatedly trigger CPU
spike protection are assigned progressively lower I/O priority at launch than processes that behave
correctly.
Exclude processes. By default, WEM CPU management excludes all of the most common Citrix and
Windows core service processes. You can, however, use this option to Add or Remove processes from
an exclusion list for CPU spike protection by executable name (for example notepad.exe). Typically,
antivirus processes would be excluded.
Tip:
• To stop antivirus scanning taking over disk I/O in the session, you can also set a static I/O
Priority of Low for antivirus processes, see I/O Management.
• When processes trigger CPU spike protection, and process CPU priority is lowered, WEM
logs a warning each time it lowers the CPU priority of a process. In the Event Log, in Ap‑
plication and Services Logs, WEM Agent Service, looks for Initializing process limitation
thread for process.
Prevent child processes from inheriting CPU priority. Specifies processes whose child processes
you do not want to inherit the CPU priority.
CPU spike protection option Choose how you want to enforce CPU spike protection:
• Automatically prevent CPU spikes. Use this option to let the agent perform CPU spike protec‑
tion when the system CPU usage (relative to a single CPU core) exceeds 90% and the process
CPU usage (relative to a single CPU core) exceeds 80%.
• Customize CPU spike protection. Lets you customize settings for CPU spike protection.
– CPU usage limit. The percentage of CPU usage that any process instance must reach to
trigger CPU spike protection. This limit is global across all logical processors on the server,
and is determined on an instance‑by‑process basis. To configure the limit based on a single
CPU core as a reference, use the Set limit relative to single CPU core option.
Note:
• Both integer and non‑integer values are supported. By entering a non‑integer value, for
example 37.5%, you restrict processes that use more than three cores on an eight‑core plat‑
form.
• Set limit relative to single CPU core. Lets you set a limit on CPU usage based on a single
CPU core as a reference. The value can be greater than 100%, for example, 200% or 250%.
Example: When the value is set to 200%, the agent optimizes processes that use two or
more CPU cores. Both integer and non‑integer values are supported.
Note:
• With Customize CPU spike protection configured, CPU spike protection is triggered when
either the global CPU usage limit or the CPU usage limit relative to a single CPU core is
reached, whichever occurs first.
For processes that trigger CPU spike protection, the agent can do the following:
• If the Enable CPU core usage limit option is not selected: The agent lowers the CPU priority of
those processes.
• If the Enable CPU core usage limit option is selected: The agent lowers the CPU priority of
those processes and limits them to the specified number of logical processors on the machine.
• Multiple instances of the same process do not have their CPU usage percentages added when
determining CPU spike protection triggers. If a process instance never reaches this limit, CPU
spike protection is not triggered. For example, in the case of a multi‑session VDA with multiple
concurrent sessions, there are multiple chrome.exe processes. Their CPU usage is not summed
together when calculating the CPU usage.
Sampling time for CPU spike protection Sample time limit. The length of time for which a
process must exceed the CPU usage limit before CPU spike protection is enforced.
Priority lowering time for CPU spike protection Idle priority time. The length of time for which
the CPU priority of the process is lowered. After that time, the priority returns to one of the follow‑
ing:
The default level (Normal), if the process priority is not specified in the CPU priority tile and the Enable
intelligent CPU optimization option is not selected.
The specified level, if the process priority is specified in the CPU priority tile, regardless of whether the
Enable intelligent CPU optimization option is selected.
The calculated random level, depending on the behavior of the process. This case occurs if the process
priority is not specified in the CPU priority tile and the Enable intelligent CPU optimization option
is selected. The more frequent the process triggers CPU spike protection, the lower its CPU priority
is.
Additional options Enable CPU core usage limit. Use this option to limit processes that trigger
CPU spike protection to a specific number of logical processors on the machine.
CPU priority
When enabled, lets you set CPU priority for processes manually.
These settings take effect if processes are competing for a resource. They let you optimize the CPU
priority level of specific processes, so that processes that are contending for CPU processor time do
not cause performance bottlenecks. When processes compete with each other, processes with lower
priority are served after other process with a higher priority. They are therefore less likely to consume
such a large share of the overall CPU consumption.
The process priority you set here establishes the “base priority”for all of the threads in the process.
The actual, or “current,”priority of a thread might be higher (but is never lower than the base). When
several processes are running on a computer, the processor time is shared between them based on
their CPU priority level. The higher the CPU priority level of a process is, the more the processor time
is assigned to it.
Note:
The overall CPU consumption does not necessarily decrease if you set lower CPU priority levels
on specific processes. There might be other processes (with higher CPU priority) still affecting
percentage CPU usage.
To add a process, click Add process. Specify the following information and then click Save process:
• Process name. The process executable name without the extension. For example, for Windows
Explorer (explorer.exe) type “explorer”.
• Priority. The “base”priority of all threads in the process. The higher the priority level of a
process is, the more the processor time it gets. Select from Idel, Below normal, Normal, Above
normal, High, and Realtime.
Tip:
Process CPU priorities you set here take effect when the agent receives the new settings and the
process is restarted.
To delete a process, click the ellipsis next to the process and select Delete.
To edit a process, click the ellipsis next to the process and select Edit.
CPU affinity
When enabled, lets you define how many “logical processors”a process uses. For example, you can
restrict every instance of Notepad launched on the VDA to the number of cores defined.
To add a process, click Add process. Specify the following information and then click Save process:
To delete a process, click the ellipsis next to the process and select Delete.
To edit a process, click the ellipsis next to the process and select Edit.
CPU clamping
When enabled, lets you prevent processes from using more than a specified percentage of the CPU’s
processing power. CPU clamping prevents processes using more than a specified percentage of the
CPU’s processing power. WEM “throttles”(or “clamps”) that process when it reaches the specified
CPU percentage you set. This lets you prevent processes from consuming large amounts of CPU.
Note:
• CPU clamping is a brute force approach that is computationally expensive. To keep the CPU
usage of a troublesome process artificially low, it is better to use CPU spike protection, at
the same time as assigning static CPU priorities and CPU affinities to such processes. CPU
clamping is best reserved for controlling processes that are notoriously bad at resource
management, but that cannot stand to be dropped in priority.
• After you apply a percentage of the CPU’s processing power for a process and configure a
different percentage for the same process later, select Refresh agent host settings for the
change to take effect.
The clamping percentage you configure is applied to the total power of any individual CPU in the
server, not to any individual core it contains. (In other words, 10% on a quad‑core CPU is 10% of the
entire CPU, not 10% of one core).
To add a process, click Add process. Specify the following information and then click Save process:
Tip:
• When WEM is clamping a process, it adds the process to its watchlist the WEM client initial‑
izes. You can verify that a process is clamped by viewing this.
• You can also verify that CPU clamping is working by looking at process monitor and con‑
firming that CPU consumption never rises above the clamping percentage.
To delete a process, click the ellipsis next to the process and select Delete.
To edit a process, click the ellipsis next to the process and select Edit.
Memory management
These settings let you optimize application memory usage through WEM.
If these settings are enabled, WEM calculates how much memory a process is using and the minimum
amount of memory a process needs without losing stability. WEM considers the difference as excess
memory. When the process becomes idle, WEM releases the excess memory that the process con‑
sumes to the page file, and optimizes the process for subsequent launches. Usually, an application
becomes idle when it is minimized to the task bar.
When applications are restored from the task bar, they initially run in their optimized state but can
continue to consume additional memory as needed.
Similarly, WEM optimizes all applications that users are using during their desktop sessions. If there
are multiple processes over multiple user sessions, all memory that is freed up is available for other
processes. This behavior increases user density by supporting a greater number of users on the same
server.
When enabled, forces processes that remain idle for a specified time to release excess memory until
they are no longer idle.
Idle sample time. Lets you specify the length of time that a process is considered idle after which it
is forced to release excess memory. During this time, WEM calculates how much memory a process
is using, and the minimum amount of memory a process needs, without losing stability. The default
value is 120 minutes.
Idle state limit. Lets you specify the percentage of CPU usage below which a process is considered
idle. The default is 1%. We recommend that you do not use a value greater than 5%. Otherwise, a
process being actively used can be mistaken for idle, causing its memory to be released.
Restrict optimization. Lets you specify a threshold limit below which WEM optimizes memory usage
for idle applications.
Exclude processes from memory usage optimization. Lets you exclude processes from memory
usage optimization. Specify the process name, for example, notepad.exe.
WEM does not optimize application memory usage for the following system processes:
• rdpshell
• wfshell
• rdpclip
• wmiprvse
• dllhost
• audiodg
• msdtc
• mscorsvw
• spoolsv
• smss
• winlogon
• svchost
• taskmgr
• System Idle Process
• System
• LSASS
• wininit
• msiexec
• services
• csrss
• MsMpEng
• NisSrv
• Memory Compression
When enabled, lets you limit the memory usage of a process by setting an upper limit for the memory
the process can consume.
Warning:
Applying memory usage limits to certain processes might have unintended effects, including
slow system responsiveness.
To add a process, click Add process. Specify the following information and then click Save process.
• Process name. Enter the name of the process you want to add (for example, notepad.exe.)
– Dynamic Limit. Lets you apply a dynamic limit to the specified process. This setting dy‑
namically limits the amount of memory allocated to the specified process. If applied, en‑
forces memory usage limits depending on available memory. Therefore, the memory that
the specified process consumes might exceed the specified amount.
– Static Limit. Lets you apply a static limit to the specified process. This setting always limits
the amount of memory allocated to the specified process. If applied, restricts the process
from consuming more than the specified amount of memory regardless of the amount of
available memory. As a result, the memory that the specified process consumes is capped
at the specified amount.
To delete a process, click the ellipsis next to the process and select Delete.
To edit a process, click the ellipsis next to the process and select Edit.
I/O management
These settings let you optimize the I/O priority of certain processes so that processes which are con‑
tending for disk and network I/O access do not cause performance bottlenecks. For example, you can
use I/O Management settings to throttle back a disk‑bandwidth‑hungry application.
The process priority you set here establishes the “base priority”for all of the threads in the process.
The actual, or “current,”priority of a thread might be higher (but is never lower than the base). In
general, Windows give access to threads of higher priority before threads of lower priority.
When enabled, Lets you optimize the I/O priority of specific processes, so that processes that are con‑
tending for disk and network I/O access do not cause performance bottlenecks.
To add a process, click Add process. Specify the following information and then click Save process.
• Process name. Enter The process executable name without the extension. For example, for
Windows Explorer (explorer.exe) type “explorer”.
• I/O Priority. Enter the “base”priority of all threads in the process. The higher the I/O priority of
a process, the sooner its threads get I/O access. Choose from High, Normal, Low, Very Low.
Tip:
Process I/O priorities you set here take effect when the agent receives the new settings and the
process is next restarted.
To delete a process, click the ellipsis next to the process and select Delete.
To edit a process, click the ellipsis next to the process and select Edit.
Fast logoff
These settings let you immediately ends the HDX connection to a remote session. Doing that gives
users the impression that the session has immediately closed. However, the session itself continues
through the session logoff phases in the background on the VDA.
Note:
Fast logoff supports Citrix virtual apps and RDS resources only.
When enabled, enables fast logoff for all users in this configuration set. Users are logged out immedi‑
ately, while session logoff tasks continue in the background.
To exclude specific groups, perform the following steps:
1. Select Exclude specified groups and then Add group. The Add group to exclude wizard ap‑
pears.
2. Select the identity type.
3. Select a domain where the group you want to add exists.
4. In the Search box, enter the name of the group you want to add. (Searches are not case‑
sensitive.)
5. Click the plus icon to add the group.
6. After you have finished, click Save to add the group and to exit the Add group to exclude wizard.
Citrix Optimizer
These settings let you optimize user environments for better performance. Citrix Optimizer runs a
quick scan of user environments and then applies template‑based optimization recommendations.
You can optimize user environments in two ways:
• Use built‑in templates to perform optimizations. To do so, select a template applicable to the
operating system.
• Alternatively, create your own customized templates with specific optimizations you want and
then add the templates to Workspace Environment Management (WEM).
To get a template that you can customize, use either of the following approaches:
• Use the template builder feature that the standalone Citrix Optimizer offers. Download the
standalone Citrix Optimizer at https://support.citrix.com/article/CTX224676. The template
builder feature lets you build your own custom templates to be uploaded to WEM.
• On an agent host (machine where the WEM agent is installed), navigate to the <C:\Program
Files (x86)>\Citrix\Workspace Environment Management Agent\Citrix
Optimizer\Templates folder, select a default template file, and copy it to a convenient
folder. Customize the template file to reflect your specifics and then upload the custom
template to WEM.
Run weekly. If selected, WEM runs optimizations on a weekly basis. If Run weekly is not selected,
WEM behaves as follows:
• The first time you add a template to WEM, WEM runs the corresponding optimization. WEM runs
the optimization only once unless you make changes to that template later. Changes include
applying a different template to OS and enabling or disabling the template.
• Each time you make changes to a template, WEM runs the optimization once.
a) For Template name, click Browse and then select the template you want to add.
b) For Applicable operating system, select from the list one or more operating systems to
which the template applies.
Tip:
You can add Windows 10 operating systems that are not available on the list but that
the template applies to. Add those OSs by typing their build numbers. Be sure to
separate the OSs with semicolons (;). For example, 2001;2004.
d) Click Save.
Important:
Citrix optimizer does not support exporting custom templates. Retain a local copy of your custom
template after you add it.
You can use the toggle in the State column to toggle the template between enabled and disabled
states. If disabled, the agent does not process the template, and WEM does not run optimizations
associated with the template.
To delete a template, select the ellipsis of the applicable template and then select Delete. Note: You
cannot delete built‑in templates.
To edit a template, select the ellipsis of the applicable template and then select Edit.
To view details of a template, select the ellipsis of the applicable template and then select Preview.
Note:
For a non‑persistent VDI environment, WEM follows the same behavior –all changes to the envi‑
ronment are lost when the machine restarts. In the case of Citrix Optimizer, WEM runs optimiza‑
tions each time the machine restarts.
Automatically select template to use. If you are unsure which template to use, use this option to
let WEM select the best match for each OS. If you want to use custom templates as the preferred tem‑
plates, enter a comma‑separated list of prefixes. Custom template follows this name format:
‑ prefix_<os version>_<os build>
‑ prefix_Server_<os version>_<os build>
Changes to Citrix Optimizer settings take some time to take effect, depending on the value that you
specified for the SQL Settings Refresh Delay option on the Advanced Settings > Configuration >
Service Options tab of the legacy console.
For the changes to take effect immediately, navigate to Monitoring > Administration > Agents, locate
the agent, and then select Process Citrix Optimizer from the More menu.
Tip:
New changes might fail to take effect immediately. We recommend that you select Refresh
agent host settings before you select Process Citrix Optimizer.
Multi‑session optimization
These settings let you optimize multi‑session OS machines with disconnected sessions for better user
experience with connected sessions.
Multi‑session OS machines run multiple sessions from a single machine to deliver applications and
desktops to users. A disconnected session remains active and its applications continue to run. The
disconnected session can consume resources needed for connected desktops and applications that
run on the same machine. These settings let you optimize multi‑session OS machines with discon‑
nected sessions for better user experience with connected sessions.
When enabled, optimizes multi‑session OS machines where disconnected sessions are present. By de‑
fault, multi‑session optimization is disabled. The feature improves the user experience of connected
sessions by limiting the number of resources disconnected sessions can consume. After a session
stays disconnected for one minute, the WEM agent lowers the CPU and the I/O priorities of processes
or applications associated with the session. The agent then imposes limits on the amount of memory
resources the session can consume. If the user reconnects to the session, WEM restores the priorities
and removes the limitations.
Exclude groups
To exclude specific groups from multi‑session optimization, perform the following steps:
1. Select Exclude specified groups and then click Add group. The Add group to exclude wizard
appears.
4. In the Search box, enter the name of the group you want to add. Enter the full name of the group.
(Searches are not case‑sensitive.)
6. After you have finished, click Save to add the group and to exit the Add group to exclude wizard.
Exclude processes
To exclude specific processes from multi‑session optimization, click Add process, browse to the
process you want to add, and then click Save process.
To delete a process, click the ellipsis next to the process and select Delete.
To edit a process, click the ellipsis next to the process and select Edit.
Some options work only with specific versions of Profile Management. Consult the Profile Man‑
agement documentation for details.
Workspace Environment Management (WEM) supports all versions of Citrix Profile Management
through the current version.
In the console (Configuration Set > Profiles > Profile Management Settings), you can configure all
settings for the current version of Citrix Profile Management.
In addition to using WEM to configure Citrix Profile Management features, you can use Active Directory
GPOs, Citrix Studio policies, or .ini files on the VDA. We recommend that you use the same method
consistently.
When enabled, you can configure and apply your settings. Enabling this option creates Profile Man‑
agement related registries in the user environment. The option controls whether WEM deploys the
Profile Management settings you configure in the console to the agent. If disabled, none of the Profile
Management settings are deployed to the agent.
By default, most Profile Management settings work only at the machine level. You can enable certain
Profile Management settings to work at the user level, so that you can tailor the profile experience for
specific users. See User‑level Profile Management settings.
You can select tags to filter the profile management settings as needed. Settings associated with the
selected tags get displayed and the rest are hidden.
When you switch between views, the selected set of tags get saved as a part of administrator prefer‑
ences for further usage.
Quick setup
To quickly set up Profile Management, you can restore your settings from a backup or start with a
template.
Backups containing Profile Management settings are shown. To upload backups containing Profile
Management settings, see Back up Profile Management settings.
Select one backup from the list. Click Preview to see the settings and make adjustments as needed.
Other types of settings (if any) in the backup are ignored.
Note:
• To restore Profile Management settings, you can also use the back up and restore feature.
• When restoring Profile Management settings from a backup, the SMB shares selected for
relevant services to use are also restored.
Important:
If you already have Profile Management configured, keep in mind that using a template over‑
writes all existing settings.
There are two types of user stores based on how profiles are handled:
• File‑based. User profiles are fetched from the remote user store to the local computer on logon
and written back on logoff.
• Container‑based. User profiles are stored in profile containers. Those containers are attached
on logon and detached on logoff.
To set up Profile Management quickly for your use case, choose a template.
This feature lets you configure certain Profile Management settings at the user level for customization
and precise control. Use this feature to apply specific Profile Management settings to individual users
or user groups, tailoring the profile experience as needed.
There are two ways to configure Profile Management settings at the user level:
The web console offers a user‑friendly, UI‑based interface for configuring Profile Management user‑
level settings.
To configure user‑level settings using the web console, complete the following steps.
• On the Profile Management Settings page, click the user‑level settings link.
• On the user‑level settings page, you can do the following:
– Add configuration.
– Set priority order for groups.
– Toggle between the two views: View by configuration and View by user/group.
Add configuration
Active Directory (AD) and Azure Active Directory (AAD) are supported.
Each time you add a configuration, it appears in Actions > Group Policy settings > Others. For your
user‑level settings to take effect, you must enable GPO processing (enable the Process GPOs option
in Group Policy Settings).
When a session starts, Profile Management determines which policy settings to apply, by prioritizing
user settings over user group settings, and user group settings over machine settings.
You can set the priority order for groups to handle the situation (where a user belongs to multiple
groups with conflicting settings) by completing the following steps.
When a user belongs to multiple groups with conflicting settings, the group that appears
higher in the list takes precedence.
You can toggle between the two views to view the user‑level settings categorized by user/group, or by
configuration.
Basic settings
Get started with Profile Management by applying basic settings. Basic settings include processed
groups, excluded groups, user store, and more.
Enable Profile Management. Controls whether to enable the Profile Management service on the
agent machine. If disabled, the Profile Management service does not work.
You might want to disable Profile Management completely so that settings already deployed to the
agent will no longer be processed. To achieve the goal, do the following:
1. Clear the Enable Profile Management checkbox and wait for the change to apply automatically
or apply the change manually for immediate effect.
Note:
The change takes some time to take effect, depending on the value you specified for SQL
Settings Refresh Delay in Advanced Settings. For the change to take effect immediately,
refresh agent host settings and then reset Profile Management settings for all related
agents. See Administration.
Set processed groups. Lets you specify which groups are processed by Profile Management. Only
the specified groups have their Profile Management settings processed. If left empty, all groups are
processed.
Set excluded groups. Lets you specify which groups are excluded from Profile Management.
Process logons of local administrators. If enabled, local administrator logons are treated the same
as non‑administrator logons for Profile Management.
Set path to user store. Lets you specify the path to the user store —the central location for Citrix user
profiles. Enter an absolute UNC path or a path relative to the home directory. Example path:
Migrate user store. Lets you specify the path to the folder where the user settings (registry changes
and synchronized files) were saved. Enter the user store path that you previously used. Use this option
along with the Set path to user store option.
Enable active write back. If enabled, profiles are written back to the user store during the user ses‑
sion, preventing data loss.
• Enable active write back registry. If enabled, registry entries are written back to the user store
during the user session, preventing data loss.
• Enable active write back on session lock and disconnection. If enabled, profile files and
folders are written back only when a session is locked or disconnected. With both this option
and the Enable active write back registry option enabled, registry entries are written back
only when a session is locked or disconnected.
Enable offline profile support. If enabled, profiles are cached locally for use while not connected.
Profile container
Configure profile container settings. Profile containers are VHDX disks stored on the network and
attached during logon and detached during logoff.
Enable Profile Container. Lets you add the folders you want to include in the profile container. To
put an entire user profile in its profile container, add an asterisk (*) instead. If enabled, Profile Man‑
agement maps the listed folders to the profile disk stored on the network, thus eliminating the need
to save a copy of the folders to the local profile. Specify at least one folder to include in the profile
container.
• Enable local caching for profile container. If enabled, each local profile serves as a local cache
of its profile container. This option requires you to put an entire user profile in its profile con‑
tainer.
• Log off users when profile container is not available during logon. Lets you specify whether
to force log‑off users when the profile container is unavailable during user logon. Enabling this
option displays a notification message to users and logs them off after they click OK.
Enable folder exclusions. If enabled, Profile Management excludes the listed folders from the profile
container. Specify at least one folder to exclude from the profile container.
Enable file exclusions. If enabled, Profile Management excludes the listed files from the profile con‑
tainer. Specify at least one file to exclude from the profile container.
Enable folder inclusions. If enabled, Profile Management keeps the listed folders in the profile con‑
tainer when their parent folders are excluded. Folders on this list must be subfolders of the excluded
folders. This means that you must use this option with the Enable folder exclusions option. Specify
at least one folder to include in the profile container.
Enable file inclusions. If enabled, Profile Management keeps the listed files in the profile container
when their parent folders are excluded. Files on this list must be contained in the excluded folders.
This means that you must use this option with the Enable folder exclusions option. Specify at least
one file to include in the profile container.
TIP:
When adding files or folders, you can use wildcards. For more information, see Wildcard support.
When adding profile container content, exclusions, and inclusions, you can add them individually
and in bulk. When adding them in bulk, enter paths separated by line breaks. After that, click Run
validation to validate items you are about to add. Only valid items can be added. Invalid items are
skipped.
Also, you can have a hierarchical view of the profile container content, exclusions, and inclusions. To
do that, click View hierarchy.
Enable VHD auto‑expansion for profile container. If enabled, when the profile container reaches
90% utilization, it automatically expands by 10 GB, with a maximum capacity of 80 GB. Depending on
your needs, you can adjust the default auto‑expansion settings using the following options:
• Auto‑expansion trigger threshold (%). Lets you specify the utilization percentage of storage
capacity at which the profile container triggers auto‑expansion.
• Auto‑expansion increment (GB). Lets you specify the amount of storage capacity (in GB) by
which the profile container automatically expands when auto‑expansion is triggered.
• Auto‑expansion limit (GB). Lets you specify the maximum storage capacity (in GB) to which
the profile container can automatically expand when auto‑expansion is triggered.
Set users and groups to access profile container. Lets you specify which AD domain users and
groups have Read & Execute permission on profile containers. By default, a profile container is ac‑
cessible only to its owner.
Profile handling
Delete locally cached profiles on logoff. If enabled, locally cached profiles are deleted when the
user logs off.
• Set delay before deleting cached profiles. Lets you specify a delay (in seconds) before cached
profiles are deleted on logoff. Supported values: 0–600.
Enable migration of existing profiles. If enabled, existing Windows profiles are migrated to Profile
Management on logon. Specify the type of user profiles to migrate if the user store is empty. Types
include:
Automatic migration of existing application profiles. If enabled, existing application profiles are
migrated automatically. Profile Management performs the migration when a user logs on and when
there are no user profiles in the user store.
Enable local profile conflict handling. Configures how WEM handles cases where Profile Manage‑
ment and Windows profiles conflict. Specify what to do if both a local Windows user profile and a
Citrix user profile exist in the user store:
Enable template profile. Lets you enter a template profile path. If enabled, Profile Management uses
the specified template profile. You can configure additional settings as follows:
• Template profile overrides local profile. If enabled, the template profile overrides local pro‑
files.
• Template profile overrides roaming profile. If enabled, the template profile overrides roam‑
ing profiles.
• Use template profile as Citrix mandatory profile for all logons. If enabled, the template
profile overrides all other profiles.
Advanced settings
Enable search index roaming for Microsoft Outlook users. If enabled, the user‑specific Microsoft
Outlook offline folder file (*.ost) and Microsoft search database are roamed along with the user profile.
This improves the user experience when searching for emails in Microsoft Outlook.
• Outlook search index database –backup and restore. If enabled, Profile Management auto‑
matically saves a backup of the last known good copy of the search index database. When there
is a corruption, Profile Management reverts to that copy. As a result, you no longer need to
manually reindex the database when the search index database becomes corrupted.
• Enable concurrent session support. Provides native Outlook search experience in concurrent
sessions. If enabled, each concurrent session uses a separate Outlook OST file.
– Maximum number of VHDX disks for storing Outlook OST files. Lets you specify the
maximum number of VHDX disks for storing Outlook OST files. If unspecified, only two
VHDX disks can be used to store Outlook OST files (one file per disk). If more sessions start,
their Outlook OST files are stored in the local user profile. Supported values: 1–10.
Enable OneDrive container. If enabled, Profile Management roams OneDrive folders with users by
storing the folders on a VHDX disk. The disk is attached during logons and detached during logoffs.
Enable UWP app roaming. If enabled, UWP (Universal Windows Platform) apps roam with users. As
a result, users can access the same UWP apps from different devices.
Enable use of application definition files. Lets you enter the path to definition files. If enabled, only
the settings included in the definition file are synchronized. Specify a folder where the Citrix virtual
apps optimization definition files are located. For more information about creating definition files,
see Create a definition file.
Default capacity of VHD containers (GB) Lets you specify the default storage capacity (in GB) of each
VHD container.
Customize storage path for VHDX files. Lets you specify a separate path to store VHDX files. By de‑
fault, VHDX files are stored in the user store. Policies that use VHDX files include the following: Profile
container, Search index roaming for Outlook, and Accelerate folder mirroring. If enabled, VHDX files
of different policies are stored in different folders under the storage path.
Enable multi‑session write‑back for profile containers. If enabled, Profile Management saves
changes in multi‑session scenarios for both FSLogix Profile Container and Citrix Profile Management
profile containers. If the same user launches multiple sessions on different machines, changes made
in each session are synchronized and saved to the user’s profile container disk.
Enable VHD disk compaction. If enabled, VHD disks are automatically compacted on user logoff
when certain conditions are met. This option enables you to save the storage space consumed by
profile container, OneDrive container, and mirror folder container.
Depending on your needs and the resources available, you can adjust the default VHD compaction
settings and behavior using the following options:
• Set free space ratio to trigger VHD disk compaction. Lets you specify the free space ratio
to trigger VHD disk compaction. When the free space ratio exceeds the specified value on user
logoff, disk compaction is triggered.
Free space ratio = (current VHD file size –required minimum VHD file size*) ÷ current VHD file size
* Obtained using the GetSupportedSize method of the MSFT_Partition class from the Mi‑
crosoft Windows operating system.
• Set number of logoffs to trigger VHD disk compaction. Lets you specify the number of user
logoffs to trigger VHD disk compaction.
When the number of logoffs since the last compaction reaches the specified value, disk com‑
paction is triggered again.
• Disable defragmentation for VHD disk compaction. Lets you specify whether to disable file
defragmentation for VHD disk compaction.
When VHD disk compaction is enabled, the VHD disk file is first automatically defragmented
using the Windows built‑in defrag tool, and then compacted. VHD disk defragmentation pro‑
duces better compaction results while disabling it can save system resources.
Enable exclusive access to profile container. If enabled, the profile container allows one access at
a time.
Enable exclusive access to OneDrive container. If enabled, the OneDrive container allows one ac‑
cess at a time.
Set number of retries when accessing locked files. Configures the number of times the WEM agent
retries accessing locked files. Supported values: 0–100.
Replicate user stores. If enabled, Profile Management replicates a user store to multiple paths on
each logoff, in addition to the path that the Set path to user store option specifies. To synchronize
to the user stores files and folders modified during a session, enable active write‑back. Enabling the
option can increase system I/O and might prolong logoffs.
By default, when multiple user stores are available, Profile Management selects the store with the
latest profile data. If more than one store has the latest profile, Profile Management selects the one
configured earliest. With the User store selection method option, you can now enable Profile Man‑
agement to select the store with the best access performance.
Enable credential‑based access to user store. If disabled, Profile Management impersonates the
current user to access user stores. Thus, make sure that the current user can directly access the user
stores. If enabled, Profile Management accesses the user stores on behalf of the user through the
connections configured for relevant services in Advanced Settings > File Shares > SMB shares. (When
needed, Profile Management accesses the selected SMB shares that host the user stores.) Enabling
this setting lets you put user stores in file shares (for example, Azure Files) that the current user has
no permission to access. When using this option, consider the following:
• To add SMB shares hosting your user stores, go to Advanced Settings > File Shares > SMB
shares.
• SMB shares you select in File Shares for relevant services appear here. Profile Management
accesses the selected SMB shares as needed.
IMPORTANT:
Disabling this setting deletes all user store connections that the WEM agent previously estab‑
lished.
Enable asynchronous processing for user Group Policy on logon. If enabled, Profile Management
roams with users a registry value that Windows uses to determine the processing mode for the next
user logon —synchronous or asynchronous processing mode. If the registry value does not exist, syn‑
chronous mode is applied. Enabling the option ensures that the actual processing mode is applied
each time users log on. If disabled, asynchronous mode can’t be applied as expected if users:
Process Internet cookie files on logoff. If enabled, stale cookies are deleted on logoff.
Log off user if problems occur. If enabled, users are logged off rather than switched to a temporary
profile if a problem occurs.
Join the Citrix Customer Experience Improvement Program. If enabled, Profile Management uses
the Customer Experience Improvement Program (CEIP) to help improve the quality and performance
of Citrix products by collecting anonymous statistics and usage information. For more information on
the CEIP, see About the Citrix Customer Experience Improvement Program (CEIP).
File system
Specify which files and folders in a profile are excluded from synchronization, which ones are synchro‑
nized to the user store, and how to synchronize them.
Enable exclusion check on logon. If enabled, configures what Profile Management does when a
user logs on when a profile in the user store contains excluded files or folders. (If disabled, the default
behavior is Synchronize excluded files or folders). You can select one of the following behaviors in
the list:
• Synchronize excluded files or folders (default). Profile Management synchronizes these ex‑
cluded files or folders from the user store to local profile when a user logs on.
• Ignore excluded files or folders. Profile Management ignores the excluded files or folders in
the user store when a user logs on.
• Delete excluded files or folders. Profile Management deletes the excluded files or folders in
the user store when a user logs on.
Enable default folder exclusions. Provides a default list of folders during synchronization. If en‑
abled, folders that are selected in this list are excluded from synchronization.
Enable folder exclusions. If enabled, the listed folders are not included in a user’s profile. This setting
lets you exclude specific folders containing a large amount of data that users do not need as part of
their profile. The list is pre‑populated with default Windows 7 exclusions, and can be pre‑populated
with default Windows XP exclusions instead.
Enable file exclusions. If enabled, the listed files are not included in a user’s profile. This setting lets
you exclude specific files containing a large amount of data that users do not need as part of their
profile. The list is pre‑populated with default Windows 7 exclusions, and can be pre‑populated with
default Windows XP exclusions instead.
Enable folder inclusions. If enabled, folders you add are forcibly synchronized to the user store.
Enable file inclusions. If enabled, files you add are forcibly synchronized to the user store.
TIP:
When adding files or folders, you can use wildcards. For more information, see Wildcard support.
Enable folder mirroring. If enabled, the folders you add are mirrored to the user store on logoff,
ensuring that files and subfolders in mirrored folders stored in the user store are exactly the same as
the local versions. See below for more information about how folder mirroring works.
Accelerate folder mirroring. By default, Profile Management copies necessary transactional folders
between the user store and local profiles. Mirroring ensures the integrity of those folders. This op‑
tion eliminates the need to copy them by using a container‑based solution, thus accelerating folder
mirroring. Profile Management attaches the virtual disk during logons and detaches it during logoffs,
eliminating the need to copy the folders between the user store and local profiles. Files in mirrored
folders will always overwrite files stored in the user store on session logoff, irrespective of whether
they are modified. If extra files or subfolders are present in the user store compared to the local ver‑
sions in mirrored folders, those extra files and subfolders are deleted from the user store on session
logoff.
• Add folders to mirror. By default, Profile Management copies necessary transactional folders
between the user store and local profiles. A transactional folder is a folder containing interde‑
pendent files, where one file references other files. You can add more as needed.
Enable large file handling. If enabled, large files are redirected to the user store, thus eliminating
the need to synchronize those files over the network.
Note:
Some applications do not allow concurrent file access. We recommend that you take application
behavior into consideration when you define your large file handling policy.
When adding exclusions, and inclusions, you can add them individually and in bulk. When adding
them in bulk, enter paths separated by line breaks. After that, click Run validation to validate items
you are about to add. Only valid items can be added. Invalid items are skipped.
Also, you can have a hierarchical view of exclusions and inclusions. To do that, click View hierarchy.
File deduplication
Specify files that you want to include in the shared store for deduplication.
Identical files can exist among various user profiles. Separating those files from the user store and
storing them in a central location saves storage space by avoiding duplicates.
You can specify files that you want to include in the shared store on the server hosting the user store.
Specify the file names with paths relative to the user profile.
Enable file deduplication. If enabled, Profile Management generates the shared store automatically.
It then centrally stores the specified files in the shared store rather than in each user profile in the user
store. Doing so reduces the load on the user store by avoiding file duplication, thus reducing your
storage cost.
Tip:
When adding files or folders, you can use wildcards. For more information, see Wildcard support.
When adding inclusions and exclusions, you can add them individually and in bulk. When adding
them in bulk, enter paths separated by commas or line breaks. After that, click Run validation to
validate items you are about to add. Only valid items can be added. Invalid items are skipped.
By default, Profile Management deduplicates files from profile containers only when those files are
larger than 256 MB. If necessary, you can increase this threshold size by providing a larger value for
Deduplicate files this size or larger (MB).
Enable file exclusions. If enabled, Profile Management excludes the specified files from the shared
store. This option is available only after you enable the Enable file deduplication option. Specify at
least one file to exclude from the shared store.
Enable profile streaming. If disabled, none of the settings in this section are processed.
• Enable profile streaming for folders. If enabled, folders are fetched only when they are being
accessed, thus eliminating the need to traverse all folders during logon. This saves bandwidth
and reduces the time to synchronize files.
Always cache. If enabled, files of the specified size (in MB) or larger are always cached. Supported
values: 0–20,000.
Set timeout for files in pending area when user store remains locked. Lets you specify the number
of days after which user’s files are written back to the user store from the pending area when the user
store remains locked. Supported values: 1–30.
Set streamed user profile groups. Lets you add user groups for which streamed profiles are used.
Set excluded folders. If enabled, Profile Management does not stream folders in this list, and all the
folders are fetched immediately from the user store to the local machine when users log on.
Enable profile streaming for pending area. If enabled, files in the pending area are fetched to the
local profile only when they are requested. This ensures optimum logon experience in concurrent
session scenarios. The pending area is used to ensure profile consistency while profile streaming is
enabled. It temporarily stores profile files and folders changed in concurrent sessions. By default,
this option is disabled. All files and folders in the pending area are fetched to the local profile during
logon.
Log settings
Include more information in the logs. Lets you specify more information (or types of events) in the
logs, including:
• Common warnings
• Common information
• File system notifications
• File system actions
• Registry actions
• Registry differences on logoff
• Active Directory actions
• Policy values on logon and logoff
• Logon
• Logoff
• Personalized user information
Set maximum size of the log file. Lets you specify a maximum allowed size for the Profile Manage‑
ment log file. If the log file grows beyond the maximum size, its backup (.bak) is deleted, the log file
is renamed to .bak, and a new log file is created. Supported values: 1–100.
Set path to log file. Lets you specify the location where the log file is created.
Registry
Specify which registry keys are included or excluded from Profile Management processing.
NTUSER.DAT backup. If enabled, Profile Management maintains a last known good backup of the
NTUSER.DAT file. If Profile Management detects corruption, it uses the last known good backup copy
to recover the profile.
Enable default registry exclusions. Provides a default list of registry keys in the HKCU hive that
are not synchronized to the user profile. If enabled, registry settings that are selected in this list are
forcibly excluded from Profile Management profiles.
Enable registry exclusions. If enabled, registry settings you add are forcibly excluded from Profile
Management profiles.
Enable registry inclusions. If enabled, registry settings you add are forcibly included in Profile Man‑
agement profiles.
Add rules to control user access to items such as files, folders, and registries. A typical use case is to
apply rules to control user access to apps installed on machines —whether to make apps invisible to
relevant users.
Suppose you need to provide applications (App1, App2, App3, and App4) in desktops assigned to users
from three departments: HR, Sales, and R&D.
To achieve the goal, you can deploy rules using just one image. The image contains applications App1,
App2, App3, and App4. You then set up application rules as follows:
• Create a rule for App1. Add objects associated with App1 and users from the Sales and R&D
departments.
• Create a rule for App2. Add objects associated with App2 and users from the HR and R&D de‑
partments.
• Create a rule for App3. Add objects associated with App3 and users from the HR and Sales
departments.
• GUI‑based tool ‑ WEM Tool Hub > Rule Generator for App Access Control
To get the application rules deployed, use app access control in the web console.
Enable app access control. If enabled, Profile Management processes the app rules. When adding
rules, you can browse to a .rule file generated using WEM Tool Hub > Rule Generator for App Access
Control or paste data from the clipboard. After adding rules, click Manage to view, edit, or update the
rules. When viewing rules, you can switch between category view and raw data view.
Wildcard support
When adding files or folders, you can use wildcards. Wildcards in file names are applied recursively
while wildcards in folder names are not. You can use the vertical bar (|) to restrict the policy only to
the current folder so that the policy does not apply to its subfolders.
Examples:
• AppData\*.tmp excludes all files with the extension .tmp in the folder AppData and its sub‑
folders.
• AppData\*.tmp| excludes all files with the extension .tmp in the folder AppData.
• Downloads\*\a.txt excludes a.txt in any immediate subfolder of the Downloads
folder. Remember: wildcards in folder names are not applied recursively.
• Downloads\* excludes all immediate subfolders of the Downloads folder.
Lists all scripted tasks available on the Scripted Tasks page. Scripted tasks run at a configuration set
level. Here, you configure which scripted tasks to enable for the current configuration set. To edit
your scripted tasks, go to Scripted Tasks.
1. On the Scripted Task Settings page, locate the scripted task, select the ellipsis, and then select
Configure.
2. In the Configure scripted task wizard, configure the following settings and then click Save.
In General:
• Enable this task. Choose whether to enable (Yes) or disable (No) the task for the current con‑
figuration set. If disabled, the agent does not process the task.
• Verify signature. Choose whether to verify the signature before running the task. Signature
verification is mandatory when the scripted task is granted full access.
• Task timeout. Choose whether to set a timeout (in minutes) for the task. When the timeout
occurs, the task is forced to end. Supported values: 1–60. We recommend setting a timeout for
the task. Otherwise, the task might be left running, preventing other tasks from running.
• Filter. Choose whether to contextualize the task by selecting a filter. With a filter selected, this
task runs only when all conditions in the filter are met. When selecting a filter, consider the
following:
– If the filter contains conditions that do not apply to scripted tasks, the agent skips those
conditions when evaluating the filter before running the task. For a complete list of con‑
ditions that do not apply to scripted tasks, see Conditions not applicable to machine set‑
tings.
In Triggers:
– Select triggers that you want to associate with the task. When activated, those triggers
start the task in the user environment.
Note:
In Parameters:
• Pass parameters to the scripted task. Choose whether to pass parameters to the scripted
task. When enabled, lets you provide inputs as parameter variables in the scripted task at run‑
time. The benefit is that you can control how the scripted task behaves without changing the
underlying code. The following parameter types are available:
Note:
In Output:
• Output files. Choose whether you want to collect files that the task outputs. If selected, in‑
cludes output file content in reports generated for the task. You can then view the output file
content in the reports without the need to access the output files in the user environment.
• Output highlights. Choose whether you want to highlight certain content in the output file
content and the console output.
– Highlight keywords. Specify keywords that you want the report to highlight. You can
type multiple keywords, separated by commas. After typing a keyword, press Enter to
continue. If specified, report contents that match your keywords will be highlighted in the
Output file content and Console output sections in the generated reports.
– Highlight regular expression matches. Enter a regular expression that describes the
content you want to highlight. The regular expression must conform to the .NET regu‑
lar expression library syntax, which is PCRE compatible. For more information, see the
Microsoft documentation: https://docs.microsoft.com/en‑us/dotnet/standard/base‑
types/regular‑expression‑language‑quick‑reference.
* Regular expression. Enter a regular expression that describes the content you want
to highlight.
* Ignore case. Choose whether content must exactly match the case.
* Use multiline matching. Choose whether to use multiline matching, where \^ and
$ match the beginning and end of each line, instead of the beginning and end of the
entire output content.
* Capture only named groups. Choose whether to capture only named groups.
Captured groups are defined by using parentheses in the regular expression pattern.
• Advanced options.
– Collect output even if runtime errors occur. Controls whether to collect output file con‑
tent and console output even if errors occur while running the task.
On the Scripted Task Settings page, locate the scripted task, select the ellipsis, and then select View
reports. As a result, you are taken to the Monitoring > Reports page, where you see the reports (if any)
related to the task. Click the ellipsis to view more detailed information. For details, see Reports.
This feature provides app delivery capabilities by allowing you to configure app installation/uninstal‑
lation tasks for agent machines that support WEM agent installers and custom .exe installers. You
can add app packages with installers stored in their SMB shares, specify the command, execution
criteria, and relevant settings for the package. You can then configure delivery tasks to deploy appli‑
cations to the user environment, with schedules and rules to handle the execution. App packages
are shared across all configuration sets. You can configure delivery tasks with app packages in each
configuration set. Only machine‑wide installers are supported.
For the cloud environment, only one built‑in WEM agent package is available. You can create a deliv‑
ery task, edit a package, and also delete a package using the ellipses associated with the WEM agent
package. All packages in use cannot be deleted. You can also sort the app packages and delivery tasks
in alphabetical order or based on the date of creation.
To configure the current configuration set’s storage location, complete the following steps.
1. Enter an SMB share and credentials of an administrator with the permission to access that share
in the Storage location page to add a new storage location and click Done.
2. The storage location specified applies to only the current configuration set.
3. Ensure to store your installers in the following path in your SMB share (Storage location
)\Citrix\WEM\AppPackages and click Save.
1. Click Add app package > EXE to access the Add app package page. This page lists Basic infor‑
mation, Execution criteria, and Settings in the tree structure.
• Execution criteria. You must specify the criteria that determine when the app package
must run. The execution criteria is classified into File or folder existence, File creation
date, File modification date, File version, File size, Registry key existence, Registry
value existence, and Registry value. Ensure to configure the Criteria to prevent errors
caused by the repeated execution of packages.
– On a 64‑bit version of Windows, when a file or folder path is configured within the
Program Files directory, the WEM agent will automatically check both the 32‑bit
Program Files (x86) and the 64‑bit Program Files folders, if you choose
the Criterion type as File or folder existence. For instance, if the configured path
is C:\Program Files\Test, the WEM agent verifies the existence of the follow‑
ing two paths: C:\Program Files (x86)\Test and C:\Program Files\
Test. Similarly, if the configured path is C:\Program Files (x86)\Test, the
WEM agent checks both C:\Program Files (x86)\Test and C:\Program
Files\Test. This ensures compatibility and accessibility across both 32‑bit and
64‑bit applications.
– If you choose the Criterion type as File size, the WEM agent calculates the file size
in kilobytes (KB) by considering the whole number part and ignoring decimal values.
For instance, if a file is 46,913,080 bytes in size, the WEM agent calculates its size in
KB as 45,813 KB (46,913,080 divided by 1024 is equal to 45,813.554, and the decimal
portion, .554,’is disregarded).
– If you choose the Criterion type as Registry key existence: In 64‑bit versions
of Windows, the registry is divided into 32‑bit and 64‑bit keys. When you config‑
ure a registry key as the 64‑bit version, the WEM agent attempts to confirm the
existence of the registry key‑in both the 32‑bit and 64‑bit versions. However, if
you configure a registry key as the 32‑bit version, the WEM agent only verifies
its presence in the 32‑bit version. For instance, if your configured registry key is
HKEY_LOCAL_MACHINE\Software\test, the criteria is met if either of the
following registry keys exists: HKEY_LOCAL_MACHINE\Software\test or
HKEY_LOCAL_MACHINE\Software\WOW6432Node\test. If your configured
registry key is HKEY_LOCAL_MACHINE\Software\WOW6432Node\test, the
criterion is met if HKEY_LOCAL_MACHINE\Software\WOW6432Node\test
exists.
3. After installing or uninstalling some packages, you can select the Reboot machine after exe‑
cution checkbox under Settings, if necessary.
• If the application package triggers a machine reboot during installation, the status is
recorded as an Unexpected Reboot as you cannot retrieve the precise result. Ensure to
incorporate a parameter in the installation command to prevent a reboot, and also select
the Reboot machine after execution check box to address this issue.
• If the application package requires ongoing operation after a reboot, the result of the pack‑
age may not be entirely accurate. This is because WEM cannot retrieve the result of a pack‑
age that was not initiated by WEM.
4. Ensure to specify return codes to indicate the success status. You can define the return code for
your packages under Settings.
1. Choose the Create delivery task > WEM agent upgrade task type to access the Create delivery
task page. This page lists Basic information and Schedule and rules in the tree structure.
4. For agents running in UI mode, enabling the Allow users to upgrade agent manually makes
the Upgrade option available in the agent user interface. You can use this option to upgrade the
agents to the version specified in the drop‑down menu (last three versions). This setting is a sub‑
set of the WEM agent upgrade delivery task. This means that manual upgrade task upgrades to
the version specified by the WEM agent upgrade delivery task subject to the set Rules.
5. Ensure to set the Schedule by specifying the time window and the day you need the delivery
task to run as the delivery task does not run manually without any set schedule. The start and
end times must be set at least two hours apart and on the same day.
6. You can also set Rules to determine which agent must run the task. You can select Match all or
Match any from Machine catalog name, Delivery group name, Device name, IP address, OS
platform type, OS version, and Persistent machine rules.
Note:
The following WEM agent upgrade settings may result in compatibility issues while performing
an agent upgrade, with versions older than 2310.
Limitation
• When you upgrade a WEM agent, the WEM agent versions earlier than 2310 can only use the first
created task among all the currently available agent upgrade tasks.
1. Choose the Create delivery task > Custom task type to access the Create delivery task page.
This page lists Basic information and Schedule and rules in the tree structure.
3. You can choose the required app packages and arrange them in the order that you want them
to run.
4. To avoid blocking the other scheduled tasks, ensure to choose Continue if failed under Task
content to continue with the seamless processing of other app packages even if one of the se‑
lected package functions (install/uninstall) fails.
5. If you select the Wait until the end to reboot checkbox, the reboot settings for individual app
packages are ignored and the machine will reboot when the entire list of tasks finish running.
6. Selecting the Run once checkbox enables you to run the scheduled task only once.
7. Ensure to set the schedule by specifying the time window and the day you need the delivery
task to run as the delivery task does not run manually without any schedule set.
8. The maximum execution time for each package is 60 minutes. Otherwise, the package times
out and gets terminated.
Advanced Settings
November 2, 2023
Use these settings to control how and when the Workspace Environment Management (WEM) agent
processes actions.
Agent settings
Agent options
• Do not launch agent for specified groups. If enabled, the Citrix WEM Agent Host is not
launched for any user belonging to the specified user groups.
• Launch agent only for specified groups. If enabled, the Citrix WEM Agent Host is launched
only for users belonging to the specified user groups.
Agent logs:
• Enable agent logging. If enabled, the agent outputs the agent log file.
• Debug mode. Controls whether to enable verbose logging for the agent.
Refresh:
• Refresh environment settings. If enabled, the agent triggers a refresh of user environment
settings when an agent refresh occurs. For information about environment settings, see Envi‑
ronment Settings.
• Refresh system settings. If enabled, the agent triggers a refresh of Windows system settings
(for example, Windows Explorer and Control Panel) when an agent refresh occurs.
• Refresh when environment settings change. If enabled, the agent triggers a Windows refresh
on endpoints when any environment setting changes.
• Refresh desktop. If enabled, the agent triggers a refresh of desktop settings when an agent
refresh occurs. For information about desktop settings, see Desktop.
• Refresh appearance. If enabled, the agent triggers a refresh of Windows theme and desktop
wallpaper when an agent refresh occurs.
• Enable automatic refresh. If enabled, the Citrix WEM Agent Host refreshes automatically. By
default, the refresh delay is 30 minutes.
Offline mode:
• Enable offline mode. If disabled, the agent does not fall back on its cache when it fails to con‑
nect to the WEM service.
• Use cache even when online. If enabled, the agent always reads its settings and actions from
its cache (which is built whenever the agent service cycles).
• Use cache to accelerate actions processing. If enabled, the agent processes actions by re‑
trieving relevant settings from the agent local cache instead of from the infrastructure services.
Doing so speeds up the processing of actions. By default, this option is enabled. Disable this
option if you want to revert to the previous behavior.
Important:
– The agent local cache is synchronized with the WEM service on a periodic basis. There‑
fore, changes to action settings take some time to take effect, depending on the value
that you specified for the Agent cache refresh delay option (in the Advanced Set‑
tings > Agent Settings > Agent service options tile).
– To reduce delays, specify a lower value. For the changes to take effect immediately,
navigate to Monitoring > Administration > Agents > Statistics , select the target
Agent cache refresh delay (min). This setting controls how long the Citrix WEM Agent Host Service
waits to refresh its cache. The refresh keeps the cache in sync with the WEM service database. The
default is 30 minutes. When using this option, keep the following in mind:
• The minimum interval at which the cache synchronizes with the WEM service database is 15
minutes. Type an integer that is equal to or greater than 15 minutes.
• The actual sync interval might vary. Based on the specified value, the WEM agent calculates
an interval in which a random value is selected as the actual sync interval each time the agent
cache refresh delay times out. For example, you set the value to 30 minutes. The agent selects
a random value from this interval: [(30 –30/2), (30 + 30/2)].
SQL settings refresh delay (min). This setting controls how long the Citrix WEM Agent Host Service
waits to refresh its SQL connection settings. The default is 15 minutes. Type an integer that is equal
to or greater than 15 minutes.
Agent extra launch delay (ms). This setting controls how long the Citrix WEM Agent Host Service
waits to launch the agent host executable. The default is 0.
Tip:
In scenarios where you want the agent host to complete the necessary work first, you can specify
how long the agent application launcher (VUEMAppCmd.exe) waits. VUEMAppCmd.exe ensures
that the agent host finishes processing an environment before Citrix DaaS (formerly Citrix Vir‑
tual Apps and Desktops service) and Citrix Virtual Apps and Desktops published applications are
started. To specify the wait time, configure the VUEMAppCmd extra sync delay setting, available
in the Agent Host Configuration group policy. For more information, see Install and configure
the agent.
Enable debug mode. Controls whether to enable verbose logging for all agents connecting to the
configuration set.
Bypass ie4uinit check. By default, the Citrix WEM Agent Host Service awaits ie4uinit to run before
launching the agent host executable. This setting forces the Citrix WEM Agent Host service to not wait
for ie4uinit.
Agent upgrade
Schedules automatic upgrades for all agents bound to this configuration set.
Upgrading an agent is now done within the new App Package Delivery feature. To configure and
schedule agent upgrades, go to App Package Delivery > Delivery tasks and create a WEM agent
upgrade delivery task. Settings configured previously are turned into delivery tasks automatically.
Miscellaneous
Configure settings such as notifications, initial environment cleanup, and Wake on LAN.
Notifications:
• Enable notifications for connection state change. If enabled, the agent displays notifica‑
tion messages on the agent host when the connection to the infrastructure service is lost or
restored. Citrix recommends that you do not enable this option on poor‑quality network con‑
nections. Otherwise, connection state change notifications might appear frequently on the end‑
point (agent host).
Extra features:
• Initial environment cleanup. If enabled, the agent cleans up the user environment during the
first logon. Specifically, it deletes the following items:
* With Preserve Auto‑created Printers on the Cleanup Actions tab enabled, the agent
does not delete auto‑created printers.
* With Preserve Specific Printers on the Cleanup Actions tab enabled, the agent does
not delete any of the printers specified in the list.
– All network drives except the network drive that is the home drive.
– All non‑system desktop, Start menu, Quick Launch, and Start‑button‑context‑menu short‑
cuts.
– All taskbar and Start menu pinned shortcuts.
• Initial desktop UI cleanup. If enabled, the agent cleans up the session desktop during the first
logon. Specifically, it deletes the following items:
– All non‑system desktop, Start menu, Quick Launch, and Start‑button‑context‑menu short‑
cuts.
– All taskbar and Start menu pinned shortcuts.
• Enable cross‑domain search for user groups. If enabled, the agent queries user groups in all
Active Directory domains. Cross‑domain search can be time‑intensive. Select this option only
if necessary.
• Enable agent to use cached domain search results. If enabled, the agent uses the cache
for domain query results to improve performance and resiliency. The domain query results is
cached up to seven days.
• Check application existence. If enabled, the agent does not create a shortcut unless it confirms
that the application exists on the machine the user signs in to.
• WEM service timeout (ms). The timeout value after which the agent switches to its own cache,
when it fails to connect to the infrastructure service. The default value is 15000 milliseconds.
• Agent max degree of parallelism. The maximum number of threads that the agent can use.
The default value is 0 (as many threads as physically allowed by the processor). 1 is single‑
threaded, 2 is dual‑threaded, and so on. Usually, this value does not need changing.
• Directory services timeout (ms). The timeout value for directory services on the Agent Host
machine, after which the agent uses its own internal cache of user group associations. The
default value is 15000 milliseconds.
• Network resources timeout (ms). The timeout value for resolving network resources (network
drives or file/folder resources located on the network), after which the agent considers that the
action has failed. The default value is 500 milliseconds.
Wake on LAN:
Use this tab to remotely turn on agent hosts. WEM automatically selects agents that reside on the
same subnet as the target agents and uses those agents as Wake on LAN messengers. This feature
requires hardware compatible with Wake on LAN. To use this feature, verify that the target machines
satisfy the hardware requirements and relevant BIOS settings are configured.
Enable Wake on LAN for agents. Controls whether to configure settings on Windows operating sys‑
tems to enable Wake on LAN for the agent hosts. If selected, the agents configure the following system
settings:
After enabling this option, navigate to Monitoring > Administration > Agents > Statistics, select one
or more agents from the list, and then select Power Management > Wake in More to wake up the
selected agents.
Action settings
This page lets you configure settings related to action processing and cleanup.
Action processing
Control how and when the agent processes actions, and whether unassigned actions get deleted from
desktops.
Action processing on logon and refresh. The following settings control what actions the agent
processes when users log on and when the agent refreshes.
Other Settings:
• Await policy and JSON file processing on logon. Use this option if you want users to complete
logon until all settings (GPOs and JSON objects) are processed.
Action processing on reconnection. The following settings control what actions the agent processes
when users reconnect to the agent machine.
Delete actions when unassigned. If these settings are enabled, the agent deletes any unassigned
actions when it next refreshes.
Enforce action processing. If these settings are enabled, the agent always refreshes those actions,
even if no changes have been made.
Enforce filter processing. If enabled, these options force the agent to reprocess filters on every re‑
fresh.
Asynchronous processing:
Action cleanup
Options present on this tile control whether the agent deletes the shortcuts or other items (network
drives and printers) on startup. When you assign actions to a user or user group, you might find that
you can also control the creation of the shortcuts or items. For example, you can specify where to
create the application shortcut when managing assignments for an application. Workspace Environ‑
ment Management processes these options according to a specific priority:
For example, suppose you have enabled the Create desktop shortcut option for the assigned appli‑
cation in Manage assignment, and the application shortcut is already created on the desktop. The
shortcut is still on the desktop when the agent starts, even though you enabled the Delete desktop
shortcuts on startup option on the Action cleanup tile.
Application shortcut. The following settings control what shortcuts to delete on startup.
Network printer:
• Delete network printers on startup. If enabled, the agent deletes all network printers on
startup.
Network drive:
• Delete network drives on startup. If enabled, the agent deletes all network drives on startup.
UI Agent Personalization
This page lets you personalize the appearance of the agent (in UI mode) in the user environment and
customize how users interact with it.
• Custom logo. By default, when the agent launches or refreshes, users see a splash screen with
the Citrix Workspace Environment Management logo. You can specify an image accessible from
the user environment to replace the logo.
• Loading circle color. Modifies the color of the loading circle to fit your custom logo.
• Text label color. Modifies the color of the loading text to fit your custom logo.
• UI agent theme. Select an appearance theme for dialogs that open from the UI agent.
• Hide agent splash screen. If enabled, hides the splash screen when the agent is loading or
refreshing. This setting does not take effect the first time the agent refreshes.
• Hide agent splash screen on reconnection. If enabled, hides the splash screen when users
reconnect to the agent machine.
• Hide agent splash screen for published applications. If enabled, hides the agent splash
screen for published applications where the agent is running.
• Hide agent icon for published applications. If enabled, published applications do not display
the agent icon.
User interaction:
• Only administrators can close agent. If enabled, only administrators can exit the agent. As a
result, the Exit option in the agent menu is disabled on endpoints for non‑administrators.
• Prohibit administrators from closing agent. If enabled, administrators cannot exit the agent.
• Disable administrative refresh feedback. If selected, no notification appears in the user envi‑
ronment when an administrator refreshes the agent using the administration console.
• Allow users to reset actions. Controls whether to display the Reset Actions option in the agent
menu. By default, the option is disabled. The Reset Actions option lets current users specify
what actions to reset in their environment. After a user selects Reset Actions, the Reset actions
dialog appears. In the dialog, the user can have granular control over what to reset. The user can
select the applicable actions and then click Reset. Doing so purges the corresponding action‑
related registry entries.
Note:
The following two options are always available in the agent menu: Refresh and About.
The Refresh option triggers an immediate update of the WEM agent settings. As a result,
settings configured in the administration console take effect immediately. The About op‑
tion opens a dialog displaying version details about the agent in use.
• Allow users to manage applications. If enabled, the Manage Applications option in the agent
menu is available to users on endpoints. Users can click the option to open the Manage appli‑
cations dialog and configure the following options. By default, the option is enabled.
• Allow users to manage printers. If enabled, the Manage Printers option in the agent menu is
available to users on endpoints. Users can click the option to open the Manage printers dialog
to configure a default printer and to modify print preferences. By default, the option is enabled.
• Show My Applications in agent menu. If enabled, show the My Applications option in the
agent menu. If shown, users can view applications assigned to them.
Specify help and support links and configure screen capture options.
Screen capture Enable screen capture. Controls whether to display the Capture option in the
agent menu. Users can use the option to open a screen capture tool. The tool provides the following
options:
Show Send to support option. Controls whether to display the Send to support option in the screen
capture tool. If enabled, users can use the option to send screenshots and log files directly to the
specified support email address, in the specified format. This setting requires a working, configured
email client.
Support email address. Enter an email address.
Email template. Specify an email content template that the screen capture tool uses to send support
emails. This field cannot be empty.
Note:
For a list of hash‑tags that you can use in the email template, see Dynamic tokens. Users are only
presented with the option to enter a comment if the ##UserScreenCaptureComment##
Custom subject. Specify an email subject template that the screen capture tool uses to send support
emails.
Use SMTP to send Email. If enabled, sends a support email using SMTP instead of MAPI.
Power saving
• Shut down at specified time. If enabled, the agent automatically shuts down the machine
where it is running at the specified time. The time is based on the agent time zone.
• Shut down when idle. If enabled, the agent automatically shuts down the machine where it is
running after the machine remains idle (no user input) for the specified length of time.
• Suspend rather than shutting down. If enabled, the agent instead suspends the machine
where it is running at the specified time or after the machine remains idle for the specified length
of time.
Monitoring preferences
• Action processing results. Lets you collect results of action processing and view a report. Se‑
lect the actions you want to collect results for.
Note:
• Results are uploaded every 4 hours. To immediately upload results from the agents, use
the Retrieve statistics from agent option in Monitoring > Administration > Agents.
• Optimization and usage insights. Lets you gain insights into application behavior. Use the
following option to control whether the agent collects and uploads data for insights.
– Enable data collection and upload for optimization and usage insights
After you enable the option, data updates might take a few hours to complete.
• Profile container insights. Lets you gain insights into profile containers for Profile Manage‑
ment and FSLogix. Use the following option to control whether the agent scans large files on
profile containers.
If enabled, run a scan of large files on profile containers when container usage exceeds
the specified threshold value. Scanning is limited to once every 24 hours. You can specify
what files are treated as large files based on their size.
• Profile Management health check. Lets you specify the scope of settings to cover in Profile
Management health check reports. Health checks run every 24 hours or on demand. Select the
Profile Management settings that you want to cover in the reports.
Note:
– To run health checks on demand, use the Run Profile Management health check
option in Monitoring > Administration > Agents.
– Changes you make are reflected only in new reports and do not affect existing reports.
Only the latest report is maintained for each agent.
• Security logs. Lets you collect logs on security rule executions and generates a report. Select
the security aspects that you want to include in the report.
– The Privilege elevation security aspect controls log collection for the events, EXE privi‑
lege elevation, MSI privilege elevation, and Self‑elevation.
– When you select the Process hierarchy control security aspect, Blocked activities option
is selected by default, but the Allowed activities option can be edited.
– When you select the Application security log security aspect, Blocked activities option
is checked by default, whereas the Audited activities, and Allowed activities option can
be edited.
• Application delivery results. Lets you collect the results of application delivery and generates
a report. If you select the Application delivery task results check box, the agent will collect
the report and upload the report to the WEM server. For more details, see Reports.
Note:
• Results are uploaded every 4 hours. To immediately upload results from the agents, use
the Retrieve statistics from agent option in Monitoring > Administration > Agents
File shares
This page lets you add SMB shares to which WEM can connect. You can then configure shares for
desired features so that those features can use the shares as needed. Using SMB shares reduces traffic
on networks and reduces the time to download files to agent machines.
A file download begins with a specific agent machine. This initial download occurs through Citrix
Cloud. After the download completes, the agent uploads the file to the file share for other agents to
use. So, later downloads occur directly through the file share rather than through Citrix Cloud.
With a file share configured, when a file download is needed, the agent first verifies whether the file
is available on the file share. If available, the download occurs through the file share. If unavailable,
the agent connects to Citrix Cloud for the initial download and then uploads the downloaded file to
the file share.
Enter an SMB share and credentials of an administrator with permission to access that share. Com‑
plete the following steps:
Select an SMB share from the list. The setting defaults to None. When selecting shares for features,
consider the following:
You can also change or remove the SMB shares for the App package delivery feature.
Select one or more SMB shares from the list. When selected, services (for example, Citrix Profile Man‑
agement service) running under the local system account in your deployment can use the shares as
needed —the connections to the shares are persistent. This feature enables those services to access
the shares through the connections.
• See Configure SMB shares for Citrix Profile Management service to use.
Directory Objects
Note:
Converting distinguished names to computer names can take some time. If the conversion is
incorrect or fails, verify that the Cloud Connectors are working properly by viewing their health
status. If the issue persists, contact Citrix Technical Support.
When agents on those machines register with the infrastructure service, the infrastructure service
sends them the necessary machine‑dependent settings related to the configuration set. To improve
the user experience, the infrastructure service caches data related to the configuration set for the
agents. Data caching allows the infrastructure service to retrieve data from the directory less fre‑
quently. The cache refreshes on an hourly basis. Changing agents to a different configuration set
can take some time to take effect.
Tip:
To check whether agents on those machines are correctly registered with the infrastructure ser‑
vice, go to Monitoring > Administration > Agents.
Click Add object, select the object type, and then navigate through the directory to the objects you
want to add. After adding objects of one type, you can switch to a different type to continue. After you
have finished, click Add.
3. Select a domain from the list and search for the machine or machine groups you want to add.
Note:
If your domain list has expired, you can force refresh your domain list by clicking the refresh
button.
1. Click the plus sign to add. Machines you add are listed in the table under the search box.
Add machines in an OU
3. Select a domain from the list and search for the OUs you want to add.
Note:
If your domain list has expired, you can force refresh your domain list by clicking the refresh
button.
1. Click the plus sign to add. Objects you add are listed in the table under the search box.
Non‑domain‑joined machines listed in Directory Objects are not shown in the list of machines
available to be added to a configuration set.
4. Click the plus sign to add. Machines you add are listed in the table under the search box.
1. On the Directory Objects node, select the object you want to edit and then select Edit from the
action bar.
2. In the Edit object wizard, edit any of the following details and then click Save.
• Distinguished Name. The distinguished name (DN) of the selected machine or machine
group. This name allows you to differentiate different OUs if they have the same name.
This section is not available for objects of the machine catalog type.
• Object type. The object type (machines, groups, OUs, or non‑domain‑joined machines).
• Configuration set. The configuration set to which you want to add the object.
• Priority. Lets you configure priority between different machines or groups. The priority
determines the order in which the actions you assign are processed. The greater the value,
the higher the priority. Type an integer. If there is a conflict (for example, when mapping
different network drives with the same drive letter), the machine or group with the higher
priority prevails.
• Object state. Controls whether to enable (Yes) or disable (No) the object. If disabled, the
machine, machine group, or OU is not available to assign actions to, and actions assigned
to it no longer take effect. Alternatively, you can toggle the state on or off by using the
toggle in the State column of the Directory Objects page.
Note:
For objects of the machine catalog type, you can change only the configuration set. To change the
name and description, use the Full Configuration interface of Citrix DaaS (formerly Citrix Virtual
Apps and Desktops service).
Delete objects
Select the object you want to delete and then select Delete from the action bar.
Advanced settings
Unbound agents
Control whether to apply settings to agents that are not bound to any configuration set. After you en‑
able the following settings, go to the “Unbound Agents”configuration set and then configure settings
there so that you can control how unbound agents behave.
• Apply settings to unbound agents. Lets you apply the settings of the “Unbound Agents”con‑
figuration set to agents that you have not yet added in Directory Objects.
– Include unbound non‑domain‑joined agents. Lets you control whether to apply the set‑
tings to unbound non‑domain‑joined agents.
Note:
With Apply settings to unbound agents enabled, if you add those unbound agents to a different
configuration set, it can take up to an hour for the new settings to be applied.
Non‑domain‑joined agents
Set up binding rules for unbound non‑domain‑joined agents. A rule dictates which configuration set
to bind the matching agents to. Each agent is evaluated against the rules in the order listed until a
match is found. You can add up to 50 rules.
– Device name. Enter a regular expression that describes device names to match. For
example, if the machines you want to match are named PC‑Sales‑01, PC‑Sales‑02, PC‑
Sales‑03, and so on, enter the following expression: PC-Sales.*.
– IP address. Enter an IP address or an IP address range. You can also enter a regular
expression that describes IP addresses to match. For example, if the addresses you
want to match are 192.168.1.0 through 192.168.1.255, enter the following expression:
192\.168\.1\..*.
– MAC address. Enter a comma‑separated list of MAC addresses.
Monitoring
The Monitoring node provides information that you can use for monitoring and troubleshooting
your Workspace Environment Management (WEM) deployment and lets you perform administrative
tasks.
• Administration. Lets you view user and agent statistics and administrative activities.
• Insights. Lets you gain insights into application behavior. To enable insights for a configuration
set, go to its Advanced Settings > Insights page and select Enable data collection and upload
for optimization and usage insights. To view insights, select a configuration set and a date
range and then click Apply.
– Optimization Insights. Displays the top 10 applications that triggered CPU spike protec‑
tion and memory usage optimization most frequently over the specified time period.
– Usage Insights. Displays the top 10 applications by usage time (hours) and the top 10
applications by number of users, along with the top 10 applications that consumed the
most CPU and memory resources over the specified time period.
– Profile Container Insights. Displays insights for Profile Management and FSLogix con‑
tainers.
• Reports. Provides reports that let you analyze your deployments. Each report appears as a table
record.
Administration
Lets you view user and agent statistics and administrative activities.
User statistics
Displays user statistics about your Workspace Environment Management (WEM) deployment. Each
time users log on to their agent machine, relevant information is collected and then appears here as
a table record.
• User summary. Displays a count of all users who have logged on to their agent machine, for all
configuration sets.
• User history. Displays connection information for all users associated with all configuration
sets, including the last connection time (in Coordinated Universal Time, UTC), the name of the
machine from which they last connected, and the session agent type (UI or CMD) and version.
Tip:
You can use Filter to filter the list. For example, display a count of all users for a specific configu‑
ration set and a count of users during the specified date range.
• Clear expired records. Lets you delete expired records from the WEM service database. If a
user’s last logon time dates back more than 24 hours, the corresponding record expires. Un‑
available when you do not have any expired records. Note: This option is not available for
records whose User ID is Local system.
• Delete record. Deletes the record from the WEM service database. Available when you select
only one agent and its corresponding record has expired. Note: This option is not available for
records whose User ID is Local system, Network service, or NT Authority (Local service).
• Export. Lets you export the data in each record in CSV or JSON format, which opens in programs
such as Microsoft Excel. To do that, perform the following steps:
Important:
– You can export up to 50,000 records. When the number of records to export exceeds
the limit, only the top 50,000 will be exported. We recommend that you use filters to
reduce the number of records to 50,000 or fewer.
– While an export is in progress, you cannot perform another export.
– If an export does not complete within 30 minutes, you will no longer receive notifica‑
tions about it. Go to Files to view the export results later.
– When exporting user statistics, the export is saved to the cloud storage. The cloud
storage has a storage limit. When you reach the limit, you cannot proceed with the
export. In that case, go to Files and delete unnecessary files to free up space. See
Files.
Agents
This page lets you view agent information and perform administrative tasks such as refreshing the
cache, resetting settings, and retrieving agent information.
Statistics
This tab shows statistics about the agents in your WEM deployment. You can view the following sta‑
tistics about the agents in your WEM deployment.
• A count of total agents users have logged on to, for all configuration sets.
Tip:
If you specify a configuration set in your filter criteria, a count of total registered agents
for that configuration set appears, along with the count of agents registered in the last 24
hours and in the last 30 days.
• Connection information for all agents registered with the configuration sets, including the last
connection time, the name of the machine from which they last connected, and the agent ver‑
sion.
• The Synchronization state column provides information about the result of the last sync of the
agent cache with the WEM service.
– Successful (check mark icon). Indicates that the last sync was successful, with the sync
result reported to the administration console.
– Unknown (exclamation mark icon). Indicates that sync is in progress, has not started yet,
or the result is not reported to the administration console.
– Failed (error icon). Indicates that the last sync failed.
– Online (check mark icon). Indicates that the agent is online. The agent has uploaded sta‑
tistics to the WEM service within a certain interval.
– A blank column field indicates that the agent is offline.
• The Profile Management health column provides information about the health status of Pro‑
file Management in your environment.
Profile Management health status performs automated status checks on your agent hosts to de‑
termine whether Profile Management is configured optimally. You can view the results of those
checks to identify specific issues from the output file on each agent machine (%systemroot
%\temp\UpmConfigCheckOutput.json). The feature performs status checks every day
or each time the WEM agent host service starts. To perform the status checks manually, se‑
lect the agent, and then select the Run Profile Management health check from the action bar.
Each status check returns a status. To view the most recent status, click Refresh. The icon in
the Profile Management health column provides general information about the health status
of Profile Management:
– Good (check mark icon). Indicates that Profile Management is in good shape.
– Notice (check mark icon with blue dot in the upper right corner). Identifies an acceptable
state of Profile Management.
– Warning (check mark icon with orange dot in the upper right corner). Informs about a
suboptimal state of Profile Management. The suboptimal state might affect the user ex‑
perience with Profile Management in your deployment. This status does not necessarily
require action on your part. To view the detailed report, use the View Profile Manage‑
ment health check report option in More.
– Error (error icon). Indicates that Profile Management is configured incorrectly, causing it
not to function properly.
– Invalid (disabled icon). Appears when Profile Management is not found or not enabled.
If the status checks do not reflect your experience or if they do not detect the issues you are
having, contact Citrix Technical Support.
• Task history. Lists the agent tasks initiated in the last 24 hours. Clicking Task history on the
Agents page directs you to the Task history page to check the progress and results of the initi‑
ated tasks.
• Columns to display. Lets you customize the table by choosing which columns you want to
display.
• Clear expired records. Lets you delete expired records from the WEM service database. If a
user’s last logon time dates back more than 24 hours, the corresponding record expires. Un‑
available when you do not have any expired records.
• View details. Lets you view detailed information about the agent.
• Export. Lets you export the data in each record in CSV or JSON format, which opens in programs
such as Microsoft Excel. To do that, perform the following steps:
Important:
– You can export up to 50,000 records. When the number of records to export exceeds
the limit, only the top 50,000 will be exported. We recommend that you use filters to
reduce the number of records to 50,000 or fewer.
– While an export is in progress, you cannot perform another export.
– If an export does not complete within 30 minutes, you will no longer receive notifica‑
tions about it. Go to Files to view the export results later.
– When exporting agent statistics, the export is saved to the cloud storage. The cloud
storage has a storage limit. When you reach the limit, you cannot proceed with the
export. In that case, go to Files and delete unnecessary files to free up space. See
Files.
The following options are available in the More menu. When applying these options to non‑domain‑
joined and enrolled agents, consider the following:
Note:
The More menu is available only when you select no more than 50 agents.
Agent:
• Refresh cache. Triggers a refresh of the local agent cache (an agent‑side replica of the WEM con‑
figuration database). Refreshing the cache syncs the local agent cache with the infrastructure
services.
• Refresh agent host settings. Triggers a refresh of the agent service settings in the user envi‑
ronment. Those settings include advanced, optimization, transformer, and non‑user assigned
settings.
• Refresh UI‑mode agent. Applies the user‑assigned actions to the WEM agents. Those actions
include network drives, printers, applications, and more. When you refresh an agent, it com‑
municates with the infrastructure services. The infrastructure services validate the agent host
identity with the WEM database.
Important:
– The Refresh UI‑mode agent option works only with the agents in UI mode that are
automatically launched (not launched by end users or by using scripts). The option
does not work with the agents in CMD mode.
– Not all settings can be refreshed. Some settings (for example, environment and group
policy settings) are applied only on startup or logon.
• Retrieve statistics from agent. Enables the agents to upload statistics to the infrastructure
services.
You can also perform the refresh operations on the agent side. However, those operations behave dif‑
ferently depending on actual conditions. For more information, see Agent‑side refresh operations.
Profile:
• Reset Profile Management settings. Clears the registry cache and updates the associated con‑
figuration settings. If Profile Management settings are not applied to your agent, click Reset
Profile Management Settings. You might need to click Refresh for this option to become avail‑
able.
Note:
If the settings are not applied to the agent after configuring Reset Profile Management
Settings from the WEM administration console, see CTX219086 for a workaround.
• Run Profile Management health check. Performs status checks on the target agent machines
to determine whether Profile Management is configured optimally. After selecting this option,
the Run Profile Management health check wizard appears. Select the Profile Management
settings that you want to cover in the health check report and then click Run. Be aware of the
following:
– By default, the health reports cover all settings. For agents earlier than 2205.1.0.1, changes
you make to the scope of settings to cover in the report do not take effect.
– It might take some time before you can see the health reports. In Reports, refresh the view
if necessary.
– Click View reports to access the reports directly.
• View Profile Management health check report. Provides quick access to Profile Management
health reports related to the target agent machines. For more information about Profile Man‑
agement health reports, see Reports.
• Reset Microsoft USV settings. Clears the registry cache and updates the associated configura‑
tion settings. If Microsoft USV settings are not applied to your agent, click Reset Microsoft USV
settings. You might need to click Refresh for this option to become available.
Power management:
• Sleep. Lets you put the selected agents into sleep mode. This option works only when the target
machine supports sleep mode.
• Hibernate. Lets you put the selected agents into hibernate mode. This option works only when
the target machine supports hibernate mode.
• Wake. Lets you wake up the selected agents. For the option to work, go to Legacy Console
> Advanced Settings > Configuration > Wake on LAN and select Enable Wake on LAN for
Agents. Also, make sure that the target machines satisfy the hardware requirements and the
relevant BIOS settings are configured. For more information, see Wake on LAN.
Tip:
– When you shut down or restart agents, you can specify a delay (in seconds) be‑
fore the shutdown or restart begins. Users receive a prompt that the machine
will shut down or restart in the amount of time you specify. Shutdown prompt
example: Your administrator has initiated the shutdown of
your machine from the Workspace Environment Management
console. The machine shuts down in 60 seconds.. Restart prompt
example: Your administrator has initiated the restart of
your machine from the Workspace Environment Management
console. The machine restarts in 60 seconds..
– Consider the differences between sleep and hibernate. In sleep mode, all actions on
the machine are stopped, and any open documents and applications are put in mem‑
ory. The machine goes into a low‑power state. In hibernate mode, open documents
and running applications are saved to the hard disk. The machine is turned off entirely,
using zero power.
– To verify that the target machine supports sleep and hibernate modes, go to the ma‑
chine and run the following PowerShell commands: powercfg /a.
Process Citrix Optimizer. Applies the settings to the agents so that changes to Citrix Optimizer set‑
tings take effect immediately.
Run scripted task. Lets you run scripted tasks on the target agent machines. After selecting this
option, the Run scripted task wizard appears. Configure the following settings and then click Run.
For more information about each setting, see Scripted Task Settings.
Note:
Run delivery task. To enable this option, select agents bound to the same configuration set. To run
a delivery task quickly, you can choose to run a delivery task from this page. Click Run delivery task
and choose the delivery task from the drop‑down list to run the selected delivery task on the agent. If
you configure rules in the task to determine which agents must run the task, those rules get ignored
when you select specific agents to run the on demand tasks.
Reset actions. Lets you reset all actions you assigned by purging all action‑related registry entries on
the applicable agent machine.
Delete record. Deletes the record from the WEM service database. If the agent is still active, this
option is unavailable. Available when you select only one agent and its corresponding record has
expired.
Registrations
This tab shows the registration status of the agents recorded in the database.
Important:
WEM agents must register with the WEM service so that settings can be applied to them. An agent
can be bound only to one configuration set.
Use Search to refine the results if necessary. Searches run only against device names and descrip‑
tions. By default, searches are restricted only to unregistered agents. To remove the restriction, en‑
able Show only unregistered agents.
• Edit the Active Directory hierarchy (relations between computers, computer groups, and OUs)
so that an agent won’t be bound to the same configuration sets multiple times.
• Edit the WEM hierarchy in Directory Objects so that an agent binds only to one configuration
set.
• Apply settings to unbound agents (if not yet done) so that the settings of the “Unbound Agents”
configuration set are applied to unbound agents (agents that you have not yet added in Direc‑
tory Objects).
After making these changes, use the Refresh UI‑mode agent option to refresh the agents.
WEM can check whether Citrix Profile Management is configured optimally on your agent machine.
For more information, see Configure Profile Management health check.
Insights
October 9, 2023
Lets you gain insights into profile container and application behavior.
Optimization insights
• Top 20 applications by CPU optimization. Shows the top 10 applications that triggered CPU
spike protection most frequently over the specified time period.
• Top 20 applications by memory optimization. Shows the top 10 applications that triggered
memory usage optimization most frequently over the specified time period.
To view insights, select a configuration set and a date range and then click Apply. Then, the charts
refresh to display relevant insights.
Important:
• For the charts to show data for a configuration set, you must enable insights for it. To enable
insights for a configuration set, go to its Advanced Settings > Insights page. The charts
show insights based on the data collected previously.
• Optimization insights data is not available until you enable CPU or memory management.
Excluded applications
You can exclude applications from the optimization insights (bar chart). To specify an excluded appli‑
cation, complete the following steps.
• Click Add.
• Type the name of the application as mentioned in the bar chart.
• Press Enter to save or Shift + Enter to save and start another entry.
• You can also edit and delete the added application by following the wizard instructions.
Usage insights
To view insights, select a configuration set and a date range and then click Apply. Then, the charts
refresh to display relevant insights.
Important:
For the charts to show data for a configuration set, you need to enable insights for it. To enable
insights for a configuration set, go to its Advanced Settings > Insights page. The charts show
insights based on the data collected previously.
Excluded applications
You can exclude applications from the usage insights (bar chart). To specify an excluded application,
complete the following steps.
• Click Add.
• Type the name of the application as mentioned in the bar chart. When filling up the name of
applications, an extension is not included.
• Press Enter to save or Shift + Enter to save and start another entry.
• You can also edit and delete the added application by following the wizard instructions.
This feature monitors profile containers for Profile Management and FSLogix. It provides insights into
the basic usage data of the profile containers, the status of sessions using the profile containers, the
issues detected, and more.
Use this feature to stay on top of space usage for profile containers and to identify problems that
prevent profile containers from working.
Summary
This page includes two doughnut charts. You can click each segment of the chart to drill down for
more details.
• Space usage. The chart on the left side shows the space usage of profile containers over the
specified time period. A numeric value represents the number of profile containers of that cat‑
egory.
• Session Status. The chart on the right side shows the results of attaching profile containers for
sessions established over the specified time period. A numeric value represents the number of
sessions of that category.
To view insights, select a configuration set and a date range and then click Apply. Then, the charts
refresh to display relevant insights.
• Space usage is high when used space is more than (GB). Lets you type a threshold value above
which to treat the space usage of the profile containers as high. Type a positive integer.
• Space usage is low when used space is less than (GB). Lets you type a threshold value below
which to treat the space usage of the profile containers as low. Type a positive integer.
Note:
• The high threshold value must be greater than the low threshold value.
• After specifying the high and the low threshold values, click Refresh to trigger a refresh of
the Used Space chart.
• After specifying the high and the low threshold values, space usage in between defaults to
Medium.
This page displays a list of status records for profile containers over a specified time period. To filter
records, select a configuration set and a date range and then click Apply. If necessary, you can use
filters to refine the results further.
• Columns to display. Lets you customize the display of the table. When customizing columns,
you must select at least two columns. After you complete your customization, the table re‑
freshes to display the columns you select.
• Get latest status. Triggers the collection of data for the container the selected record pertains
to. This option brings you up to date with the user’s container status.
Note:
If the container is in use, the agent attempts to collect relevant data. If successful, the latest
status is updated in the container’s latest record. It might take a while for the update to
complete. Click Refresh for the up‑to‑date record to appear.
The Attach status column displays information about status and error codes. For information about
error codes, see the Microsoft
documentation https://docs.microsoft.com/en‑us/fslogix/fslogix‑error‑codes‑reference.
The Large file scan column provides information on the results of the large file scan. To enable large
file scanning for a configuration set, go to its Advanced Settings > Insights page. To view details of
the large file scan results for a record, click Results in the relevant column field. The large file scan
wizard appears, presenting the results of the large file scan performed on the profile container. Files
and folders smaller than 100 MB are not listed individually.
Reports
Introduction
This page provides reports that let you analyze your deployments. Reports are generated on a per‑
event basis. However, not all events generate corresponding reports. Currently, events of the follow‑
ing types generate reports.
– Each time you enable the Application security logs, a corresponding record is generated.
We consolidate those records into a single report every four hours. Within the details of
each report, administrators can view the logs by subtype. The table includes information
such as the filter used, Event time, Event type, Result code, Result summary, Severity,
list of agents and users, and the Configuration set. The table also includes the following
subtypes.
When you enable Application security logs, you can view all the four EXE and DLL, MSI
and script, Packaged app deployment, and Packaged app execution subtype reports
in the web console, but cannot view the report corresponding to each subtype separately.
The table provides the logs for the fields Time, Rule name, Event ID, Target, and Result.
The result of this selection can be Allowed, Audited, or Blocked.
– Each time you enable the Privilege elevation and process hierarchy control logs, a corre‑
sponding record is generated. We consolidate those records into a single report every four
hours. Within the details of each report, administrators can view the logs by subtype. The
table includes information such as the filter used, Event time, Event type, Result code,
Result summary, Severity, list of agents and users, and the Configuration set. You can
choose from the four security aspects to view more details.
– EXE privilege elevation. When the EXE privilege elevation subtype is selected, the table
provides the logs for the fields Time, Process, Command line, Rule name, and Result.
The result of the elevation can either be a success or a failure.
– MSI privilege elevation. When the MSI privilege elevation subtype is selected, the table
provides the logs for the fields Time, Packages, Command line, Rule name, and Result.
The result of the elevation can either be a success or a failure.
– Self‑elevation. When the Self‑elevation subtype is selected, the table provides the logs
for the fields Time, Process, Rule name, Reason and Result. The result of the elevation
can either be a success or a failure.
Note:
Enabling the Show failures only toggle displays only the records with the result Failure
and hides the rest.
– Process hierarchy control. When you select the Process hierarchy control subtype, the
table provides the logs for the fields Time, Child process, Parent process ID, Rule name,
and Result. The result of this selection results in displaying either a blocked or allowed
activity.
Note:
– You see the error icon on the security aspect tab when at least one failure occurs in
each subtype.
– Enabling the Show blocked only toggle displays only the records with the result
Blocked and hides the rest.
* Applied (processed). Means that the action was applied to the target user success‑
fully (or processed successfully).
* Outdated. Means that the action processed is not the latest. This happens when an
action gets updated but not yet applied.
* Error. An error occurred while applying the action. To troubleshoot, enable debug
mode to view the logs of the agent. See View log files.
– Currently, you can view only Group Policy setting and JSON file processing results. To en‑
able results collection, see Monitoring preferences.
• Scripted task
– Each time a task runs, a corresponding report is generated. The reports include informa‑
tion about when the task runs, the task execution results, and more.
– Both built‑in and custom tasks generate reports. In those reports, we provide predefined
report data. When adding custom tasks, you can customize the data to be reported. If
the predefined report data does not suit your needs, consider using the extended data for
further analysis.
– With Enable data collection and upload for optimization and usage insights enabled
for a configuration set on its Advanced Settings > Insights page, the agent collects and
uploads optimization and usage data on a daily basis. A report based on the data collected
is generated.
– Each time you apply insights for a configuration set, a corresponding report on optimiza‑
tion and usage is generated. The reports let you gain insights into application behavior.
We aggregate usage and optimization insights into one report.
Note:
On the Optimization Insights or the Usage Insights page of Monitoring > Insights, you
apply insights by selecting a configuration set and a date range. We maintain only one
report for insights applied using the same configuration set and date range. Applying in‑
sights using the same configuration set and date range updates the report later.
– The agent runs Profile Management health checks every 24 hours or on demand. A corre‑
sponding report is then generated. The report contains the following elements:
– To fix the errors/warnings and to reach the required profile management settings, click
More > Profile > View Profile Management health check report in the Statistics tab of
the Agents page, that leads you to the Reports page. You can then select Profile Manage‑
ment Settings under Results to change/update your Profile Management settings under
the Details tab of the Profile Management health check page, that leads you to the Pro‑
file Management configuration page. You can cycle through all the errors/warnings in the
footer that have the corresponding setting highlighted, and make the required change to
the configuration.
– If you set the filter by selecting the Application delivery task results event type, the agent
will display only the corresponding report. However, the Application delivery task re‑
sults page provides only the Raw data.
Each report appears as a table record. Those reports provide useful diagnostic information that can
inform your action. For example, you can check reports based on event severity. Based on the severity
level, you can decide what action to take.
Tip:
We have pre‑defined levels of severity for certain reports, for example, built‑in scripted task re‑
ports.
For a scripted task, the Result code column can provide the following information:
For information about result codes (status codes) of profile container status, see the Microsoft docu‑
mentation https://docs.microsoft.com/en‑us/fslogix/fslogix‑error‑codes‑reference. Remember:
“‑1”means that WEM might not retrieve the status code.
You can customize the display of the table. Click Columns to display to choose which columns you
want to display. When customizing columns, you must select at least two columns. After you complete
your customization, the table refreshes to display the columns you select.
You can click a column header to sort. You can apply filters to filter reports.
You can select a report for more detailed information. To do that, locate the report and then click the
ellipsis on the right. The report wizard appears. It contains two tabs:
For a scripted task that has Highlight regular expression matches enabled, you can see the following
option on the Details tab of its report:
• View regular expression matches. Lets you view regular expression matches in detail.
Export reports
You can export the data in each report in CSV or JSON format. To do that, perform the following
steps:
In addition, the formatted options can parse the script task reports into variables if the report con‑
tent follows the format variable = value or variable: value. However, if you choose the
CSV (formatted) option, some of the excessive number of columns might be omitted in the exported
data.
1. Optionally, select Save a copy of the export to your local machine. The export will be saved
to the default download location of your browser.
Important:
• You can export up to 50,000 records (reports). When the number of records to export ex‑
ceeds the limit, only the top 50,000 will be exported. We recommend that you use filters to
reduce the number of records to 50,000 or fewer.
• While an export is in progress, you cannot perform another export.
• If an export does not complete within 30 minutes, you will no longer receive notifications
about it. Go to Files to view the export result later.
• When exporting reports, the export will be saved to the cloud storage. The cloud storage
has a storage limit. When you reach the limit, you cannot proceed with the export. In that
case, go to Files and delete unnecessary files to free up space. See Files.
Scripted Tasks
September 8, 2023
Introduction
Tip:
Scripted tasks work at a machine level. To run tasks at a user session level, use External tasks
instead.
This page lets you add scripted tasks that you customize to suit your unique environment manage‑
ment needs. You can then automate those tasks with Workspace Environment Management (WEM)
by configuring them in the applicable configuration set.
Currently, we provide the following built‑in scripted task for you to use:
• Cloud Health Check. Lets you run checks that gauge the health of Virtual Delivery Agents (VDAs).
VDA health checks identify possible causes for common VDA registration and session launch
issues. Cloud Health Check runs under the local system account on the agent host.
Tip:
• You can differentiate between custom and built‑in scripted tasks: Custom tasks are marked
with the “CUSTOM”label and built‑in ones with the “CITRIX”label.
• Built‑in scripted tasks always appear above custom ones. Custom scripted tasks are sorted
in descending order based on the last modified time.
With this feature, you can extend the capabilities of WEM for your unique management needs. For
example, the built‑in scripted task Cloud Health Check lets you gauge the health of the VDAs. The task
is script based. You can write your own script file. Then, you add the script file to WEM as a scripted
task so you can automate the task using WEM.
Each time a scripted task runs, a corresponding report is generated for it. The report includes infor‑
mation about when the task runs, the task execution results, and more, thus giving you the ability to
audit activities related to the task.
Scripted tasks work at a configuration set level. A general workflow to use scripted tasks is as fol‑
lows:
2. Navigate to the configuration set for which you want to enable the scripted task.
3. On the Scripted Task Settings page of that configuration set, enable the scripted task. See
Scripted Task Settings.
4. Optionally, view reports related to the scripted task. There are two ways to do that:
2. In the Add scripted task wizard, configure the following settings and then click Save.
• Tags. Select from existing tags or enter tags separated by commas. A tag must be no more
than 20 characters long. Tags are like keywords or labels. Using tags enables you to iden‑
tify your tasks in new ways. Also, they act as filters, letting you rearrange your view of
tasks in Scripted Tasks depending on criteria that are important to you. You can use as
many tags as you like.
• Description. Optionally, specify additional information to help you identify the task.
• File type. Select a file type for the task. Two types of files are supported:
• Upload file. Click Browse, navigate to the file, select it, and then click Open. You are
returned to the Add scripted task wizard.
• Grant permissions. Specify the level of access that you want to grant to the scripted task.
Ensure that you understand the permissions associated with each option.
– Full access. A scripted task assigned Full access has extensive local access. If selected,
the scripted task is granted permissions as if it runs under the local system account.
– Limited access (with network access). A scripted task assigned Limited access
(with network access) does not have extensive local access but can access network
resources. If selected, the scripted task is granted permissions as if it runs under the
network service account.
– Limited access (without network access). A scripted task assigned Limited access
(without network access) does not have extensive local access and cannot access net‑
work resources. If selected, the scripted task is granted permissions as if it runs under
the local service account.
• Working folder. Optionally, type the absolute path of the local folder on the end‑user operating
system. The working folder is the current folder for the file when it starts. You can build the path
with environment variables (for example, %ProgramFiles%). If unspecified, PSScriptRoot
is used as the default working folder. For more information about PSScriptRoot, see the
Microsoft documentation https://docs.microsoft.com/en‑us/powershell/module/microsoft.p
owershell.core/about/about_automatic_variables?view=powershell‑7.1.
• Does this task generate output files. Choose whether the task you add generates output files.
• Output path. Type a path relative to the folder where the file resides. The path must contain
the file name and the file name extension. Example: output\report.txt.
1. On the Scripted Tasks page, locate the task. If needed, use the search box to quickly search for
the task.
2. Click the ellipsis of the task and then select Edit task. The Edit scripted task wizard appears.
5. Click Save.
Note:
1. On the Scripted Tasks page, locate the task. If needed, use the search box to quickly search for
the task.
2. Click the ellipsis of the task and then select Delete task.
Important:
1. On the Scripted Tasks page, locate the task. If needed, use the search box or tags to quickly
find the task.
2. Click the ellipsis of the task and then select Clone task.
Note:
When cloning a task, you are prompted to change the name to avoid duplicate names.
1. On the Scripted Tasks page, locate the task. If needed, use the search box or tags to quickly
find the task.
2. Click the ellipsis of the task and then select Configure task settings.
4. Click Go to reach the filtered task in the Scripted Task Settings page, where only the chosen
task is filtered out.
More information
Files
This page lets you manage all your files on your cloud storage in one place. The total size of your
storage space is 10 GB. If necessary, delete files to free up space.
Currently, you can download and delete files available on the storage.
Note:
• Backup and restore files are not shown here but they take up storage space.
• You can’t delete files associated with scripted tasks. To delete them, delete their tasks.
Enrollment
The Enrollment node lists enrolled agents for you to manage and lets you use the enrollment method
to enroll agents.
The enrollment method is one of the three setup methods you can use to connect the Workspace En‑
vironment Management (WEM) agent to the WEM service. For more information, see Enroll agents.
• Enrolled Agents. Lists all enrolled agents. You can manage them as needed.
• Invitation. Lets you send enrollment invitations to users. Each invitation includes an invitation
code and the steps needed to complete the enrollment.
Enrolled Agents
Lists all enrolled Workspace Environment Management (WEM) agents. You can manage them as
needed.
Introduction
After an agent enrolls, it becomes managed. In Directory Objects, you can bind it to a configuration
set as needed. For information about enrollment, see Enroll agents.
• Enroll by invitation. This requires the web console. Users can be invited to participate in the
enrollment process.
• Enroll with the bearer token or API secure client. This doesn’t require the web console and
doesn’t require users to participate in the enrollment process. For more information, see Enroll
with the bearer token or API secure client.
• Edit associated user. Changes the association or removes the associated user.
Unenroll an agent
You can unenroll multiple agents at a time. Unenrolling an agent invalidates its enrollment and re‑
moves it from WEM.
When enrolled, non‑domain‑joined devices are automatically associated with invited users. Associat‑
ing a user with a non‑domain‑joined machine lets WEM apply settings to the user on logon.
2. In the action bar, select Edit associated user. The Edit associated user wizard appears.
5. In the Select user box, enter the name of the user that you want to add.
To remove the associated user for a device, perform the following steps:
2. In the action bar, select Edit associated user. The Edit associated user wizard appears.
If an enrolled agent has been inactive for 270 days, its enrollment becomes invalid. It will no longer be
managed by WEM. The Remove invalid agents button appears only when there are invalid agents.
Invitation
Lets you send enrollment invitations to users. Each invitation includes an invitation code and the
steps needed to complete the enrollment.
Introduction
You have the flexibility to determine how to enroll your Workspace Environment Management (WEM)
agents. There are two ways:
• Enroll by invitation. This requires the web console. Users can be invited to participate in the
enrollment process.
• Enroll with the bearer token or API secure client. This doesn’t require the web console and
doesn’t require users to participate in the enrollment process. For more information, see Enroll
with the bearer token or API secure client.
1. In Manage > Web Console > Enrollment > Invitation, enable Enroll by invitation and then
click Generate to generate an enrollment key.
2. On the agent machine, install the enrollment key using the enrollment tool.
b) Run the following command. (Replace <enrollment key> with the actual key.)
• Citrix.Wem.Agent.EnrollmentUtility.exe configenrollmentkey
-k <enrollment key>
Tip:
3. In Manage > Web Console > Enrollment > Invitation, create an invitation or send enrollment
invitations to users.
• If you do not want to send enrollment invitations through WEM, create an invitation and
then do either of the following:
– Go to the agent and enroll it with the invitation code.
– Share the invitation code with your user. Then, your user logs on to the agent and
enrolls it with the invitation code.
• If you want to send enrollment invitations through WEM, no further action is required on
your part. After the users receive the invitation email, they can enroll their agents using
the invitation code.
For information about how to enroll the agent with an invitation code, see Enroll the agent with
an invitation code.
After an agent enrolls, it becomes managed and appears in Enrollment > Enrolled Agents. You can
add it to a desired configuration set for precise management. For more information, see Manage the
enrolled agent.
Enroll by invitation
When enabled, you can generate an enrollment key and send invitations. When disabled, agents can’
t be enrolled using invitations.
Enrollment key
Lets you generate an enrollment key. You then install the key on the agent, using the enrollment tool,
Citrix.Wem.Agent.EnrollmentUtility.exe, available in the agent installation folder. Without the key,
the agent can’t enroll using invitations.
The generated key expires in 180 days. After generating a key, you can perform the following opera‑
tions:
Important:
Regenerating a key automatically invalidates the current one. For unenrolled agents, make sure
that the valid key is installed before sending invitations.
Enrollment invitation
• Create an invitation
• Invite users
• Refresh the list
• View the details of an invitation
• Resend an invitation
• Delete an invitation
• Clear expired invitations
Create an invitation
You create an invitation by generating an invitation code. The code supports enrolling up to 5 devices
and expires after 48 hours.
With the code, you can do the following as needed:
• Use the code yourself. Go to the agent and enroll it with the code.
• Share the code with your user. Then, your user logs on to the agent and enrolls it with the code.
Important:
WEM audits activities associated with an invitation code on a per code basis, for example, who
does the enrollment, when the enrollment occurs, and which device is enrolled. So, we recom‑
mend that you do not share the same code with multiple users.
1. In the action bar, select Create invitation. The Create invitation wizard appears.
2. Select Generate code.
3. After the code is generated, select Copy to clipboard.
Invite users
You can send enrollment invitations to your users. Each invitation includes an invitation code and the
steps needed to complete the enrollment.
• An invitation code is created for each user. The code supports enrolling up to 5 devices and
expires after 48 hours.
• Users with a registered email address will receive the invitation code by email. For users without
a registered email address, you can share the invitation code with them using other methods.
1. In the action bar, select Invite user. The Invite user wizard appears.
3. Select the domain of the users you want to add. Select Users and Security groups as needed.
4. In the Select box, enter the name of the user or the group you want to invite.
Note:
The search returns only the top 50 results. Refine your search if necessary.
5. Select desired users or user groups from the list. Selected users and user groups are shown
under Search.
If you have installed the enrollment key on the users’agents using the enrollment tool, no further ac‑
tion is required on your part. Your users need to complete the enrollment using the invitation code.
To view details of an invitation, select the invitation and then select View details in the action bar.
The View details window appears, displaying the following information:
• Invitation code
• Expiration date
• Delivery status
Possible values:
– Delivered. Indicates that the invitation email was delivered to the user successfully.
Resend an invitation
To resend an invitation, select the invitation and then select Resend email in the action bar.
This action does not extend the expiration time of the invitation code.
Delete an invitation
To delete an invitation, select the invitation and then select Delete in the action bar. You can delete
multiple invitations at a time.
Deleting an invitation invalidates the invitation code sent to or shared with users. As a result, those
users can’t enroll their agents with the code.
To delete all expired invitations, select Clear expired invitations in the action bar. The Clear expired
invitations button appears only when there are expired invitations.
You can use Workspace Environment Management (WEM) to manage non‑domain‑joined machines in
Citrix DaaS Standard for Azure (formerly Citrix Virtual Apps and Desktops Standard for Azure) deploy‑
ments.
This feature enables you to assign policies and settings to non‑domain‑joined machines as you do
with domain‑joined machines.
1. In Azure, prepare a master image that has a Citrix VDA and a WEM agent.
2. Import that image from Azure for use with catalog creation. For more information, see Master
images.
Important:
• For this feature to work, you must use WEM agent version 2103.2.0.1 or later. Down‑
load the WEM agent from the WEM service’s Utilities tab.
• For this feature to work, you must select Skip Configuration when installing the
agent.
• By design, the agent running on the virtual machine that is used to create the image
cannot connect to the WEM service.
3. In Citrix DaaS Standard for Azure, create a non‑domain‑joined catalog. For more information,
see Create catalogs.
a) Go to the Administration Console > Active Directory Objects > Machines tab, click the
down arrow next to Add Object, and then select Add Non‑Domain‑Joined Computers.
c) Click Add to add the selected machines and to exit the Add‑Non‑Domain‑Joined Com‑
puters window.
5. Optionally, verify that those machines are registered with the WEM service. To do that, navigate
to the Administration Console > Administration > Agents > Statistics tab, double‑click a ma‑
chine you added and then confirm registration information in the Agent Information window.
Important:
Non‑domain‑joined agent machines automatically register with the WEM service and are
added to the default configuration set.
After adding non‑domain‑joined machines to the WEM service, you can assign policies and settings to
those machines as you do with domain‑joined machines. However, when you assign policies and set‑
tings in the case of non‑domain‑joined machines, you have only the Everyone assignment option.
Upload files
June 2, 2022
Note:
This article applies to uploading files when using the legacy console.
You can use Upload to upload files you want to import or add to the Workspace Environment Manage‑
ment administration console. The Upload option is available in the menu on the WEM service Manage
tab.
• Use the Restore wizard to restore your WEM settings to WEM service. Those settings include:
– Security settings
– AD objects
– Configuration set
• Use the Migrate wizard to migrate a zip backup of your Group Policy Objects (GPOs) to WEM
service. For more information, see Ribbon.
• Import your registry files. For more information, see Registry Entries.
• Add custom icons for your applications. For more information, see Applications.
The files you upload are saved to the default folder (DefaultUploadFolder) in Citrix Cloud.
1. In Manage > Legacy Console, hover over the hamburger menu and then click the Citrix Work‑
space app icon.
2. Click Upload to upload the file to the default folder in Citrix Cloud.
Keep the following limitations in mind when using this feature to upload your files:
• File count limit. This feature supports uploading multiple files at a time. By default, it
supports storing up to 10 files for every account. Uploaded files are handled on a first‑come,
first‑deleted basis.
• File size limit. By default, you can upload only files whose size is smaller than 5 MB.
• File sync interval. By default, this feature synchronizes uploaded files to the Azure storage
every 30 minutes.
When you attempt to add or restore the uploaded files to the administration console for the first time
after an upgrade, you might find that they are not available for use. The issue might also occur the
first time you use the console. Possible causes:
• Those files have not yet been downloaded from the Azure storage. Downloading them to the
administration console can take some time to complete. Exit the administration console and
try again later.
• An error might occur while downloading those files. If the problem persists, contact Citrix Tech‑
nical Support.
REST APIs
March 9, 2021
With the Workspace Environment Management (WEM) service REST APIs, you can automate the man‑
agement of resources within a WEM deployment.
The API service does not require you to sign in to the WEM administration console to call the ser‑
vices.
• Machine AD Object APIs: a set of APIs for managing your machine‑level AD objects within a
WEM deployment.
• Site APIs: a set of APIs for managing your configuration sets within a WEM deployment.
• System Optimization APIs: a set of APIs for managing and optimizing resources (for example,
CPU, memory, and I/O) of Windows devices within a WEM deployment.
• User AD Object APIs: a set of APIs for managing your user‑level AD objects within a WEM de‑
ployment.
February 3, 2023
As an administrator, you might want to aggregate all applications you assigned to your user in one
place for quick and convenient launch. Also, your users might prefer to directly open their book‑
marked websites rather than take additional steps —open the browser first and then access the web‑
sites.
Workspace Environment Management (WEM) provides an application launcher tool that lets users
launch assigned applications in one place and directly open bookmarked websites using a browser
(if assigned). For more information about the tool, see Application launcher.
1. As an administrator, assign applications to target users or user groups through the administra‑
tion console.
2. Users log on to the agent machine to launch applications using the tool.
Prerequisites
• Make sure that the assigned applications are present on the agent machine. Only applications
present on the agent machine appear in the application launcher window.
• This feature supports only Google Chrome and Microsoft Edge. For the browser bookmark fea‑
ture to work, make sure that Google Chrome or Microsoft Edge is present on the agent machine.
Recommendation
The tool can run independently as part of WEM. For best user experience, we recommend that you do
the following:
• Publish the tool as a Citrix virtual app. When used as a published app in Citrix Workspace,
the tool launches assigned applications faster and makes it convenient for users to open book‑
marked websites. If used otherwise, the browser bookmark feature does not work.
• Use the tool with Citrix Profile Management. Application launcher lets users mark assigned
applications as favorites. When used with Profile Management, users’favorites and browser
bookmarks can roam regardless of which machine they log in to.
The following information is supplemental to the guidance in Action assignment. To assign applica‑
tions, follow the general guidance in that article.
• Chrome
• Edge
• Notepad++
• notepad
After users log on to their agent machines, they can launch the application launcher tool and then do
the following:
• Favorite applications
The following information is supplemental to the Application launcher article. Follow the general
guidance in that article and mind details below.
Users can directly open bookmarked websites. The browser bookmarks feature provides a faster and
more convenient way to open bookmarked websites.
To add bookmarks, users open the assigned browser using application launcher, access websites, and
then bookmark them. The bookmarked websites then appear in Browser bookmarks.
To sign out of the current session, users click the ellipsis icon in the upper right corner and select Sign
out.
Unlike closing the window, signing out ensures that the application session ends.
February 3, 2023
Long logon times decrease user productivity and result in a poor user experience. As an administrator,
you might want to get a detailed overview of logon times to identify processes that cause slow logons
so that you can take remedial action accordingly.
To achieve this goal, you can use the script Analyze_Logon_Duration.ps1. It is a PowerShell
script that queries the event log for every major event relating to the logon process. The script offers
the following benefits and more:
Workspace Environment Management (WEM) provides you with a scripted task feature that automates
the running of the script for you. All you need to do is configure a scripted task. A general workflow is
as follows:
The following content is for reference only. Verify that the “DomainUser”is resolved correctly.
Otherwise, the script will not work as expected.
The following information is supplemental to the guidance in Add a scripted task. To create a task that
analyzes logon duration, follow the general guidance in that article, minding the details below.
The following information is supplemental to the guidance in Configure a scripted task. To config‑
ure the Analyze_Logon_Duration task, follow the general guidance in that article, minding the details
below.
1. Go to the relevant configuration set, navigate to Scripted Task Settings, and configure the An‑
alyze_Logon_Duration task in General as follows:
• WEM lets you decide whether to verify the signature before running the task. Signature ver‑
ification is mandatory when the scripted task is granted full access. This ensures security
by protecting the scripts from being compromised. The Filter and Task timeout settings
are optional.
• Use triggers to control when to run the task. Make sure that the task runs after machine
startup. For example, you can create a “scheduled”trigger to schedule the running of the
task and then assoicate the trigger with the task.
3. In Parameters, choose whether to pass parameters to the task. In this example, you can skip
this step.
After the task runs successfully, you can view the results by checking the reports. For more informa‑
tion, see Reports. In this example, you can see the following report:
You can use filters to narrow your view to relevant reports and then export them. For information
about exporting reports, see Export reports. Based on the exported data, you can perform further
analysis.
The following is an example of visualizing data of interest in Power BI. It shows a breakdown of the
user’s logon duration.
Tip:
Logon performance optimization is one of the highlights of the Workspace Environment Manage‑
ment service. The feature can change the overall logon process to drastically reduce logon times.
See Logon Optimization.
February 8, 2023
As an administrator, you might have many devices to manage. They might exist in different domains
and have different security levels or Windows OS versions. Updating those devices in a timely manner
to prevent potential risks can be a tedious task. To achieve this goal, you might do the following:
• Draw comparisons between the collected information to identify the devices where updates are
missing.
Workspace Environment Management (WEM) provides you with a scripted task feature that simplifies
the task of applying updates to your devices.
All you need to do is configure two scripted tasks. A general workflow is as follows:
11 }
12
13 }
14
15 Exit $ExitCode
16 <!--NeedCopy-->
1 Param(
2 [string]$consoleOutputPath
3 )
4 $List = Get-Content $consoleOutputPath
5 $List | ForEach-Object {
6
7 Write-host "Installing hotfix: $_"
8 Get-WindowsUpdate -Install -KBArticleID $_
9 }
10
11 <!--NeedCopy-->
Note:
Put this file in a place that the WEM agent can access, for example, in a shared path: \\
hyenvwenserver\share\hotfix.list.
The following information is supplemental to the guidance in Add a scripted task. To create the two
scripted tasks, follow the general guidance in that article, minding the details below.
In Web Console > Scripted Tasks, add the two scripted tasks.
The following information is supplemental to the guidance in Configure a scripted task. To configure
the two scripted tasks, follow the general guidance in that article, minding the details below.
1. Go to the relevant configuration set, navigate to Scripted Task Settings, and configure the “Ap‑
ply updates”task.
After the tasks run successfully, you can view the results by checking the reports. For more informa‑
tion, see Reports. In this example, you can see the following reports:
Report summary:
As a Workspace Environment Management (WEM) administrator, you might need to back up your con‑
figuration sets on a regular basis to prevent settings from getting lost. You might want to trigger the
backup, for example, every 12 hours, and manage the backup files locally and automatically. Using
WEM public APIs and Windows PowerShell, you can accomplish that goal.
Prerequisites
Before you start, make sure that you know your Citrix customer ID and the related API base URLs.
Sign in to Citrix Cloud, navigate to Identity and Access Management > API Access, and find your
Citrix customer ID.
The API base URLs, including Citrix Auth API base URL and WEM API base URL, are related to the region
of Citrix Cloud you’re connecting to. The region is determined when you onboard to Citrix Cloud. You
can also query your region in Account Settings.
You can find the API base URLs by checking the table below.
Region Citrix Auth API base URL WEM API base URL
For more information about the API base URLs, see Get Started With Citrix Cloud APIs and WEM API
overview.
Navigate to Identity and Access Management > API Access. Type the name of your secure client,
click Create Client, and save the secure client ID and client secret locally.
21 $Body = "grant_type=client_credentials&client_id=${
22 ClientId }
23 &client_secret=${
24 ClientSecret }
25 "
26 $Response = Invoke-RestMethod -Method 'Post' -Uri $URL -Body $Body -
ContentType 'application/x-www-form-urlencoded'
27
28 $BearerToken = $Response.access_token
29
30 if ([string]::IsNullOrEmpty($BearerToken))
31 {
32
33 throw 'Cannot retrieve bearer token.'
34 }
35
36
37 Write-Host "Retrieved bearer token successfully."
38
39 # back up WEM configuration sets
40
41 if (-not (Test-Path -Path $FolderToSaveBackup -PathType 'Container'))
42 {
43
44 throw 'The folder to save backup not exists.'
45 }
46
47
48 $Headers = @{
49
50 'Citrix-CustomerId' = $CitrixCustomerId
51 'Accept' = 'application/json'
52 'Authorization' = "CWSAUTH bearer=${
53 BearerToken }
54 "
55 }
56
57
58 if ($ConfigSetsToBackUp.Count -eq 0 -or $ConfigSetsToBackUp -eq $null)
59 {
60
61 $URL = "https://${
62 CitrixWEMAPIBaseURL }
63 /services/wem/sites"
64 $Response = Invoke-RestMethod -Method 'Get' -Uri $URL -Headers
$Headers
65 $ConfigSetsToBackUp = $Response.items |% {
66 $_.name }
67
68 }
69
70
71 $ConfigSetsToBackUp | ForEach-Object {
72
73 Write-Host "Backing up configuration set ""$_"""
74 $URL = "https://${
75 CitrixWEMAPIBaseURL }
76 /services/wem/sites/%24export?name=$_"
77 Write-Host "GET $URL"
78 $Response = Invoke-RestMethod -Method 'Get' -Uri $URL -Headers
$Headers
79 $Timestamp = Get-Date -Format "yyyyMMddHHmmss"
80 $Response | ConvertTo-Json -Depth 10 | Out-File (Join-Path
$FolderToSaveBackup "${
81 _ }
82 -${
83 Timestamp }
84 .json")
85 }
86
87
88 <!--NeedCopy-->
For more information about bearer tokens, see Get Started With Citrix Cloud APIs.
For more information about using the WEM API to back up configuration set, see Exporting WEM con‑
figuration set API.
Note:
Each bearer token expires after an hour. To avoid frequently invoking the Citrix Cloud auth APIs
and WEM APIs, cache the bearer token and reuse it if the backup duration takes less than an hour.
On a machine with access to Citrix Cloud, start Task Scheduler from the Windows Start menu or
start taskschd.msc from the Windows command prompt.
Configuring file type associations (FTA) used to be an easy task. As an administrator, you could achieve
that by using scripts. However, a hash was introduced for FTA validation starting with Windows 8,
making FTA configuration a pain for administrators.
You can use Workspace Environment Management (WEM) to customize FTA for a specific user or user
group. For example, you can associate URL types (HTTP and HTTPS) and file types (*.htm and *.html)
with Google Chrome, making it the default browser.
Prerequisites
• Make sure that the agent machines have Google Chrome installed.
The ProgID for Google Chrome is ChromeHTML. To discover the ProgID of an installed appli‑
cation, use the OLE/COM Object Viewer (oleview.exe) and look for it in Object Classes/Ole 1.0
Objects. For more information about ProgID, see Programmatic identifier (ProgID).
1. Go to Legacy Console > Advanced Settings > Configuration > Main Configuration and enable
Process File Associations.
2. Go to Legacy Console > Actions > File Associations > File Association List and click Add.
3. In the New File Association window, type the information as follows and then click OK.
Note:
In this example, the correct ProgID ChromeHTML is provided, so there is no need to fill out
the following three fields: Action, Target application, and Command. However, if you
can’t provide the ProgID for an installed application or the installed application doesn’t
register a ProgID during installation, you must fill out the three fields. For more informa‑
tion, see File Associations.
1. Go to Legacy Console > Assignments > Action Assignment and then double‑click the user or
user group to which you want to assign the action.
2. Go to Legacy Console > Administration > Agents > Statistics and then click Refresh.
3. Right‑click the agent and then select Refresh Workspace Agent(s) in the context menu.
For more information about FTA configuration in WEM, see File Associations.
With Workspace Environment Management (WEM), you can configure FSLogix Profile Container
settings without logging on to the domain controller. After uploading the administrative templates
(.admx) to WEM, you can configure the policy in WEM just as you usually do on a domain con‑
troller. You then assign the policy to desired assignment targets. For precise control, you can also
contextualize the assignment using predefined filters.
A general workflow for configuring FSLogix settings using WEM GPO is as follows:
2. Create a GPO to configure FSLogix and then enable the corresponding settings in the GPO.
Prerequisites
WEM supports creating template‑based and registry‑based GPOs. To create a template‑based GPO for
FSLogix, upload the zip file as follows:
2. On the Template‑based tab, click Manage template. The Manage template wizard appears.
For a template‑based GPO, you can configure both machine‑level and user‑level settings. In this ex‑
ample, you don’t need to configure user‑level settings.
1. On the Template‑based tab, click Create GPO. The Create GPO with template wizard appears.
3. In Computer configuration, go to Machine > FSLogix > Profile Containers > Container and
Directory Naming and configure the following two settings:
• Enabled. Select the setting, set Status to Enabled, and set Options to Enabled.
• VHD location. Select the setting, set Status to Enabled, and type the path to the VHD.
4. In Summary, verify that you configured the settings as intended and click Done.
After creating the GPO, you can assign it to desired assignment targets. You can assign the GPO to dif‑
ferent AD groups, just like you assign other actions. 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.
In this example, the GPO is assigned to the “Everyone”Group, with the default “Always True”filter
applied.
After assigning the GPO, go to the target agent machine to confirm that the policy has taken effect.
With Workspace Environment Management (WEM), you can set up MSIX app attach for use in Citrix
DaaS (formerly Citrix Virtual Apps and Desktops service) and Citrix Virtual Apps and Desktops envi‑
ronments and on physical workstations. To provide a seamless MSIX app attach based application
experience for users, you can roam MSIX app attach data with Profile Management.
Prerequisites
• Place an MSIX app attach container (VHDX file) in a file share that Citrix DaaS or Citrix Virtual
Apps and Desktops can access. To prepare a VHDX file that contains MSIX applications, use the
MSIX packaging tool and the MSIXMGR tool.
• Prepare PowerShell scripts for MSIX app attach. The scripts cover the following four distinct
phases to be performed during logon and logoff for MSIX app attach: stage, register, deregister,
and destage.
To create external tasks, follow the general guidance in that article, minding the details specific to
MSIX app attach scenarios.
In Actions > External Tasks of the legacy console, add the following two tasks:
• A task to mount the MSIX VHD file, stage MSIX app packages, and have the apps register with the
desktop session when the end user logs on.
• A task to dismount the MSIX VHD file, destage MSIX app packages, and deregister the apps from
After that, assign the two tasks to the target users you want to enable MSIX app attach for. For informa‑
tion about assigning external tasks, see Assignment. The WEM agent running on the desktop machine
will then run the tasks, making the MSIX apps accessible in the desktop session.
MSIX app data is saved to the user profile in the user session. To retain MSIX app data in non‑persistent
desktops or to roam the data across desktops, you can use Profile Management. For information
about how to configure profile roaming using Profile Management, see Citrix Profile Management Set‑
tings.
• Change settings in Profiles > Profile Management Settings under the relevant configuration
set.
• Configure the scope of settings to cover in the Profile Management health check report.
Prerequisites
In the web console, go to Monitoring > Administration > Agents and check the Profile Management
health column. For more information about the health statuses, see Administration.
To view the detailed health check report of an agent, select the agent and then select More > Profile
> View Profile Management health check report.
The report includes issues found and fix recommendations. For each issue, go to Profiles > Profile
Management Settings under the relevant configuration set and change the setting accordingly. To
dismiss an issue, go to Advanced Settings > Monitoring Preferences and specify the scope of set‑
tings to cover in the report.
When no issue is found, the health check returns a good status, indicating that Profile Management is
in good shape.
Note:
If the issue is an error, you must fix it in Profiles > Profile Management Settings under the rel‑
evant configuration set. Otherwise, Profile Management cannot function properly.
To customize the scope of settings to cover in a health check report, go to Advanced Settings > Mon‑
itoring Preferences under the relevant configuration set.
By default, all settings are included. For more information, see Advanced Settings.
To run Profile Management health checks on an agent machine on demand, perform the following
steps:
1. In the web console, go to Monitoring > Administration > Agents, select the agent, and select
More > Profile > Run Profile Management health check.
2. In the wizard that appears, choose whether to change the scope of the settings that the health
check report covers and then click Run.
Note:
The changes you make here affect only the health check report to be generated.
February 3, 2023
As an administrator who manages user profiles with Citrix Profile Management, you need to specify
file shares as user stores.
You might want to put user stores in storage repositories (for example, Azure Files) that the current
user has no permission to access. Using Workspace Environment Management (WEM) to establish
SMB connections to the storage repositories accomplishes that goal. Doing so enables Profile Man‑
agement to access the user stores.
Prerequisites
The following information is supplemental to the guidance in SMB shares. Follow the general guid‑
ance in that article and mind the details below.
1. In the web console, go to Advanced Settings > File Shares under the relevant configuration set
and add the SMB share you prepared.
2. Select the SMB share that you want the Profile Management service to use.
The following information is supplemental to the guidance in Citrix Profile Management Settings. Fol‑
low the general guidance in that article and mind the details below.
1. In the web console, go to Profiles > Profile Management Settings under the relevant configu‑
ration set and enable Profile Management Settings.
2. Go to Basic settings, enable Profile Management, and then set the path to the user store.
3. Go to Profile container, enable profile container, and then add an asterisk (*).
Note:
Adding an asterisk (*) puts the entire user profile in the profile container. This ensures that
NTFS permissions are retained.
February 3, 2023
As an administrator, you might want to perform system‑level tasks such as configuration or cleanup
tasks when the operating system starts or shuts down.
Workspace Environment Management (WEM) provides you with machine startup and shutdown trig‑
gers that you can associate with scripted tasks. The tasks are triggered to run when the operating
system starts or shuts down.
Prerequisites
• Fast startup is turned off for the target machines. Example: for Windows 10 machines, go to
Control Panel > All Control Panel Items > Power Options > System Settings and disable the
Turn on fast startup option. The option affects only startup processing.
• The scripted tasks are signed with trusted certificates and the certificates are installed on the
target machines.
Recommendation
We recommend that you sign the scripted tasks with trusted certificates.
The following information is supplemental to the guidance in Scripted Tasks. Follow the general guid‑
ance in that article and mind the details below.
Tip:
You can combine the two scripts into one so that you just need to add a single task.
1. In Web Console > Scripted Tasks, first add the startupscript task as follows:
In this example:
The following information is supplemental to the guidance in Scripted Task Settings. Follow the gen‑
eral guidance in that article and mind the details below.
Go to the relevant configuration set, navigate to Scripted Tasks Settings, and configure the two tasks
as follows:
• In Triggers, select Machine startup for the startupscript task and select Machine shut‑
down for the shutdownscript task.
For your changes to take effect immediately, go to Monitoring > Administration > Agents and select
Refresh agent host settings.
After the tasks run successfully, you can view the results by checking the reports. For more informa‑
tion, see Reports. In this example, you can see the following two reports: One for shutdown and the
other for startup.
January 4, 2023
1. Go to DaaS > Manage > Full Configuration > Machine Catalogs to locate the catalog you want
to manage using WEM.
2. Select the catalog and then select Manage Configuration Set in the action bar.
Prerequisites
Before you start, verify that the following prerequisites are met:
2. Navigate to My Services > DaaS > Manage > Full Configuration > Machine Catalogs.
3. Select the catalog and then select Manage configuration set in the action bar. The Manage
configuration set blade appears.
Note:
If the selected configuration set has not been configured to include settings relating to the
basic configuration of WEM, the Apply basic settings to configuration set option appears.
We recommend that you select the option to apply basic settings to the configuration set.
5. After you have finished, click Save to save your change and exit the blade.
To verify which configuration set the catalog is bound to, select the catalog and check the Workspace
Environment Management tab in the lower pane. The tab shows the configuration set to which the
catalog is bound.
For more information, see Manage configuration set for a catalog in the DaaS documentation.
Before configuring settings, you can first view relevant information in WEM:
• In Directory Objects, check the non‑domain‑joined machines and the configuration set to
which those machines are bound.
In this example, some settings are enabled. Those settings are configured automatically be‑
cause the Apply basic settings to configuration set option was selected in DaaS.
You can then apply settings to the non‑domain‑joined machines by configuring the configuration set.
For example, you can apply policies to them:
• In Actions > Group Policy Settings, select a GPO, click Manage assignments, and then select
Everyone.
You can go to a non‑domain‑joined machine to verify that the policy has taken effect. You can also
assign other actions if needed. For settings to be applied to non‑domain‑joined machines, be sure to
select Everyone.
More information
Recommendation
We recommend that you use the WEM tool VUEMAppCmd to publish applications. The tool ensures
that the WEM agent finishes processing process hierarchy control rules before published applications
start.
Use the Full Configuration management interface to edit the application settings and then add an
executable file path that points to VUEMAppCmd.exe. For more information, see Applications.
To enable the feature, use the AppInfoViewer tool on the agent machine. The tool is located in the
agent installation folder. A machine restart is required after you enable or disable the feature.
Suppose you want to block CMD from launching through Notepad. To create process hierarchy control
rules, complete the following steps:
1. Go to Legacy Console > Security > Process Hierarchy Control and select Enable Process Hi‑
erarchy Control.
Note:
In this example, you create a rule to prevent CMD from launching through Notepad. You
can use one of the three rule types (Path, Publisher, and Hash) to specify parent and child
processes. Under Assignments, you choose the users to which you want to apply the rule.
For more information about the settings, see Process hierarchy control.
Note:
The user interface differs depending on which rule type you select in step 2.
4. Add multiple child processes in the rule as needed and click Create.
This completes creating the rule. The agent will prevent CMD from launching through Notepad in the
Citrix Workspace environment.
February 8, 2023
As an administrator, you might want to proactively discover issues related to Virtual Delivery Agents
(VDAs) in your deployment. This insight can help you resolve issues in time before your users are
affected.
Workspace Environment Management (WEM) provides a built‑in scripted task, Cloud Health Check,
that lets you run checks to gauge the health of VDAs. Using the task, you can identify possible causes
for VDA registration and session launch issues. Each time the task runs, a detailed health check report
is generated. Based on the report, you can analyze and resolve issues accordingly.
The following information is supplemental to the guidance in Create a trigger. To add a scheduled
trigger, follow the general guidance in that article, minding the details below.
Go to the relevant configuration set, navigate to Triggers, and create a trigger as follows:
In this example:
• For Date and time, configure the task to run at 02:00, April 4, 2023.
The following information is supplemental to the guidance in Configure a scripted task. To configure
the Cloud Health Check task, follow the general guidance in that article, minding the details below.
Go to the relevant configuration set, navigate to Scripted Task Settings, and configure the Cloud
Health Check task as follows:
In this example, select the scheduled trigger DailyRunTrigger to associate it with the Cloud
Health Check task.
The Cloud Health Check task runs at the scheduled time. After it completes, you can view the health
check results by checking the reports. For more information, see Reports.
In Web Console > Home > Overview, you can get an overview of VDA health status. To view VDA
health status in detail:
• Click View under Normal to see reports about VDAs in normal state.
• Click View under Unusual to see reports about VDAs in unusual state.
The reports about VDAs in unusual state include issues found and fix recommendations. You can re‑
solve the issues accordingly.
WEM also provides a method to run the task on an agent machine on demand. To do that, perform
the following steps:
1. Go to Monitoring > Administration > Agents, select the agent, and select More > Run scripted
task.
2. In the wizard that appears, select Cloud Health Check as the task and then click Run.
3. After the task completes, you can view the health check results by checking the reports. For
more information, see Reports.
February 3, 2023
As an administrator, when you encounter VDA registration issues, you might need to log on to each
VDA to run the Citrix Health Assistant to troubleshoot VDA registration issues.
With Workspace Environment Management (WEM), you can use Windows events as triggers to detect
VDA registration issues. You then associate the triggers with the scripted task, Cloud Health Check.
The task is then triggered to run to identify possible causes. Finally, you can use the task report to
resolve issues accordingly. This enables you to stay on top of any VDA registration issues and resolve
them in time before more users are impacted.
3. Associate the Windows event trigger with the task, Cloud Health Check.
You need to collect Windows event logs resulting from unregistered VDAs. The information provides
clues to understanding the reasons VDAs are unregistered.
The following is an example message in Windows Event Log relating to an unregistered VDA.
The following information is supplemental to the guidance in Create a trigger. To add a Windows event
trigger, follow the general guidance in that article, minding the details below.
• Go to the relevant configuration set, navigate to Triggers, and create a trigger named
UnregisteredEventLogTrigger.
Associate the Windows event trigger with Cloud Health Check task
The following information is supplemental to the guidance in Configure a scripted task. To configure
the Cloud Health Check task, follow the general guidance in that article, minding the details below.
• Go to the relevant configuration set, navigate to Scripted Task Settings, and configure the
Cloud Health Check task.
When VDAs are in an unregistered state, the WEM agent detects the corresponding Windows event log.
The Cloud Health Check task runs automatically. You can view the results by checking the reports. For
more information, see Reports. In this example, you can see the following report:
Based on the report, you can analyze and resolve the issues accordingly.
This article provides a comprehensive list of WEM event logs, along with their corresponding, and
distinct event IDs.
Optimization events
CPU optimization
For messages with event IDs starting from 7003 through 7008 to be written, add the following reg‑
istry.
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Norskale\Agent Host
Name: EnableExtraLoggingForOptimization
Type: REG_DWORD
Value: 1
Caution:
Editing the registry incorrectly can cause serious problems that require you to reinstall your oper‑
ating system. Citrix cannot guarantee that problems resulting from the incorrect use of Registry
Editor can be solved. Use Registry Editor at your own risk. Be sure to back up the registry before
you edit it.
Memory optimization
The Workspace Environment Management agent can run in CMD mode and UI mode.
When you configure the agent to run on logon, you can control whether to start it in CMD mode or UI
mode. To do that, use the Agent Type setting, available on the Administration Console > Advanced
Settings > Configuration > Main Configuration tab. For more information, see Advanced settings.
If you do not configure the agent to run automatically on logon, you (administrators or end users) can
start the agent in CMD mode or UI mode on the agent machine. To do that, navigate to the agent
installation folder and identify the following two .exe files:
• When running automatically on logon, CMD mode displays a command prompt. CMD mode
exits automatically after startup.
• On startup, CMD mode applies the user‑assigned actions to the agent. Those actions include
network drives, printers, applications, and more.
– Capture Screen. Lets you open a screen capture tool. This option requires Enable Screen
Capture on the Administration Console > Advanced Settings > UI Agent Personaliza‑
tion > Helpdesk Options tab to be enabled. For more information, see Helpdesk Options.
– Reset Actions. Lets you open the Reset actions tool to specify what actions to reset in
the environment.
This option requires Allow Users to Reset Actions on the Administration Console > Advanced
Settings > UI Agent Personalization > UI Agent Options tab to be enabled. For more informa‑
tion, see UI Agent Options.
– Manage Applications. Lets you open the Manage applications tool to manage applica‑
tions.
This option requires Allow Users to Manage Applications on the Administration Console >
Advanced Settings > UI Agent Personalization > UI Agent Options tab to be enabled. For
more information, see UI Agent Options.
– Manage Printers. Lets you open the Manage printers tool to configure a default printer
and modify printing preferences.
This option requires Allow Users to Manage Printers on the Administration Console > Ad‑
vanced Settings > UI Agent Personalization > UI Agent Options tab to be enabled. For more
information, see UI Agent Options.
– Refresh. Refreshes the agent, applying the user‑assigned actions to the agent. Those ac‑
tions include network drives, printers, applications, and more.
– Help. Lets you open a website through which you can ask for help.
This option requires Help Link Action on the Administration Console > Advanced Settings >
UI Agent Personalization > Helpdesk Options tab to be specified. For more information, see
Helpdesk Options.
To reset actions and manage applications and printers, you can directly use the following tools (avail‑
able in the agent installation folder) without the need to use the agent in UI mode:
• The CMD agent applies settings and then exits. You can configure the WEM agent service (Citrix
WEM Agent Host Service or Citrix WEM User Logon Service) to start the CMD agent at a particular
point in time (for example, logon or reconnect). If necessary, administrators can invoke the CMD
agent manually.
• The UI agent keeps running. The Citrix WEM Agent Host Service starts or stops the UI agent. The
UI agent provides self‑service options to end users. We recommend that administrators do not
launch the UI agent manually.
Note:
You cannot run the CMD agent and the UI agent at the same time in a session.
On the agent side, you can perform the following refresh operations:
• Refresh cache. Use a command line to run AgentCacheUtility.exe in the agent installation folder,
for example:
– AgentCacheUtility.exe -RefreshCache
• Refresh agent host settings. Use a command line to run AgentCacheUtility.exe in the agent in‑
stallation folder, for example:
– AgentCacheUtility.exe -RefreshSettings
• Refresh workspace agents. When the agent is in UI mode, navigate to the agent menu and then
click Refresh.
Refresh cache Refreshing the cache The agent local cache cannot
synchronizes the agent local be refreshed.
cache with the infrastructure
service.
Refresh agent host settings If the Use Cache Even When The agent applies the settings
Online option is enabled, the that it retrieves from the agent
agent applies the settings that local cache.
it retrieves from the agent local
cache rather than from the
infrastructure service. In this
case, refresh the cache before
refreshing the settings. If the
Use Cache Even When Online
option is not enabled, the
agent applies the settings that
it retrieves from the
infrastructure service.
Refresh workspace agents If the Use Cache Even When If the Enable Offline Mode
Online or the Use Cache to option is enabled, the agent
Accelerate Actions Processing applies the user‑assigned
option is enabled, the agent actions that it retrieves from
applies the settings that it the agent local cache. If the
retrieves from the agent local Enable Offline Mode option is
cache rather than from the not enabled, the agent does
infrastructure service. In this not work.
case, refresh the cache before
refreshing the settings. If the
Use Cache Even When Online
and the Use Cache to
Accelerate Actions Processing
options are not enabled, the
agent applies the settings that
it retrieves from the
infrastructure service.
This article describes the customer data associated with Workspace Environment Management (WEM)
service. It provides information concerning the collection, storage, and retention of customer data
involved.
Overview
WEM service uses intelligent resource management and Profile Management technologies to deliver
the best possible performance, desktop logon, and application response times for Citrix DaaS (for‑
merly Citrix Virtual Apps and Desktops service) and Citrix Virtual Apps and Desktops deployments. It
is a software‑only, driver‑free solution.
Data location
The following data sources are aggregated in a Microsoft Azure Cloud environment located in the
United States (US) or the European Union (EU), depending on the WEM service UI URL.
• For organizations that onboard to WEM service before the enablement of EU‑based instances,
their storage locations reside in the US.
• For organizations that onboard to WEM service after the enablement of EU‑based instances,
their storage locations can be different, depending on the home region that the administrators
select when onboarding their organizations to Citrix Cloud.
– If the home region is EU, their storage locations reside in the EU.
– If the home region is not EU, their storage locations reside in the US.
Data collection
• Logs collected from the WEM management console and from the WEM infrastructure services
Log files. You can use the WEM management console (Manage tab) to control the log settings as‑
sociated with WEM service at any time. You can also enable or disable the log function. The “Citrix
WEM Database Management Utility Debug Log.log”log file is located in the WEM infrastructure service
installation directory.
WEM service agent actions and policies. All the actions and policies you set up are saved and stored
in the back‑end Azure database and are accessible only to you through the WEM management console
(Manage tab).
Statistics on end‑user activity. All statistics you monitor in the WEM management console (Manage
tab) are saved and stored in the back‑end Azure database and are accessible only to you through the
WEM management console.
Data retention
The customer data associated with WEM service is retained in an identifiable form during the entire
service period. Retention periods differ for different types of data:
• Log files are retained for 90 days by default and deleted thereafter. Retaining those log files for
a custom time period is not supported.
• WEM service agent actions and policies are kept long term.
• Statistics on end‑user activity are retained for 30 days by default and deleted thereafter. Retain‑
ing those statistics for a custom time period is not supported.
Dynamic tokens
You can use dynamic tokens in any Workspace Environment Management actions to make them more
powerful.
Note:
Group Policy settings come in two types: Machine settings and user settings. For machine set‑
tings, some dynamic tokens are not supported. See Dynamic token support for Group Policy
settings.
Using dynamic tokens in Group Policy settings allows for more adaptable policy configuration in dif‑
ferent environments, reduces manual configuration, and simplifies policy management.
• Machine settings. Those settings apply only to machines regardless of who logs on to them.
• User settings. Those settings apply only to users regardless of which machine they log on to.
All dynamic tokens are supported for Group Policy settings. The following ones are not supported for
machine settings.
• Hashtags
– ##FullUserName##
– ##UserInitials##
– ##ClientName##
– ##ClientIPAddress##
– ##UserLDAPPath##
– ##ClientRemoteOS##
• ADAttribute
– [ADAttribute:attrName]
– [UserParentOU: 1]
• Applications
– With Installation application as the application type: Command Line, Working Direc‑
tory, and Parameters
– With File/Folder as the application type: Target
– With URL as the application type: Shortcut URL
– Icon File
• Printers
– Target Path
• Network drives
• Virtual drives
– Target Path
• Registries
Note:
The Target value field does not support environment variable expansion. If you use envi‑
ronment variables, they do not work as expected.
• Environment variables
– Variable value
• Ports
– Port Target
• Ini files
– Target path, Target section, Target value name, and Target value
Note:
The Target section, Target value name, and Target value fields do not support environ‑
ment variable expansion. If you use environment variables, they do not work as expected.
• External tasks
– Example: With Active Directory Attribute Match as the condition type: Tested Active
Directory Attribute and Matching Result
Note:
For a complete list of supported fields for filter conditions, see Supportability matrix for
filter conditions.
String operations
Sometimes you need to manipulate strings within a script to map drives or launch applications. The
following string operations are accepted by the Workspace Environment Management agent:
Note:
• String operations are also supported with hashtags and Active Directory attributes. For ex‑
ample: #Left([ADAttribute:NAME],2)# where the name attribute of the current
domain user is Administrator returns Ad, and $Split(##ClientIPAddress
##,[\.],2)$ returns 157.
• !Mid(string,startindex,length)! and !Substring(string,startindex
,length)! operations are always performed last.
Hashtags
Hash‑tags are a replacement feature widely used in the processing of Workspace Environment Man‑
agement items. The following example illustrates how you use hash‑tags:
To write to an .ini file, you can use %UserName% in the .ini file’s path and Workspace Environment
Management processes it and expands the final directory. However, assessing the value which Work‑
space Environment Management writes in the .ini itself is more complicated: you may want to write
%UserName% literally, or write the expanded value.
To increase flexibility, ##UserName## exists as a hash‑tag, so that using %UserName% for a value
writes it literally and ##UserName## writes the expanded value.
To work with Active Directory attributes, WEM replaces the [ADAttribute:attrName] value with the re‑
lated Active Directory attribute. [ADAttribute:attrName] is the dynamic token for any Active Directory
attributes. There is a related filter that checks the value of the specified attributes.
For user organizational unit (OU) structures, WEM replaces the [UserParentOU:level] value with the
related Active Directory OU name. The Active Directory path is the complete user path (LDAP) in Active
Directory and [UserParentOU:level] is a subset of it.
For example, suppose you want to build a network drive for an OU to which the users belong. You
can use the dynamic token [UserParentOU:level] in the network drive path to resolve the users’OU
dynamically. There are two ways to use the dynamic token:
• Use the [UserParentOU:level] dynamic token directly in the network drive path. For example,
you can use the following path: \\Server\Share\[UserParentOU:0]\.
• Set an environment variable called OU, and then set its value to [UserParentOU:0]. You can then
map the drive as \\Server\Share\\%OU%\.
Note:
• You can substitute the digit “0”with the number that corresponds to the level you want to
reach in the OU structure.
• You can append variables to the path. To do this, ensure that you have an exact folder struc‑
ture that matches your OU layout.
You can also use Active Directory attributes for filtering purposes. On the Administration > Filters
> Conditions > Filter Condition List tab, you can open the New Filter Condition window after you
click Add. In the New Filter Condition window, you can see the following four filter condition types
associated with Active Directory attributes:
Registries
To work with a registry, WEM replaces the [RegistryValue:<Registry path>] value with the
related registry value. For example, you can specify the following value:
• [RegistryValue:HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Norskale\Agent
Host\AgentLocation]
XML files
To work with an XML file, WEM replaces the [GetXmlValue:<XML path>|<tag name>] value
with the specific tag value in the XML file. The XML path can be an actual path or an environment
variable that resolves to a path. You must enclose the environment variable with %. For example, you
can specify the following value:
• [GetXmlValue:C:\citrix\test.xml|summary] or
• [GetXmlValue:%xmlpath%|summary]
INI files
To work with an .ini file, WEM replaces the [GetIniValue:<INI path>|<section name in
the .ini file>|<key name in the .ini.file>] with the key value. The INI path can be
an actual path or an environment variable that resolves to a path. You must enclose the environment
variable with %. For example, you can specify the following value:
• [GetIniValue:C:\citrix\test.ini|PLD_POOL_LIC_NODE_0_0|LicExpTime] or
• [GetIniValue:%inipath%|PLD_POOL_LIC_NODE_0_0|LicExpTime]
More information
The following table lists all condition types whose tested value or matching result supports dynamic
tokens.
June 2, 2020
This article describes the registry values associated with Environmental Settings in Workspace Envi‑
ronment Management service.
Enabled Value 1
Disabled Value 0
Processing Service called by agent
Hide Help
Hide Find
Hide Find
Lock Taskbar
Set Wallpaper
Set Wallpaper
Disabled Value 0
Processing Service called by agent
Disable Switcher
Enabled Value 1
Disabled Value 0
Processing Service at logon
Enable AutoEndTasks
WaitToKillApp Timeout
Disable SmoothScroll
Disable MinAnimate
Filter conditions
Workspace Environment Management includes the following filter conditions which you use to config‑
ure the circumstances under which the agent assigns resources to users. For more information about
using these conditions in the administration console, see Filters.
When using the following filter conditions, be aware of these two scenarios:
• If the agent is installed on a physical endpoint, conditions that contain “client”in the condition
names are not applicable.
Expected value type String. Full path and name of the registry value
to test. Example: Registry Key
HKCU\Software\Citrix\TestValueName
Expected result type String. Expected value of the tested registry
entry.
Expected syntax Single name test: value Not null test: ?
Returns True if registry value exists and value matches,
false otherwise.
Expected value type String. Full file path of the XML list generated by
the Integrity List manager utility.
Expected result type String. Expected value of the name/value to look
for in the list.
Expected syntax String
Returns True if the input value is found in the name/value
pairs in the specified list, false otherwise.
Negative condition behavior Runs IP Address Match and returns the opposite
result (true if false, false if true). See condition IP
Address Match for more information.
Negative condition behavior Runs Client IP Address Match and returns the
opposite result (true if false, false if true). See
condition Client IP Address Match for more
information.
Negative condition behavior Runs Active Directory Site Match and returns the
opposite result (true if false, false if true). See
condition Active Directory Site Match for more
information.
Negative condition behavior Runs Registry Value Match and returns the
opposite result (true if false, false if true). See
condition Registry Value Match for more
information.
Negative condition behavior Runs WMI Query result Match and returns the
opposite result (true if false, false if true). See
condition WMI Query result Match for more
information.
Negative condition behavior Runs User Country Match and returns the
opposite result (true if false, false if true). See
condition User Country Match for more
information.
Negative condition behavior Runs User UI Language Match and returns the
opposite result (true if false, false if true). See
condition User UI Language Match for more
information.
Negative condition behavior Runs Active Directory Path Match and returns the
opposite result (true if false, false if true). See
condition Active Directory Path Match for more
information.
Negative condition behavior Runs Active Attribute Path Match and returns the
opposite result (true if false, false if true). See
condition Active Attribute Path Match for more
information.
Negative condition behavior Runs Name or Value is in List and returns the
opposite result (true if false, false if true). See
condition Name or Value is in List for more
information.
Negative condition behavior Runs Client Remote OS Match and returns the
opposite result (true if false, false if true). See
condition Client Remote OS Match for more
information.
Negative condition behavior Runs Dynamic Value Match and returns the
opposite result (true if false, false if true). See
condition Dynamic Value Match for more
information.
Negative condition behavior Runs Client OS Match and returns the opposite
result (true if false, false if true). See condition
Client OS Match for more information.
Negative condition behavior Runs Active Directory Group Match and returns
the opposite result (true if false, false if true).
See condition Active Directory Group Match for
more information.
Expected value type String. Full path and name of the file to test.
Example: C:\Test\TestFile.dll
Expected result type String. Expected file version value of the tested
file.
Expected syntax Single name test: value Not null test: ?
Returns True if registry value exists and value matches,
false otherwise.
Negative condition behavior Runs File Version Match and returns the opposite
result (true if false, false if true). See condition
File Version Match for more information.
Important:
Before you use Published Resource Name as the filter condition type, keep the following in mind:
If the published resource is a published application, type the browser name of the application in
the Matching Result field. If the published resource is a published desktop, type the published
name of the desktop in the Matching Result field.
Expected value type String. Full file path of the XML list generated by
the Integrity List manager utility.
Expected result type String. Expected value of the name to look for in
the list.
Expected syntax String
Returns True if there is a name match in the name/value
pairs in the specified list, false otherwise.
Negative condition behavior Runs Name is in List and returns the opposite
result (true if false, false if true). See condition
Name is in List for more information.
Negative condition behavior Runs File/Folder exists and returns the opposite
result (true if false, false if true). See condition
File/Folder exists for more information.
Negative condition behavior Runs DateTime Match and returns the opposite
result (true if false, false if true). See condition
DateTime Match for more information.
Filter conditions related to Citrix DaaS and Citrix Virtual Apps and Desktops
WEM supports the following filter conditions for use in your Citrix DaaS (formerly Citrix Virtual Apps
and Desktops service) and Citrix Virtual Apps and Desktops deployment. The conditions apply to all
currently supported versions. When using the version match condition, be aware of the following
considerations:
• You can specify the version numbers in different formats. For example, type 7.30, 7.30.0, or
7.30.0.0. If needed, you can also use the asterisk (*) as a wildcard. For example, 7.30*. The
asterisk matches zero or more characters.
• The specified version is the version number of the Delivery Controller rather than that of the
Virtual Delivery Agent. To view the version number, locate the AutoSelect application (the Au‑
toSelect.exe file) on the installation media, right‑click AutoSelect, and click the Details tab. The
Product version field displays the version number that you can specify in WEM.
Negative condition behavior Runs Citrix Virtual Apps Version Match and
returns the opposite result (true if false, false if
true). See condition Citrix Virtual Apps Version
Match for more information.
Negative condition behavior Runs Citrix Virtual Apps Farm Name Match and
returns the opposite result (true if false, false if
true). See condition Citrix Virtual Apps Farm
Name Match for more information.
Negative condition behavior Runs Citrix Virtual Apps Zone Name Match and
returns the opposite result (true if false, false if
true). See condition Citrix Virtual Apps Zone
Name Match for more information.
Negative condition behavior Runs Citrix Virtual Desktops Farm Name Match
and returns the opposite result (true if false, false
if true). See condition Citrix Virtual Desktops
Farm Name Match for more information.
Log parser
July 9, 2020
Workspace Environment Management includes a log parser application, which is located in the agent
installation directory:
The WEM Agent Log Parser allows you to open any Workspace Environment Management agent log
file, making them searchable and filterable. The parser summarizes the total number of events, warn‑
ings, and exceptions (in the top right of the ribbon). It also includes details about the log file (the name
and port of the infrastructure service it first connected to and the agent version and user name).
Port information
November 7, 2019
Home page
• Configurations for both WEM agent and the WEM infrastructure server. Select the Name, Agent
Type, Agent version, and the Join type.
• The pre‑requisite for the Join type can be either an AD joined or a Non‑domain joined type.
• You can enable the Force debug mode or the Debug mode for WEM agent and WEM infrastruc‑
ture server respectively.
• When you enable the Force debug mode, the debug mode is turned on for the agent regardless
of the settings specified in the Administration console.
• For the changes to take effect on the WEM agent or the WEM infrastructure server immediately,
you can restart the Citrix WEM agent Host Service and VUEMUIAgent.exe or the
Citrix WEM Infrastructure Service respectively.
• Retrieve logs lets you retrieve and save the logs in a zipped folder as a package. You can then
check the package saved on your local machine.
Service agent
To check the configuration of the WEM agent, click the Start check button. The following components
are considered to generate the health check report.
Note:
• Ensure that the agent cache resides in a persistent location. Using a non‑persistent cache
location can cause potential cache synchronization issues, excessive network data usage,
performance issues, and so on.
• We recommend that you set the directory service timeout based on your connection time.
The following services are required for the WEM agent to function as expected. Ensure that the ser‑
vices are running and the startup type for each service is set to automatic.
WEM Tool Hub is a collection of tools that aims to simplify the configuration experience for Workspace
Environment Management (WEM) administrators. To download it, go to Citrix Cloud > WEM service
> Utilities.
The prerequisites for running the WEM Tool Hub are as follows:
• Application assistant
• File Type Association Assistant
• Printer assistant
• Rule generator for app access control
Note:
• WEM Tool Hub does not save data for you. Data will be cleared after you exit a tool. To avoid
potential data loss, be sure to save your work.
• To paste data copied from the WEM Tool Hub into the web console, ensure that the browser
allows data copying. Example: For Microsoft Edge, be sure to have the Site permissions
> Clipboard > Ask when a site wants to see text and images copied to the clipboard
option enabled.
Application Assistant
Use this tool to prepare configuration information for icons and Citrix Workspace resources that you
want to use when adding applications in the management console.
Workspace resources
Note:
When adding an application of type “Citrix Workspace resource”to the web console, you need to spec‑
ify a resource. To get information for a resource, complete the following steps:
2. Click Browse resources to browse your resources. Resources are then enumerated and listed.
3. From the list, select the target application and copy its information.
In the web console, paste the information you copied by clicking Paste resource info. See Add an
application.
Icons
When setting the icon for an application in the web console, you can add new icons. To get data for
an icon, complete the following steps:
1. Click Browse to browse to a file that contains the icon. Icons in the file are then loaded. Sup‑
ported file types: .exe, .dll, .ico.
In the web console, paste the icon data you copied by clicking Paste icon data. See Add an applica‑
tion.
You can use this tool to view logon duration reports and get the tips for logon duration optimization
and troubleshooting.
To receive complete reports, enable log collection for relevant Windows event logs on the ma‑
chine.
• Click Windows Logon analysis > Get reports to access the Get latest reports wizard.
• Select the time range by choosing one of the options from the drop down list and click Get
reports. The default range is Last 24 hours.
• The phase and description are displayed in the form of a chart based on the following table.
The following table lists all the metrics, submetrics, and tips in detail.
Base‑metric
Base‑metric Description(UI) Sub‑metrics Tips Details
Base‑metric
Base‑metric Description(UI) Sub‑metrics Tips Details
Base‑metric
Base‑metric Description(UI) Sub‑metrics Tips Details
Base‑metric
Base‑metric Description(UI) Sub‑metrics Tips Details
Base‑metric
Base‑metric Description(UI) Sub‑metrics Tips Details
Base‑metric
Base‑metric Description(UI) Sub‑metrics Tips Details
CitrixWemCache
(Sync) Cit‑
rixWemJsonFile
CitrixWemMa‑
chineGroupPolicy
CitrixWemUser‑
GroupPolicy
Group policy Single group
objects policy object list
Pre‑shell Time for the
(UserInit) userinit.exe
to the
explorer.exe
startup.
Logon Script Time taken to run UserLogonScript Optimize your
Processing logon scripts. logon script. You
can optimize your
logon script by
removing
unnecessary
commands and
reducing the size
of the script.
Use Group Policy
Preferences.
Group Policy
preferences can
be used to
replace logon
scripts. They are
easier to manage
and can be
processed faster
than logon
scripts.
Base‑metric
Base‑metric Description(UI) Sub‑metrics Tips Details
Base‑metric
Base‑metric Description(UI) Sub‑metrics Tips Details
Base‑metric
Base‑metric Description(UI) Sub‑metrics Tips Details
Base‑metric
Base‑metric Description(UI) Sub‑metrics Tips Details
AppxLoadPackage(AppX
Adjust the
packages loaded appearance and
during logon) performance of
SingleAppxLoad‑ Windows. You
Package can adjust the
appearance and
performance of
Windows to
speed up your PC’
s login process.
To do this,
right‑click My
Computer and
select Properties.
Click Advanced
System Settings
and then click the
Settings button
under
Performance.
You can adjust
the appearance
and performance
of Windows here.
Use this tool to get the information needed for configuring FTAs to add them as assignable actions in
the management console.
Selecting File Type Association Assistant leads you to the File Type Association Assistant page in
the WEM Tool Hub. You can configure an FTA by completing the following steps.
• When you type a file name extension, you can choose from the matching file name extension
options that begins with your input.
• Check if the extension entered has an associated ProgID and whether the ProgID has associated
actions in the registry.
• Click Browse to list all the applications that have the entered ProgID registered.
• Configure the application that you want to associate it with.
• You can also select Customize action to perform the Open, Edit, and Print actions.
• You can copy the configured FTA data by clicking the Copy button.
Printer Assistant
Use this tool to get a list of printers from your print server so that you can add them as assignable
actions in the management console.
When adding printers from a network print server, you need printer information to add them. To get
the printer information, complete the following steps:
In the web console, paste the information you copied by clicking Paste printer info. See Add printers
from a print server.
Use this tool to create rules to control user access to items such as files, folders, and registries. The
rules are implemented through Citrix Profile Management. A typical use case is to apply rules to con‑
trol user access to apps installed on machines —whether to make apps invisible to relevant users.
• App rule name. Specify a name to help you identify the rule.
• Target objects. Add target objects. Target objects can be files, folders, and registries re‑
lated to the app that you want to hide. Click Scan for a list of apps installed on the current
machine and objects associated with each app.
Note:
– The tool might not be able to get the path for a folder after a scan. The path field
shows the following warning: No path found. The issue occurs, for example,
when the installation folder of an app resides in the user’s profile folder. In that
case, you must locate the installation folder and then enter the path manually.
– You cannot add paths for items on which certain Citrix and Windows services rely.
Otherwise, those services might stop working properly. For a complete list of
those paths, see Paths not allowed to be added.
3. On the Assignments page, add users, computers (organizational units), and processes you want
to assign the rule to. For more information about how to get the AAD users or groups and NDJ
machines, see AAD/NDJ object selector.
Note:
• After you assign this rule to certain users, computers, and processes, the target objects
are invisible when users run the processes on related computers.
• Without assignments specified, this rule always hides the target objects.
• Assignments come in three categories: users, computers, and processes. The “OR”
operator is used between items within a category, and the “AND”operator is used be‑
tween categories.
• You cannot add users and computers when running the tool on a non‑domain‑joined
or Azure Active Directory joined machine.
• You can add bulk processes. Enter process names (including the .exe extension), sep‑
arated by line breaks.
1. Select the desired rules or click Select all to select all rules.
2. Click Generate raw data in the action bar. The raw data is then generated for the selected rules.
3. In the Generate raw data window, save the raw data to a file for later restoration or copy the
raw data to your clipboard.
Note:
• Use the raw data when adding rules in the WEM administration console or when con‑
figuring the Profile Management policy “App access control,”depending on how you
want to get the rules deployed.
• After you save the raw data to a file, you can restore the rules from the file. To achieve
that, use Import in the action bar.
You cannot add the following paths and their parent paths for items on which certain Citrix and Win‑
dows services rely.
Profile Management related registries:
• HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Citrix\UserProfileManager
• HKLM:\SOFTWARE\Policies\Citrix\UserProfileManager
• HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\UserProfileManager
• HKLM:\SOFTWARE\Citrix\UserProfileManager
• HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Norskale
• HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\WEM
• HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Norskale
• HKLM:\SOFTWARE\Policies\Norskale
• HKLM:\SOFTWARE\Citrix\WEM
• HKLM:\SYSTEM\CurrentControlSet\Control\Norskale
• HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\VirtualDesktopAgent
• HKLM:\SOFTWARE\Citrix\VirtualDesktopAgent
• HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\
Uninstall\Citrix Virtual Desktop Agent
• HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\Citrix
Virtual Desktop Agent
• HKCU:
• HKEY_CURRENT_USER
• HKU:
• HKEY_USERS
• c:\windows\system32
• \Citrix\User Profile Manager\
• \Citrix\Workspace Environment Management Agent\
• \Citrix\XenDesktopVdaSetup\
• \\%windir\\%\system32
To assign app access rules to AAD users or groups and NDJ machines, complete the following steps.
1. Click AAD/NDJ object selector from the web console. Go to Manage > Web Console.
2. Select Configuration Sets > Site name > Profiles > Profile Management Settings > App access
control.
3. Select the Enable app access control checkbox and click Add rules.
4. In the Rules page, click AAD/NDJ object selector to add the desired AAD users and NDJ ma‑
chines. For more details, see App access control.
6. Go to WEM Tool Hub > Rule Generator for App Access Control, where you create an app rule.
10. Go to the web console > configure set > Profile Management settings > App access control
and paste the data there.
Use this tool to configure Start menu layouts for Windows 11 and generate configurations in JSON
format that you can assign as actions in the management console.
To customize the Start menu layout for Windows 11, complete the following steps.
1. Click Start Menu Configurator for Windows 11 in the WEM Tool Hub. Select applications that
you prefer to add to the Pinned section of the Start menu and arrange the layout as needed.
3. In the web console, click Add a new JSON object and select Start menu configuration for
Windows 11. Paste the configuration in the Add JSON object page and click Done.
4. Assign JSON file configuration to the users by selecting the required assignment target in the
Manage assignments page and click Save.
Add applications
To add applications using the WEM Tool Hub, complete the following steps.
1. Click Add applications in the Start Menu Configurator for Windows 11 page.
2. Choose the applications from the Add applications page by selecting the required applications
that you intend to add to the Start menu, and click Add.
3. You can change the order of the applications by dragging the applications as needed under the
Pinned layout section.
4. Click Generate configuration and after the configuration is generated, click Copy. While gen‑
erating the configuration, the selected layout is applied to the Start menu.
Use this tool to create the user stores with Citrix Profile Management on the current machine, running
the tool, or on a different machine. You can specify the folder path and share the name for the user
store. When the user store is created, the recommended configuration for the path to the user store
is provided, allowing you to use it directly in your Profile Management settings.
To create a user store on the current machine, complete the following steps.
1. Specify the Folder path that you want to set as the user store location. The folder is created
and shared with the specified users and groups.
2. Choose Stop and let me know or Use the existing folder, if the folder already exists.
3. Optionally, specify a name for the file share. By default, the name of the folder is used as the
share name.
4. Choose Stop and let me know or Stop sharing the existing item and take the name, if a share
with the same name already exists.
5. Select the users and groups that use this user store by clicking Add. This opens the native AD
selector to select users and groups.
6. Select the Users or Groups object type from the location specified.
7. Add the object names in the Enter the object names to select field in the native AD selector
and click OK.
8. Click Create user store.
1. Specify the machine name and enter the credentials of a domain user with the local administra‑
tor privilege on the machine specified. Make sure that the PowerShell remoting is enabled on
the machine.
2. Specify the Folder path that you want to set as the user store location. The folder is created
and shared with the specified users and groups.
3. Choose Stop and let me know or Use the existing folder, if the folder already exists.
4. Optionally, specify a name for the file share. By default, the name of the folder is used as the
share name.
5. Choose Stop and let me know or Stop sharing the existing item and take the name, if a share
with the same name already exists.
6. Select the users and groups that use this user store by clicking Add. This opens the native AD
selector to select users and groups.
7. Select the Users or Groups object type from the location specified.
8. Add the object names in the Enter the object names to select field in the native AD selector
and click OK.
9. Click Create user store.
Errors
If you receive an error message apart from the ones listed, you can view the error details at the bottom
of the page with the title An error occurred. View details below.
To create another user store, click Create another. This choice redirects you to the starting page with
all the inputs cleared and reset.
This feature lets you add local applications to the WEM Tool Hub for quick access. The added appli‑
cations are considered as part of your personal data. The data is retained when you switch machines
while using the Profile Management environment.
To add an application, click the plus sign on the top right corner of the WEM Tool Hub and then navi‑
gate to the application. You can add multiple applications at a time.
The added applications appear as tiles in the WEM Tool Hub. You can click a tile to start the application
quickly.
Note:
Workspace Environment Management includes the ability to configure user printers via an XML printer
list file.
After you have created an XML printer list file, create a printer action in the administration console
with an Action Type option set to Use Device Mapping Printers File.
Note:
Only printers that do not require specific Windows credentials are supported.
The XML file is encoded in UTF‑8, and has the following basic XML structure:
Every client and associated device is represented by an object of the following type:
1 SerializableKeyValuePair<string, List<VUEMUserAssignedPrinter>>>
1 <SerializableKeyValuePairOfStringListOfVUEMUserAssignedPrinter>
2 <Key>DEVICE1</Key>
3 <Value>
4 <VUEMUserAssignedPrinter>
5 ...
6 </VUEMUserAssignedPrinter>
7 </Value>
8 </SerializableKeyValuePairOfStringListOfVUEMUserAssignedPrinter>
9
10 <!--NeedCopy-->
Note:
Each block of devices must be matched to a specific client or computer name. The <Key> tag contains
the relevant name. The <Value> tag contains a list of VUEMUserAssignedPrinter objects matching
the printers assigned to the specified client.
Note:
To ensure that the WEM agent can access the XML printer list file, the XML printer list file must be
Each configured printer must be defined in a <VUEMUserAssignedPrinter> tag, using the following
attributes:
<IdPrinter>. This is the Workspace Environment Management printer ID for the configured printer.
Each printer must have a different ID. Note The XML Printer List action configured in the Workspace
Environment Management Administration Console is also a printer action with its own ID which must
be different from the ID of printers individually configured in the XML list.
<IdSite>. Contains the site ID for the relevant Workspace Environment Management site, which must
match the ID of an existing site.
<State>. Specifies the state of the printer where 1 is active and 0 is disabled.
<UseExtCredentials>. Must be 0. The use of specific Windows credentials is not currently sup‑
ported.
<isDefault>. If 1, the printer is the default Windows printer. If 0, it is not configured as default.
<RevisionId>. Must always be 1. If printer properties are further modified, increment this value by 1
to notify the Agent Host and ensure that the printer action is re‑processed.
<Name>. This is the printer name as perceived by the Workspace Environment Management Agent
Host. This field cannot be left blank.
<Description>. This is the printer description as perceived by the Workspace Environment Manage‑
ment Agent Host. This field can be blank.
<ExtLogin>. Contains the name of the Windows account used when specifying Windows credentials
for connection. [Currently unsupported. Leave this field blank].
<ExtPassword>. Contains the password for the Windows account used when specifying Windows
credentials for connection. [Currently unsupported. Leave this field blank].
1 ><VUEMActionAdvancedOption><Name>SelfHealingEnabled</
Name><Value>0</Value></VUEMActionAdvancedOption
2 <!--NeedCopy-->
To activate self‑healing for a given printer object, simply copy and paste the above contents, changing
the highlight 0 value to 1.
The following example assigns two active printers on the client or computer DEVICE1:
• HP LaserJet 2200 Series on UNC path \\server.example.net\HP LaserJet 2200 Series (default
printer)
• Canon C5531i Series printer on UNC path \\server.example.net\Canon C5531i Series
24 <Value>
25 <VUEMUserAssignedPrinter>
26 <IdPrinter>2</IdPrinter>
27 <IdSite>1</IdSite>
28 <State>1</State>
29 <ActionType>0</ActionType>
30 <UseExtCredentials>0</UseExtCredentials>
31 <isDefault>0</isDefault>
32 <IdFilterRule>1</IdFilterRule>
33 <RevisionId>1</RevisionId>
34 <Name>Canon C5531i Series</Name>
35 <Description />
36 <DisplayName />
37 <TargetPath>\\server.example.net\Canon C5531i
Series</TargetPath>
38 <ExtLogin />
39 <ExtPassword />
40 <Reserved01><?xml version="1.0" encoding="utf-8"
?><ArrayOfVUEMActionAdvancedOption xmlns:
xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
;<VUEMActionAdvancedOption><Name>
SelfHealingEnabled</Name><Value>0<
;/Value></VUEMActionAdvancedOption><
;/ArrayOfVUEMActionAdvancedOption></
Reserved01>
41 </VUEMUserAssignedPrinter>
42 </Value></
SerializableKeyValuePairOfStringListOfVUEMUserAssignedPrinter
>
43 <
SerializableKeyValuePairOfStringListOfVUEMUserAssignedPrinter
>
44 <Key>DEVICE2</Key>
45 <Value>
46 <VUEMUserAssignedPrinter>
47 <IdPrinter>1</IdPrinter>
48 <IdSite>1</IdSite>
49 <State>1</State>
50 <ActionType>0</ActionType>
51 <UseExtCredentials>0</UseExtCredentials>
52 <isDefault>0</isDefault>
53 <IdFilterRule>1</IdFilterRule>
54 <RevisionId>1</RevisionId>
55 <Name>HP LaserJet 2200 Series</Name>
56 <Description />
57 <DisplayName />
58 <TargetPath>\\server.example.net\HP LaserJet 2200
Series</TargetPath>
59 <ExtLogin />
60 <ExtPassword />
61 <Reserved01><?xml version="1.0" encoding="utf-8"
?><ArrayOfVUEMActionAdvancedOption xmlns:
xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
;<VUEMActionAdvancedOption><Name>
SelfHealingEnabled</Name><Value>0<
;/Value></VUEMActionAdvancedOption><
;/ArrayOfVUEMActionAdvancedOption></
Reserved01>
62 </VUEMUserAssignedPrinter>
63 </Value></
SerializableKeyValuePairOfStringListOfVUEMUserAssignedPrinter
>
64 </
ArrayOfSerializableKeyValuePairOfStringListOfVUEMUserAssignedPrinter
>
65 <!--NeedCopy-->
Glossary
This article contains terms and definitions used in the Workspace Environment Management (WEM)
software and documentation.
administration console. An interface that connects to the infrastructure services. You use the admin‑
istration console to create and assign resources, manage policies, authorize users, and so on.
In Citrix Cloud, the Workspace Environment Management service administration console is hosted on
a Citrix Cloud‑based Citrix virtual apps server. You use the administration console to manage your
WEM installation from the service’s Manage tab using your web browser.
administration port [1]. Port on which the administration console connects to the infrastructure
service. The port defaults to 8284 and corresponds to the AdminPort command‑line argument.
agent. The Workspace Environment Management agent consists of two components: the agent ser‑
vice and the session agent. These components are installed on the agent host.
agent host configuration GPO. The Group Policy Object (GPO) administrative template provided with
the agent installation as ADM or ADMX files. Administrators import these files into Active Directory and
then apply the settings to a suitable organizational unit.
agent port [1]. Listening port on the agent host which receives instructions from the infrastructure
service. Used, for example, to force agents to refresh from the administration console. The port de‑
fault is 49752.
agent service. The service deployed on VDAs or on physical Windows devices in Transformer use
cases. It is responsible for enforcing the settings you configure using the administration console.
agent service port [1]. A port on which the agent connects to the infrastructure server. The port
defaults to 8286 and corresponds to the AgentPort command‑line argument.
Agent Sync Broker Port. Legacy term for “cache synchronization port”.
cache synchronization port [1]. A port on which the agent cache synchronization process connects
to the infrastructure service to synchronize the agent cache with the infrastructure server. The port
defaults to 8285 and corresponds to the AgentSyncPort command‑line argument.
Citrix License Server port [1]. The port on which the Citrix License Server is listening and to which
the infrastructure service then connects to validate licensing. The port default is 27000.
Citrix Cloud Connector [2]. Software which allows machines in resource locations to communicate
with Citrix Cloud. Installed on at least one machine (cloud connector) in each resource location.
database server account [1]. The account used by the database creation wizard to connect to the
SQL instance to create the Workspace Environment Management database.
DSN. A data source name (DSN) contains database name, directory, database driver, UserID, password,
and other information. Once you create a DSN for a particular database, you can use the DSN in an
application to call information from the database.
infrastructure server [1]. The computer on which the Workspace Environment Management infra‑
structure services are installed.
infrastructure service. The service installed on the infrastructure server which synchronizes the vari‑
ous back‑end components (SQL Server, Active Directory) with the front‑end components (administra‑
tion console, agent host). This service was previously called the “broker.”
On Citrix Cloud, the infrastructure services are hosted on Citrix Cloud and managed by Citrix. They
synchronize the various back‑end components (Azure SQL Database service, administration console)
with the front‑end components (agent, Active Directory).
infrastructure service account [1]. The account which the infrastructure service uses to connect to
the database. By default this account is the vuemUser SQL account, but during database creation you
can optionally specify other Windows credentials for the infrastructure service to use.
infrastructure services. Services installed on the infrastructure server by the infrastructure services
installation process.
On Citrix Cloud, the infrastructure services are hosted on Citrix Cloud and managed by Citrix. They
synchronize the various back‑end components (Azure SQL Database service, administration console)
with the front‑end components (agent, Active Directory).
initial administrators group [1]. A user group which is selected during database creation. Only mem‑
bers of this group have Full Access to all Workspace Environment Management sites in the adminis‑
tration console. By default this group is the only group with this access.
integrated connection [1]. Connection of the database creation wizard to the SQL instance using the
current Windows account instead of an SQL account.
kiosk mode. A mode in which the agent becomes a web or application launcher redirecting users to
a single app or desktop experience. This allows administrators to lock down the user environment to
a single app or desktop.
mixed‑mode authentication [1]. In SQL Server, an authentication mode that enables both Windows
Authentication and SQL Server Authentication. This is the default mechanism by which the infrastruc‑
ture service connects to the database.
License server port. Legacy term for “Citrix License Server port”.
resource location [2]. A location (such as a public or private cloud, a branch office, or a data center)
containing the resources required to deliver services to your subscribers.
SaaS [2]. Software as a service is a software distribution model in which a third‑party provider hosts
applications and makes them available to customers over the Internet.
self‑service window. An interface in which end users can select functionality configured in Work‑
space Environment Management (for example icons, default printer). This interface is provided by
the session agent in “UI mode.”
service principal name (SPN). The unique identifier of a service instance. SPNs are used by Kerberos
authentication to associate a service instance with a service logon account.
session agent. An agent that configures app shortcuts for user sessions. The agent operates in “UI
mode”and “command line”mode. UI mode provides a self‑service interface accessible from a status
bar icon, from which end users can select certain functions (for example icons, default printer).
SQL user account [1]. An SQL user account with name of “vuemUser”created during installation. This
is the default account that the infrastructure service uses to connect to the database.
virtual drive. A Windows virtual drive (also called an MS‑DOS device name) created using the subst
command or the DefineDosDevice function. A virtual drive maps a local file path to a drive letter.
virtual IP address (VIP). An IP address that does not correspond to an actual physical network inter‑
face (port).
VUEM. Virtual User Environment Management. This is a legacy Norskale term that appears in some
places in the product.
vuemUser [1]. An SQL account created during Workspace Environment Management database cre‑
ation. This is the default account that the Workspace Environment Management infrastructure service
uses to connect to the database.
WEM monitoring port [1]. A listening port on the infrastructure server used by the monitoring service.
The port defaults to 8287. (Not yet implemented.)
Windows account impersonation. When a service runs under the identity of a Windows account.
Windows authentication. In SQL Server, the default authentication mode in which specific Windows
user accounts and group accounts are trusted to log in to SQL Server. An alternate mode of authenti‑
cation in SQL Server is mixed mode authentication.
Workspace Environment Management (WEM) service [2]. A Citrix Cloud service which delivers WEM
management components as a SaaS service.
Workspace Environment Management service
© 2024 Cloud Software Group, Inc. All rights reserved. Cloud Software Group, the Cloud Software Group logo, and other
marks appearing herein are property of Cloud Software Group, Inc. and/or one or more of its subsidiaries, and may be
registered with the U.S. Patent and Trademark Office and in other countries. All other marks are the property of their
respective owner(s).