Get started

This is a reference document to help you set up your environment after you install Citrix Workspace app.

Prerequisites:

Verify that all system requirements are met as listed in System requirements section.

You must configure the following before starting to use the Citrix Workspace app:

Group Policy Object administrative template

Citrix recommends using the Group Policy Object administrative template to configure rules for network routing, proxy servers, trusted server configuration, user routing, remote user devices, and user experience. You can use the receiver.admx / receiver.adml template files with domain policies and local computer policies. For domain policies, import the template file using the Group Policy Management console. This is especially useful for applying Citrix Workspace app settings to a number of different user devices throughout the enterprise. To affect a single user device, import the template file using the local Group Policy Editor on the device.

Citrix recommends using the Windows Group Policy Object (GPO) administrative template to configure Citrix Workspace app.

Starting with Citrix Receiver for Windows Version 4.6, the installation directory includes CitrixBase.admx and CitrixBase.adml, and, administrative template files (receiver.adm or receiver.admx\receiver.adml -depending on the Operating system) in the installation directory.

Note:

The .adm file is for use with Windows XP Embedded platforms only. The .admx/.adml files are for use with Windows Vista/Windows Server 2008 and all later versions of Windows.

If Citrix Workspace app is installed with the VDA, admx/adml files are found in the Citrix Workspace app installation directory. For example: <installation directory>\Online Plugin\Configuration.

If Citrix Workspace app is installed without the VDA, the admx/adml files are typically found in the C:\Program Files\Citrix\ICA Client\Configuration directory.

See the table below for information on Citrix Workspace app templates files and their respective location.

Note:

Citrix recommends that you use the GPO template files provided with latest version of Citrix Workspace app.

   
File type File location
receiver.adm \ICA Client\Configuration
receiver.admx \ICA Client\Configuration
receiver.adml \ICA Client\Configuration\[MUIculture]
CitrixBase.admx \ICA Client\Configuration
CitrixBase.adml \ICA Client\Configuration\[MUIculture]

Note:

  • If the CitrixBase.admx\adml is not added to the local GPO, the Enable ICA File Signing policy might be lost.
  • When upgrading Citrix Workspace app, add the latest template files to local GPO as explained in the procedure below. While importing the latest files, previous settings are retained.

To add the receiver.adm template file to the local GPO (Windows XP Embedded Operating system only):

Citrix recommends that you use the CitrixBase.admx and CitrixBase.adml files to ensure that the options are correctly organized and displayed within the Group Policy Object Editor.

You can use .adm template files to configure both the Local and/or the domain-based GPO.

  1. Open the Citrix Workspace app Group Policy Object administrative template by running gpedit.msc.
  2. In the left pane of the Group Policy Editor, select the Administrative Templates folder.
  3. From the Action menu, choose Add/Remove Templates.
  4. Select Add and browse to the template file location \<Installation Directory>\ICA Client\Configuration\receiver.adm.
  5. Select Open to add the template and then Close to return to the Group Policy Editor.

    Citrix Workspace app template file is available in the local GPO directory Administrative Templates > Classic Administrative Templates (ADM) > Citrix Components > Citrix Workspace.

After the .adm template files are added to the local GPO, the following message is displayed:

“The following entry in the [strings] section is too long and has been truncated: Click OK to ignore the message.

To add the receiver.admx/adml template files to the local GPO (later versions of Windows Operating System):

You can use .adm template files to configure both the Local and/or the domain-based GPO. Refer to the Microsoft MSDN article about managing ADMX files here.

After installing Citrix Workspace app, copy the template files as given in the table below:

File type Copy from Copy to
receiver.admx Installation Directory\ICA Client\Configuration\receiver.admx %systemroot%\policyDefinitions
CitrixBase.admx Installation Directory\ICA Client\Configuration\CitrixBase.admx %systemroot%\policyDefinitions
receiver.adml Installation Directory\ICA Client\Configuration[MUIculture]receiver.adml %systemroot%\policyDefinitions[MUIculture]
CitrixBase.adml Installation Directory\ICA Client\Configuration[MUIculture]\CitrixBase.adml %systemroot%\policyDefinitions[MUIculture]

