feat: adds finding groups

03-groups/01-viewing-group-information/index.qmd

@@ -0,0 +1,45 @@
+---
+title: 3.1 Viewing Group Information
+---
+
+## Problem
+
+You want to view group information.
+
+## Solution
+
+:::{.panel-tabset group="language"}
+
+## Python
+
+Use the `groups` attribute.
+
+```{.python}
+from posit import connect
+
+client = connect.Client()
+group = client.groups.find_one()
+```
+
+```{.python}
+>>> import json
+>>> print(json.dumps(group, indent=4))
+{
+    "guid": "54ed1e9d-4bee-4797-97a3-f22e990bccfe",
+    "owner_guid": "6ca57cef-186f-4897-9875-d692f97edd5a"
+    "name": "Data Scientists",
+}
+```
+
+## R
+
+
+```{.r}
+# TODO
+```
+
+:::
+
+## Discussion
+
+The `groups` object contains *guid*, *owner_guid*, and *name* field. The *guid* is a globally unique identifier for the group. The *owner_guid* is a reference to the user that created the group. The *name* field is a human readable description of the group.

03-groups/02-finding-groups/index.qmd

@@ -0,0 +1,63 @@
+---
+title: 3.2 Finding Groups
+---
+
+## Problem
+
+You want to find a subset of groups.
+
+## Solution
+
+:::{.panel-tabset group="language"}
+
+## Python
+
+Use the `groups` attribute and use the `prefix` parameter to filter groups by group name. The prefix is case insensitive (.e.g, "PoSiT" is logically equivalent to "pOsIt").
+
+```{.python}
+from posit import connect
+
+client = connect.Client()
+groups = client.groups.find(prefix="data")
+```
+
+The `groups.find()` method returns a list of groups whose name matches the `prefix` parameter.
+
+```{.python}
+>>> import polars as pl
+>>> pl.DataFrame(groups)
+shape: (2, 3)
+┌─────────────────────────────────┬─────────────────────────────────┬─────────────────┐
+│ guid                            ┆ owner_guid                      ┆ name            │
+│ ---                             ┆ ---                             ┆ ---             │
+│ object                          ┆ object                          ┆ str             │
+╞═════════════════════════════════╪═════════════════════════════════╪═════════════════╡
+│ 6d77fcab-92b0-48a2-94fd-f80c6b… ┆ 867f6d6f-53b4-4ee6-8f37-37ce5d… ┆ Data Scientists │
+│ 85d1ddff-bb05-4d3b-9f5b-37bb20… ┆ fd7b011b-7d07-4b92-8c7a-69279a… ┆ Data Engineers  │
+└─────────────────────────────────┴─────────────────────────────────┴─────────────────┘
+```
+
+## R
+
+```{.r}
+# TODO
+```
+
+:::
+
+## Discussion
+
+You can also use the prefix parameter to find a specific group by name if you do not know the group *guid*. Beware that multiple groups can exists with the same prefix. If this happens, the SDK will only return one group without warning that multiple possible matches exist. Therefore, verifying that group information is correct is important before performing additional actions.
+
+:::{.panel-tabset group="language"}
+
+## Python
+
+```python
+from posit import connect
+
+client = connect.Client()
+group = client.groups.find_one(prefix="Data Scientists")
+```
+
+:::

03-groups/index.qmd

@@ -0,0 +1,15 @@
+---
+title: Groups
+---
+
+## Introduction
+
+Groups are a way to organize users into collections for easier management and access control. Control of group membership depends on how Posit Connect is configured. In some instances, they can be created by administrators. In some cases, they can be synced from external identity providers like LDAP or Active Directory.
+
+3.1 [Viewing Group Information](./01-viewing-group-information/)
+
+3.2 [Finding Groups](./02-finding-groups/)
+
+## See also
+
+- [Group Management](/admin/group-management/)