Configuring Auto Launch on the ThingWorx Platform
You can configure local applications such as SSH terminals or VNC clients to launch automatically when starting remote sessions. This feature is supported by the Remote Access Extension (RAE) version 3.1.4 and the Remote Access Client (RAC) version 2.3.1 or later. You can use services to manage configurations for Auto Launch commands using the Remote Access Subsystem of RAE. For example, you can configure the Auto Launch feature to start a terminal window and establish an SSH connection when a service technician connects to a RemoteAccessible Thing for a routine service. The technician can then manage and interact with the remote Thing without manually launching the required applications. Using Auto Launch reduces the total number of steps required to perform repetitive tasks when connecting to multiple remote end points.
The Auto Launch feature is disabled by default. As a ThingWorx administrator, you can configure Auto Launch using the Remote Access Subsystem in the following ways:
• Enable Auto Launch globally on the server.
• Create new configurations for Auto Launch commands.
• View, update, and delete existing configurations.
You can use the Auto Launch options and services within the subsystem to create configurations for any user who is using the RAC to access remote Things. Storing multiple configurations enables you to launch specific applications for different Things that may be associated with different roles. The following section describes the services that you can use to define, edit, and delete configurations.
Configuring the Auto Launch Using Services
To use the data services for Auto Launch in the platform, perform the following steps:
1. In Composer, click Browse, then under System choose Subsystems. A list of available subsystems on the server is displayed.
2. Select the RemoteAccessSubsystem entity from the list.
3. On the services tab, select a configuration service, then click 
.
.4. Provide the required inputs for the service, and then click Execute.
All configurations for the Auto Launch feature are stored on the platform. The following table lists the available configuration services.
Service | Description | Access Level | Required Inputs | Return Base Type | ||
|---|---|---|---|---|---|---|
CreateAutoLaunchConfig | Creates a new Auto Launch configuration using the value provided in defaultCommand input parameter. The RAE retrieves launch commands for a Thing in the following order: 1. The configuration for the Thing. 2. The configuration for the parent Thing Template of the Thing. 3. Any configuration for parents of the Thing Template, and up to the RemoteThing entity. When isAutoLaunch is set to False, click-to-launch is used in the RAC instead. For some client and remote device, pre-configured Auto Launch commands are downloaded from a PTC server when a configuration is not available. Pre-configured commands are only available for Axeda Desktop Viewer endpoints.
| Administrator | • remoteEndpoint—A string • One of the following fields: ◦ A Thing name, THINGNAME of a RemoteAccessible Thing. ◦ A Thing Template name: THINGTEMPLATENAME • isAutoLaunch—A boolean • defaultCommand—A string | None | ||
UpdateAutoLaunchConfig | Updates an existing Auto Launch configuration for a specific Thing or Thing Template. You can update the command syntax, whether Auto Launch is enabled for this specific configuration, and the Thing or Thing Template name.
| Administrator | • remoteEndpoint— A string • One of the following fields: ◦ A Thing name, THINGNAME, that is defined using the RemoteAccessible Thing Shape. ◦ A Thing Template name: THINGTEMPLATENAME • isAutoLaunch—A boolean • defaultCommand—A string | None | ||
DeleteAutoLaunchConfig | Deletes an existing Auto Launch configuration. | Administrator | • remoteEndpoint—A string • One of the following fields: ◦ A Thing name, THINGNAME, of RemoteAccessible Thing . ◦ A Thing Template name: THINGTEMPLATENAME | None | ||
GetAutoLaunchConfigs | Returns an infotable that contains a list of all Auto Launch configurations that are stored in the platform. | Administrator | None | INFOTABLE | ||
GetAutoLaunchConfig | Returns an infotable that contains the Auto Launch configuration when accessing remote Thing using the RAC. | Standard user | • remoteEndpoint—A string • A thingName, THINGNAME, of a RemoteAccessible Thing. | INFOTABLE |
Configuring the Auto Launch Options under the Remote Access Subsystem
When you execute the GetAutoLaunchConfigs service in the Remote Access Subsystem, you must set the maximum number of configurations to retrieve from the subsystem under Maximum Number of AutoLaunchConfigs to Return from Data Storage. The default value is 500. The following figure shows the configuration options that are available for the subsystem:
Using Click-To-Launch When Auto Launch is Disabled
To disable Auto Launch for all available configurations on the platform, clear the check box next to the Enable Auto Launch configuration option of the Remote Access Subsystem. When Auto Launch is disabled globally on the server, applications are not launched automatically. The isAutoLaunch field for any existing configuration is returned as false when the GetAutoLaunchConfig service is executed. However, the defined configurations are still applied to the remote access client when a starting a remote session. To launch an application, users can click the launch button to start applications manually.
Setting Up the Required Permissions
To configure access permissions that are required for RAC, run the RemoteAccessPermissionServices.GrantPermissions() service for a ThingWorx organization. The service grants permissions to user groups, including the ServiceInvoke run-time permissions that is required to execute the RemoteAccessSubsystem.GetAutoLaunchConfig(remoteEndpoint, thingName) service.
 | To access a Thing remotely, you must have permissions to the Thing and ServiceInvoke permissions to the StartSession service on the Thing. |
