Distribution Groups

introduction this document provides comprehensive documentation for the distribution groups feature distribution groups are fundamental to managing targeted communications and notifications within the system they function as curated contact lists, ensuring that the right individuals receive relevant information based on their roles, responsibilities, or location affiliations this feature incorporates a robust system of defaults and customization system level defaults pre configured groups are established at the highest administrative level (referred to as "commandit"), serving as a baseline for all organizations organizational customization managed service providers (msps) and direct customers can tailor these groups to meet their specific needs or the needs of their clients customization employs a "copy on write" mechanism, preserving the integrity of the original system defaults this document details the concept, hierarchical structure, customization workflow, user interface interactions, and the underlying database schema associated with distribution groups overview of distribution groups at its core, a distribution group is simply a named list of contacts designated to receive specific notifications or communications generated by the system (e g , alerts, reports, incident updates) key concepts system defaults (commandit level) the system defines a standard set of distribution groups these are identified in the database by having a null value in the organization id field they act as the foundational templates inheritance & customization customers with no parent msp these organizations inherit the system level defaults directly they can use them as is or choose to customize them managed service providers (msps) msps also inherit the system level defaults but typically customize them extensively to manage communications for their various clients copy on write mechanism when an organization (msp or customer) modifies a distribution group (e g , renames it, adds/removes contacts, deletes it), the system does not alter the original system level group instead, it creates a new record specifically for that organization, marked with their unique organization id this ensures organizational autonomy and protects the system defaults protected system groups certain crucial system level groups, like the major incident stakeholders group, are flagged as non editable and non deletable ( is editable = false ) this protection is vital because these groups are often tied to critical automated system functions (e g , triggering notifications when a high priority "major incident" ticket is created) hierarchical structure and assignment distribution groups leverage the system's organizational and location hierarchy to enable highly targeted communication this structure allows groups to be defined or assigned at various levels, ensuring messages reach the appropriate audience based on scope typical hierarchy example commandit (system level organization id is null) defines system wide default groups managed service provider (organization organization type = "msp") can customize system groups or create new ones specific to their operations manages client company #1 (organization organization type = "client") can inherit groups from msp/commandit or have custom groups defined by the msp or themselves location #1 (e g , hq) groups can be assigned here for location specific comms building #1 groups can be assigned here wiring closet a highly specific groups can be assigned here or customer without parent msp inherits commandit settings directly unless customized follows a similar location hierarchy as clients under an msp assignment flexibility distribution groups can be associated with any level in this hierarchy, from the top level organization down to the most granular sub location, providing precise control over notification delivery key features explained system level groups (defaults) purpose provide a consistent baseline set of communication groups across the entire system identification defined by a null organization id in the database protection mechanism critical system groups (e g , major incident stakeholders ) are marked with is editable = false this prevents accidental modification or deletion that could disrupt essential system processes like automated incident notifications organizational customization mechanism utilizes a "copy on write" approach when an msp or customer admin modifies a default group, a new group record is created linked to their organization id benefits preserves defaults system level templates remain untouched and available for other organizations or future reference tailored communication allows each organization to adapt groups (membership, naming) to their specific structure and needs autonomy empowers organizations to manage their communications independently inheritance organizations initially see and can use the system level defaults customization overrides the default for that specific organization multi level hierarchy support scope distribution groups can be assigned contextually based on the organizational and location hierarchy granularity allows for broad communication (e g , all users in an organization) or highly specific communication (e g , network team contacts for a specific wiring closet) nesting the parent group id field allows for creating nested distribution groups, enabling complex relationship modeling (e g , a "regional it" group containing "site a it" and "site b it" sub groups) this supports an theoretically infinite depth of nesting for sophisticated communication structures common use cases & system behavior this table illustrates how common actions affect distribution group records action performed by organization id involved resulting system state view default groups any user n/a (viewing null org id) ui displays system level groups groups flagged is editable = false appear read only rename a default group msp / customer it admin their org id a new group record is created with the user's organization id and the new name the original system level group (with null org id) remains unchanged add contacts to a group msp / customer it admin their org id if modifying a default group, a new record is created under the user's organization id with the added contacts if modifying an existing custom group owned by the org, that record is updated delete a default group msp / customer it admin their org id if a customized copy exists for their org, that copy is deleted the original system level group (with null org id) remains untouched and visible if deleting a group created by the organization, it is removed delete a protected group any user n/a action is disallowed by the ui/backend because is editable = false system level protected groups cannot be deleted create a new custom group msp / customer it admin their org id a new group record is created directly under the user's organization id it is not linked to a system level default user interface (ui) flow initial view when accessing the distribution groups page, the ui displays a consolidated list this list includes system level default groups ( organization id = null ) any custom groups already created by or for the user's organization ( organization id matches user's org) system groups marked as non editable/non deletable ( is editable = false ) will have editing/deleting controls disabled or hidden editing/customizing when an administrator (msp or customer it) selects a system level group and initiates an edit (e g , clicks "rename," "add contact," or "delete") the system intercepts this action it creates a new distribution group record associated with the administrator's organization id the specific change (rename, adding contacts) is applied to this new record if the action was "delete", the customized copy is deleted (if it exists); the system default remains if editing a group already customized or created by the organization, the changes are applied directly to that existing organizational record assignment distribution groups (both system level and custom) can be associated with entities within the organization/location hierarchy (e g , assigning a "building maintenance" group to a specific building record) this assignment dictates which group receives notifications related to events or items linked to that specific hierarchical entity database table structure distributiongroups table this table stores the definitions for all distribution groups within the system (note uuid/int indicates the data type might be a universally unique identifier or an integer depending on the specific database implementation ) column name data type constraints description group id uuid/int primary key, not null unique identifier for each distribution group record organization id uuid/int nullable, foreign key identifier of the organization that owns this specific group record if null , this is a system level (commandit) default group parent group id uuid/int nullable, foreign key identifier of the parent group, enabling hierarchical nesting of groups null indicates a top level group name varchar not null the display name of the distribution group (e g , "network admins," "site contacts") description text nullable optional field for providing more context or details about the group's purpose or membership criteria is editable boolean not null, default true flag indicating if the group can be modified or deleted set to false for protected system level groups (where organization id is null ) created at timestamp not null, default now() timestamp indicating when the group record was initially created updated at timestamp nullable timestamp indicating the last time the group record was modified null if never updated example database entries 1\ system level protected group group id organization id parent group id name description is editable created at updated at sys 001 null null major incident stakeholders critical group notified on major incidents via system automation false 2025 01 10 08 00 00 null 2\ customized group for an organization (e g , msp) (this might be a copy of a system default, now customized) group id organization id parent group id name description is editable created at updated at cust 101 org abc null alpha msp it support primary it support contacts for alpha msp internal operations true 2025 04 01 10 30 00 2025 04 01 11 15 00 3\ custom group created by an organization group id organization id parent group id name description is editable created at updated at cust 102 org xyz null client beta onboarding contacts involved in onboarding client beta project true 2025 03 15 14 00 00 null