Groups of People Developer Guide - edmozley/freeitsm GitHub Wiki

Groups of People — Developer Guide

FreeITSM has several things called "group", and they are not the same thing. This page is the map: what each one is, which are groups of people at all, and which features accept which.

Read this before adding another one.

The three reusable groups of people

These are the only three things you can build once and point several features at.

	Table	Holds	Made in	Extra
Team	`teams` + `analyst_teams`	analysts	System → Teams	Carries module access, RBAC roles, department mapping, tenant reach
Learning group	`lms_learning_groups` + `lms_learning_group_members`	analysts	LMS → Groups	Nothing else uses it
People group	`knowledge_user_groups` + `knowledge_user_group_members`	analysts and portal users	Tickets → Users → Groups	Per-member `expires_at`

A team is not just a group. It is a permission-bearing object: team_modules grants module access, rbac_team_roles grants capabilities, department_teams decides which departments it sees, teams.can_access_all_tenants decides its company reach. Adding somebody to a team changes what they can do. That is why team management is administrator-only and lives in System.

A people group is the only one that can hold a portal user. member_type is 'analyst' or 'user', so it is the only grouping that spans both populations. See People Groups.

The knowledge_ prefix on the people-group tables is historical and must not be renamed — see People Groups Developer Guide.

Who accepts what

This is the part that actually matters, and the part that is inconsistent.

Consumer	Stored as	Accepts
Knowledge ACL	`knowledge_acl.principal_type`	`analyst` · `team` · `user` · `user_group`
LMS assignment	`lms_course_assignments.target_type`	`analyst` · `user` · `learning_group` · `user_group` · `all_users`
Module access	`analyst_modules` / `team_modules`	analyst · team
RBAC roles	`rbac_analyst_roles` / `rbac_team_roles`	analyst · team
Department visibility	`department_teams`	team
Morning check routing	`morningChecks_Groups.AssignedTeamID` / `AssignedAnalystID`	analyst · team

The asymmetry, stated plainly

You cannot give a knowledge folder to a learning group.
You cannot assign a course to a team.

Both are perfectly reasonable things to want, and neither is possible. Each consumer grew its own vocabulary at the time it was built, and nothing has since reconciled them.

💭 What to do about that is written up in Consolidating groups of people (parked). Short version: converge the consumers, never the tables — a team is not a group with extra fields, and merging learning groups into people groups would silently widen what every existing learning group can be used for.

Everything else routes through team, which is the de facto standard principal — except the two newest consumers, Knowledge and the LMS, which are the two that needed to reach portal users and so grew their own answers.

Where a group resolves to a principal

Knowledge: knowledgeViewerPrincipals() in includes/knowledge/visibility.php turns a viewer into ["analyst:5", "team:2", "user_group:7"] and matches against knowledge_acl.
LMS: lmsAssignmentReachSql() in includes/lms_access.php builds a WHERE fragment per learner; lmsAssignedLearnersSql() goes the other way.

Both apply the people-group expiry at read time. Nothing sweeps expired rows, so "who had access and until when" stays answerable and there is no job to fail.

Not reusable: per-record member lists

These attach a set of people to one record. They are not groups, cannot be reused, and should not become groups.

Table	The list on	Notes
`change_cab_members`	one change	Carries `is_required` and a `vote`
`task_collaborators`	one task	The "Involved" people; carries `is_completed`
`warroom_channel_members`	one channel
`watchtower_item_members`	one analyst's dashboard	Per-analyst, not shared
`rfp_scores`, `rfp_invited_suppliers`	one RFP

This is the right shape for all of them. Each carries per-membership state that only makes sense against that record — a vote, a tick, a score. Hoisting any of them into a reusable group would mean inventing somewhere to put that state.

If you are tempted to add a "group" and your members need per-membership data, you probably want one of these instead.

Not groups of people at all

Two tables are named *_groups and contain no people. Both are easy to trip over when grepping.

process_groups — a coloured box on a Process Mapper diagram. Columns are x, y, width, height, colour. Nothing to do with people.
morningChecks_Groups — a group of checks, not of people. It has AssignedTeamID / AssignedAnalystID, so it routes to people, but its members are checks.

Things that group people without being groups

Concept	What it is	Watch out for
Company / tenant	`tenants`, plus `tenant_id` on people and records	An axis of visibility, not a group you assign to. `analyst_tenant_access` says which companies an analyst can reach.
Department (the table)	`departments` + `department_id` on tickets	A ticket-routing category. Teams see departments via `department_teams`.
Department (the column)	`analysts.department`, `users.department` — free text	An HR attribute, often directory-synced. 🔴 Completely unrelated to the `departments` table. Same word, two meanings, no link between them.
RFP department	`rfp_departments`	A third thing called department, local to the RFP builder.
Role	`rbac_roles`	A group of capabilities, not of people. Granted to analysts and teams.

🔴 "Department" is the most overloaded word in the schema. Three unrelated meanings. If you are writing anything that touches one, say which.

Choosing, when you add a feature

Does it need to reach portal users? Then it must accept a people group (or an individual user). Nothing else can hold one.
Is it about what somebody may do? Then it is teams and RBAC roles, not a new group.
Does membership carry state — a vote, a tick, a score, an expiry that only means something here? Then it is a per-record list, not a group.
Otherwise, accept the existing principals. Store (type, id) the way knowledge_acl and lms_course_assignments do, and resolve through the module's own helper.

Do not add a fourth reusable grouping. The people-group table exists precisely because the third one was about to be created, and it already spans both populations.