The GetVersion command allows to determine on the web server side which Parallels Client version is installed on a user device, or if the Parallels Client is installed at all. If Parallels Client is an older version or not installed on a device, you can display a message to the user with a link from which they can download and install the correct version of Parallels Client.
The command works as follows:
A user opens a custom scheme URL with the GetVersion command in it.
The URL starts Parallels Client which receives the parameters contained in the URL, including server name, port number, the web portal session ID, and the path to which Parallels Client needs to connect to pass its version information back to the web portal.
The Parallels Client uses the received information and connects to the web portal using the specified path with the version information appended to it.
The web portal parses the received data and evaluates the Parallels Client version number. If the request times out (no response is received from Parallels Client), it means that Parallels Client is not installed on the user device.
The following table describes the GetVersion command options:
| Key | Datatype | Value |
|---|---|---|
Command
String
The name of the command to execute. In this instance, it's "GetVersion".
Server
String
The server on which the web portal is hosted. Server can be specified by IP address or its local name.
Port
Int
The port number of the web portal
Session
String
The web portal Session ID.
Secure
Boolean
The SSL boolean value.
Path
String
The path to which Parallels Client needs to connect in order to pass the version information.
The OS type and the Parallels Client version info need to be specified with the path:
OS:
Key: os
Type: Int
Value: 0 (Windows); 1 (Linux); 2 (macOS); 4 (Android); 5 (iOS).
Version:
Key: version
Type: String
Value: The Parallels Client version. This needs to be URL encoded.
RequestPage
String
The exact path of the current web portal page from where the URL was opened.
This is used in iOS, so that the iOS client can redirect the user back to the RAS Web Portal page.
The LaunchApp command is used to configure a connection in Parallels Client, authenticate a user, and launch published resources.
Note that the LaunchApp command passes sensitive information inside a URL, including server name, port, and possibly username and password. If this is a concern, use a more secure Get2xa command.
The following table describes the LaunchApp command options:
| Key | Datatype | Value |
|---|---|---|
The following URL creates a new connection (but doesn't save it in Parallels Client as the "Save" key is set to "NO"), authenticates a user using the specified credentials, and launches an application in Parallels Client.
The Get2xa command performs the same tasks as the LaunchApp command, but uses an advanced security mechanism to pass sensitive information between the web portal and the Parallels Client.
Advanced security is achieved as follows:
A user clicks a published resource on a third-party web portal. This opens a URL that uses the Parallels Client URL scheme and includes the following information:
The web portal server name, port number, and session ID.
A path from which Parallels Client can download an XML file containing the Parallels RAS connection information, user credentials, and the ID of the published resource to launch.
The XML file that the Parallels Client will be downloading is called a 2XA file, which is a historical name used in Parallels RAS to identify the specific file format. The 2XA file specifications (XML) are described later in this section.
The URL opens Parallels Client in the background. The information contained in the URL is passed to Parallels Client.
Parallels Client connects to the web server using the received information and downloads a 2XA file using the path that it received via the URL.
Note that the 2XA file should be dynamically generated for every user and every published resource when a given user attempts to launch a resource in the web portal.
Parallels Client parses the information contained in the XML file and uses it to create a connection, authenticate a user, and launch a resource.
The following table describes the Get2xa command options:
| Key | Datatype | Value |
|---|---|---|
URL example
The following URL opens Parallels Client and passes to it the web server information, the web portal session ID, the path to the 2XA file, and the path to the original web portal web page.
When Parallels Client receives the information from the URL, it uses it to connect to the web server and download the 2XA file.
The following is an example of the GET request performed by Parallels Client:
The following table describes the XML document structure used in the 2XA file (see also the XML example below):
The XML document must begin with UTF-8 BOM (byte order mark), which consists of the following 3 bytes:
Note that BOM is not a text. You need to use a script that can add these 3 bytes to the beginning of the file.
The following is a sample 2XA XML document:
Note that another option to pass the password is to use the ClearPassword key instead of Base64ClearPassword, as shown below:
| Section | Key | Description |
|---|---|---|
Boolean
YES, NO
The values are case sensitive.
Command
String
The name of the command to execute. In this instance, it's "LaunchApp".
AppID
Int
The application ID to launch.
You can look up the ID in the RAS Console (Publishing > select a resource > Information tab > look at the first field on the tab page, which displays the resource ID followed by resource name). Note that the ID must be specified without the pound sign (#).
You can also obtain a resource ID via RAS PowerShell by executing Get-RASPubItem "resource-name". The returned PubItem object has the Id property that specifies the resource ID. To get the list of all available published resources, execute the Get-RASPubItem cmdlet with no parameters.
If this parameter is empty, Parallels Client will perform an application listing.
MultiID
A comma separated list of applications to be launched by the client. This is used for the 'Start On Logon' option. If this is present, AppID will be ignored.
Note: Currently not used by mobile clients.
Alias
String
Connection name (when creating a new connection).
ConnType
Int
Connection type:
0 — Parallels RAS Connection
2 — Standard RDP Connection
ConnMode
Int
Connection mode:
0 — Gateway
1 — Direct
2 — Gateway SSL
3 — Direct SSL
Server
String
The server FQDN or IP address.
Backup
String
The secondary connection server (if available and required).
Port
Int
The port number.
UserName
String
Deprecated, but still supported for backwards compatibility. For new integrations, use LoginEx.
User name. If this parameter is empty, the user will be prompted to enter a name.
LoginEx
String
User name. If this parameter is empty, the user will be prompted to enter a name. Usernames can have 'username', 'domain\user', or 'username@domain' format.
Password
Plain text password. If neither this key nor the “EncPass” (see below) is included, the user will be prompted for password when connecting.
EncPass
String
Encrypted ('hashed') password. If neither this key nor the “Password” is included, the user will be prompted for password when connecting.
SessionID
String
The Auth Session ID.
Connect
Boolean
Whether to connect to Parallels RAS right after the connection is configured. "YES" -- connect. "NO" -- don't connect (this should be used when you only want to create a connection without launching a published resource). Note that the values are case sensitive.
Save
Boolean
Whether to save the connection in Parallels Client. If set to "YES", the connection information will be saved (possibly overwriting existing settings). The default value is "NO". Note that the values are case sensitive.
Request Page
String
[Optional] The exact path of the web portal page from where the original URL was launched.
This parameter is used on iOS devices, so that the iOS client can redirect the user back to the original web portal page after closing the application.
SSO
String
[Optional] Custom 3rd party SSO GUID. Used only by Windows clients. Currently only used by invitation emails.
HelpDeskEmail
String
[Optional] Helpdesk or support contact email. Currently only used by Parallels Clients for Android and iOS.
OverrideArgs
String
Override application arguments. Currently only used by Parallels Client for Mac.
Command
String
The name of the command to execute. In this instance, it's "Get2xa".
Server
String
The server where the web portal is hosted. The server can be specified by IP address or its local name.
Port
Int
The port number.
Session
String
The web portal session ID. This is used by Parallels Client in the GET request. It is being passed as a cookie named "ASP.NET_SessionId" (see The GET request from Parallels Client below).
Secure
Boolean
The SSL boolean value. "YES" - use SSL. "NO" - don't use it. The values are case sensitive.
Path
String
A path to which Parallels Client needs to connect in order to download the 2XA file. This needs to be URL encoded.
RequestPage
String
[Optional] The exact path of the current web portal page from where the original URL was launched.
This is used in iOS, so that the iOS client can redirect the user back to the web portal page.
IIS
ValidSession
This should be set to 1.
Logon
User
Deprecated, but still supported for backwards compatibility. For new integrations, use LoginEx.
The username.
Logon
LoginEx
The username. Usernames can have 'username', 'domain\user', or 'username@domain' format.
Logon
Base64ClearPassword
[Optional] Base 64 encoded plain text password. If this is not set, the Parallels Client will try to load the ClearPassword parameter (see below), else the user will be prompted for password when connecting.
The parameter is available in all Parallels Client versions (desktop and mobile) since RAS v16.5.2.
Logon
ClearPassword
[Optional] Plain text password. If this is not set, the user will be prompted for password when connecting.
This parameter has been available in Parallels Client for Windows for some time. It is available in Parallels Client for other platforms (desktop and mobile) since RAS v16.5.2.
Logon
SSO
[Optional] The Authentication mode. Can be one of the following:
0 = credentials (default)
3 = web
Connection
Port
The server's port number.
Connection
StartMode
The connection mode. Can be one of the following:
0 : Gateway Mode
1 : Direct Mode
2 : Gateway SSL
3 : Direct SSL
Connection
PrimaryServer
The server name. Server can be specified by IP or by its local name.
Startup
PublishedApp
[Optional] The ID of the published resource to be launched, including the pound sign (e.g. "#256").
You can look up the ID in the RAS Console (Publishing > select a resource > Information tab > look at the first field on the tab page, which displays the resource ID followed by resource name).
You can also obtain a resource ID via RAS PowerShell by executing Get-RASPubItem "resource-name". The returned PubItem object has the Id property that specifies the resource ID. To get the list of all available published resources, execute the Get-RASPubItem cmdlet with no parameters.
If this key is not set, the Parallels Client will show the list of all available published resources.
Startup
OverrideParams
[Optional] URL encoded arguments to be passed to the published application. If included, the arguments will override existing arguments (if any).
The parameter is available in Parallels Clients for all platforms (desktop and mobile) since RAS v16.5.2.
Command | String | The name of the command to execute. In this instance, it's "LogOff". |
Server | String | [Optional] Server name. Server can be specified by IP address or its local name. If this key is omitted, the user will be logged off from all sessions on all servers. |
RequestPage | String | [Optional] The path to the current web portal page. This is used in iOS, so that the iOS client can redirect the user back to the web portal page. |