ThingWorx Model Definition in Composer > System > Subsystems > WebSocket Communications Subsystem
WebSocket Communications Subsystem
The WebSocket (WS) communications subsystem handles core WS communications.
Configuration
Bind Protection Settings
Setting
Base Type
Default
Notes
Bind Protection Policy
STRING
First-in-wins
Choose the desired Bind Protection Policy from the menu. By default the policy is First-in wins. This policy means that if the platform receives a new bind attempt from an edge device that is already bound, the platform rejects the new bind attempt.
The Last-in wins policy means that, rather than rejecting a new bind for the already-bound device, the platform should accept that new bind and update the routing rules on how messages are sent out to the edge.
Enable Visibility Permission Check
BOOLEAN
false
When this policy is enabled, the app key user used to bind the edge device to the Remote Thing will be validated for visibility permissions. If the visibility permissions are not set, binding will not be allowed.
WebSocket Communication Settings
Setting
Base Type
Default
Notes
Idle Connection Timeout (sec)
INTEGER
60
Once the connection is established, the WebSocket communications subsystem waits the specified number of seconds before shutting the connection down. If there is activity, the idle timer is reset.
Idle Ping Rate (secs)
INTEGER
45
ThingWorx waits the specified number of seconds for a ping from a client. If a ping is received, the communication cycle continues.
If a pong is not received for a ping request in the specified number of seconds, the SDK will disconnect and attempt to reconnect. The disconnect will close the socket, ThingWorx connection, WebSocket connection, TLS connection, and the OS-level socket. The reconnect will create new versions of these connection layers, assuming each layer of authentication is successful.
Amount of time to wait for authentication message (secs)
INTEGER
15
After the connection is established, the remote server waits the specified amount of time for authentication. If authentication is not received, the socket is shut down.
Amount of time a request will wait for the response message before timing out (secs)
INTEGER
30
If the server is online and the request fails, an error is thrown.If the server is offline, the request is placed in the queue until the server is online again.
Send a ping after sending a message or tunnel traffic
BOOLEAN
True
Sends a ping after a message is sent from a client to the platform. This setting is applied when the connection is created.
Asynchronous Configuration Setting
Setting
Base Type
Default
Notes
Max Thread Count
NUMBER
10
Used for egress communications to edge devices specifies the number of threads available to communicate with Remote Things. An example of an egress communication would be executing a remote service on a Remote Thing. Any requests above the specified value are sent to a queue.
Client Endpoint Settings
Setting
Base Type
Default
Notes
Endpoint Name
STRING
n/a
User-defined name
Endpoint URI
STRING
n/a
URI of the remote server with which to federate
Max Endpoint Connections
INTEGER
1
Number of connections open to the remote server
Idle Ping Rate (sec)
INTEGER
45
Used when federating two servers. The idle ping rate specifies how often the server sends a ping to the remote server. It keeps the connection active so intermediate systems do not shut the server down due to it being idle, and it prevents the remote server from shutting down the connection due to it being idle.
Application Key
PASSWORD
n/a
When you click the Change Password button, the Change Password screen appears. Here you can enter a new application key.
Services
The services of the WSCommunicationsSubsystem enable an administrator to query and close AlwaysOn WebSockets connected to the ThingWorx Platform.
* 
Only Administrators are allowed to use the services of the WSCommunicationsSubsystem.
If you want to know what is currently connected to the platform in addition to remote things, follow these steps:
1. Run the QueryEndpointSessions service to obtain the number of Things bound to the specified endpoint, along with the number of currently open connections. See the table below for details about this service.
2. Run the GetBoundThingsForEndpoint service to determine which Things are bound to which endpoints. See the table below for details about this service.
3. If a given connection is compromised or otherwise needs to be shut down, run the CloseEndpointSessions service to close the connection.
* 
You may also trigger the CloseEndpointSessions service to disconnect devices with expired application keys at regular intervals. Below is a sample script that identifies devices with expired application keys and closes their connections:

// This script is for informational and example purposes only, and you must
// configure/validate it to ensure that it meets your functional and security requirements.

// result: INFOTABLE dataShape: ""
var expiredKeysTable = Subsystems["UserManagementSubsystem"].GetApplicationKeyExpirationInfo({
expiredKeys: true /* BOOLEAN */ ,

unexpiredKeys: false /* BOOLEAN */
});

// Create InfoTable from EntityList DataShape
var params = {
infoTableName: "InfoTable",
dataShapeName: "EntityList"
};

// CreateInfoTableFromDataShape(infoTableName:STRING("InfoTable"), dataShapeName:STRING):INFOTABLE(EntityList)
var result = Resources["InfoTableFunctions"].CreateInfoTableFromDataShape(params);

