Using URIs to Configure HTML Access Web Clients

You can use uniform resource identifiers (URIs) to create web or email links for end users. End users can click these links to start HTML Access, connect to a server, and start a remote desktop or published application with specific configuration options.

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

Server address
Port number for the server
Active Directory user name
RADIUS or RSA SecurID user name, if different from the Active Directory user name
Domain name
Remote desktop or published application display name
Actions, including browse, reset, log out, and start session

URI Specification

The required syntax includes a path part to specify the server, and, optionally, a query to specify a user, remote desktop or published application, and actions or configuration options.

To create URIs for starting HTML Access, use the following syntax:

https://authority-part[/?query-part]

authority-part

Specifies the server address and, optionally, a non-default port number. Server names must conform to DNS syntax.

To specify a port number, use the following syntax:

server-address:port-number

query-part

Specifies the configuration options to use or the actions to perform. Queries are not case-sensitive. To use multiple queries, use an ampersand (&) between the queries. If queries conflict with each other, the last query in the list is used. Use the following syntax:

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

Observe the following guidelines when creating the query part:

If you do not use at least one of the supported queries, the default VMware Horizon web portal page appears.
In the query part, some special characters are not supported, and you must use the URL encoding format for them, as follows: For the pound symbol (#) use %23, for the percent sign (%) use %25, for the ampersand (&) use %26, for the at sign (@) use %40, and for the backslash (\) use %5C.
For more information about URL encoding, go to http://www.w3schools.com/tags/ref_urlencode.asp.
In the query part, 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/.

Supported Queries

This topic lists the queries that are supported for HTML Access. 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.

action

Table 1. 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 you use this action.
start-session	Starts 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. Unsaved data is lost. Resetting a remote desktop is the equivalent of pressing the Reset button on a physical PC. This action is not valid for a published application.
logoff	Logs the user out of the guest operating system in the remote desktop. This action is not valid for a published application.
restart	Shuts down and restarts the primary remote desktop after the user confirms the restart operation request. This action is not valid for a published application.

applicationId

The published application display name. The display name is the name specified in Horizon Console when the application pool was created. If the display name contains a space, the browser uses %20 to represent the space.

args

Specifies command-line arguments to add when starting a published application. 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.

desktopId

The remote desktop display name. The display name is the name specified in Horizon Console when the desktop pool was created. If the display name contains a space, the browser uses %20 to represent the space.

domainName

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

tokenUserName

The RSA or RADIUS user name. Use this query only if the RSA or RADIUS user name is different from the Active Directory user name. If you do not specify this query and RSA or RADIUS authentication is required, the Windows user name is used.

userName

The Active Directory user who is connecting to the remote desktop or published application. The user name can be in one of the following formats:

userName
domainName%5CuserName
user principal name (UPN), that is, userName@domainName

unauthenticatedAccessEnabled

When this option is set to true, the Unauthenticated Access feature is enabled by default. HTML Access starts and an anonymous user account appears. An example of the syntax is unauthenticatedAccessEnabled=true.

unauthenticatedAccessAccount

Sets the account to use if the Unauthenticated Access feature is enabled. If Unauthenticated Access is deactivated, then this query is ignored. An example of the syntax using the anonymous1 user account is unauthenticatedAccessAccount=anonymous1

webviewMode

When this option is set to true, the remote session starts in webview mode. In webview mode, the HTML Access sidebar is hidden. Webview mode also enables certain third-party mobile apps to do the following:

Send events from the soft keyboard to the remote desktop
Use the mobile app interface to switch between native touch mode and trackpad touch mode in HTML Access

URI Syntax Examples

Each of the following URI examples is followed by a description of what the end user sees after clicking the URI link. Queries are not case-sensitive, for example, you can use domainName or domainname.

```
https://horizon.mycompany.com/?domainName=finance&userName=fred
```
HTML Access starts and connects to the horizon.mycompany.com server. In the login box, the User name text box is populated with the name fred, and the Domain text box is populated with finance. The user must supply only a password.
```
https://horizon.mycompany.com/?userName=finance%5Cfred
```
HTML Access starts and connects to the horizon.mycompany.com server. In the login box, the User name text box is populated with the name finance\fred. The user must supply only a password.
```
https://horizon.mycompany.com/?userName=fred@finance
```
HTML Access starts and connects to the horizon.mycompany.com server. In the login box, the User name text box is populated with the name fred@finance. The user must supply only a password.
```
https://horizon.mycompany.com/?desktopId=Primary%20Desktop&action=start-session
```
HTML Access starts and connects to the horizon.mycompany.com server. The login box prompts the user for a user name, domain name, and password. After a successful login, the client connects to the remote desktop that has the display name Primary Desktop and the user is logged in to the guest operating system.
```
https://horizon.mycompany.com/?applicationId=Notepad&action=start-session
```
HTML Access starts and connects to the horizon.mycompany.com server. The login box prompts the user for a user name, domain name, and password. After a successful login, the Notepad application starts.
```
https://horizon.mycompany.com:7555/?desktopId=Primary%20Desktop
```
This URI has the same effect as the previous example, except that it uses the non-default port 7555 for the server. The default port is 443. Because a remote desktop identifier is provided, the remote desktop starts even though the start-session action is not included in the URI.
```
https://horizon.mycompany.com/?applicationId=Primary%20Application&desktopId=Primary%20Desktop
```
This URI specifies both a published application and a remote desktop. When you specify both a published application and a remote desktop, only the remote desktop starts.
```
https://horizon.mycompany.com/?desktopId=Primary%20Desktop&action=reset
```
HTML Access starts and connects to the horizon.mycompany.com server. The login box prompts the user for a user name, domain name, and password. After a successful login, the client displays a dialog box that prompts the user to confirm the reset operation for Primary Desktop.

Note: This action is available only if an administrator has allowed end users to reset their machines.
```
https://horizon.mycompany.com/?My%20Notepad++?args=%22My%20new%20file.txt%22
```
Opens My Notepad++ on server horizon.mycompany.com and passes the argument My new file.txt in the application start command. The filename is enclosed in double quotes because it contains spaces.
```
https://horizon.mycompany.com/?Notepad++%2012?args=a.txt%20b.txt
```
Opens Notepad++ 12 on server horizon.mycompany.com and passes the argument a.text b.txt in the application start command. Because the argument is not enclosed in double quotes, a space separates the filenames and the two files are opened separately in Notepad++.

Note: Applications can differ in the way that they use command-line arguments. For example, if you pass the argument a.txt b.txt to WordPad, WordPad opens only one file, a.txt.
```
https://horizon.mycompany.com/?desktopId=Primary%20Desktop&action=restart
```
HTML Access starts and connects to the horizon.mycompany.com server. The login box prompts the user for a user name, domain name, and password. After a successful login, the client displays a dialog box that prompts the user to confirm the restart operation for Primary Desktop.

Note: This action is available only if an administrator has allowed end users to restart their machines.

https://horizon.mycompany.com/?unauthenticatedAccessEnabled=true&unauthenticatedAccessAccount=anonymous_user1

HTML Access starts and connects to the horizon.mycompany.com server using the anonymous_user1 account.

HTML Code Examples

You can use URIs to make hypertext links and buttons to include in emails or on web pages. The following examples show how to use the URI from the first URI example to code a hypertext link that reads Test Link and a button that reads TestButton.

<html>
<body>

<a href="https://horizon.mycompany.com/?domainName=finance&userName=fred">Test Link</a><br>

<form><input type="button" value="TestButton" onClick="window.location.href=
'https://horizon.mycompany.com/?domainName=finance&userName=fred'"></form> <br>

</body>
</html>