ORGONAUT
Login Signup
Docs
Org model
Departments and department types

Departments and department types

Departments provide stable structure for planning, reporting, and governance.

Department types provide taxonomy so views and filters stay meaningful at scale.

What you can edit on a department

Use Add Department from the Departments list, Charts/Org Units menu, scenario add menu, or department detail page to open the department form in a wide modal without leaving the current screen.

Use Edit Department or a row-level Edit action to open the same form in a modal. Dedicated /departments/create and /departments/{department}/edit pages are no longer supported; direct visits to those URLs return 404. Store and update submissions remain available behind the modal workflow.

In the department form, you can set:

  • name
  • department type (required)
  • parent department/org unit (optional)
  • cost center (optional)
  • lead actor (optional)
  • active/inactive status
  • description in Advanced (optional)

Where department types are managed

  • Settings page: /settings/department-types

Types are tenant-scoped labels used for consistent categorization in charts, matrix, and reporting.

How parent placement works

Department hierarchy is not stored as parent_department_id.

Instead, the parent relationship is maintained by the linked org unit node. This keeps department hierarchy aligned with the canonical org tree.

Department lead and membership are different

  • lead_id indicates leadership ownership metadata.
  • Actual department membership comes from placements (org_unit_actor), not from lead or legacy foreign keys.

Scenario behavior

Department changes are context-aware:

  • in Live View, edits affect baseline
  • in scenario context, edits stay inside that scenario until promotion
  • in archived/snapshot contexts, editing is blocked

Good practices

  • define a small, stable set of department types
  • keep naming normalized (Engineering vs multiple variants)
  • use status/inactive flags rather than deleting historical structure too early
  • validate parent placement after restructures in charts view

Common mistakes

  • using type labels as hierarchy (types classify; they do not parent)
  • assuming lead metadata creates placement membership
  • letting duplicate department names drift across scenarios without clear intent

API

Department types are managed via the REST API. All endpoints are tenant-scoped and require the X-Tenant header.

Search department types

Code
GET /api/v1/department-types/search?q={term}

Requires departments.read ability. Returns up to 20 matching types ordered by display order then name. Omit q to return all types.

Create a department type

Code
POST /api/v1/department-types

Requires departments.create ability.

Field Type Required Notes
name string yes Max 120 chars. Must be unique within the tenant.
slug string no Auto-derived from name if omitted.
color string no Hex colour code with or without leading #.
description string no Max 500 chars.

Show a department type

Code
GET /api/v1/department-types/{id}

Requires departments.read ability. Returns 404 if the type belongs to another tenant.

Update a department type

Code
PATCH /api/v1/department-types/{id}

Requires settings.manage ability. All fields are optional for partial updates.

Field Type Notes
name string Max 120 chars. Must be unique within the tenant.
slug string Max 120 chars. Must be unique within the tenant.
color string Hex colour code.
description string Max 500 chars.
is_active boolean Controls whether the type appears in selectors.
display_order integer 0–999. Controls sort order.

Delete a department type

Code
DELETE /api/v1/department-types/{id}

Requires settings.manage ability. Returns 204. Associated departments will have their department_type_id set to null.