Groups Management
      Back to home
      1. Tortal Learning Management System Knowledge Base
      2. Admin FAQ
      3. Groups Management

      Group Hierarchy Management Tools

      Overview of the Group Hierarchy Management Tools

      Group Hierarchy Tool - Save Logic Documentation

      Overview

      This document outlines the complete scope of operations that occur when saving changes to group hierarchy relationships in the Group Hierarchy tool within the Edit Group workflow.

      Audience: Client Administrators and Support Agents
      Location: Admin → Groups → Edit Group → Step 3: Group Hierarchy

      What Happens When You Click "Save"

      When you save changes to the Group Hierarchy tool, the system performs a comprehensive series of operations to maintain group relationships and user permissions. The save process handles both Child Groups and Parent Groups tabs.

      1. Initial State Capture (Edit Mode Only)

      When: Only when editing an existing group
      What: The system records all current child and parent group relationships before making changes.

      • Child Groups: Captures all groups currently assigned as children

      • Parent Groups: Captures all groups currently assigned as parents

      • Purpose: This baseline allows the system to identify which relationships are being added or removed

      Note: The system respects your access permissions:

      • Super Admins: Can see all relationships

      • Group Managers: Only see relationships for groups they have permission to manage

      2. Relationship Cleanup (Edit Mode Only)

      When: Only when editing an existing group
      What: Removes all existing parent-child relationships for the target group.

      • Deletes relationships where this group is the parent (child group relationships)

      • Deletes relationships where this group is the child (parent group relationships)

      • Purpose: Prepares a clean slate before adding new relationships

      Important: This cleanup respects your access level:

      • Super Admins: Can delete all relationships

      • Group Managers: Can only delete relationships for groups they manage

      3. Adding New Child Groups

      When: When you assign groups to the "Assigned Child Groups" list
      What: Creates parent-child relationships and automatically propagates permissions.

      3.1 Relationship Creation

      • Creates entries in tblGroupParentChildLink linking the target group as a parent to each child group

      • Prevents duplicate relationships (checks if relationship already exists before creating)

      • Processes all new child groups in a single batch operation for efficiency

      3.2 Permission Propagation (Automatic)

      The system automatically grants group administrator permissions to child groups for users who manage the parent group.

      What happens:

      • Identifies all users who have management permissions for the target (parent) group

      • Grants the same management permissions to each newly assigned child group

      • Tags these permissions with idGroupHierarchy to track they were inherited from hierarchy

      Example Scenario:

      • Parent Group: "Region 1" has admins: User A, User B

      • Action: Assign "District 1" and "District 2" as child groups

      • Result: User A and User B automatically receive management permissions for both "District 1" and "District 2"

      • These permissions are flagged as hierarchy-derived (not direct assignments)

      Important Notes:

      • Only creates permissions that don't already exist (prevents duplicates)

      • Only propagates to users who already have permissions for the parent group

      • If a user already has direct permissions for a child group, the hierarchy-derived permission is not created

      4. Adding New Parent Groups

      When: When you assign groups to the "Assigned Parent Groups" list
      What: Creates parent-child relationships (reverse direction) and propagates permissions.

      4.1 Relationship Creation

      • Creates entries in tblGroupParentChildLink linking parent groups to the target group (which becomes a child)

      • Prevents duplicate relationships

      • Processes all new parent groups in a single batch operation

      4.2 Permission Propagation (Automatic)

      The system automatically grants group administrator permissions to the target (child) group for users who manage the parent groups.

      What happens:

      • Identifies all users who have management permissions for each newly assigned parent group

      • Grants management permissions to the target group for those users

      • Tags these permissions with idGroupHierarchy to track the specific parent group that granted the permission

      Example Scenario:

      • Target Group: "District 1" (currently being edited)

      • Action: Assign "Region 1" and "Region 2" as parent groups

      • Parent Group Admins:

        • "Region 1" has admins: User A, User B

        • "Region 2" has admins: User C

      • Result: User A, User B, and User C automatically receive management permissions for "District 1"

      • Each permission is tagged to track which parent group granted it

      Important Notes:

      • Only creates permissions that don't already exist

      • If a user already has direct permissions for the target group, the hierarchy-derived permission is not created

      • Permissions are tracked per parent group (you can see which parent group granted each permission)

      5. Removing Permissions for Removed Child Groups (Edit Mode Only)

      When: When you remove groups from the "Assigned Child Groups" list
      What: Cleans up hierarchy-derived permissions that are no longer valid.

      What happens:

      • Identifies child groups that were previously assigned but are now removed

      • Removes all permissions that were created for users of the parent group on those child groups

      • Only removes permissions tagged with idGroupHierarchy matching the target group

      • Preserves any direct permissions users may have had (not hierarchy-derived)

      Example Scenario:

      • Previous State: "District 1" was a child of "Region 1"

      • Current State: "District 1" is no longer a child of "Region 1"

      • Action: System removes hierarchy-derived permissions that Region 1's admins had for District 1

      • Result: Region 1's admins lose their management permissions for District 1 (unless they have direct permissions)

      6. Removing Permissions for Removed Parent Groups (Edit Mode Only)

      When: When you remove groups from the "Assigned Parent Groups" list
      What: Cleans up hierarchy-derived permissions that are no longer valid.

      What happens:

      • Identifies parent groups that were previously assigned but are now removed

      • Removes all permissions that were created for users of those parent groups on the target group

      • Only removes permissions tagged with idGroupHierarchy matching the removed parent group

      • Preserves any direct permissions users may have had

      Example Scenario:

      • Previous State: "District 1" had "Region 1" as a parent

      • Current State: "Region 1" is no longer a parent of "District 1"

      • Action: System removes hierarchy-derived permissions that Region 1's admins had for District 1

      • Result: Region 1's admins lose their management permissions for District 1 (unless they have direct permissions)

      7. Bidirectional Relationship Management

      Important: Group relationships are stored bidirectionally to ensure consistency.

      What this means:

      • When Group A makes Group B its child, the system creates entries from both perspectives:

        • Group A → Group B (parent → child)

        • Group B → Group A (child → parent reference)

      • When relationships are deleted, both directions are cleaned up

      • This ensures that viewing either group shows the relationship correctly

      8. Circular Reference Prevention

      Protection: The system prevents creating circular relationships that would cause infinite loops.

      Example of prevented scenario:

      • Group A → Group B (parent → child) ✓

      • Group B → Group C (parent → child) ✓

      • Prevented: Group C → Group A (would create a cycle)

      How it works:

      • Before creating a new relationship, the system checks if it would create a circular reference

      • If a cycle would be created, the relationship is not added

      • An error message may be displayed to inform you of the prevented action

      9. Performance Optimizations

      The system uses several optimizations to handle large group hierarchies efficiently:

      • Change-Only Processing: Only processes groups that were added or removed, not all groups

      • Batch Operations: Groups multiple database operations into single efficient queries

      • Duplicate Prevention: Checks for existing relationships/permissions before creating new ones

      • Compatibility Handling: Supports both modern SQL Server features and legacy database versions

      10. Error Handling

      If any step of the save process fails:

      • Transaction Safety: Database operations are designed to prevent partial saves

      • Error Messages: Clear error messages indicate which operation failed

      • Rollback: Failed operations do not leave the database in an inconsistent state

      • User Notification: You will see an error message indicating what went wrong

      Common Scenarios

      Scenario 1: Adding Your First Child Groups

      1. You assign 3 groups as children

      2. System creates 3 parent-child relationships

      3. All users who manage your group automatically get permissions for those 3 child groups

      4. Permissions are tagged as hierarchy-derived

      Scenario 2: Removing a Child Group

      1. You remove 1 child group from the assignment list

      2. System removes the parent-child relationship

      3. System removes hierarchy-derived permissions for that child group

      4. Users who had only hierarchy-derived permissions lose access; direct permissions remain

      Scenario 3: Changing Parent Groups

      1. You remove "Region 1" as a parent and add "Region 2" as a parent

      2. System removes relationships and permissions related to "Region 1"

      3. System adds relationships and permissions for "Region 2"

      4. Users from Region 1 lose access; users from Region 2 gain access (unless they already had direct access)

      Scenario 4: Adding Multiple Relationships

      1. You assign 10 child groups at once

      2. System processes all 10 in a single efficient batch operation

      3. All permissions are propagated in one operation

      4. Process completes quickly even with large hierarchies

      Support Troubleshooting Guide

      Issue: Permissions not appearing after saving

      Check:

      • Verify the user has permissions for the parent group (for child group propagation)

      • Check if permissions already exist (system doesn't create duplicates)

      • Verify idGroupHierarchy column is being populated correctly

      Issue: Permissions not being removed

      Check:

      • Verify the relationship was actually removed (not just hidden from view)

      • Check if the user has direct permissions (these are not removed)

      • Verify idGroupHierarchy matches the removed parent group

      Issue: Circular reference errors

      Check:

      • Review the entire hierarchy chain for the target group

      • Identify where the cycle would be created

      • Suggest removing an intermediate relationship to break the cycle

      Issue: Performance issues with large hierarchies

      Check:

      • Verify batch processing is working (check database logs)

      • Consider breaking large operations into smaller batches

      • Review database compatibility level for optimization features

      Database Tables Referenced

      • tblGroupParentChildLink: Stores parent-child group relationships

        • idGroup: The main group

        • idChildGroup: A child group

        • idParentGroup: A parent group

      • tblPermissionGroupLink: Stores user-group management permissions

        • idUser: The user

        • idGroup: The group they can manage

        • idGroupHierarchy: (Optional) The parent group that granted this permission via hierarchy

      Additional Notes

      • Audit Logging: All hierarchy changes are logged with before/after group IDs

      • Access Control: Operations respect user permission levels throughout

      • Data Integrity: Multiple validation checks prevent data corruption

      • Scalability: Designed to handle organizations with hundreds of groups efficiently

      Last Updated: [Current Date]
      Feature Version: Group Hierarchy v2.0
      Document Version: 1.0