for (var i = 0; i < expiredKeysTable.rows.length; i++) {
var expirationInfoTable = expiredKeysTable.rows[i].expirationInfo.rows;
for (var j = 0; j < expirationInfoTable.length; j++) {

// Add the name and key to result InfoTable
var newEntry = new Object();
newEntry.name = expirationInfoTable[j].name;// STRING [Primary Key]
result1 = Subsystems["WSCommunicationsSubsystem"].CloseEndpointSessions({
appKeyName: expirationInfoTable[j].name /* APPLICATIONKEYNAME */
});
logger.warn("Number of closed Sessions: " + result1);
logger.warn("Expired application keys: " + expirationInfoTable[j].name);
}
}
* 
The CloseEndpointSessions service does not expire or otherwise invalidate any application keys that are used by the sessions that it closes. If you want to disconnect devices using a given application key and prevent the devices from reconnecting, first force the application key to expire by updating its expiration date. Then invoke this service to close the sessions.
See the table below for more details about the CloseEndpointSessions service.
Service
Description
QueryEndpointSessions
This service takes the following parameters to query for endpoint sessions:
authenticationType (STRING)
appKeyName (APPLICATIONKEYNAME)
userName (USERNAME)
startedBefore (DATETIME)
startedAfter (DATETIME)
lastUsedBefore (DATETIME)
lastUsedAfter (DATETIME)
hasBoundThings (BOOLEAN)
hasMultipleConnections (BOOLEAN)
maxItems (NUMBER). The default value is 500 results.
This service returns an INFOTABLE that contains the following fields:
endpointId. The identifier of the endpoint, not of the session itself.
authenticationType. For example, "Application Key" or "User Credentials".
appKeyName The name of the application key, if applicable.
userContext. The name associated with the account under which the service was run. For all of these services, it is "Administrator".
startDate
lastUsedDate. Excludes pings.
numberBoundThings. The number of Things bound over this endpoint.
numberConnections. The current number of open connections. For a ThingWorx Connection Server or a ThingWorx connector, there can be multiple connections.
GetBoundThingsForEndpoint
This service takes an endpoint ID. When you invoke the service from the Composer UI, you can optionally set a maximum number of rows to return. It returns an INFOTABLE that contains the names of the Things bound to the specified endpoint, up to the specified maximum number of rows.
This service enables administrators to determine which Things are bound to which endpoints without running into potential memory issues by including them in the results from QueryEndpointSessions.
CloseEndpointSessions
This service takes either an endpoint ID or all the parameters from the QueryEndpointSessions service, except for maxItems. If both are supplied, the service returns an error.
This service closes all sessions that match the criteria. When specifying the endpoint, use an endpoint ID that was returned by the QueryEndpointSessions service.
This service does not expire or otherwise invalidate any application keys that are used by the sessions it closes. For this reason, if you intend to disconnect devices using a given application key and prevent them from reconnecting, you should first force the application key to expire by updating its expiration date, and then invoke this service to close the sessions.
Invocations of this service are audited, if the audit subsystem is enabled. The audit messages fall in the category, DEVICE_COMMUNICATIONS. For information about the audit subsystem, see Audit Subsystem and its related topics.
* 
This service will only attempt to close endpoints for devices directly connected to the ThingWorx Platform. For closing endpoints connected to an AlwaysOn Connection Server and directly-connected devices, use the CloseEndpoints service instead.
CloseEndpoints
This service takes the following parameters to query for endpoint sessions:
appKeyName (APPLICATIONKEYNAME)
endpointId (STRING)
If both are supplied, the service returns an error.
This service returns a NUMBER indicating the number of endpoint connections attempted to be closed.
This service closes all endpoint connections associated with the provided appKeyName or the endpoint ID. Use the endpoint ID returned by the QueryEndpointSessions service when specifying the endpoint.
* 
This service does not expire or invalidate any application keys that are used by the sessions it closes. For this reason, if you intend to disconnect devices using a given application key and prevent them from reconnecting, you must first force the application key to expire by updating its expiration date, and then invoke this service to close the sessions.
Invocation of this service that results in endpoint connection closure(s) are audited if the audit subsystem is enabled. Audit messages are categorized under DEVICE_COMMUNICATIONS. For information about the audit subsystem, see Audit Subsystem and its related topics.
* 
This service is preferred over the existing CloseEndpointSessions service for the two primary uses:
Close by application key name
Close by endpoint ID
Endpoint closures are a best effort attempt for endpoints on an AlwaysOn Connection Server. The returned count of closed endpoints is a count of the number of endpoints attempted to be closed.
* 
Only Administrators are allowed to use the new QueryEndpoints service.
Was this helpful?