Skip to content

Commit cc3dbca

Browse files
jorwoodsclaude
jorwoods
and
claude
committed
docs: add GroupSets section to api-ref.md
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent f4a1003 commit cc3dbca

File tree

1 file changed

+334
-0
lines changed

1 file changed

+334
-0
lines changed

‎docs/api-ref.md‎

Lines changed: 334 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1790,6 +1790,340 @@ job = server.groups.update(group, as_job=True)
17901790

17911791
---
17921792

1793+
## GroupSets
1794+
1795+
Using the TSC library, you can get information about all the group sets on a site, create or delete group sets, and add or remove groups from a group set.
1796+
1797+
The group set resources for Tableau Server are defined in the `GroupSetItem` class. The class corresponds to the group set resources you can access using the Tableau Server REST API. The group set methods are based upon the endpoints for group sets in the REST API and operate on the `GroupSetItem` class.
1798+
1799+
<br>
1800+
<br>
1801+
1802+
### GroupSetItem class
1803+
1804+
```py
1805+
GroupSetItem(name)
1806+
```
1807+
1808+
The `GroupSetItem` class contains the attributes for the group set resources on Tableau Server. The `GroupSetItem` class defines the information you can request or query from Tableau Server. The class members correspond to the attributes of a server request or response payload.
1809+
1810+
Source file: models/groupset_item.py
1811+
1812+
**Attributes**
1813+
1814+
Name | Description
1815+
:--- | :---
1816+
`id` | The id of the group set.
1817+
`name` | The name of the group set. The `name` is required when you create an instance of a group set.
1818+
`groups` | The list of groups (`GroupItem`) that belong to this group set.
1819+
`group_count` | The number of groups in the group set.
1820+
1821+
**Example**
1822+
1823+
```py
1824+
new_groupset = TSC.GroupSetItem('My Group Set')
1825+
1826+
# call groupsets.create() with new group set
1827+
groupset = server.groupsets.create(new_groupset)
1828+
```
1829+
1830+
<br>
1831+
<br>
1832+
1833+
### GroupSets methods
1834+
1835+
The Tableau Server Client provides several methods for interacting with group set resources, or endpoints. These methods correspond to endpoints in the Tableau Server REST API.
1836+
1837+
Source file: server/endpoint/groupsets_endpoint.py
1838+
1839+
<br>
1840+
<br>
1841+
1842+
#### groupsets.get
1843+
1844+
```py
1845+
groupsets.get(req_options=None, result_level=None)
1846+
```
1847+
1848+
Returns information about the group sets on the specified site.
1849+
1850+
REST API: [Get Group Sets](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_users_and_groups.htm#get_group_sets)
1851+
1852+
**Version**
1853+
1854+
This endpoint is available with REST API version 3.22 and up.
1855+
1856+
**Parameters**
1857+
1858+
Name | Description
1859+
:--- | :---
1860+
`req_options` | (Optional) You can pass the method a request object that contains additional parameters to filter the request. Filter parameters can include `page_size` and `page_number`.
1861+
`result_level` | (Optional) Specifies the level of detail in the response. Can be `"members"` to include member groups, or `"local"` for local group sets only.
1862+
1863+
**Returns**
1864+
1865+
Returns a list of `GroupSetItem` objects and a `PaginationItem` object.
1866+
1867+
**Example**
1868+
1869+
```py
1870+
all_groupsets, pagination_item = server.groupsets.get()
1871+
for groupset in all_groupsets:
1872+
print(groupset.id, groupset.name)
1873+
```
1874+
1875+
<br>
1876+
<br>
1877+
1878+
#### groupsets.get_by_id
1879+
1880+
```py
1881+
groupsets.get_by_id(groupset_id)
1882+
```
1883+
1884+
Returns information about the specified group set.
1885+
1886+
REST API: [Get Group Set](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_users_and_groups.htm#get_group_set)
1887+
1888+
**Version**
1889+
1890+
This endpoint is available with REST API version 3.22 and up.
1891+
1892+
**Parameters**
1893+
1894+
Name | Description
1895+
:--- | :---
1896+
`groupset_id` | The id of the group set.
1897+
1898+
**Returns**
1899+
1900+
Returns a `GroupSetItem` object.
1901+
1902+
**Example**
1903+
1904+
```py
1905+
groupset = server.groupsets.get_by_id('1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d')
1906+
print(groupset.name)
1907+
```
1908+
1909+
<br>
1910+
<br>
1911+
1912+
#### groupsets.create
1913+
1914+
```py
1915+
groupsets.create(groupset_item)
1916+
```
1917+
1918+
Creates a new group set on the specified site.
1919+
1920+
REST API: [Create Group Set](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_users_and_groups.htm#create_group_set)
1921+
1922+
**Version**
1923+
1924+
This endpoint is available with REST API version 3.22 and up.
1925+
1926+
**Parameters**
1927+
1928+
Name | Description
1929+
:--- | :---
1930+
`groupset_item` | The `GroupSetItem` specifies the group set to add. You first create a new instance of a `GroupSetItem` and pass that to this method.
1931+
1932+
**Returns**
1933+
1934+
Returns the newly created `GroupSetItem` object.
1935+
1936+
**Example**
1937+
1938+
```py
1939+
new_groupset = TSC.GroupSetItem('My Group Set')
1940+
created_groupset = server.groupsets.create(new_groupset)
1941+
print(created_groupset.id)
1942+
```
1943+
1944+
<br>
1945+
<br>
1946+
1947+
#### groupsets.update
1948+
1949+
```py
1950+
groupsets.update(groupset_item)
1951+
```
1952+
1953+
Modifies an existing group set. You can use this method to rename a group set.
1954+
1955+
REST API: [Update Group Set](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_users_and_groups.htm#update_group_set)
1956+
1957+
**Version**
1958+
1959+
This endpoint is available with REST API version 3.22 and up.
1960+
1961+
**Parameters**
1962+
1963+
Name | Description
1964+
:--- | :---
1965+
`groupset_item` | The `GroupSetItem` to update. The group set item must have a valid `id`.
1966+
1967+
**Returns**
1968+
1969+
Returns the updated `GroupSetItem` object.
1970+
1971+
**Example**
1972+
1973+
```py
1974+
groupset.name = 'Renamed Group Set'
1975+
updated_groupset = server.groupsets.update(groupset)
1976+
```
1977+
1978+
<br>
1979+
<br>
1980+
1981+
#### groupsets.delete
1982+
1983+
```py
1984+
groupsets.delete(groupset)
1985+
```
1986+
1987+
Deletes the specified group set from the site.
1988+
1989+
REST API: [Delete Group Set](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_users_and_groups.htm#delete_group_set)
1990+
1991+
**Version**
1992+
1993+
This endpoint is available with REST API version 3.22 and up.
1994+
1995+
**Parameters**
1996+
1997+
Name | Description
1998+
:--- | :---
1999+
`groupset` | The `GroupSetItem` or group set id (`str`) to delete.
2000+
2001+
**Returns**
2002+
2003+
None.
2004+
2005+
**Example**
2006+
2007+
```py
2008+
server.groupsets.delete(groupset.id)
2009+
```
2010+
2011+
<br>
2012+
<br>
2013+
2014+
#### groupsets.add_group
2015+
2016+
```py
2017+
groupsets.add_group(groupset_item, group)
2018+
```
2019+
2020+
Adds a group to the specified group set.
2021+
2022+
REST API: [Add Group to Group Set](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_users_and_groups.htm#add_group_to_group_set)
2023+
2024+
**Version**
2025+
2026+
This endpoint is available with REST API version 3.22 and up.
2027+
2028+
**Parameters**
2029+
2030+
Name | Description
2031+
:--- | :---
2032+
`groupset_item` | The `GroupSetItem` specifying the group set to update.
2033+
`group` | The `GroupItem` or group id (`str`) to add to the group set.
2034+
2035+
**Returns**
2036+
2037+
None.
2038+
2039+
**Example**
2040+
2041+
```py
2042+
all_groups, _ = server.groups.get()
2043+
mygroup = all_groups[0]
2044+
2045+
server.groupsets.add_group(groupset, mygroup)
2046+
```
2047+
2048+
<br>
2049+
<br>
2050+
2051+
#### groupsets.remove_group
2052+
2053+
```py
2054+
groupsets.remove_group(groupset_item, group)
2055+
```
2056+
2057+
Removes a group from the specified group set.
2058+
2059+
REST API: [Remove Group from Group Set](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_users_and_groups.htm#remove_group_from_group_set)
2060+
2061+
**Version**
2062+
2063+
This endpoint is available with REST API version 3.22 and up.
2064+
2065+
**Parameters**
2066+
2067+
Name | Description
2068+
:--- | :---
2069+
`groupset_item` | The `GroupSetItem` specifying the group set to update.
2070+
`group` | The `GroupItem` or group id (`str`) to remove from the group set.
2071+
2072+
**Returns**
2073+
2074+
None.
2075+
2076+
**Example**
2077+
2078+
```py
2079+
server.groupsets.remove_group(groupset, mygroup)
2080+
```
2081+
2082+
<br>
2083+
<br>
2084+
2085+
#### groupsets.filter
2086+
2087+
```py
2088+
groupsets.filter(**kwargs)
2089+
```
2090+
2091+
Returns a list of group sets that match the specified filters. Fields and operators are passed as keyword arguments in the form `field_name=value` or `field_name__operator=value`.
2092+
2093+
**Version**
2094+
2095+
This endpoint is available with REST API version 3.22 and up.
2096+
2097+
**Supported fields and operators**
2098+
2099+
Field | Operators
2100+
:--- | :---
2101+
`domain_name` | `eq`, `in`
2102+
`domain_nickname` | `eq`, `in`
2103+
`is_external_user_enabled` | `eq`
2104+
`is_local` | `eq`
2105+
`luid` | `eq`, `in`
2106+
`minimum_site_role` | `eq`, `in`
2107+
`name` | `eq`, `cieq`, `in`, `like`
2108+
`user_count` | `eq`, `gt`, `gte`, `lt`, `lte`
2109+
2110+
**Returns**
2111+
2112+
Returns a `QuerySet` of `GroupSetItem` objects.
2113+
2114+
**Example**
2115+
2116+
```py
2117+
local_groupsets = server.groupsets.filter(is_local=True)
2118+
for groupset in local_groupsets:
2119+
print(groupset.name)
2120+
```
2121+
2122+
<br>
2123+
<br>
2124+
2125+
---
2126+
17932127
## Jobs
17942128

17952129
Using the TSC library, you can get information about an asynchronous process (or *job*) on the server. These jobs can be created when Tableau runs certain tasks that could be long running, such as importing or synchronizing users from Active Directory, or running an extract refresh. For example, the REST API methods to create or update groups, to run an extract refresh task, or to publish workbooks can take an `asJob` parameter (`asJob-true`) that creates a background process (the *job*) to complete the call. Information about the asynchronous job is returned from the method.

0 commit comments

Comments
 (0)