Retiring is_rcpch_audit_team_member and is_rcpch_staff¶
This is the plan for replacing the two NPDAUser boolean flags with permissions attached to the npda_audit_team_full_access group, which every user with the RCPCH Audit Team role belongs to. Code checks those permissions with has_perm, never group membership.
How the code works now¶
- Two separate systems. The
RCPCH_AUDIT_TEAMrole (4) puts a user in thenpda_audit_team_full_accessgroup (general_functions/group_for_group.py). The two booleans are set on their own, and about 70 non-test call sites check them directly. - They can disagree. The model comments say an audit team member can also be a clinician. So a Coordinator with
is_rcpch_audit_team_member=Truegets national access without the role or group. This is the main migration risk (see Phase 0). - Group membership is derived from role.
NPDAUserUpdateView.form_validclears a user's groups and re-addsgroup_for_role(role). Any extra group is lost on the next edit, so role must be the single source of truth. - Superuser checks get simpler.
has_perm()is always True for an active superuser, so everyis_superuser or flagbecomes a singlehas_perm(...).
Decisions¶
- Flagged users without the role: their role is changed to RCPCH Audit Team.
is_rcpch_staff-only users: they gain full audit team access. This is accepted.- Alert on joining the audit team: add an
m2m_changedhandler onNPDAUser.groupsthat sends the existing admin notification when a user is added tonpda_audit_team_full_access. This replaces the email currently sent when a flag changes.
New permissions¶
Define each in project/constants/user.py, add it to PERMISSIONS and to the model's Meta.permissions, and attach it only to the audit team group.
| Permission | Model | Replaces the flag checks in |
|---|---|---|
can_access_all_pdus |
PaediatricDiabetesUnit |
PaediatricDiabetesUnitManager.get_pdu_for_request, mixins.py patient/visit PK check, organisations_adapter.py, home.new_home inactive PDUs, get_user_home_page, NPDAUserListView.get_queryset, submissions.py list and get_submission_checking_permission, the employer_match and include_admin_users template tags, submission_history.html, submission_employer_selector.html, submissions_list.html, NPDAUpdatePasswordForm.is_admin (16-character passwords) |
can_manage_inactive_pdus |
PaediatricDiabetesUnit |
Adding users or employers to inactive PDUs (npda_users.py) |
can_view_hidden_audit_periods |
AuditPeriod |
AuditPeriodManager.get_audit_period_for_request, home.new_home, context_processors.get_audit_periods_user_can_see |
can_edit_closed_audit_periods |
AuditPeriod |
CheckCurrentAuditYearMixin, AuditPeriod.is_allowed_to_edit, the CSV upload closed check |
can_override_data_upload_rules |
Submission |
QuestionnaireContextMixin, CheckCanCompleteQuestionnaireMixin, switch-to-questionnaire / switch-to-csv, patient_table_actions.html |
can_manage_users_in_any_pdu |
NPDAUser |
Cross-PDU user creation, npda_user_employers, activate/deactivate, get_readonly_fields |
can_assign_rcpch_audit_team_role |
NPDAUser |
The role == RCPCH_AUDIT_TEAM guards on create/update, show_rcpch_team |
can_reset_user_two_factor |
NPDAUser |
The reset-two-factor branch |
can_preview_features |
NPDAUser |
home.feature_flags, avatar_dropdown.html |
No new permission needed for banners: use Django's built-in view_banner permission in place of the flag check in the context_processors banner targeting, and add view_banner to the audit team group in Phase 1.
Keep the existing protections for superusers: an audit team member still can't change a superuser's email or reset their 2FA. Write these as has_perm(...) and not target.is_superuser.
Phases¶
Phase 0 – data audit (before any code change)¶
Run the read-only report:
python manage.py audit_rcpch_user_flags
python manage.py audit_rcpch_user_flags --active-only
python manage.py audit_rcpch_user_flags --csv --output rcpch_flags_report.csv
It lists users with any of these findings:
flag_without_role: a flag is set but the role is not RCPCH Audit Team. Phase 1 changes their role. Check each one is meant to have national access, and remove the flag instead if not.staff_flag_only:is_rcpch_staffis set withoutis_rcpch_audit_team_member. These users gain full audit team access.role_without_flag: the role is RCPCH Audit Team but a flag is False. These users gain whatever that flag gates.group_mismatch: the user's groups are not exactlygroup_for_role(role).
The command never writes to the database.
Phase 1 – add the permissions and fix the data (additive, safe to deploy)¶
- Add the constants and
Meta.permissionsentries (migration0047_rcpch_audit_team_permissions). - Add the new permissions, and the built-in
view_banner, toRCPCH_AUDIT_TEAM_ONLY_PERMISSIONSingroups_seeder(create_groups.py). - Make
groups_seederidempotent, like E12's: it creates any missing group and adds any missing permission to every group.s/start-prodalready runs it on every deploy (seed --mode=seed_groups_and_permissions), but until now it only gave permissions to groups it created, so new permissions never reached existing groups. It never removes a permission. - The inconsistent users found by Phase 0 were fixed by hand, so no data migration is needed to change roles or re-sync groups.
- Log and email the admins when a user joins
npda_audit_team_full_access(signals.notify_joined_rcpch_audit_team). Group syncs usegroups.set()so re-saving an existing member doesn't trigger it. - Django admin: changing a user's role syncs their group and flags (
NPDAUserAdmin.save_model).groupsis no longer editable there, because the admin saves m2m fields aftersave_modeland would undo the sync.
Why some Coordinators were only in the Editor group: until April 2025 (437a926d) the edit-user view changed role without changing groups, so users promoted from Editor (many created by the March 2025 user import) kept the Editor group. The view has synced groups since; a regression test now covers it. The Django admin could still cause it until this phase.
Phase 2 – switch the checks¶
- Replace each call site in the table with
user.has_perm("npda.<codename>"), orperms.npda.<codename>in templates. - Where code needs to know what a user is rather than what they may do (for example the user table badges and
user_roles()), useuser.role == RCPCH_AUDIT_TEAM. - When the check is about the target user, use role, not
has_perm:has_permis False for inactive users.NPDAUserUpdateView.get_restricted_fieldsdoes this, so a coordinator can't change the email of a deactivated audit team member. - Left for Phase 3, because they read or write the flags themselves: the guards on setting the flags in the user create and update views (now gated on
can_assign_rcpch_audit_team_role), the user table badges,user_roles(),signals.py,create_dev_usersandNPDAUserAdmin.save_model.
Phase 3 – remove the fields¶
- Drop both fields from
NPDAUserand runmakemigrations. - Remove them from
REQUIRED_FIELDS,create_or_update_userandcreate_superuser. - Remove them from:
NPDAUserFormfields and widgets, and theexclude_admin_user_fieldtag (also fix its"id_is_staffid_is_rcpch_staff"typo);- the "can't set this flag" guards in
npda_users.pyandshow_rcpch_staff_box; signals.py(EMAIL_TRIGGER_FIELDS,LOGGED_FIELDS,ADMIN_FLAGS, the role-change notification list and the deletion email). Role changes already trigger both notifications;npda_user_table.htmlbadges.
- Update
create_dev_users,documentation/docs/developer/users.md,testing.md,manual-setup.mdandtests/misc_py_shell_code.py. - Delete the
audit_rcpch_user_flagscommand and its tests.
Phase 4 – tests¶
- Update the factories and fixtures (
NPDAUserFactory,seed_users,UserDataClasses,tests/utils.py), which set the flags directly. - Update
test_patient_model_actions.py,test_mixins_against_session.py,test_npda_user_model_actions.py,test_meta_tests.pyandtest_download_template.py. - Add a test per new permission: the audit team group has it, the other groups don't.
- Run the full suite.
Behaviour changes to sign off¶
- Inactive superusers lose implicit access, because
has_permreturns False for inactive users. The current flag checks don't look atis_active. is_rcpch_staff-only users gain full audit team access (accepted).
Suggested PRs¶
- Phase 0 (this command).
- Phase 1.
- Phase 2.
- Phases 3–4, after Phase 2 has run in production.