Search groups

Table of Contents

Response format
Lists of metadata
Retrieve specific objects
Filtering and sorting

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:

{
  "record_offset" : 0,
  "record_size": 10
}

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.