Getting Started & Setup
This page walks an administrator through standing up the ERPat Helpdesk module end to end: turning on the master toggle, deciding which support pillars to expose, granting the right permissions to the right people, and confirming that everything shows up where it should. Follow it top to bottom the first time you enable Helpdesk in a tenant.
The setup mental model
Helpdesk is an umbrella module that brings five support pillars — Tickets, Internal Wiki, Knowledge Base, Web Pages, and the Company Handbook — under one roof at modules/Helpdesk/. Whether a user can see and use any given pillar comes down to a single rule that repeats everywhere in the code:
Master toggle vs. per-pillar sub-toggles
There are two layers of toggles, and they are deliberately independent:
- Master toggle — the settings key
module_helpdesk. This is the umbrella switch surfaced in Settings → Manage Modules as Helpdesk (iconfa-life-ring, categoryHelp Center). It is seeded on by a core migration for every tenant, and it is what makes the module's permission rows appear in the Roles editor. The Company Handbook pillar gates directly on this master toggle. - Per-pillar sub-toggles —
module_ticket,module_help,module_knowledge_base, andmodule_page. Each pillar can be turned on or off independently under the master. The Tickets, Internal Wiki, Knowledge Base, and Web Pages controllers each gate on their own sub-toggle (viawith_module()), not on the master.
| Pillar | Module toggle it gates on | Primary permission | Doc page |
|---|---|---|---|
| Company Handbook | module_helpdesk (master) | handbook | Company Handbook |
| Tickets | module_ticket | ticket | Tickets — Lifecycle |
| Internal Wiki | module_help | help | Internal Wiki |
| Knowledge Base | module_knowledge_base | knowledge_base public read | Knowledge Base |
| Web Pages | module_page | page | Web Pages & Help Center |
SOP 1 — Enable the Helpdesk module
- Sign in as an administrator with access to Settings.
- Open Settings → Manage Modules.
- Find the Helpdesk card (category Help Center, life-ring icon) and enable it. This sets
module_helpdeskand immediately makes the module's permission rows available in the Roles editor. - Enable the per-pillar sub-toggles you intend to use:
module_ticket,module_help,module_knowledge_base,module_page. Each pillar's own module entry controls whether that pillar is reachable at all. - Save. The module is defined as
can_disable = true, so you can safely turn it back off later without losing per-tenant data.
Enable the master
Manage Modules → Helpdesk on. module_helpdesk is now enabled for this tenant and the RBAC rows unlock.
Enable each pillar
Flip the sub-toggles for the pillars you want live. Leaving a sub-toggle off keeps that pillar dark even though the umbrella is on.
Grant permissions
Move to Settings → Roles and grant the pillar permits to the roles that need them (SOP 2).
Verify visibility
Impersonate or log in as a granted user and confirm the Help Center sidebar entries appear (SOP 4).
module_helpdesk is seeded enabled by a core migration, but the individual pillar sub-toggles reflect whatever the tenant had before. If a pillar isn't showing after you enabled the umbrella, the pillar's own sub-toggle is almost certainly still off.SOP 2 — Assign permissions (RBAC)
Helpdesk is fully module-owned for permissions: every permission key the module needs is declared in modules/Helpdesk/config/permissions.php and surfaced into the Roles editor by the RBAC UI. These rows appear in Settings → Roles only when module_helpdesk is enabled. Existing role assignments are unaffected by the module migration — the permission keys are byte-identical to their legacy names, and permissions are read from the serialized users.permissions regardless of where the keys are defined.
current_has_permit() and the controller helper $this->with_permission(); the modern path uses Guards and $this->can() / $this->guard->hasModuleAccess(). Helpdesk pillar controllers gate access with with_module() + with_permission() in their constructors. You configure both from the same Roles screen — you do not manage them separately.- Confirm
module_helpdeskis enabled (otherwise the Helpdesk rows are hidden). - Open Settings → Roles and edit (or create) the target role.
- Scroll to the Help Center permission groups (and Web Pages for the Pages pillar). Each pillar contributes one or more rows.
- For an access-scope row (rendered as an all / specific dropdown), choose All to grant across the board or Specific to scope it. For a module-style row, flip the Enable toggle on.
- Grant the child action rows (Create / Edit / Remove, plus category variants) the role should have.
- Save the role. Users in that role pick up the grant on their next request.
Module toggle vs. all/specific dropdown rows
Each permission declares a default_level that decides how it renders in the Roles editor:
default_level | How it renders | What it means | Example keys |
|---|---|---|---|
module (default) | An Enable toggle | On/off capability for the whole role. | handbook, ticket_manage, help, knowledge_base, page |
specific | An all / specific dropdown | Access can be granted globally or scoped to specific records. | ticket, ticket_staff, ticket_collaborator, help_categories, knowledge_base_categories |
Permission groups at a glance
The pillars contribute the following permission groups. This is a summary — the exhaustive, key-by-key matrix (labels, actions, dropdown vs. toggle) lives on the Permissions Reference.
| Pillar | Key permits (with CRUD variants) | Roles editor group |
|---|---|---|
| Handbook | handbook, handbook_create, handbook_update, handbook_delete, handbook_publish | Help Center: Handbook |
| Tickets | ticket, ticket_create, ticket_update, ticket_delete | Help Center: Ticket Type |
| Tickets | ticket_staff (+ create/update/delete) | Help Center: Ticket Staff |
| Tickets | ticket_collaborator, ticket_manage, ticket_comment | Help Center: Ticket Collaborators / Manage Tickets / Ticket Comments |
| Tickets | add_ticket_label, override_ticket_due_date, override_ticket_type | Help Center: Allow Adding Ticket Label / Override Due Date / Override Type |
| Tickets | ticket_groups (+ create/update/delete) | Help Center: Ticket Groups |
| Internal Wiki | help (+ create/update/delete), help_category*, help_categories | Help Center: Internal Wiki / Internal Wiki Category |
| Knowledge Base | knowledge_base (+ create/update/delete), knowledge_base_category*, knowledge_base_categories | Help Center: Knowledge Base / Knowledge Base Category |
| Web Pages | page, page_create, page_update, page_delete | Web Pages |
help_articles / help_categories tables discriminated by a type column (help vs. knowledge_base), but they are separately permissioned. Grant help for the staff-only Wiki and knowledge_base for the KB independently.SOP 3 — Navigate the Help Center
Helpdesk surfaces its entries inside the shared left sidebar's Help Center group. The pillars sit together there — Tickets, Internal Wiki, Knowledge Base, Pages — and the module appends its own Company Handbook reader entry to the tail of that same group.
| Sidebar entry | Menu name | URL | Shows when |
|---|---|---|---|
| Company Handbook (reader) | helpdesk_handbook | handbook | module_helpdesk on and user has handbook |
| Tickets | core Help Center item | tickets | module_ticket on and user has ticket |
| Internal Wiki | core Help Center item | help | module_help on and user has help |
| Knowledge Base | core Help Center item | knowledge_base | module_knowledge_base on and user has knowledge_base |
| Web Pages | core Help Center item | pages | module_page on and user has page |
admin/handbook, but it is intentionally not a sidebar item. HR reaches it via the Edit button on the Handbook reader page, gated by handbook_create / handbook_update. See Company Handbook for the full admin workflow.How items appear (and disappear)
Sidebar items are gated the same way as the pillars themselves: an entry renders only when the module toggle and the item permit are both satisfied. The Handbook entry is contributed by the module's config/menu.php; the default left-menu slice in config/default_menu.php merges it into the core Help Center group (reusing the same header, ordered by position 151, just after the core group at 150) so it is part of the "Restore to default" left-menu set rather than a stray top-level leaf.
SOP 4 — First-run checklist
Run this the first time you turn Helpdesk on in a tenant. Do it in order; each step assumes the previous one succeeded.
- Enable the module. Settings → Manage Modules → Helpdesk on (
module_helpdesk). Confirm the pillar sub-toggles you want are also on. - Create or pick a role. Settings → Roles → create a support role (e.g. "Support Agent") or edit an existing one.
- Grant the pillar permits. Enable the toggles / set the dropdowns for the pillars this role should own (SOP 2).
- Configure each pillar. Set up ticket types, groups, and email intake (Tickets, Email & Automation); seed KB and Wiki categories/articles (Knowledge Base, Internal Wiki); create Web Pages (Web Pages); upload or template the handbook (Company Handbook).
- Verify visibility. Log in as a granted user and confirm the Help Center entries appear and open. Log in as a non-granted user and confirm they do not.
Who can access what
Use this persona map to decide which pillars and permits each type of user needs. It is a starting point — scope down with the specific dropdowns where appropriate.
| Persona | Pillars they need | Representative permits |
|---|---|---|
| Support Agent | Tickets, Knowledge Base (read) | ticket, ticket_staff, ticket_comment, ticket_manage, add_ticket_label, knowledge_base |
| Support Lead | Tickets (full), Ticket Groups | above + ticket_create, ticket_groups (+ CRUD), override_ticket_due_date, override_ticket_type |
| KB Manager | Knowledge Base, Internal Wiki | knowledge_base (+ CRUD), knowledge_base_category*, help (+ CRUD), help_category* |
| HR Admin | Company Handbook, Web Pages | handbook, handbook_create, handbook_update, handbook_delete, handbook_publish, page (+ CRUD) |
| Employee | Company Handbook (read), Knowledge Base (read) | handbook, knowledge_base |
| Guest / Public | Knowledge Base (published only) | none — public read when module_knowledge_base is on |
module_knowledge_base is enabled, published KB categories and articles are visible to anonymous visitors — a guest is not bounced to the sign-in page (the controller uses OptionalAuthGuard). Guests are limited to active/published content and cannot reach the management panels or drafts. The knowledge_base permit is required only for logged-in staff who want the in-app management view; all create/edit/delete stays in the permission-gated Internal Wiki (Help) controller.Common setup pitfalls
module_ticket / module_help / module_knowledge_base / module_page), or module_helpdesk for the Handbook; or (2) the user's role lacks the permit. Both halves are required. Verify both before assuming a bug.module_knowledge_base is disabled, the Knowledge Base controller responds with show_404() rather than a "forbidden" page. This is intentional — it hides the very existence of the resource from anonymous visitors. Do not interpret the 404 as a broken route; it means the module is off.module_helpdesk is off. The module surfaces its permission rows into the RBAC UI only when the master is enabled. Enable Manage Modules → Helpdesk first, then reopen the role.module_helpdesk + the handbook permit and is never exposed publicly (it is confidential company content). A guest cannot read it.Setup terminology
The module_helpdesk settings key. The umbrella switch in Manage Modules; also the gate that surfaces Helpdesk's permission rows in the Roles editor and gates the Handbook pillar.
A per-pillar module switch: module_ticket, module_help, module_knowledge_base, module_page. Independently on/off under the master.
A serialized entry in users.permissions such as ticket or handbook_publish. Checked in controllers with with_permission().
default_levelA permission's render mode in the Roles UI: module renders an Enable toggle; specific renders the all/specific dropdown.
One of the five Helpdesk sub-capabilities: Tickets, Internal Wiki, Knowledge Base, Web Pages, Company Handbook.
The shared left-sidebar group where the pillar menu entries live, ordered by position.
Troubleshooting
The master toggle governs the umbrella and the RBAC rows, but Tickets gates on its own module_ticket sub-toggle plus the ticket permit. Confirm module_ticket is on and that the user's role grants ticket.
Those rows are surfaced only when module_helpdesk is enabled. Turn on Manage Modules → Helpdesk, then reopen the role editor.
That is by design. A disabled module_knowledge_base makes the controller show_404() to hide the resource's existence. Enable the sub-toggle to restore it.
They should not have. The permission keys were re-declared verbatim in the module, and permissions are read from the serialized users.permissions regardless of where the keys are defined. If a role appears to have lost access, verify the relevant sub-toggle is still enabled — a toggle, not a permit, is the usual cause.
HR administration is at admin/handbook, reached via the Edit button on the Handbook reader page (gated by handbook_create / handbook_update). It is intentionally not a sidebar item. See Company Handbook.