Axeda Global Access Server: Registration
In 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 v.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. Concordantly, 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. For details, refer to
TokenPropertyAuthenticator Behavior (eMessage Connector).
The Thing that represents an Axeda Global Access Server can reflect the state of the GAS. The 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 GAS Thing has two properties that indicate that it is "registered", namely lastRegistrationDate and firstRegistrationDate. The eMessage Connector handles any GAS status events (that is, "pings") and ensures that the lastConnectionTime property for the GAS Thing is updated.
The 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.
The GAS also sends in a token that is generated automatically on the server 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 the Connector cannot start the session on the offline GAS.
Possible Errors During Registration
During GAS registration, the eMessage Connector 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 Axeda Compatibility Extension and the Remote Access Extension have 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 services on the eMessageServices Thing 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.
◦ 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 eMessage Connector sets the isReporting property of the GAS Thing to false
During GAS un-register processing, the eMessage Connector may return FAILURE due to 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 eMessage Connector may return SUCCESS and log an error that was cause by one of the following conditions:
• 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 eMessage Connector may return FAILURE due to one of the following conditions:
• 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 log for error messages and make sure that the eMessage Connector has the proper permissions and visibility to update or set the properties of a GAS Thing.