Groups of People Developer Guide

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

1. Does it need to reach portal users? Then it must accept a people group (or an individual user). Nothing else can hold one.
2. Is it about what somebody may do? Then it is teams and RBAC roles, not a new group.
3. 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.
4. 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.

---

See also

• People Groups · developer guide
• Training for Portal Users · developer guide
• Knowledge Folders and Permissions
• Consolidating groups of people — 💭 what to do about the asymmetry above, and why the obvious fix is wrong (parked)
• Roles and Permissions — teams, roles and module access
• Multi-Tenancy — companies as an axis of visibility