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.
|
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.
|
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.
|
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.
|
|
Only Administrators are allowed to use the services of the WSCommunicationsSubsystem.
|
|
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.
|
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.
|
||||||
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.
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.
|