Using URIs to Configure Horizon Client

You can use uniform resource identifiers (URIs) to create web page or email links that end users can click to start Horizon Client, connect to a server, or open a remote desktop or published application.

You create these links by constructing URIs that provide some or all the following information so that your end users do not need to supply it.

• Server address
• Port number for the server
• Active Directory user name
• Domain name
• Remote desktop or published application display name
• Window size
• Actions including reset, log out, and start session
• Display protocol
• Options for redirecting USB devices

To construct a URI, you use the URI scheme with Horizon Client specific path and query parts.

To use URIs to start Horizon Client, Horizon Client must already be installed on client computers.

Syntax for Creating URIs

URI syntax includes the URI scheme, a path part to specify the remote desktop or published application, and, optionally, a query to specify remote desktop or published application actions or configuration options.

URI Specification

The only required element is the URI scheme. The scheme name is case-sensitive for some versions of some client operating systems.

Important: In all parts, non-ASCII characters must first be encoded according to UTF-8 [STD63], and then each octet of the corresponding UTF-8 sequence must be percent-encoded to be represented as URI characters.

For information about encoding for ASCII characters, see the URL encoding reference at http://www.utf8-chartable.de/.

• authority-part

  The server address and, optionally, a user name, a non-default port number, or both. Underscores (_) are not supported in server names. Server names must conform to DNS syntax.

  To specify a user name, use the following syntax.

  user1@server-address
  

  You cannot specify a UPN address, which includes the domain. To specify the domain, you can use the domainName query part in the URI.

  To specify a port number, use the following syntax.

  server-address:port-number
  

• path-part

  The display name of the remote desktop or published application. The display name is specified in Omnissa Horizon Console when the desktop pool or application pool is created. If the display name contains a space, use the %20 encoding mechanism to represent the space.

  Alternatively, you can specify a desktop or application ID, which is a path string that includes the desktop or application pool ID. To find a desktop or application ID, open ADSI Edit on the Omnissa Horizon Connection Server host, navigate to the distinguished naming context for a Horizon Connection Server, and select the OU=Applications node. All the desktop and application pools are listed. The distinguishedName attribute specifies the ID value. You must encode the ID value before you specify it in a URI.

  Note: More than one remote desktop or published application can have the same display name, but the desktop and application ID is unique. To specify a particular remote desktop or published application, use the desktop or application ID rather than the display name.

• query-part

  The configuration options to use, or the remote desktop or published application actions to perform. Queries are not case-sensitive. To use multiple queries, use an ampersand (&) between the queries. If the queries conflict, Horizon Client uses the last query in the list. Use the following syntax.

  query1=value1[&query2=value2...]
  

Supported Queries

The following queries are supported for this type of Horizon Client. If you are creating URIs for multiple types of clients, such as desktop clients and mobile clients, see the guide document for each type of client system for the list of supported queries.

• action

  Values That Can Be Used with the action Query

  Value	Description
  browse	Displays a list of available remote desktops and published applications hosted on the specified server. You are not required to specify a remote desktop or published application when using this action. If you use the browse action and specify a remote desktop or published application, the remote desktop or published application is highlighted in the list of available items.
  start-session	Opens the specified remote desktop or published application. If no action query is provided and the remote desktop or published application name is provided, start-session is the default action.
  reset	Shuts down and restarts the specified remote desktop or published application. Unsaved data is lost. Resetting a remote desktop is the same as pressing the Reset button on a physical PC.
  restart	Shuts down and restarts the specified remote desktop. Restarting a remote desktop is the same as the Windows operating system restart command. The operating system usually prompts the user to save any unsaved data before it restarts.
  logoff	Logs the user out of the guest operating system in the remote desktop. If you specify a published application, the action is ignored or the end user sees the warning message "Invalid URI action."

• args

  Specifies command-line arguments to add when the published application starts. Use the syntax args=value, where value is a string. Use percent encoding for the following characters:

  • For a colon (:), use %3A
  • For a back slash (\), use %5C
  • For a space ( ), use %20
  • For a double quotation mark ("), use %22 For example, to specify the filename "My new file.txt" for the Notepad++ application, use %22My%20new%20file.txt%22.

• appProtocol

  For published applications, valid values are PCOIP and BLAST. For example, to specify PCoIP, use the syntax appProtocol=PCOIP.

• connectUSBOnInsert

  Connects a USB device to the foreground remote desktop or published application when you plug in the device. This query is implicitly set if you specify the unattended query for a remote desktop. To use this query, you must set the action query to start-session or else not have an action query. Valid values are true and false. An example of the syntax is connectUSBOnInsert=true.

• connectUSBOnStartup

  Redirects all USB devices that are currently connected to the client system to the remote desktop or published application. This query is implicitly set if you specify the unattended query for a remote desktop. To use this query, you must set the action query to start-session or else not have an action query. Valid values are true and false. An example of the syntax is connectUSBOnStartup=true.

• desktopLayout

  Sets the size of the window that displays a remote desktop. To use this query, you must set the action query to start-session or else not have an action query.

  Valid Values for the desktopLayout Query

  Value	Description
  fullscreen	Full screen on all connected external monitors. This value is the default.
  windowLarge	Large window.
  windowSmall	Small window.
  WxH	Custom resolution, where you specify the width by height, in pixels. An example of the syntax is desktopLayout=1280x800.

• desktopProtocol

  For remote desktops, valid values are PCOIP and BLAST. For example, to specify PCoIP, use the syntax desktopProtocol=PCOIP.

• domainName

  Specifies the NETBIOS domain name associated with the user who is connecting to the remote desktop or published application. For example, you might use mycompany rather than mycompany.com.

• filePath

  Specifies the path to the file on the local system that you want to open with the published application. You can specify the full path or a relative path, for example, ~/username/test%20file.txt. Use percent encoding for the following characters:

  • For a colon (:), use %3A
  • For a back slash (\), use %5C
  • For a space ( ), use %20 For example, to represent file path /Users/username/test file.txt, use /User/username/test%20file.txt.