Note:

Citrix Workspace app template files are available on local GPO in Administrative Templates > Citrix Components > Citrix Workspace folder only if you add the CitrixBase.admx/CitrixBase.adml to the \PolicyDefinitions folder.

StoreFront

Citrix StoreFront authenticates a connection to Citrix Virtual Apps and Desktops, Citrix DaaS (formerly Citrix Virtual Apps and Desktops service), and ​VDI-in-a-Box, enumerating, and aggregating available desktops and applications into stores that you can access using Citrix Workspace app.

In addition to the configuration summarized in this section, you must also configure Citrix Gateway to enable users to connect from outside the internal network (for example, users who connect from the Internet or from remote locations).

Note:

When you select the option to show all stores, you might see the old StoreFront user interface.

To configure StoreFront:

Install and configure StoreFront as described in the StoreFront documentation. Citrix Workspace app requires an HTTPS connection. If the StoreFront server is configured for HTTP, a registry key must be set on the user device as described in Using command-line parameters under the ALLOWADDSTORE property description.

Note:

For administrators who need more control, Citrix provides a template you can use to create a download site for Citrix Workspace app for Windows.

Citrix Gateway Store

To add or specify a Citrix Gateway using Group Policy Object administrative template:

  1. Open the Citrix Workspace app Group Policy Object administrative template by running gpedit.msc.
  2. Under the Computer Configuration node, go to Administrative Templates > Classic Administrative Templates (ADM) > Citrix Components > Citrix Workspace > StoreFront.
  3. Select Citrix Gateway URL/StoreFront Accounts List.
  4. Edit the settings.

    • Store name – Indicates the displayed store name
    • Store URL – Indicates the URL of the store
    • #Store name – Indicates the name of the store behind Citrix Gateway
    • Store enabled state –Indicates the state of the store, On/Off
    • Store Description – Provides description of the store
  5. Add or specify the Citrix Gateway URL. Enter the name of the URL, delimited by a semi-colon:

Example: CitrixWorkspaceApp.exe STORE0= HRStore;https://ag.mycompany.com#Storename;On;Store Where #Store name is the name of store behind Citrix Gateway.

In earlier releases, when you add or remove an account using the Citrix Gateway URL/StoreFront Account List policy in the GPO, you must reset the Citrix Receiver for the changes to take effect.

Starting with Version 1808, any changes made to the Citrix Gateway URL/StoreFront Account List policy is applied in a session when you restart the Citrix Workspace app. A reset is not required.

Note:

Resetting Citrix Workspace app is not required on a fresh installation of Citrix Workspace app Version 1808 and later. In case of an upgrade to Version 1808 and later, reset the Citrix Workspace app for the changes to take effect.

Limitations:

  • Citrix Gateway URL must be listed as first followed by StoreFront URL(s).
  • Multiple Citrix Gateway URLs are not supported.
  • Citrix Gateway URL configured using this method does not support PNA Services site behind Citrix Gateway.

Manage workspace control reconnect

Workspace control lets applications follow users as they move between devices. This enables, for example, clinicians in hospitals to move from workstation to workstation without having to restart their applications on each device. For Citrix Workspace app, you manage workspace control on client devices by modifying the registry. This can also be done for domain-joined client devices using Group Policy.

Caution

Editing the registry incorrectly can cause serious problems that may require you to reinstall your operating system. Citrix cannot guarantee that problems resulting from the incorrect use of Registry Editor can be solved. Use the Registry Editor at your own risk. Be sure to back up the registry before you edit it.

Create WSCReconnectModeUser and modify the existing registry key WSCReconnectMode in the Master Desktop Image or in Citrix Virtual Apps server. The published desktop can change the behavior of the Citrix Workspace app.

