Spark ERP Docs

Appearance

HCM Roles & Permissions (HCM) ​

This page documents the shipped HCM Roles & Permissions screen (hcm-foundation), for HR administrators managing who can do what inside the HCM application — not for plugin developers. If you're building a page like this one for your own plugin, see Add your own app-owned roles & permissions instead.

Who this page is for: whoever holds the HCM Administrator role. Anyone can open this page and browse the list of roles, but making any change — creating, editing, turning a role on/off, archiving, cloning, assigning it to someone, granting/removing a permission, bulk actions, exporting — needs the HCM Administrator role. If you try one of these without it, you'll see a clear "administrator role required" message.

This page manages roles that only apply inside HCM — it's separate from the company-wide Roles Studio designer, which manages a different, broader set of roles.

Getting there ​

/app/hcm/administration/hcm-foundation/hcm-roles-permissions (under HCM's Administration menu).

The list ​

A grid of every role defined in this tenant's own HCM installation, with:

  • Role name and code
  • Type — SYSTEM, STANDARD, CUSTOM, APPLICATION, POSITION, or APPROVAL
  • Status — DRAFT, ACTIVE, INACTIVE, or ARCHIVED (color-coded chip)
  • Permissions count and Users count
  • System flag — a small set of built-in roles (like the HCM Administrator role itself) are marked system roles and can't be archived

Use the column filters to narrow by type or status. Select multiple rows to Activate or Deactivate them in bulk — you'll get a confirmation dialog naming the action and how many roles it affects before anything happens.

Export downloads the current role list as a CSV (admin-only, same as every mutation). There's no matching import yet — the platform's own file-upload block can't hand a page raw file bytes to send onward yet, so this is a one-way capability for now.

Creating a role ​

New Role opens a dialog: Name and Description (required), Role Type, and an optional Parent Role ID — set this to make the new role inherit another role's permissions on top of its own (see Role hierarchy below). There's also an Administrator role toggle; turning it on makes the new role itself is_admin — grant this carefully, since anyone assigned it gets full control of this page.

The role detail view ​

Click any row to open its detail panel, with four tabs:

Overview ​

The role's own fields (name, code, description, type, status), whether it's a system role, whether it's an administrator role, and how many users currently hold it. From here:

  • Activate / Deactivate — flips the role's status. A deactivated role stops granting access immediately — anyone holding only that role loses whatever it granted the moment it's deactivated, not on their next login.
  • Archive — the closest thing to deleting a role. Not offered for system roles.
  • Clone — makes a copy of the role (all its permissions, none of its assigned users) under a new name you choose, for when you want a near-identical role without rebuilding it from scratch.

Permissions ​

The role's effective permissions — its own grants plus anything inherited from a parent role (see Role hierarchy), each one showing whether it was inherited and from where.

Users ​

Everyone currently assigned this role.

Audit History ​

A real log of every change made to this role — created, activated, deactivated, archived, cloned, permission granted/revoked, and who did it and when — pulled from the platform's own audit trail.

Role hierarchy — one role can build on another ​

Setting a Parent Role when you create a role means the new role automatically gets everything the parent role can do, on top of its own permissions. You can chain this up to 10 levels deep (a role's parent can have its own parent, and so on).

This isn't just a label in the UI — it's checked for real every time someone tries to do something. So if you turn off a parent role, or remove one of its permissions, everything that inherits from it loses that access right away.

Known gaps ​

  • No CSV import — export only; see above.
  • Reparenting an existing role (changing its parent after creation) has a real backend endpoint but isn't wired to any button on this page yet.
  • Audit search is a substring match, not an exact role-id match — so a search for role id 5 can also surface unrelated entries mentioning 15 or 50 in passing. A known, accepted precision trade-off, not a bug.
  • The very first HCM Administrator can't be created from this page — every action on this page needs an administrator to already exist, so there'd be no way to create the first one here. Instead, whoever already holds your company's own "Tenant Owner"/"Tenant Admin" role is automatically given the HCM Administrator role the first time HCM is set up. If nobody on your tenant has HCM Administrator and you're stuck, that's the thing to check.
  • Add your own app-owned roles & permissions — the developer-facing guide, if you're building a similar page.