# Group Management

User collections for bulk permission assignment.

## What are Groups?

Groups assign permissions to multiple users at once.

**Use cases**:

* Department-based access (Sales, Support, Engineering)
* Role-based access (Managers, Agents, Viewers)
* Project-based access (Project Alpha team, Beta testers)

**Benefits**:

* Add user to group → inherits all group permissions
* Change group permissions → affects all members
* Remove user from group → removes all group permissions

## Create Group

**Location**: Admin → Groups → Create New Group

**Required fields**:

* **Name**: e.g., "Customer Support Team" (unique per org)
* **Description**: e.g., "Tier 1 and 2 support agents"

**Optional fields**:

* **Parent Group**: For hierarchical permissions (dropdown)
* **Auto-Assignment Rule**: Regex for email matching (advanced)

**Steps**:

1. Fill form fields
2. Click **Create Group**
3. Group appears in list (initially 0 members)

**Expected result**: Group ID generated (format: `grp_abc123`), status "Active"

**API equivalent**:

```bash
POST /api/v1/groups
{
  "name": "Engineering Team",
  "description": "All engineers",
  "parent_group_id": null
}
```

## Group Hierarchy

### Parent-Child Relationships

```
Company
├─ Sales
│  ├─ Sales Reps
│  └─ Sales Managers
├─ Support
│  ├─ Tier 1 Support
│  ├─ Tier 2 Support
│  └─ Support Managers
└─ Engineering
   ├─ Frontend Team
   └─ Backend Team
```

**Benefits:**

* Inherited permissions
* Logical organization
* Easier management
* Scalable structure

### Permission Inheritance

```
Parent Group: "Support"
→ Access: "Basic Support Agent"

Child Group: "Tier 2 Support"
→ Inherits: "Basic Support Agent"
→ Additional: "Advanced Support Agent"
```

## Manage Members

### Add Members

**Individual**:

1. Groups → \[Group Name] → Members tab
2. Click **Add Member** button
3. Search by email or name
4. Select user from dropdown
5. Assign role: Member or Manager
6. Click **Add**

**Expected result**: User appears in members list immediately, inherits group permissions on next login/refresh

**Bulk** (CSV import):

1. Members tab → **Import** button
2. Download template CSV
3. Fill: `email,role` (role: `member` or `manager`)
4. Upload CSV
5. Review preview (shows: added, skipped, errors)
6. Confirm import

**Max import**: 1,000 users per CSV

### Remove Members

1. Members tab → find user
2. Click **×** icon
3. Confirm: "Remove \[user] from \[group]?"

**Expected result**: User immediately loses group permissions, but retains individual role permissions

### Member Roles in Group

| Role        | Can use group resources | Can add/remove members | Can modify group |
| ----------- | ----------------------- | ---------------------- | ---------------- |
| **Member**  | ✅                       | ❌                      | ❌                |
| **Manager** | ✅                       | ✅                      | ❌                |

**Note**: Group role separate from user's org-level role (ReadOnly/Train/Configure/Admin)

## Assign Resources

### Assign Agents to Group

**Location**: Groups → \[Group Name] → Agents tab

1. Click **Add Agent** button
2. Select agents (checkboxes, multi-select)
3. Choose permission level:
   * **View & Use**: Query agent only
   * **Edit**: Modify agent config
4. Click **Assign**

**Expected result**: Group members can now access these agents

**Bulk via API**:

```bash
POST /api/v1/groups/grp_abc123/agents
{
  "agent_ids": ["agent_1", "agent_2"],
  "permission": "view_and_use"
}
```

### Assign Data Sources

**Location**: Groups → \[Group Name] → Data Sources tab

Same process as agents. Permissions:

* **View**: See data source details
* **Use**: Query uses this data
* **Edit**: Modify sync settings

## Auto-Assignment Rules

### Rule-Based Assignment

Automatically add users to groups based on attributes:

**By Email Domain:**

```typescript
{
  "rule": "user.email endsWith '@support.company.com'",
  "action": "ADD_TO_GROUP",
  "group": "Support Team"
}
```

**By Department:**

```typescript
{
  "rule": "user.department == 'Engineering'",
  "action": "ADD_TO_GROUP",
  "group": "Engineering Team"
}
```

**By Title:**

```typescript
{
  "rule": "user.title contains 'Manager'",
  "action": "ADD_TO_GROUP",
  "group": "Managers"
}
```

### SSO Attribute Mapping

Map SSO groups to Twig groups:

```typescript
{
  "ssoGroupMapping": [
    {
      "ssoGroup": "Azure-Support-Team",
      "twigGroup": "Support Team",
      "role": "MEMBER"
    },
    {
      "ssoGroup": "Azure-Support-Managers",
      "twigGroup": "Support Managers",
      "role": "MANAGER"
    }
  ]
}
```

Users automatically added/removed as SSO groups change.

## Group Analytics

### Usage Metrics

```
Group: Support Team (45 members)
├─ Queries (30d): 12,450
├─ Avg per Member: 276
├─ Most Used Agent: Support Agent
├─ Accuracy Rate: 89%
└─ Response Time: 1.9s
```

### Performance Comparison

| Group          | Queries | Accuracy | Satisfaction |
| -------------- | ------- | -------- | ------------ |
| Tier 1 Support | 8,200   | 87%      | 4.3          |
| Tier 2 Support | 4,250   | 92%      | 4.6          |

## Troubleshooting

### Group Doesn't Appear When Assigning Agent

**Symptom**: Group missing from dropdown when assigning agent access

**Diagnostic steps**:

1. Admin → Groups → verify group status "Active" (not "Archived")
2. Check group has ≥1 member
3. Verify you have Admin or Configure role

**Fix**: If group archived, click **Unarchive**. If no members, add at least 1 user.

***

### User Doesn't Inherit Group Permissions

**Symptom**: User added to group but can't access group's agents

**Diagnostic steps**:

1. Groups → \[Group Name] → Members → verify user listed
2. Groups → \[Group Name] → Agents → verify agents assigned
3. Have user log out and log back in (permissions cached for 5 minutes)

**Fix**: If user still can't access after re-login, remove and re-add user to group.

***

### Auto-Assignment Rule Not Working

**Symptom**: New users with matching email not added to group (Enterprise SSO feature)

**Diagnostic steps**:

1. Groups → \[Group Name] → Settings → verify Auto-Assignment enabled
2. Check rule syntax: `email.endsWith('@support.company.com')` (exact format)
3. Admin → Logs → filter by "auto\_assignment" → check error messages

**Fix**: Common syntax errors:

* Missing quotes around domain: Use `'@company.com'` not `@company.com`
* Wrong operator: Use `endsWith` not `ends_with`

## When This Doesn't Apply

Groups available on Pro and Enterprise plans only. Free plan users manage permissions per-user.

## Next Steps

[User Management](/product/administration/user-management.md) - Add/remove users

[User Permissions](/product/administration/user-permissions.md) - Role definitions


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.twig.so/product/administration/group-management.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.