{
"record_offset" : 0,
"record_size": 10
}
Search groups
The /groups/search
API endpoint is used to retrieve details about ThooughtSpot groups (referred to as user groups or with the USER_GROUP
value in the API), with many specific filtering capabilities for answering a number of relevant questions about groups.
You can search for the USER_GROUP
type using metadata/search
, but groups/search
provides considerably more control.
The overall structure of groups/search
request is described as a combination of objects.
Note that many parameters in the request are optional, and leaving the parameter name out entirely has a different effect from including the parameter and specific values.
Throughout this article, requests and responses will be shown as JSON, without any of the code to send the requests. The v2.0 Playground generates requests that always include the default values for any parameters that have them, but this article excludes them. Assume every request you see has the following parameters in addition to what is shown:
For precise results, you can set record_size
to -1
and record_offset
to 0
.
Response format🔗
The response from any call to groups/search
will resemble the following:
[
{
"author_id": "59481331-ee53-42be-a548-bd87be6ddd4a",
"complete_detail": true,
"content": NULL,
"creation_time_in_millis": 1354006445722,
"default_liveboards": [],
"deleted": false,
"deprecated": false,
"description": NULL,
"display_name": "System Management Group",
"external": false,
"generation_number": 867825,
"hidden": false,
"id": "179d8867-cf36-4a8d-a019-63a226fd3196",
"index": 3,
"index_version": 867825,
"metadata_version": 0,
"modification_time_in_millis": 1354006445722,
"modifier_id": "59481331-ee53-42be-a548-bd87be6ddd4a",
"name": "System",
"orgs": NULL,
"owner_id": "59481331-ee53-42be-a548-bd87be6ddd4a",
"parent_type": "GROUP",
"privileges": [],
"sub_groups": [],
"system_group": true,
"tags": [],
"type": "LOCAL_GROUP",
"users": [
{
"id": "67e15c06-d153-4924-a4cd-ff615393b60f",
"name": "nick.cooper"
},
...
],
"visibility": "SHARABLE",
"roles": null
}
...
]
Lists of metadata🔗
The /groups/search
API performs listing functions when you do not send specific object IDs as part of your request. Note you must send some request in the body of the POST, even if this is only { }
.
The basic metadata selectors are placed in the metadata
parameter as an array of Metadata List objects.
For example, to see all groups, you can simply send the record_offset
and record_size
parameters:
{
"record_offset": 0,
"record_size": 100000
}
Retrieve specific objects🔗
Several parameters allow referencing a group object directly. The group_identifier
parameter takes either the group name or group GUID:
{
"group_identifier": "Marketing Team"
}
-
display_name
checks against the visible display name that shows within the ThoughtSpot UI. -
description
is also available as a filtering parameter.
Filtering and sorting🔗
sort_options🔗
The sort_options
parameter requires Sort Options to sort on one field of the metadata response either in the ascending (ASC
) or descending (DESC
) order:
{
"sort_options": {
"field_name": "DISPLAY_NAME",
"order": "ASC"
}
}
If you need multiple levels of sorting, you’ll have to parse the response programmatically and apply a sorting algorithm on the properties within each response item.
user_identifiers🔗
You can filter responses based on which users belong to a group.
The user_identifiers
parameter takes an array of strings of either username or user GUID. Note that users have a display_name
property separate from username that cannot be used in the user_identifiers
array.
{
"user_identifiers" : [
"Developers"
]
}
As with other filters that take arrays, the query treats multiple items as a logical OR operation. If you need to identify groups with an exact set of users, you’ll need to process the result and inspect the users
array of each returned group object.
privileges🔗
Responses can be filtered based on privileges assigned to the user. Privileges are assigned through groups directly or via roles on ThoughtSpot instances with the newer roles feature enabled.
The array of privileges works as an OR condition, returning any group with any of the privileges listed. If you need to find a group with a set of privileges, you’ll have to check the privileges
array for each group object in the response.
{
"privileges": [
"DEVELOPER",
"DATADOWNLOADING"
]
}
visibility🔗
Every group has a visibility
property which can either be SHARABLE
or NON_SHARABLE
. A SHARABLE
group can have content shared by users who belong to the same sharable
group.
You can list groups with a specific visibility setting by specifying the visibility
property in the request:
{
"visibility": "SHARABLE"
}
user_identifiers🔗
You can filter responses based on which users belong to a group.
The user_identifiers
parameter takes an array of strings of either username or user GUID. Note that the display_name
property is different from username
and cannot be used in the user_identifiers
array.
{
"user_identifiers" : [
"Developers"
]
}
type🔗
The type
property tracks which authentication method was used to create a given group. The two options are LOCAL_GROUP
and LDAP_GROUP
.
{
"type": "LDAP_GROUP"
}
sub_group_identifiers🔗
Groups in ThoughtSpot can belong to other groups. The sub_group_identifiers
parameter takes an array of strings of either group name or group GUID and returns a list of groups with those sub-groups.
{
"sub_group_identifiers" : [
"A Sub Group Name"
]
}
default_liveboard_identifiers🔗
The default_liveboard_identifiers
parameter filters groups with the specified Liveboards set as default Liveboards for users in that group. The value can take the GUID of a Liveboard or its name, but because Liveboard names are not guaranteed to be unique, it is best to use the GUIDs of any specific Liveboards when using this filtering parameter:
{
"default_liveboard_identifiers":
["a1fdcb4d-9cf9-466b-b866-22c53db9b1ac"]
}
org_identifiers🔗
On a ThoughtSpot instance with Orgs, a user can belong to multiple Orgs.
The org_identifiers
parameter takes an array of strings representing either Org names or Org ID.
As with other filtering parameters that take arrays, the list of identifiers is handled as a logical OR, returning any users who belong to the specified identifiers. To filter the response to get a user that belongs to a particular set of Orgs, you will need to do additional processing on the result set to confirm the full set of Orgs matches:
{
"org_identifiers": [
"Dev",
"UAT"
]
}
The Orgs
key of each user item in the response contains the details of the Orgs, which can be read and compared to the set of Orgs you want to match for that user:
...
"orgs":[
{
"id": 1568202965,
"name": "Dev"
},
{
"id": 2004448319,
"name": "Secondary"
}
]
...
Note that the Org ID is an integer in this portion of the response.
role_identifiers🔗
On ThoughtSpot instances with the Role-Based Access Control(RBAC) feature enabled, you can use the role_identifiers
parameter to send an array of either GUID or the name of the roles to which a given group is assigned.