> For the complete documentation index, see [llms.txt](https://help.resouris.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.resouris.com/manage-people/reporting-structure-tool.md). # Reporting-structure tool Practical walk-through of the v1.7.2 P37 Cohort B roster-area-admin org-chart tool at `/ui/admin/reporting-structure`. One audience: * **Roster area admins** (any user holding the `roster_area_admin` role, MIG-096) — view the current reporting tree for any manager in the tenant, then bulk-reassign that manager's subordinates to a different manager in one shot. Requires **no new permission** — the tool reuses the existing `roster_area_admin` role check. Adding or removing single line-management relationships still happens per-worker via the Staff-edit **Details** tab (v1.6.8 P33.B1) with `admin.staff.edit`. *** ## When to use this tool The bulk-reassign flow closes the "John got promoted; move his 5 subordinates to Steven" gap. Before v1.7.2 that operation required opening each of the 5 subordinates' Staff-edit pages one-by-one. This tool does it in a single gesture with a preview. Common triggers: * A manager is promoted; a peer or newly-hired manager takes their team. * A manager leaves the trust; their subordinates get a temporary parent while the vacancy is filled. * Departmental reshuffle: a team moves under a different clinical lead. ## View the reporting tree 1. Sign in and open **Roster area admin → Reporting structure** from the sidebar. 2. Under **Chart root**, pick any current manager. The chart re-renders as a top-down tree rooted at that person. 3. Click the arrow `→` next to any name to re-root the chart on that person (drills down into a subtree). The tree shows every current line-management relationship the P33 MIG-171 spell table currently holds. A numeric badge next to any name shows their direct-report count. Deeper hierarchy shows via indent. Empty state: if no line-management relationships exist yet (no rows in `staff_line_management` with `effective_until IS NULL`), the page shows a hint pointing at the Staff admin page. Assign a manager to one worker there and the chart populates. ## Bulk-reassign subordinates 1. Scroll to the **Bulk-reassign subordinates** card below the chart. 2. **Source manager** — pick the manager whose subordinates you want to move. Defaults to the current chart root (usually what you want after focusing). 3. **Target manager** — pick the manager who'll receive the subordinates. 4. **Effective from** — optional; defaults to today. Same-day cutover: old spells close and new spells open on this date. 5. Click **Preview** to see which rows will move. Preview highlights the affected direct-report nodes with a pending state. **Preview only works when the chart is rooted at the source manager** — if it isn't, the preview status will tell you to re-root first. 6. Click **Confirm reassign**. A browser confirmation prompt appears; confirm to commit the operation. After Confirm the page reloads focused on the new manager with a success flash: "Reassignment complete: N subordinate(s) moved (M skipped due to current-manager mismatch)". ### What happens under the hood Per reassigned subordinate: * The current line-management spell (`staff_line_management` row where `subordinate_staff_id = X AND effective_until IS NULL`) is closed with `ended_reason = 'reassigned'` and `effective_until = `. * A new spell opens on the same day (`effective_from = `) under the target manager. * A `line_management.reassigned` audit event is emitted for that spell with a `correlation_id` payload field linking it to the aggregate event below. Once all per-spell events are emitted, a single **aggregate** `line_management.bulk_reassigned` audit event is emitted with the same `correlation_id`, plus `from_manager_staff_id`, `to_manager_staff_id`, `subordinate_count`, `skipped_count`, `effective_from`, and `via = 'ui'`. The auditor can query by `correlation_id` to see every subordinate touched by one bulk gesture. ### Refusals The service refuses two classes of moves: * **Self-management** — a subordinate can never be their own manager (F5 lock; already impossible via the picker, only fires if the operator tampers with the form). * **Cycles** — assigning the target as manager of one of the source's subordinates would form a management cycle (X reports to Y reports to Z reports to X). The pre-existing WP-P33 F4 cycle guard walks the target's ancestry chain. On refusal the reassignment is aborted (the transaction rolls back) and the page shows "that move would introduce a management cycle." ### Skipped subordinates If a subordinate's current manager doesn't match the source manager (someone else moved them between when you loaded the chart and when you clicked Confirm), that subordinate is **skipped** — not moved, not raised as an error. The success flash names the skipped count so you can re-check the affected worker via the Staff-edit page. ## Limits + roadmap The v1.7.2 tool ships: * View + focus + bulk-reassign of all direct subordinates of one manager. * Per-spell + aggregate audit events with correlation\_id. * Client-side preview scoped to the chart root. Deferred to v1.7.3 (P38) if you have real operational demand: * **Multi-manager relationships** — currently one manager per subordinate (P33 F2 EXCLUDE constraint). Shared roles + multi-parent DAG rendering are v1.7.3 concerns. * **Per-subordinate editing from the chart** — currently you go back to Staff-edit for single moves; the chart is read-only aside from bulk-reassign. * **Historical view** — currently shows CURRENT relationships only; time-travel to "who reported to whom on 2025-01-15?" ships in v1.7.3. * **SVG edge lines** — current render is a nested list with depth-indent; SVG with lines between parent-child comes with the DAG upgrade. See `docs/phases/v1.7.3-shared-management-and-historical-org-chart-build-plan.md` for the full v1.7.3 shape (currently DRAFT — awaiting ratification). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://help.resouris.com/manage-people/reporting-structure-tool.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.