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:

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:

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:

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

By Department:

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

By Title:

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

SSO Attribute Mapping

Map SSO groups to Twig groups:

{
  "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 - Add/remove users

User Permissions - Role definitions