WSCReconnectMode key settings for Citrix Workspace app:

  • 0 = do not reconnect to any existing sessions
  • 1 = reconnect on application launch
  • 2 = reconnect on application refresh
  • 3 = reconnect on application launch or refresh
  • 4 = reconnect when Citrix Workspace interface opens
  • 8 = reconnect on Windows log on
  • 11 = combination of both 3 and 8

Disable workspace control for Citrix Workspace app

To disable workspace control, create the following key:

HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Citrix\Dazzle (64-bit)

HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\\Dazzle for (32-bit)

Name: WSCReconnectModeUser

Type: REG_SZ

Value data: 0

Modify the following key from the default value of 3 to zero

HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Citrix\\Dazzle (64-bit)

HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\\Dazzle (32-bit)

Name: WSCReconnectMode

Type: REG_SZ

Value data: 0

Note:

Alternatively, you can set the REG_SZ value WSCReconnectAll to false if you do not want to create a key.

Changing the status indicator timeout

You can change the amount of time the status indicator displays when a user is launching a session. To alter the time-out period, create a REG_DWORD value SI INACTIVE MS in HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\ICA CLIENT\Engine\. The REG_DWORD value can be set to 4 if you want the status indicator to disappear sooner.

Customizing location for application shortcut using command line

Start menu integration and desktop shortcut only mode lets you bring published application shortcuts into the Windows Start menu and onto the desktop. Users do not have to subscribe to applications from the Citrix Workspace user interface. Start menu integration and desktop shortcut management provide a seamless desktop experience for groups of users, who need access to a core set of applications in a consistent way.

As a Citrix Workspace app administrator, use a command-line install flags, GPOs, account services, or registry settings to disable the usual “self-service” Citrix Workspace app interface and replace it with a pre-configured Start menu. The flag is called SelfServiceMode and is set to true by default. When the administrator sets the SelfServiceMode flag to false, the user no longer has access to the self-service Citrix Workspace app user interface. Instead, they can access subscribed apps from the Start menu and via desktop shortcuts - referred to here as a shortcut-only mode.

Users and administrators can use a number of registry settings to customize the way shortcuts are set up.

Working with shortcuts

  • Users cannot remove apps. All apps are mandatory when working with the SelfServiceMode flag set to false (shortcut-only mode). If the user removes a shortcut icon from the desktop, the icon comes back when the user selects Refresh from the Citrix Workspace app system tray icon.
  • Users can configure only one store. The Account and Preferences options are not available. This is to prevent the user from configuring additional stores. The administrator can give a user special privileges to add more than one account using the Group Policy Object template, or by manually adding a registry key (HideEditStoresDialog) on the client machine. When the administrator gives a user this privilege, the user has a Preferences option in the system tray icon, where they can add and remove accounts.
  • Users cannot remove apps using the Windows Control Panel.
  • You can add desktop shortcuts via a customizable registry setting. Desktop shortcuts are not added by default. After you make any changes to the registry settings, restart the Citrix Workspace app.
  • Shortcuts are created in the Start menu with a category path as the default, UseCategoryAsStartMenuPath.

Note:

Windows 8/8.1 and Windows 10 do not allow the creation of nested folders within the Start Menu. Applications are displayed individually or under the root folder but not within Category sub folders defined with Citrix Virtual Apps.

  • You can add a flag [/DESKTOPDIR=”Dir_name”] during installation to bring all shortcuts into a single folder. CategoryPath is supported for desktop shortcuts.
  • Auto Reinstall Modified Apps is a feature which can be enabled via the registry key AutoReInstallModifiedApps. When AutoReInstallModifiedApps are enabled, any changes to attributes of published apps and desktops on the server are reflected on the client machine. When AutoReInstallModifiedApps are disabled, apps and desktop attributes are not updated and shortcuts are not restored on refresh if deleted on the client. By default, this AutoReInstallModifiedApps is enabled. See Using registry keys to customize app shortcut locations.

Customizing location for application shortcut using the Registry editor