Using Launch Commands in the Remote Access Client (RAC)
The RAC executes the Auto Launch command when the isAutoLaunch field of the AutoLaunchConfig is set to true. The command supports multiple arguments that are separate by a space. You can add double quotation marks around arguments to allow spaces in an argument value, such as a file path that contains folder names with spaces.
The following image shows a PuTTY terminal instance that was launched automatically when using the client to connect to a remote entity named ra-test-agent.
A success icon 
is displayed when the command is launched successfully.
is displayed when the command is launched successfully.
When Auto Launch is disabled, the RAC user must click the 
launch button before the launch command is executed.
launch button before the launch command is executed.Example: Launching Axeda Desktop Viewer on Windows
The following example shows a command that is used to launch the Axeda Desktop Viewer (ADV) automatically. The HOST, PORT, and ENV variables are replaced with the values of the local host, port, and environment variable values where the RAC is running.
"<$ENV:ADV_HOME>\AxedaDesktopViewer_v69215.exe" <$HOST>:<$PORT>
| | To run this command, you must have ADV installed. |
To connect to the Axeda Desktop Server, enter your password when ADV launches.
The command contains the following variables:
1. <$ENV:env_var>
The RAC checks the environment variable on the client operating system and substitutes its value. RAC is case sensitive. All variable names must be used with the same capitalization. When a value is not found, an empty string is returned.
| | The RAC may not detect environment variable that is added or changed after it is launched. To make sure those variables are detected, you must restart the system. |
2. <$HOST>
The RAC provides the host name or server address that the application or ADV must connect to and then replaces this variable with that value.
3. <$PORT>
The RAC replaces this variable with that port number that is running the socket server. The default port number for Axeda Desktop Server is 5920 on the Windows viewer. The default number may be replaced with a different number when the default is not available.
For example, the previous stored command is resolved as follows when the RAC is used to start a local server socket on port 8553 of a local host:
• <$ENV:ADV_HOME> is replaced with C:\Program Files\ADV, which is the value of the environment variable on the current system.
| | ADV_HOME is the environment variable name for ADV. You can replace this value with other environment variable names for different programs that are installed on the system. Variable names are case sensitive. |
• <$HOST> is replaced with localhost
• <$PORT> is replaced with 8553
The following is the resolved command that is executed and displayed in the RAC:
"C:\Program Files\ADV\AxedaDesktopViewer_v69215.exe” localhost:8553
| | You must add quotation marks to delimit launch command arguments that contain spaces, such as paths that reference: "C:\Program Files" |
Example: Launching a PuTTY SSH Session on Linux
The following example shows a command that uses the HOST, PORT and ENV variables for a remote application named PuTTY:
| | To run this command, you must have PuTTY installed. |
"<$ENV:PUTTY_HOME>\putty" -ssh testuser@<$HOST> <$PORT>
The command contains the following variables:
1. <$ENV:PUTTY_HOME>
This variable is replaced by the value of the PUTTY_HOME environment variable, which contains the path to PuTTY on the system. After you provide the password for testuser, RAC creates an SSH connection.
2. <$HOST>
This variable is replaced by the host name or server address that the PuTTY terminal should connect to.
3. <$PORT>
This variable is replaced by the available listening port that is started by the RAC.
Error Handling of the Auto Launch Command
An error is displayed when a command cannot be launched, and the RAC displays a warning 
icon. You can click this icon to display a tooltip, as shown in the following image:
icon. You can click this icon to display a tooltip, as shown in the following image:
For details about the error, open the tw-ra-client.log file for the RAC. In this example, the putty-error launch command causes an error that is logged in the file as follows:
[2021-10-19T13:16:47.181] [WARN] renderer - Command (putty-error) raised an error: spawn putty-error ENOENT
The ENOENT error code is used to indicate that the launch command was not found or that the file or directory does not exist. To resolve this error, check the location where the script file is stored be and make sure that the path used in the Launch Command box matches.
The following is another example of an error in the RAC log file:
[2021-10-19T13:59:24.275] [WARN] renderer - Command (/tmp/test.sh) raised an error: spawn /tmp/test.sh EACCES
The EACCES error code is used to indicate that access is denied. In this example, the RAC fails to launch /tmp/test.sh because the users lacks access permissions that are required to launch the script file. To resolve access issues, make sure that the client user has the required access permissions to run the script.