Advanced settings

These settings modify how and when the agent processes actions.


Configuration

These options control basic agent behavior.

Main configuration

Agent Actions. These settings determine whether the agent processes actions configured in the Actions tab. These settings apply on logon, and on refresh - automatic or manual refresh (user or administrator triggered).

Process Applications. When selected, the agent processes application actions.

Process Printers. When selected, the agent processes printer actions.

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 Ports. When selected, the agent processes port 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 Logon. Controls whether the agent runs on logon.

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 Assignment tab. Workspace Environment Management processes these options according to a specific priority:

  1. The options present on the Cleanup Actions tab
  2. The options configured for the assigned actions in the Assigned pane

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 refreshes.

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

These options control the agent settings.

Enable Agent Logging. Enables the agent log file.

Log File. The log file location. By default, this is the profile root of the logged-in user.

Debug Mode. This enables verbose logging for the agent.

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, navigate to the Administration > Agents > Statistics tab, right-click the applicable agent, and then select Refresh Cache in the context menu.

Refresh Environmental Settings. If enabled, the agent triggers a refresh of user environment settings 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 wallpaper 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 asynchronously, 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:

  • User network printers.
    • 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 an extremely time-intensive process which should only be selected 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 notifications 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

These settings configure the Agent Host service.

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.

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.

Agent Extra Launch Delay. This setting controls how long the Citrix WEM Agent Host Service waits to launch the agent host executable.

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 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 WEM 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 belonging 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. 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. The URL must be specified in the form http[s]://hostname[:port], where hostname is the fully qualified domain name of the store and 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.

Description. Optional text describing the store.

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 configuration set.

To apply changes

Click Apply to apply store settings immediately to your agents.

Agent switch

Options present on this tab let you switch from the on-premises agent to the service agent.

Important:

Agent switch works at a configuration set level. The switch operation you perform affects only the agents in the configuration set.

Switch to Service Agent. If enabled, the agent switches from the on-premises agent to the service agent. You can then specify Citrix Cloud Connectors to which the agent connects. This is useful when you want to migrate your existing on-premises deployment to the WEM service.

Warning:

Enable this option only if you want to move your on-premises deployment to the WEM service. This move cannot be reversed through the WEM administration console.

Configure Citrix Cloud Connectors. Lets you configure the Citrix Cloud Connectors by typing the FQDN or IP address of the Cloud Connector. Click Add to add one Cloud Connector at a time. To ensure high service availability, Citrix recommends that you install at least two Cloud Connectors in each resource location. Therefore, you need to configure at least two Citrix Cloud Connectors.

Skip Citrix Cloud Connector Configuration. Select this option if you want to configure Citrix Cloud Connectors using Group Policy.

Important:

It might take some time for the agent switch settings to take effect, depending on the SQL Settings Refresh Delay setting you configured on the Advanced Settings > Configuration > Service Options tab.

The agent might fail to connect to the WEM service after you switch from the on-premises agent to the service agent, and you might want to roll back. To do so, use the AgentConfigurationUtility.exe command line; for example:

  • <WEM agent installation folder path>AgentConfigurationUtility.exe switch -o --server <server name> --agentport <port number> --syncport <port number>
  • <WEM agent installation folder path>AgentConfigurationUtility.exe switch -o --server <server name>
  • <WEM agent installation folder path>AgentConfigurationUtility.exe switch --usegpo -o

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 systems to enable Wake on LAN for the agent hosts. If selected, the agents configure the following system settings:

  • Disable Energy Efficient Ethernet for the network adapter
  • Enable Wake on Magic Packet for the network adapter
  • Enable Allow this device to wake the computer for the network adapter
  • Enable Only allow a magic packet to wake the computer for the network adapter
  • Disable Turn on fast startup

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 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.

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.

  • Desktop. Adds the application shortcut to the desktop.
  • Start Menu. Creates the application shortcut in the Start menu folder.
  • QuickLaunch. Adds the application to the quick launch toolbar.
  • Taskbar (P). Creates the application shortcut in the taskbar.
  • Start Menu (P). Pins the application to the Start menu.

    Note:

    Shortcuts created in self-healing mode cannot be deleted using this menu. The QuickLaunch option is available only in Windows XP and Windows Vista.

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, settings configured in the administration console take effect immediately. The About option opens a dialog displaying version details about the agent in use.

Helpdesk options

These options control help desk functionalities available to users on endpoints.

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:

  • New capture. Takes a screenshot of errors in the user environment.
  • Save. Saves the screenshot.
  • Send to support. Sends the screenshot to support staff.

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, configured 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 ##UserScreenCaptureComment## 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.

Advanced settings