Note:

  • By default, registry keys use String format.
  • You should make changes to registry keys before configuring a store. If at any time you or a user wants to customize the registry keys, you or the user must reset Citrix Workspace app, configure the registry keys, and then reconfigure the store.

Registry keys for 32-bit machines:

alt_text

Registry keys for 64-bit machines:

alt_text

User accounts

You can provide users with the account information that they need to access virtual desktops and application using the following:

  • Configuring email-based account discovery
  • Provisioning file
  • Providing users with account information to enter manually

Important

Citrix recommends that you restart Citrix Workspace app after the installation. This is to ensure that users can add accounts and Citrix Workspace app can discover USB devices that were in a suspended state during installation.

A dialog appears to indicate a successful installation, followed by the Add Account dialog. For a first time user, the Add Account dialog requires you to enter an email or server address to set up an account.

Suppressing Add Account dialog

Add Account dialog is displayed when the store is not configured. Using the Add Account dialog, you can set up a Citrix Workspace app account by entering email address or a server URL.

Citrix Workspace app determines the Citrix Gateway, StoreFront server, or App Controller virtual appliance associated with the email address and then prompts the user to log on for enumeration.

Add account dialog can be suppressed in the following ways:

  1. At system logon

    localized image

    Select Do not show this window automatically at logon to prevent the Add Account window to pop up on subsequent logon. This is a per-user setting and resets during Citrix Workspace app for Windows Reset.

  2. Command line Installation

    Install Citrix Workspace app for Windows as an administrator using the command line interface with the following switch.

    CitrixWorkspaceApp.exe /ALLOWADDSTORE=N

    This is a per-machine setting; hence the behavior shall be applicable for all users.

    The following message is displayed when Store is not configured.

    localized image

Also, Add Account dialog can be suppressed in the following ways.

  • Renaming Citrix execution file: Rename the CitrixWorkspaceApp.exe to CitrixWorkspaceAppWeb.exe to alter the behavior of Add Account dialog. When you rename the file, the Add Account dialog is not displayed from the Start menu.

  • Group Policy Object administrative template: To hide the Add Account option from the Citrix Workspace app installation wizard, disable EnableFTUpolicy under Self-Service node in Local Group Policy Object administrative template as shown below. This is a per-machine setting, hence the behavior is applicable for all users.

    localized image

Configure email-based account discovery

When you configure Citrix Workspace app for email-based account discovery, users enter their email address rather than a server URL during initial Citrix Workspace app installation and configuration. Citrix Workspace app determines the Citrix Gateway or StoreFront Server associated with the email address based on Domain Name System (DNS) Service (SRV) records and then prompts the user to log on to access virtual desktops and applications.

Note:

Email-based account discovery is not supported for deployments with Web Interface.

For more information about configuring email-based account discovery, see Global App Configuration Service.

Provide users with provisioning files

StoreFront provides provisioning files that users can open to connect to stores.

You can use StoreFront to create provisioning files containing connection details for accounts. Make these files available to your users to enable them to configure Citrix Workspace app automatically. After installing Citrix Workspace app, users simply open the file to configure Citrix Workspace app. If you configure Workspace for website, users can also obtain Citrix Workspace app provisioning files from those sites.

For more information, see To export store provisioning files for users in the StoreFront documentation.

Provide users with account information to enter manually

To enable users to set up accounts manually, be sure to distribute the information they need to connect to their virtual desktops and applications.

  • For connections to a StoreFront store, provide the URL for that server. For example:https://servername.company.com.

    For web interface deployments, provide the URL for the Citrix DaaS site.

  • For connections through Citrix Gateway, first determine whether user should see all configured stores or just the store that has remote access enabled for a particular Citrix Gateway.

    • To present all configured stores: Provide users with the Citrix Gateway fully qualified domain name.

    • To limit access to a particular store: Provide users with the Citrix Gateway fully qualified domain name and the store name in the form:

CitrixGatewayFQDN?MyStoreName:

