Configuring Auto Launch Commands using JSON Data from the RemoteAccessClientLinker Widget
Overview
You can use parameter substitution to update Auto Launch commands dynamically based on data from the ThingWorx platform, such as data from the current user session, services, or mashup widgets and functions. Using substitutions is helpful when a value is not known until run time or is unique for each user session. For example, you can use this feature to pass a unique user ID that is stored in the ThingWorx Platform as an argument within an Auto Launch command. You can define parameter data for the AutoLaunchParams property by creating a service that returns a JSON object that contains key and value pairs. The following example defines two parameters named username and id:
{
"username":"user",
"!id":"id"
}
"username":"user",
"!id":"id"
}
When the RAC is launched, the parameters within the Auto Launch commands are automatically replaced by the values that are defined in the JSON. After defining the parameters to use in the launch commands, you can bind the JSON data to the widget property. See the following sections for more information.
 |
To mask parameter values, add an exclamation mark (!) at the start of the key name. Masking a parameter hides its actual value in ThingWorx logs and in the Remote Access Client user interface. However, applying a mask to sensitive data is not safe and does not guarantee security. Masked data is displayed as plain text when copying a command in the RAC, for example.
|
Binding JSON Data to the RemoteAccessClientLinker Widget
1. In Mashup Builder, select a RemoteAccessClientLinker widget on the canvas or using the Explorer panel.
2. On the Properties panel, locate the AutoLaunchParams property.
3. Bind a JSON data source that defines the parameters with the data that you want include in Auto Launch commands as key and value pairs to the AutoLaunchParams property.
4. Click Done, then Save to save your changes to the widget.
You can now include the defined parameters in an Auto Launch command by creating or updating an existing command in the remote access subsystem.
Adding a Parameter Name to an Auto Launch Command
1. In ThingWorx Composer, open the RemoteAccessSubsystem entity, then open the Services tab.
2. Use the CreateAutoLaunchConfigs or UpdateAutoLaunchConfigs services to create or update auto launch commands on the Remote Access subsystem using the following syntax:
<$ALP:ParameterName>
Where:
◦ $ALP is the prefix used to specify a parameter.
◦ ParameterName is the parameter name that is defined in the RemoteAccessClientLinker widget JSON.
| | Do not include the exclamation mark (!) when adding masked parameters to the DefaultCommand field. |
For more information about these services, see .Configuring the Auto Launch Using Services.
3. Save the input and execute the service to update the stored commands on the platform server.
When the RAC is launched at run time, the parameter values are automatically substituted using JSON data that is bound to RemoteAccessClientLinker widget.
Example: Using Parameters and Environment Variables to Launch an SSH Session on Linux
The following example shows a command that combines the HOST and PORT environment variables from the local system with three parameters from the RemoteAccessClientLinker widget to start a remote SSH session:
ssh -o UserKnownHostsFile=<$ALP:UserKnownHostsFileValue> -o StrictHostKeyChecking=<$ALP:StrictHostKeyCheckingValue> <$ALP:username>@<$HOST> -p <$PORT>
The command contains the following parameters and variables:
• <$ALP:UserKnownHostsFileValue>
Replaced by the path for known hosts file used to store a list of trusted hosts to connect to.
• <$ALP:StrictHostKeyCheckingValue>
Specifies whether the host keys are checked when connecting.
• <$ALP:username>
The user name to use for the SSH connection.
• <$HOST> and <$PORT>—Replaced by the available listening port and host name. For more information about environment variables, see the examples in the Configuring Auto Launch on the ThingWorx Platform topic.
The following JSON data is used to set the values for the parameters in the RemoteAccessClientLinker widget:
{
"!UserKnownHostsFileValue": "~/sshconfig/known_hosts",
"StrictHostKeyCheckingValue": "no",
"username":"user"
}
"!UserKnownHostsFileValue": "~/sshconfig/known_hosts",
"StrictHostKeyCheckingValue": "no",
"username":"user"
}
The following command is executed in the RAC after the parameter and environment variable values are substituted:
ssh -o UserKnownHostsFile=(*****) -o StrictHostKeyChecking=no user@localhost -p 22
The UserKnownHostsFile parameter is masked in the RAC because of the added exclamation mark in the JSON data.