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

---

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 /dev/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.