Platform Service collects and stores information about client activity such as when a device connects, disconnects, or sends messages. Use the client connection state API to query the activity of one or many device clients.
As an example, you can get information on when a client was last active and why it became disconnected, or you can view all clients that did not connect in the past day so that you can address any issues.
For a detailed description of the API details, see the swagger documentation at the following URL: https://docs.internetofthings.ibmcloud.com/apis/swagger/v0002/clientstate.html#/Client%20Connection%20State/get_clientconnectionstates__clientId
In Maximo Monitor, replace workspaceId with your workspace or tenant ID.
Note: Brief delay might occur between the time that a client connects or disconnects and the time that the connection status from the API reflects the correct status. To receive live notifications over MQTT when a client connects or disconnects, use the device monitoring topic.
You must activate the client connection state API feature before you can start querying.
To find the current activation status for the client connection state feature, use the GET /config/clientstate API call.
If a 403 response is returned, the feature is not active.
Important: Deactivating the feature deletes any stored client activity status documents and all devices must send another update before the connection state can be determined if you reactivate the feature later.
Use one of the two following methods to activate client connection state API:
PUT /config/clientstate API call with the following application/JSON body:{"enabled": true}.With the client connection state API, you can retrieve and query the connection status for any clients that are connected or were earlier connected to Platform Service.
The connection status includes the following information:
The following examples illustrate some common connection state queries.
Retrieve the client connection status for a single client:GET /clientconnectionstates/{clientId}
Retrieve the connection status of all clients:GET /clientconnectionstates
Retrieve all connected clients:GET /clientconnectionstates?connectionStatus=connected
Retrieve all clients that were active within the past two days:
GET /clientconnectionstates?connectedAfter={currentTime-2D}
For more information about the API, including all of the available query filters, see the Client Connection State API Swagger document.
A brief delay might occur between the time that a client connects and the time that the connection status from the API reflects the correct status.
If constant monitoring is required, you can subscribe to the monitor topic to receive live connectivity status updates for the client. For more information, see Subscribing to device status messages.
The number of stored recent client states is based on the connection type:
| Type | Stored client states |
|---|---|
| Applications | 100 |
| Gateways | 10,000 |
| Devices | 1,000,000 |
Important: Connections that last a long time might eventually be removed as new connections are made.
Platform Service provides a per-device log of connection information, which you can use to diagnose device connectivity problems or to provide more context to the information that is provided by the monitoring topic or connecting status API.
The connection log provides information such as:
The connection log API returns up to the last 10 log messages for the devices.
For more information, see the Connection Logs API Swagger document.
SDKs with client connectivity HTTP APIs are available for Node.js and for Python.