Using the RAClientLinker Widget
The ThingWorx Remote Access Extension (RAE) includes the RAClientLinker 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 focus here is on the widget.
This topic contains the following sections:
The RAClientLinker Widget
Widgets enable you to create mashups with pre-packaged functionality. The RAClientLinker 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 state. Note that the Things that represent the Edge devices must implement the RemoteAccessible Thing Shape.
For specifics on using Mashup Builder and widgets, see the documentation for ThingWorx Mashup Builder.
The RAClientLinker 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 on the RemoteAccessProvider Thing Shape.
When developing a mashup, you do not need to call the StartSession service if you are using the RAClientLinker widget. Just set the ThingName, RemoteEndpoint, and ProviderConfig properties on the widget, and they are passed to the StartSession service. The ProviderConfig 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 WS EMS or the GASRemoteAccessProvider Thing for Axeda eMessage Agents
Adding the Widget to a Mashup
By importing the ThingWorx Remote Access Extension (RAE) into your ThingWorx Platform, the widget is available as RemoteAccessClientLinker in 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.
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 RAClientLinker widget. On theEntityPicker widget select to add an outbound data binding to the RAClientLinker widget. 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 RAClientLinker 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. 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.
4. The ProviderConfig property of the widget represents any additional provider-specific properties that are required or are used by the RemoteAccessProvider (GAS or ThingWorx Internal) that is facilitating the session. Whether this property is optional depends on the provider. This property is represented as a JSON blob and should be bound as the output from an Expression widget or something similar that can assemble a JSON block from other mashup inputs.
5. The SessionId property is bind-able 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.
6. 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.
Handling Client Launch
The RAClientLinker widget fires several events as part of the LaunchClient service:
• 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 RAClientLinker widget detects whether the client is installed by waiting for it to 'call back' to the 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 (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, 127.0.0.1, because it may resolve to an IPv6 address that will not work correctly. |