API command: get_connected_clients
The get_connected_clients command returns XML data containing details of all connected BeyondTrust clients.
The command API is an authenticated API. For instructions on using authenticated APIs using OAuth, see Authenticate to the Remote Support API. The API account must have read-only or full access to the command API.
Required parameters for get_connected_clients
| type=[string] | The types of clients to return in the results. Can be a comma-separated list of values. Supported values are all (default), representative, support_customer, presentation_attendee, and push_agent. |
| id=[string] | The ID of the client. To get client IDs, see API command: get_connected_client_list. Can be a comma-separated list of values. A maximum of 100 IDs is supported. This ID is a unique identifier which remains valid only while the client is connected. |
| include_connections=[boolean] | If this is set to 1, then the client's list of connections to B Series Appliances and an event log about those connections will be included in the results. |
XML response for get_connected_clients
| <connected_clients> | Contains a child element for each connected client, including <connected_representative>, <connected_support_customer>, <connected_presentation_attendee>, and <connected_push_agent>. |
Element names and attributes
| id (attribute) | A unique identifier which remains valid only while the client is connected. |
| <client_connections> | Contains a <client_connections> element and an <event_log> element. This element is returned only if the query specifies include_connections. |
| <hostname> | The hostname of the representative’s computer. |
| <platform> | The operating system of the representative’s computer. Also contains an id attribute that briefly notes the selected platform for the client. |
| <timezone_offset> | The number of seconds away from UTC. |
| <connected_since> | The date and time at which this connection was made. Data is returned in ISO 8601 format. Also contains a ts attribute which displays the connection start time as a UNIX timestamp (UTC). This element is returned only if the query specifies include_connections. |
| <user_id> | Unique ID assigned to the representative. |
| <type> | The type of account the representative is using. Can be one of Normal or Invited. |
| <username> | The username assigned to the representative. |
| <public_display_name> | The public display name assigned to the representative. Note that this field contains the public display name's value at the time of the conference, which may not match the current value if the public_display_name has subsequently been changed. |
| <private_display_name> | The private display name assigned to the representative. Note that this field contains the private display name's value at the time of the conference, which may not match the current value if the private_display_name has subsequently been changed. |
| <start_session_url> | A URL that can be sent to a customer to start a support session with the representative. |
| <presentation_count> | The number of presentations the representative is performing. Can be either 0 or 1. |
| <support_session_count> | The number of sessions the representative is participating in. |
| <showing_on_rep_list> | Integer value (1 or 0) indicating if the representative appears in the representative list on the public site. |
| <routing_idle> | Integer value (1 or 0) indicating if the representative has a status of idle. |
| <routing_busy> | Integer value (1 or 0) indicating if the representative has a status of busy. |
| <routing_enabled> | Integer value (1 or 0) indicating if the representative has automatic session assignment enabled or disabled. |
| <routing_available> | Integer value (1 or 0) indicating if the representative is available to have sessions automatically assigned. |
| <support_license> | The type of license used by the representative. |
| <support_session_lsids> | Contains an <lsid> element for each session in which the representative is participating. This field corresponds with the <lsid> field of the <connected_support_customer> element. |
| id (attribute) | A unique identifier which remains valid only while the client is connected. |
| <client_connections> | Contains a <client_connections> element and an <event_log> element. This element is returned only if the query specifies include_connections. |
| <hostname> | The hostname of the customer’s computer. |
| <platform> | The operating system of the customer’s computer. Also contains an id attribute that briefly notes the selected platform for the client. |
| <timezone_offset> | The number of seconds away from UTC. |
| <connected_since> | The date and time at which this connection was made. Data is returned in ISO 8601 format. Also contains a ts attribute which displays the connection start time as a UNIX timestamp (UTC). This element is returned only if the query specifies include_connections. |
| <name> | The name which the customer entered in the Your Name field of the front-end survey or which was assigned programmatically. |
| <non_interactive> | Indicates if the session is a remote desktop protocol (RDP) session or a Shell Jump session. Can be either rdp or shelljump. If neither, this element is not returned. |
| <lsid> | A string which uniquely identifies this session. This field corresponds with the <lsid> field of the <connected_representative> element. |
| id (attribute) | A unique identifier which remains valid only while the client is connected. |
| <client_connections> | Contains a <client_connections> element and an <event_log> element. This element is returned only if the query specifies include_connections. |
| <hostname> | The hostname of the attendee’s computer. |
| <platform> | The operating system of the attendee’s computer. Also contains an id attribute that briefly notes the selected platform for the client. |
| <timezone_offset> | The number of seconds away from UTC. |
| <connected_since> | The date and time at which this connection was made. Data is returned in ISO 8601 format. Also contains a ts attribute which displays the connection start time as a UNIX timestamp (UTC). This element is returned only if the query specifies include_connections. |
| <name> | The name which the attendee entered when joining the presentation or which was assigned programmatically. |
| id (attribute) | A unique identifier which remains valid only while the client is connected. |
| <client_connections> | Contains a <client_connection> element and an <event_log> element. This element is returned only if the query specifies include_connections. |
| <hostname> | The hostname of the Jumpoint’s host computer. |
| <platform> | The operating system of the Jumpoint’s host computer. Also contains an id attribute that briefly notes the selected platform for the client. |
| <timezone_offset> | The number of seconds away from UTC. |
| <connected_since> | The date and time at which this connection was made. Data is returned in ISO 8601 format. Also contains a ts attribute which displays the connection start time as a UNIX timestamp (UTC). This element is returned only if the query specifies include_connections. |
| <name> | The Jumpoint's name. |
| <appliance_id> | The GUID of the B Series Appliance to which the client is connected. |
| <purpose> | The reason the representative is connected to this B Series Appliance. Can be either primary or traffic. If not part of a cluster, this will always be primary. |
| <receive_traffic_node> |
Integer value (1 or 0) indicating whether this is the client's default traffic node or not. If not part of a cluster, this will always be 0. |
| <connected_since> | The date and time at which the client connected. Data is returned in ISO 8601 format. Also contains a ts attribute which displays the connection start time as a UNIX timestamp (UTC). |
| <private_ip> | The client's private IP address that was used to connect to the B Series Appliance. |
| <event> |
An <event> element is created for each event that took place during this connection. Up to the last 20 events are returned. Events detail when and why a client connected to a B Series Appliance. Events also include failures to connect to nodes and normal disconnects. Includes a ts attribute which displays the timestamp of the event. |
Query examples: get_connected_clients
| Get a detailed list of all connected clients |
https://support.example.com/api/command?action=get_connected_clients |
| Get a detailed list of all connected representatives |
https://support.example.com/api/command?action=get_connected_clients&type=representative |
| Get a detailed list of all connected representatives and support customers |
https://support.example.com/api/command?action=get_connected_clients&type=representative,support_customer |
| Get a detailed list of all clients with IDs 101, 102, and 103 |
https://support.example.com/api/command?action=get_connected_clients&id=101,102,103 |
| Get a detailed list of all clients with IDs 101, 102, and 103 AND whose type is representative or customer |
https://support.example.com/api/command?action=get_connected_clients&id=101,102,103&type=representative,support_customer |
| Get a detailed list, with connection information, of all connected clients |
https://support.example.com/api/command?action=get_connected_clients&include_connections=1 |
| Get a detailed list, with connection information, of all connected representatives |
https://support.example.com/api/command?action=get_connected_clients&type=representative&include_connections=1 |
| Get a detailed list, with connection information, of all connected representatives and support customers |
https://support.example.com/api/command?action=get_connected_clients&type=representative,support_customer&include_connections=1 |
| Get a detailed list, with connection information, of all clients with IDs 101, 102, and 103 |
https://support.example.com/api/command?action=get_connected_clients&id=101,102,103&include_connections=1 |
| Get a detailed list, with connection information, of all clients with IDs 101, 102, and 103 AND whose type is representative or customer |
https://support.example.com/api/command?action=get_connected_clients&id=101,102,103&type=representative,support_customer&include_connections=1 |
