Skip to content
English
Customer portal
Contact us
  • There are no suggestions because the search field is empty.

03.04 Organizational Hierarchy

The Organizational Hierarchy Extra adds business units on top of the team model — users select a business unit context, the dashboards and reports filter to that unit, and the Open Risks Dashboard gains a per-business-unit exposure widget.

Requires: Organizational Hierarchy Extra

Business units, the per-user business-unit context, and the business-unit exposure widget on the Open Risks Dashboard are added by the Organizational Hierarchy Extra at simplerisk/extras/organizational_hierarchy/. Without the Extra activated, SimpleRisk has only the team model (see Team-Based Segregation) — flat, no hierarchical grouping.

Why this matters

Organizations larger than a single team often have a business unit layer above teams — a Finance group containing multiple finance-related teams, an Engineering group containing engineering teams, etc. Without the Organizational Hierarchy Extra, SimpleRisk's team model is flat: a list of teams, each independent of the others, with no way to ask "show me everything for the Finance group" without listing every team in Finance individually.

The Organizational Hierarchy Extra adds the business-unit layer. Each team belongs to one business unit; users see a business-unit picker that scopes their view to the selected unit; reports and dashboards aggregate by business unit. For multi-business-unit organizations, the Extra is the operational lever that makes per-unit reporting tractable.

The honest scope to know: the Extra adds business units as a concept, not full organizational hierarchy in the org-chart sense (no parent-child business units, no rollup chains). Each team belongs to exactly one business unit; business units don't nest. Programs needing deeper hierarchical structure work around this with naming conventions ("Finance.Treasury" and "Finance.Accounting" as business unit names that capture the parent-child relationship in their names) or layer on additional custom organization through the Customization Extra.

The other thing worth knowing: activating the Extra has a load-bearing first step — every existing team gets assigned to a Default Business Unit during activation. This is the migration that converts a flat install into a unit-aware install. After activation, you reorganize teams into actual business units; the Default Business Unit is just the starting point that ensures no teams are orphaned.

Before you start

Have these in hand:

  • Admin access to the SimpleRisk install with permission to activate Extras and configure business units.
  • A planned business-unit structure for your organization. Don't activate the Extra and figure out the structure later; the activation produces the Default Business Unit and assigns existing teams to it, and reorganizing afterward is more work than planning ahead.
  • The list of teams currently configured, with a planned mapping of each team to its target business unit.
  • A backup before activating; the Extra creates new tables and modifies team assignments. See Database Backup and Restore.
  • An understanding that the Extra and the Separation Extra are different things. Organizational Hierarchy adds business units; Separation Extra adds fine-grained role-based visibility within teams (see Separation of Duties). The two can coexist; they solve different problems.

Step-by-step

1. Activate the Extra

Sidebar: Configure → Extras opens the Extras list. Find Organizational Hierarchy Extra and click Activate. The activation:

  1. Sets the organizational_hierarchy configuration setting to 'true'.
  2. Creates the database tables: business_unit, business_unit_to_team, business_unit_to_template_group.
  3. Creates a Default Business Unit (with its ID stored in default_business_unit_id) and assigns every existing team to it via business_unit_to_team.
  4. Adds the open_business_unit_exposure widget to the available widgets for the Open Risks Dashboard layout.
  5. Writes an audit-log entry recording the activation.

After activation, the Configure → Business Units page (or equivalent) becomes available for managing business units; the per-user business-unit picker appears in the user account UI; reports and dashboards begin filtering by business unit.

2. Define your business units

Sidebar: Configure → Business Units (or the equivalent path the Extra adds). Create the business units that match your organization. Examples:

  • "Finance"
  • "Engineering"
  • "Sales"
  • "Operations"
  • "Corporate IT"

For each business unit, provide:

  • Name — the display label (visible in the user picker, in reports, in dashboards).
  • Description — optional context.

The business unit gets an internal id written to the business_unit table; the operator-facing references are by name.

3. Reassign teams to business units

The Default Business Unit holds every team that existed at activation time. Move teams to their actual business units:

  1. Open the business-unit management UI.
  2. For each team, change its business-unit assignment from Default to the appropriate target unit.
  3. The change updates the business_unit_to_team row for that team.

A team can belong to exactly one business unit; this is a 1:1 relationship from team to business unit. If your team structure doesn't fit the business-unit grouping cleanly, you may need to restructure the teams themselves — splitting a team that genuinely spans business units into per-unit sub-teams, for example.

