Auto Launch
The ThingWorx Remote Access Extension v.3.1.0 and the ThingWorx Remote Access Client v.2.3.0 support the same type of automatic launching of client applications such as an SSH terminal or VNC Client. ThingWorx Administrators can enable or disable auto launch globally from the configuration page of the Remote Access Subsystem. By default auto-launch is disabled. To enable it, go to the Configuration page for the Remote Access Subsystem.
Configuring Auto Launch
When using the GetAutoLaunchConifg service, you must set the maximum number of entries to return from this query. To limit the maximum number of configurations that are returned, set the maxConfigsToReturn configuration property for the Remote Access Subsystem. The default value is 500. In the following figure, this property is the last one in the list:
Permissions
To allow the ThingWorx Remote Access Client (RAC), to call the RAS.GetAutoLaunchConfoig(remoteEndpoint, thingName) service as a non-admin user, the RemoteAccessPermissionServices.GrantPermissions() service includes granting the Runtime permission, ServiceInvoke. If you upgraded the Remote Access Extension (RAE) and RAC to take advantage of the auto-launch command, make sure that you run the RemoteAccessPermissionServices.GrantPermissions() service after upgrading the RAE, even if you ran it the last time you upgraded.
Configuring "Click to Launch"
To allow your end users to simply click the Launch command shown in the Remote Access Client, disable Auto Launch by clearing the check box next to Enable Auto Launch.
 | When the Enable Auto Launch is disabled and the GetAutoLaunchConifg server finds a configuration, the service sets the isAutoLaunch field on the configuration to false. |
Using Variables for a Launch Command
The Remote Access Client (RAC) supports the use of variables for the <$HOST> and <$PORT> as well as the use of environment variables.
 | When you enter values for the Launch Command, you are responsible for ensuring that those values work, whether or not you use variables. |
The following table describes the variables that you can use with a Launch Command; examples follow the table:
Variable | How It Works | ||
|---|---|---|---|
<$HOST> | RAC finds the host that the remote application or desktop viewer needs to connect to and substitutes that name for this variable. | ||
<$PORT> | RAC finds the first available listening port and substitutes that port number for the variable. The Launch Command supports a range of port numbers for remote applications that require a range of ports. All of the ports in the range must be available for the application on the remote asset to succeed. If any port is in use by another application, the remote session is terminated. If a configured port has been remapped due to port conflicts on a machine, <$PORT> is expanded to the actual port in use.
| ||
<$ENV:env_var> | When you use this variable, RAC checks the environment variables on the client operating system and substitutes the value found there for the specified variable. If a value is not found, an empty string is returned. The resolution of <$ENV:env_var> does not affect any other text defined in the Launch Command. If an environment variable is not defined or otherwise is not found on the client system, the remainder of the Launch Command remains in effect. For example, suppose the administrator sets up the Launch Command as follows: <$ENV:proframfilles>\\Axeda\\Desktop\\Viewers\\aviewer.exe with programfiles misspelled as proframfilles. The environment variable as typed is not found and returns an empty string. After substitution, the Launch Command is: \\Axeda\\Desktop\\Viewers\\aviewer.exe RAC checks if the executable file exists in the directory and launches it, if found. |
Here is an example of using the <$ENV:env_var> variable to launch Axeda Desktop Viewer:
"<$ENV:programfiles>\\Axeda\\Desktop\\Viewers\\AxedaDesktopViewer_vvvvvv.exe" <$HOST>:<$PORT>
You must use quotation marks to delimit Launch Command arguments that contain spaces such as a path referencing C:\Program Files. When using the variables, if a command argument might contain spaces after expansion, use the double quotation marks to delimit the argument. For example, using "<$ENV:programfiles>" in the Launch Command would result in "C:\Program Files", which requires a space.
To run PuTTY, you could use the following Launch Command:
putty.exe -ssh -P <$PORT> localhost
RAC launches putty in an SSH terminal using the local machine and a port in the range putty looks for.
To run Microsoft RDP, type the following:
C:\WINDOWS\system32\mstsc.exe /v:<$HOST>:<$PORT>
Make sure that you use the complete file name for the executable, including the extension ("exe" in this example). For this application, you must use a colon between the <$HOST> and <$PORT> variables. When the remote application is launched, <$HOST> is expanded to the destination, localhost. As long as the configured port is available, <$PORT> is expanded to the configured port, typically 3030.
How Auto Launch Works in the Remote Access Client (RAC)
The Remote Access Client (RAC) executes the Auto Launch command if the isAutoLaunch field of the AutoLaunchConfig is set to true, after RAC calls the GetAutoLaunchConfig service. The command can support multiple arguments with spaces separating arguments and double quotation marks around the arguments to allow for spaces.
When the RAC launches the command successfully, this icon is displayed next to the command field: 
. The following figure shows the icon in the RAC screen on the left and the putty session on the right:
. The following figure shows the icon in the RAC screen on the left and the putty session on the right:
The success icon supports a tooltip, as shown below:
Error Handling of the Auto Launch Command
If any error occurs when launching the command, the Remote Access Client (RAC) displays this icon: 
. You can click this icon to display a tooltip, as shown below:
. You can click this icon to display a tooltip, as shown below:
For details about the error, review the tw-ra-client.log file for the RAC. In the example above, the launch command, putty-error could not be found. The corresponding error in the log is:
[2021-10-19T13:16:47.181] [WARN] renderer - Command (putty-error) raised an error: spawn putty-error ENOENT
The ENOENT error code means "No such file or directory". Check the directory where the script file should be and make sure the path used in the Launch command matches.
Here is another example of an error in the log file for RAC:
[2021-10-19T13:59:24.275] [WARN] renderer - Command (/tmp/test.sh) raised an error: spawn /tmp/test.sh EACCES
In this example, the RAC attempted to launch /tmp/test.sh, but it does not have the necessary permissions to launch the script file. EACCES means “Access Denied”. To resolve an access issue, run the GrantPermissions service on the RemoteAccessServices Thing.