Consolidating Groups of People - edmozley/freeitsm GitHub Wiki

Consolidating groups of people

Status: parked. Explored, not committed to.

FreeITSM has three reusable groups of people and no two features agree on which of them they accept. This page is what could be done about that, what I would actually do, and — the part that matters — the reasons the obvious fix is the wrong one.

The catalogue of what exists today is Groups of People — Developer Guide. This page assumes it.

The problem, in one table

Consumer	Accepts
Knowledge ACL	`analyst` · `team` · `user` · `user_group`
LMS assignment	`analyst` · `user` · `learning_group` · `user_group` · `all_users`
Module access, RBAC, department visibility, morning-check routing	analyst · team

So:

You cannot assign a course to a team — even though every installation has teams, and "the service desk" is the most obvious group to train.
You cannot give a knowledge folder to a learning group.

Everything except Knowledge and the LMS routes through team. Those two are the newest, they are the two that needed to reach self-service portal users, and each grew its own vocabulary alone.

Nobody has complained. It is a papercut, not a fault — which is exactly why it belongs here rather than on a roadmap.

🔴 Why the obvious fix is wrong

The instinct is "three group tables, make it one". Do not.

A team is not a group with extra fields

teams carries team_modules (module access), rbac_team_roles (capabilities), department_teams (which departments it sees) and can_access_all_tenants. Adding somebody to a team changes what they can do. That is why team management is administrator-only and lives in System.

Merge teams into a generic groups table and you get one of two outcomes, both bad:

every group can carry module access and RBAC roles — so a "Finance" group somebody made to share a folder is now a thing that could hold capabilities; or
a flag says which groups are really teams — which is the same distinction, re-implemented worse, with the safety property now depending on a column nobody validates.

The distinction is doing real work. Erasing it to save a table is a bad trade.

Merging the other two is a silent privilege expansion

Learning groups and people groups look mergeable — neither carries module access. But people groups can grant knowledge folders, and learning groups cannot.

Fold learning groups into people groups and every existing learning group appears in the Knowledge permission picker overnight. Somebody's New Starters group, made years ago purely to assign an induction course, becomes a thing that can be given a restricted folder. Nothing about that is announced, and nothing about it is visible on the screen where the group was made.

🔑 A migration that widens what an existing row can be used for is a privilege change wearing a schema change's clothes.

That is the same class of risk as the rename this codebase already refused — see why knowledge_user_groups must not be renamed.

What I would actually do

Converge the consumers, not the tables. Additive, no migration, and it fixes the thing a user can actually see.

1. Teach the LMS to accept a team

The larger win by far. Every installation has teams; most have no learning groups at all until somebody makes one for this purpose.

Concretely: a team branch in lmsAssignmentReachSql() and lmsAssignedLearnersSql(), plus 'team' in LMS_TARGET_TYPES and one more optgroup in the picker. The assignment table already stores (target_type, group_id), so no schema change at all — this is roughly the same size as the change that added individual targets.

2. Do not teach Knowledge to accept a learning group

This is the asymmetric bit, and it is deliberate.

Learning groups are the weakest of the three: analyst-only, LMS-only, and fully superseded in capability by people groups. Widening their reach entrenches them at the exact moment the goal should be to make them unnecessary. Anybody who wants a folder shared with a training cohort can make a people group, which is better in every respect.

3. Let learning groups wither

Not a migration. A sequence, and each step is optional:

When a course is assigned, offer people groups first in the picker (they already appear; make them the leading option).
Add a one-click "convert to a people group" on a learning group — an administrator action, run deliberately, that copies the membership and leaves the original alone. Never automatic, and never on upgrade.
Only once a release goes by where nothing new is created as a learning group, consider making the option new-only rather than removing anything.

Existing learning groups keep working throughout. There is no version at which somebody's assignments stop reaching people.

4. Separately: fix "department" in the interface, not the schema

Three unrelated things are called department: the ticket-routing table, a free-text HR attribute on analysts and users, and the RFP builder's own list. They will never be reconciled — they genuinely are three different things — but the labels could stop pretending otherwise. "Routing department", "Department (from your directory)", "RFP department". That is a lang-file change and nothing else.

The catch

Convergence makes the vocabulary wider, not narrower. After step 1 the LMS accepts six principal kinds and Knowledge four. The user-visible problem is solved and the underlying inconsistency is larger. Anybody expecting this to tidy the code will be disappointed — it tidies the product.

A shared principal resolver is less useful than it looks. The tempting next move is one principalsFor($actor) helper both modules call. But Knowledge only ever asks the forward question — what does this viewer count as. The LMS asks that and the reverse — who does this assignment reach — and the reverse has no Knowledge equivalent. So a shared helper covers half of one consumer and none of the other's harder half. Two callers is already the bare minimum for an abstraction to pay; half of two is not enough.

Withering has no end date. Step 3 depends on nobody creating learning groups, which is not something anyone controls. It is entirely possible all three groupings still exist in five years. That is an acceptable outcome — it is what "parked" means — but it should not be sold as a plan with a finish line.

And nobody has asked. No issue, no discussion, no report. The whole of this is an internal-consistency argument, which is the weakest kind of argument for spending a release on something.

What would make this worth doing

Somebody asks to assign training to a team. That is step 1 on its own, and it is small enough to do the day it is asked for.
A third consumer needs to accept groups. Two can disagree and be survivable; three cannot, and that is the point at which a shared vocabulary stops being tidiness and starts being necessary.
Somebody is confused by "department" in a way that costs them time. Step 4 is a lang-file change and could go in any release.