Skip to content

Organisation Chart on the Portal Developer Guide

Ed Mozley edited this page Nov 21, 2026 · 4 revisions

🛠️ Organisation chart on the portal - Developer Guide

The internals of the portal's Organisation chart (discussion #414). It is the People module's chart, not a copy: the same markup, script and queries (Organisation chart - Developer Guide), asked by a different reader. Read that guide first; this one is only what the portal adds.


1. 📁 Files

File What it does
includes/org_chart_view.php Shared. The chart's markup - sidebar, tree and chart tools, the Mouse and keyboard dialog - as orgChartViewRender($opt). people/org.php and the portal page both call it
assets/js/people-org.js Shared. The script, driven by window.PEOPLE_ORG (see §4)
includes/people.php Shared. The peopleOrg*() queries, which take an analyst id or a PeopleOrgReader (see §3)
assets/css/people.css Shared. Every class is ppl- prefixed, so the portal loads it whole
api/self-service/org.php The portal's endpoint: level, path, branch, context, gaps (departments only), search. No person
self-service/org-chart.php The page: guard, the portal fit (no page padding, full height, phone stacking), then orgChartViewRender()
includes/portal_org_chart.php portalOrgChartAllowed() (who may see it) and portalOrgChartSearch()
self-service/includes/header.php The org_chart nav item, 'cap' => 'org_chart', mapped to the people module
self-service/help.php The org help section, only when $portalNavCap('org_chart')
includes/self_service_settings.php, api/system/self_service_portal.php, system/self-service/index.php The setting
tests/portal-org-chart.php The rules, against a throwaway database

No new table and no new column: two system_settings rows.

2. ⚙️ Settings and who may see it

Key Values
self_service_org_chart off (default) / all / groups. Anything else reads as off
self_service_org_chart_groups Comma-separated directory_groups.ids, checked on save

portalOrgChartAllowed($conn, $userId) fails closed: People switched off, the setting off, not in an active chosen group, or any error - all no. selfServicePortalSettings() caches per request; it takes bool $fresh for tests.

TRAP: three callers, one rule. The nav tab, the page and the endpoint all call portalOrgChartAllowed(); the endpoint is the permission. The page's guard runs before require header.php (after it, header('Location: ...') has nothing to send).

3. 👤 The reader

Every peopleOrg*() function takes int|PeopleOrgReader $analystId and asks only two things of it:

function peopleOrgScope(PDO $conn, int|PeopleOrgReader $reader, string $qualified): array
{
    if (!$reader instanceof PeopleOrgReader) return peopleScope($conn, $reader, $qualified);
    return peopleCompanyMatch($conn, $reader->tenantId, $qualified);   // own company; NULL = Default's
}

function peopleOrgCanSee(PDO $conn, int|PeopleOrgReader $reader, int $userId): bool
{
    if (!$reader instanceof PeopleOrgReader) return analystCanAccessUser($conn, $reader, $userId);
    // ...current, and in the reader's company
}

and peopleOrgShownSql() returns AND x.is_active = 1 for a portal reader whatever $leavers says - so a leaver never appears, not even one with a team (the analyst chart's "gap" exception). With an int, every function behaves exactly as before: tests/people-org.php (94) and tests/people-org-api.php (43) pass unchanged, and people/org.php's rendered markup is identical apart from the cache-buster.

PeopleOrgReader::portal($conn, $userId) reads the user's tenant_id. peopleOrgNodes() leaves company null for a portal reader - it is always their own.

4. 🧩 The script's switches

window.PEOPLE_ORG as each page sets it:

Key People Portal
api api/people/org.php ../api/self-service/org.php
list api/people/list.php ../api/self-service/org.php?action=search (the script adds & when there is already a ?)
personPage (true) false - names are plain text, no Open page
contact (true) false - no contact block in the side panel, so no action=person request
me - the reader's users.id: opened on them, marked You

The page leaves out the Show leavers box and the Gaps (orgChartViewRender(['leavers' => false, 'gaps' => false, ...])); the script copes with both missing - a stand-in leavers box that is never ticked, and action=gaps still read for the department colours.

TRAP: load order. people-org.js calls window.t() as it starts, and the portal loads i18n.js in its footer. So the portal page loads the script from $pageScripts (which the footer prints after i18n), passing the settings through $pageData → window.PAGE.peopleOrg. A <script src> printed by the page itself runs too early and the chart stays empty.

5. 🔎 Search

portalOrgChartSearch(): current people in the reader's company whose preferred name, display name, job title or department contains the text (likeContainsPattern()), 10 at most. A person's email is searched only when they have no name - the case where the email is what the chart shows.

6. 🧪 Tests

FREEITSM_TEST_DATABASE=<throwaway db> php tests/portal-org-chart.php

21 checks inside a rolled-back transaction: the setting (off / everyone / groups, inactive group, none chosen, an unknown value); then the shared queries as the portal reader - a colleague in the manager's team, no leaver even when asked for, a leaver with a team not at the top and their team starting there instead, a nameless person named by email and no other email in the answer, no company on a box, the reader's line from the top, search by name but not by a named person's email, and nobody from another company. On a one-company database the test adds a temporary second company first.

Related pages

FreeITSM

Getting Started

Modules

Multi-tenancy (planned)

Responses to feedback

Blue sky thinking

Bugs resolved

Pull requests

Links

Clone this wiki locally