Using the RemoteAccessClientLinker Widget
The ThingWorx Remote Access Extension (RAE) includes the RemoteAccessClientLinker widget that you can use to build your own user interface, using ThingWorx Mashup Builder. This widget facilitates starting a remote session, launching the client, and detecting whether the client is installed on the user's system. This topic assumes that you are familiar with Mashup Builder, have the appropriate license for the application, and that you have learned how to use it.
The RemoteAccessClientLinker Widget
Widgets enable you to create mashups with pre-packaged functionality. The RemoteAccessClientLinker widget is no exception. It has the properties that are common to all widgets as well as properties that are specific for creating remote sessions with Edge devices that are currently in the isReporting and/or isConnected state. Note that the Things that represent the Edge devices must implement the RemoteAccessible Thing Shape for users to run remote sessions on the devices.
For specifics on using Mashup Builder and widgets, see the Mashup Builder section in the ThingWorx Platform Help Center.
The RemoteAccessClientLinker widget works for all types of remote access sessions. It is up to you to link the RemoteEndpoint property of the widget to a valid value. Typically, you do this by binding the property to a row returned by the GetRemoteAccessibleEndpoints service. This service is on the RemoteAccessible Thing Shape.
When developing a mashup, you do not need to call the StartSession service if you are using the RemoteAccessClientLinker widget. Just set the properties listed in the following table on the widget, and they are passed to the StartSession service.
Property | Description | ||
|---|---|---|---|
ThingName | The name of the Thing that represents the asset with which you want to establish a remote session. | ||
RemoteEndpoint | You need to bind this property to a row returned by the GetRemoteAccessibleEndpoints service. This service is provided on the RemoteAccessible Thing Shape and therefore to the Remote Access Server you are using for remote sessions. For example, the Global Access Server (GAS). | ||
ProviderConfig |
This property is JSON that is specifically formatted to the type of RemoteAccessProvider being used, either the ThingWorxInternalRemoteAccessProvider Thing for ThingWorx AlwaysOn agents, such as the ThingWorx Edge MicroServer (EMS), or the GASRemoteAccessProvider Thing for Axeda eMessage Agents. For information about the JSON format, refer to RemoteAccessProvider providerConfig Property Details. | ||
SessionDescription | The JSON-formatted metadata field from the RemoteSessionParameters Data Shape supports this property. When the widget calls the StartSession service, it adds the content of this field with the key description and the value of the SessionDescription property. | ||
AutoLaunchParams | A bindable JSON property that defines substitution parameters for Auto Launch commands. You can bind JSON data from multiple data sources in the platform, such as services, user session, widgets, or functions. |
Adding the Widget to a Mashup
By importing the ThingWorx Remote Access Extension (RAE) into your ThingWorx Platform, the widget is listed as RemoteAccessClientLinkerin the IDE view of Mashup Builder, as shown below:
From there, you can drag an instance of the widget into your mashup. Note that although it displays in the IDE UI, there is no visible rendering of this widget in the actual mashup at run time. Similar to an Expression widget, you will see the following in the mashup:
Once you have dragged it into the mashup, you can select it, move it around, and drag bindable elements onto the widget to connect its properties and services. Where the widget is located in the mashup is irrelevant to its function.
When creating a mashup, add fields for the user to enter the property information for ThingName, RemoteEndpoint, and SessionDescription properties. For example:
From the Configure Widget page, set the binding between the SessionDescription property of the RemoteAccessClientLinker widget and the corresponding Session Description parameter in the mashup example above, as shown here:
For a mashup that starts a remote session, add a text field for the SessionDescription, as shown here:
Selecting a Thing and Starting a Session
To enable users to select a Thing at runtime and then start a session via the widget, follow these steps:
1. Add an EntityPicker widget to the mashup to allow users to select a Thing at runtime.
2. Bind the contents of the EntityPicker widget to the ThingName property on the RemoteAccessClientLinker widget:
a. On the EntityPicker widget select to add an outbound data binding to the RemoteAccessClientLinker widget.
b. Make sure that the Things that will be visible to the users all implement the RemoteAccessible Thing Shape.
At runtime, the Thing Name the user selects in the EntityPicker widget is passed to the RemoteAccessClientLinker widget.
3. Next locate the RemoteEndpoint property. This property is required to start a session and generally refers to the application on the remote device with which you are attempting to start a session.
4. Bind this property to a value derived from another widget. This value must match the name value of an endpoint from the GetRemoteAccessibleEndpoints service on the Thing.
5. In general, you do not need to set anything for the ProviderConfig property of the widget. This property represents any additional provider-specific information that may be used by the RemoteAccessProvider (either GAS or ThingWorxInternalRemoteAccessProvider) that is facilitating the session.
 | Unless you need to override the defaults for remote sessions, do not enter anything for this property. In addition, do NOT bind it to the RemoteAccessProvider entity because remote sessions will fail. If you must override the defaults, you can enter static text in JSON format. For details, refer to RemoteAccessProvider providerConfig Property Details. |