For example, if a store named “SalesApps” has remote access enabled for server1.com and a store named “HRApps” has remote access enabled for server2.com, a user must enter server1.com?SalesApps to access SalesApps or enter server2.com?HRApps to access HRApps. This feature requires that a first-time user create an account by entering a URL and is not available for email-based discovery.

When a user enters the details for a new account, Citrix Workspace app attempts to verify the connection. If successful, Citrix Workspace app prompts the user to log on to the account.

To manage accounts, open the Citrix Workspace app home page, and click down-arrow icon, and then click Accounts.

Sharing multiple stores accounts automatically

Warning

Using Registry Editor incorrectly can cause serious problems that can require you to reinstall the operating system. Citrix cannot guarantee that problems resulting from incorrect use of Registry Editor can be solved. Use Registry Editor at your own risk. Ensure you back up the registry before you edit it.

If you have more than one store account, you can configure Citrix Workspace app for Windows to automatically connect to all accounts when establishing a session. To automatically view all accounts when opening Citrix Workspace app:

For 32-bit systems, create the key “CurrentAccount”:

Location: HKEY_LOCAL_MACHINE\Software\Citrix\Dazzle

KeyName: CurrentAccount

Value: AllAccount

Type: REG_SZ

For 64-bit systems, create the key “CurrentAccount”:

Location: HKEY_LOCAL_MACHINE\Software\Wow6432Node\Citrix\Dazzle

KeyName: CurrentAccount

Value: AllAccount

Type: REG_SZ

Client drive mapping

Citrix Workspace app for Windows supports device mapping on user devices so they are available from within a session. Users can:

  • Transparently access local drives, printers, and COM ports
  • Cut and paste between the session and the local Windows clipboard
  • Hear audio (system sounds and .wav files) played from the session

During log on, Citrix Workspace app informs the server of the available client drives, COM ports, and LPT ports. By default, client drives are mapped to server drive letters and server print queues are created for client printers so they appear to be directly connected to the session. These mappings are available only for the current user during the current session. They are deleted when the user logs off and recreated the next time the user logs on.

You can use the redirection policy settings to map user devices not automatically mapped at logon. For more information, see the Citrix Virtual Apps and Desktops documentation.

Turn off user device mappings

You can configure user device mapping including options for drives, printers, and ports, using the Windows Server Manager tool. For more information about the available options, see your Remote Desktop Services documentation.

Redirect client folders

Client folder redirection changes the way client-side files are accessible on the host-side session. When you enable only client drive mapping on the server, client-side full volumes are automatically mapped to the sessions as Universal Naming Convention (UNC) links. When you enable client folder redirection on the server and the user configures it on the user device, the portion of the local volume specified by the user is redirected.

Only the user-specified folders appear as UNC links inside sessions instead of the complete file system on the user device. If you disable UNC links through the registry, client folders appear as mapped drives inside the session. For more information, including how to configure client folder redirection for user devices, see the Citrix Virtual Apps and Desktops documentation.

Map client drives to host-side drive letters

Client drive mapping allows drive letters on the host-side to be redirected to drives that exist on the user device. For example, drive H in a Citrix user session can be mapped to drive C of the user device running Citrix Workspace app for Windows.

Client drive mapping is built into the standard Citrix device redirection facilities transparently. To File Manager, Windows Explorer, and your applications, these mappings appear like any other network mappings.

The server hosting virtual desktops and applications can be configured during installation to map client drives automatically to a given set of drive letters. The default installation maps drive letters assigned to client drives starting with V and works backward, assigning a drive letter to each fixed drive and CD-ROM drive. (Floppy drives are assigned their existing drive letters.) This method yields the following drive mappings in a session:

Client drive letter Is accessed by the server as
A A
B B
C V
D U

The server can be configured so that the server drive letters do not conflict with the client drive letters; in this case the server drive letters are changed to higher drive letters. For example, changing server drives C to M and D to N allows client devices to access their C and D drives directly. This method yields the following drive mappings in a session:

Client drive letter Is accessed by the server as
A A
B B
C C
D D