After all teams are reassigned, the Default Business Unit can typically be deleted (or kept as the catch-all for new teams that haven't yet been assigned). If you delete it, set the default_business_unit_id to a different unit's ID so newly-created teams don't reference a nonexistent BU.

4. Set per-user business unit context

Each user has a selected_business_unit field on their user record. This is the unit they're currently viewing — the dashboards, reports, and lists scope to this unit unless the user explicitly changes context.

The user-facing surface:

  • The user's profile or the dashboard header (depending on theme) shows the current business unit and a picker for changing it.
  • The picker offers the business units the user has access to (via team membership; admins see all units).

For most users, the right pattern is to set their initial business unit to match the unit their primary team belongs to. Users who work across multiple units can switch context as needed.

5. Configure dashboards with business-unit widgets

The Open Risks Dashboard (one of the Risk Management dashboards) gains the open_business_unit_exposure widget when the Extra is active. The widget shows risk exposure broken down by business unit — useful for executive readouts where the question is "which business unit carries the most risk?"

To add the widget:

  1. Open the relevant dashboard at /reports/....
  2. Enter edit mode (the toolbar at the top).
  3. Click Add Widget and select Open Business Unit Exposure.
  4. Position and size the widget; the dashboard saves automatically.

The widget renders per-business-unit exposure based on the risks visible in the user's current view; combined with the business-unit picker, this produces an interactive "show me Finance's exposure, then Engineering's exposure" workflow.

6. Update reporting cadences

If your program runs per-business-unit reporting (a quarterly readout to each business unit's leadership), the Extra makes the per-unit reports straightforward. The reports under Reporting → Reports Hub (see The Built-In Reports) respect the business-unit context; switch the user's business unit context before running a report to scope its output.

For automated per-unit reports, scripted access via the v2 API (with explicit business-unit filtering parameters) is the right pattern; the UI's filtering is interactive.

7. Plan for deactivation (if you ever need it)

If you deactivate the Extra later, the deactivation:

  1. Removes the open_business_unit_exposure widget from all saved dashboard layouts (so user dashboards don't fail to load with a now-unknown widget).
  2. Sets organizational_hierarchy to 'false'.
  3. Leaves the business_unit and business_unit_to_team tables in the database (the data isn't cascade-deleted).
  4. Reverts the application's behavior to flat-team mode — the business-unit picker disappears, dashboards stop respecting business-unit context, reports run across all teams the user has access to.

The data preservation is intentional; reactivation later picks up where it left off. But the selected_business_unit user records become inert during deactivation, and the per-unit dashboards aren't available.

Common pitfalls

A handful of patterns recur with the Organizational Hierarchy Extra.

  • Activating without a planned structure. The Extra activates with all teams in a single Default Business Unit. If you don't reassign teams promptly, the install effectively has no business-unit segregation — every team is in the same unit, so per-unit filtering returns the same data for every unit. Plan the structure before activating.

  • Trying to model deep hierarchies. Business units don't nest in this Extra. Programs that need a multi-level hierarchy (Finance → Treasury → Investment Operations) end up using either naming conventions or custom modeling via the Customization Extra. Confirm the depth you need before activating.

  • Confusing business units with teams. Teams are the unit of access control (who can see what risks); business units are the organizational layer above teams. A user in a team belongs (transitively) to the business unit that team is assigned to. Don't try to use business units as a substitute for teams; they answer different questions.

  • Forgetting to update default_business_unit_id after deleting the Default Business Unit. If you delete the Default BU, the default_business_unit_id setting still points at it. Newly-created teams reference a nonexistent BU, which produces confusing behavior. Set the setting to a real BU's ID after deleting the default.

  • Activating without backup. The activation creates new tables, modifies team assignments, and writes to user records. A backup taken before activation gives you the rollback path. Without it, undoing the activation is more work than necessary.

  • Treating the business-unit context as authoritative for permissions. Business units affect what reporting and dashboards show; they don't change what the user can do. A user with submit_risks permission can still submit risks regardless of which business unit context they've picked. The permission check is independent.

  • Not coordinating with the Separation Extra. Both Extras affect what users see. The Organizational Hierarchy Extra filters by business unit context; the Separation Extra filters by role and team membership. With both active, the visible-records set is the intersection of the two filters. This is the right behavior for serious access-control programs but produces "I can't see this thing" puzzles when not understood. Document which Extra is doing which filtering.

  • Letting users' selected_business_unit drift from operational reality. If a user changes role and moves to a different business unit, their selected_business_unit doesn't auto-update. The dashboards keep showing the old unit's data until the user manually switches context. Include the business-unit context check in user-management workflows (when reassigning a user's primary team, also update their selected_business_unit).

Related

Reference

  • Permission required: check_admin for activating the Extra and configuring business units. Per-user selected_business_unit is settable by the user themselves (within their team-derived options).
  • API endpoint(s): None specific to the Extra in the Core v2 API documentation; business-unit filtering may apply implicitly to risk/asset/compliance API calls when the Extra is active.
  • Implementing files: simplerisk/extras/organizational_hierarchy/index.php (the enable_organizational_hierarchy_extra(), disable_organizational_hierarchy_extra(), get_available_business_units(), assign_teams_to_default_business_unit() functions); simplerisk/extras/organizational_hierarchy/upgrade.php (schema migrations).
  • Database tables: business_unit (id, name, description); business_unit_to_team (composite PK on business_unit_id + team_id); business_unit_to_template_group (composite PK on business_unit_id + template_group_id).
  • config_settings keys: organizational_hierarchy (boolean — Extra activation); default_business_unit_id (the BU created during activation, holds teams that haven't been reassigned yet). User table: selected_business_unit (per-user current context).
  • Dashboard widgets: open_business_unit_exposure (added to the Open Risks Dashboard's available widget list when the Extra is active).
  • External dependencies: None.