6. The SessionId property is bindable in and out, allowing you to bind in the id of a session that already exists or out if the widget had previously started a session. If the session id is bound in from elsewhere, this session id takes precedence and the widget does not attempt to start a new session. You can use this session id to launch the client if a session already exists or to provide the session id to something else. Both cases are helpful in implementing retry logic.
7. The AutoLaunchParams property allows you to bind JSON data that contains parameters and values to substitute for Auto Launch commands.
8. Once the properties have been set, you can launch the session by invoking the LaunchClient service:
The LaunchClient service performs the following actions:
a. Starts the session.
b. Attempts to launch the Remote Access Client (RAC).
c. Detects whether the RAC launches successfully.
 | To launch the RAC, you must allow the browser to open pop-ups for the mashup. |
Handling Client Launch
The RemoteAccessClientLinker widget fires the following events as part of the LaunchClient service:
Event Name | Description |
|---|---|
SessionCreated | Fired when the session has started and the widget is about to attempt to launch the client with the created session. |
AwaitingLaunch | Fired after the client has attempted to launch. |
ClientLaunched | Fired if the widget detects that the client launched successfully. Use this event to indicate the session was successfully started and that the client successfully launched. |
ClientNotInstalled | Fired if the widget detects that the client did not launch. This event indicates only that the client did not connect back to the ThingWorx Platform. The session was started and may timeout due to inactivity. |
Detecting If Client Is Installed
The RemoteAccessClientLinker widget detects whether the client is installed by waiting for it to 'call back' to the ThingWorx Platform once launched. By detecting this callback, the widget can positively identify that the user has the client installed. If the client does not call back within a configured timeout period, the widget can be reasonably assured that the user does not have the client installed or that the client is having trouble connecting to the platform.
This timeout period is configurable on the RemoteAccessSubsystem configuration page. The default value is 10 seconds. Before changing this value, keep in mind that the ClientNotInstalled event does not fire until this entire timeout period has expired. Setting it too high could lead to long wait times before feedback is provided. Here is the relevant part of the subsystem's Configuration page:
User-side (Local) Server
As part of connecting to a remote session, all available remote access implementations provide a server that is local to the user's machine. The Remote Access Client notifies users of an available local port to which they can connect whatever application client they are using for that session, such as SSH or VNC (Desktop). To prevent anyone from accessing this server from outside the user's machine (for instance, if they had access to the IP address of the user's machine), the client-side server listens only on the loopback interface of the local machine. This means that any attempt to connect to that server using the IP of the machine does not work. All connections must be made to a loopback address, such as 127.0.0.1.
| | ThingWorx Edge tunneling does not support protocols that make multiple connections to and disconnections from the Edge, such as using a browser to access an HTTP server. For example, RDP triggers disconnects when you use the wrong credentials and when you are connecting to an RDP server that is not trusted by your computer. To be most effective, make sure you understand the connection and disconnection behavior of the protocol you are trying to forward. |
| | Do not use localhost instead of the IP address, for example 127.0.0.1, because it may resolve to an IPv6 address that will not work correctly. |