The drive letter used to replace the server drive C is defined during Setup. All other fixed drive and CD-ROM drive letters are replaced with sequential drive letters (for example; C > M, D > N, E > O). These drive letters must not conflict with any existing network drive mappings. If a network drive is mapped to the same drive letter as a server drive letter, the network drive mapping is not valid.

When a user device connects to a server, client mappings are reestablished unless automatic client device mapping is disabled. Client drive mapping is enabled by default. To change the settings, use the Remote Desktop Services (Terminal Services) Configuration tool. You can also use policies to give you more control over how client device mapping is applied. For more information about policies, see the Citrix Virtual Apps and Desktops documentation.

HDX Plug and Play USB device redirection

HDX Plug and Play USB device redirection enables dynamic redirection of media devices, including cameras, scanners, media players, and point of sale (POS) devices to the server. You or the user can restrict redirection of all or some of the devices. Edit policies on the server or apply group policies on the user device to configure the redirection settings. For more information, see USB and client drive considerations in the Citrix Virtual Apps and Desktops documentation.

Important

If you prohibit Plug and Play USB device redirection in a server policy, the user cannot override that policy setting.

A user can set permissions in Citrix Workspace app to always allow or reject device redirection or to be prompted each time a device is connected. The setting affects only devices plugged in after the user changes the setting.

To map a client COM port to a server COM port:

Client COM port mapping allows devices attached to the COM ports of the user device to be used during sessions. These mappings can be used like any other network mappings.

You can map client COM ports at the command prompt. You can also control client COM port mapping from the Remote Desktop (Terminal Services) Configuration tool or using policies. For information about policies, see the Citrix Virtual Apps and Desktops documentation.

Important

COM port mapping is not TAPI-compatible.

  1. For Citrix Virtual Apps and Desktops deployments, enable the Client COM port redirection policy setting.

  2. Log on to Citrix Workspace app.

  3. At a command prompt, type:

    net use comx: \\\\client\\comz:

    where x is the number of the COM port on the server (ports 1 through 9 are available for mapping) and z is the number of the client COM port you want to map.

  4. To confirm the operation, type:

    net use

    at a command prompt. The list that appears contains mapped drives, LPT ports, and mapped COM ports.

To use this COM port in a virtual desktop or application, install your user device to the mapped name. For example, if you map COM1 on the client to COM5 on the server, install your COM port device on COM5 during the session. Use this mapped COM port as you would a COM port on the user device.

DNS name resolution

You can configure Citrix Workspace app for Windows that uses the Citrix XML Service to request a Domain Name Service (DNS) name for a server instead of an IP address.

Important:

Unless your DNS environment is configured specifically to use this feature, Citrix recommends that you do not enable DNS name resolution in the server farm.

Citrix Workspace app connecting to published applications through the Web Interface also use the Citrix XML Service. For Citrix Workspace app connecting through the Web Interface, the Web server resolves the DNS name on behalf of Citrix Workspace app.

DNS name resolution is disabled by default on the server and enabled by default on the Citrix Workspace app. When DNS name resolution is disabled on the server, any Citrix Workspace app request for a DNS name returns an IP address. There is no need to disable DNS name resolution on Citrix Workspace app.

To disable DNS name resolution for specific user devices:

If your server deployment uses DNS name resolution and you experience issues with specific user devices, you can disable DNS name resolution for those devices.

Caution

Using Registry Editor incorrectly can cause serious problems that can require you to reinstall the operating system. Citrix cannot guarantee that problems resulting from incorrect use of Registry Editor can be solved. Use Registry Editor at your own risk. Ensure you back up the registry before you edit it.

  1. Add a string registry key xmlAddressResolutionType to HKEY\_LOCAL\_MACHINE\Software\\Wow6432Node\Citrix\ICA Client\Engine\Lockdown Profiles\All Regions\Lockdown\Application Browsing.
  2. Set the value to IPv4-Port.
  3. Repeat for each user of the user devices.
Get started