Global Access Server: Registration
For Axeda GAS, the ThingWorx model of the GAS server does not exist until the GAS itself sends a request through the eMessage Connector to register itself with ThingWorx Platform. In this registration message a token, unique to the GAS server, is provided and can be stored for future verification of messages from this GAS device.
Prior to GAS 6.9.0, the GAS would generate a new token each time the GAS restarted. The effect was that the eMessage Connector / ThingWorx needed to accept any token provided by the GAS and set it as the authoritative token from that GAS, even if it changed from a previously stored value. In effect, this caused the token to be fairly useless from a security standpoint.
As of GAS 6.9.0, the token generation code in the GAS was modified to ensure the token is generated only once and the same token is reused between restarts. Similarly, the eMessage Connector Remote Access support was updated to use the token with the TokenPropertyAuthenticator. This authenticator works the same way for GAS as it does for the eMessage Agents.
The Thing that represents an Axeda or ThingWorx Global Access Server can reflect the state of the GAS. The Axeda GAS sends a registration message to the eMessage Connector, and the Connector updates the stats of the Thing that represents this GAS in the ThingWorx Platform. The ThingWorx GAS can operate in the same way or, as of 7.1.0, can register directly with the ThingWorx Platform. Any GAS Thing has two properties that indicate that it is "registered", namely lastRegistrationDate and firstRegistrationDate. The eMessage Connector handles any Axeda GAS status events (that is, "pings") and ensures that the lastConnectionTime property for the GAS Thing is updated. A ThingWorx GAS 7.1.0 sends updates directly to the ThingWorx Platform.
The Axeda GAS registers itself with the eMessage Connector by posting a "register" message to the endpoint <host:port>/remote/rsstatus. The message provides the following information:
• description — text that briefly describes the GAS.
• hostName — the URL of the GAS. For example, abc_gas.ptc.com.
• externalHostName — the URL of an external GAS. For example, abc_gas.external.ptc.com.
• Alternate user host name — An alternate GAS to use. For example, abc-gas.alt.ptc.com
• name — The name of the GAS. For example, agc-gas.
• port — The port on the host machine that listens for incoming requests. For example, 8082.
For a ThingWorx GAS 7.x, the same information is provided to the platform on registration.
The Axeda and ThingWorx Global Access Servers also send in a token that is generated automatically on the GAS and that serves to authenticate subsequent communications from the GAS to the eMessage Connector/ThingWorx Platform. When the GAS is shut down or disconnects from the network, the GAS Thing remains and is not automatically unregistered. If a user attempts to start a session with that GAS, the request fails because a session cannot be started on an offline GAS.
Possible Errors During Registration
During GAS registration, the eMessage Connector or ThingWorx Platform may return FAILURE due to one the following conditions:
• The hostName or token fields are not populated.
• The maxSessions is set to less than 1.
• The GASModel Thing Template does not exist on the ThingWorx Platform. Make sure that the the Remote Access Extension has been imported properly to the ThingWorx Platform.
• The GAS Thing does not exist for one of the following reasons:
◦ The Connector does not have the proper permissions to create the GASRemoteAccessProvider. Make sure that the permission-granting services have been run so that the eMessage Connector has the permissions and visibility needed to create the provider and GAS Thing and also to enable and restart it.
◦ An error occurred during the creation of the GAS Thing.
◦ An error occurred during an attempt to enable the GAS Thing for remote sessions.
◦ An error occurred during an attempt to restart the GAS Thing.
• The token does not match the token sent in previously by the GAS.
• An error occurred while attempting to bind to the GAS Thing on the ThingWorx Platform.
• An error occurred while attempting to set properties on the GAS Thing. In particular, an error may have occurred while the first and last registration properties are being set..
During GAS un-register processing, the isReporting property of the GAS Thing is set to false
During GAS un-register processing, a FAILURE may be returned for one of the following conditions:
• The hostName or token fields are not populated.
• The token does not match the token that was previously passed in by the Global Access Server.
During GAS status/audit processing the status SUCCESS be returned and an error caused by one of the following conditions may be returned:
• An error occurred when attempting to bind to the GAS Thing on the ThingWorx Platform.
• An error occurred when setting the currentNumberOfSessions property on the GAS Thing.
• An error occurred when attempting to update RemoteSession fields (agentIP, userIP, createdTime, endTime, terminationCause, and/or bytesTransferred).
During GAS status/audit processing the status FAILURE may be returned for one of the following reasons:
• The current number of sessions is less than 0.
• The hostName field is not populated.
• The token does not match the one previously sent in by the same GAS.
• The GAS Thing does not exist
Check the logs for error messages and make sure that the proper permissions and visibility to update or set the properties of a GAS Thing have been granted.