FAQ and Troubleshooting
Answers for the most common setup, access, workflow, and support questions for Tools Hub.
Frequently Asked Questions
Why can an admin see the module but a staff member cannot?The module likely depends on both the module enable setting and role permissions. Confirm the module is enabled, then assign the relevant permission keys to the staff role and test with a non-admin account.
Why is a list empty even though records exist?Check filters, deleted/archived status, tenant context, date range, ownership, and specific-member permissions. Some module lists intentionally hide records until a status, location, category, or assignment filter is selected.
What should we do before deleting or disabling records?Confirm there is no active transaction, public page, report, job, or linked workflow depending on that record. Prefer deactivation or status changes when history must remain visible.
How do we know which screens belong to this module?Use the Data and Screen Reference page. It lists controllers, routes, views, menu entries, and supporting files discovered from the module package.
When should this guide be updated?Update it whenever routes, screens, permissions, public pages, APIs, jobs, seeders, reports, or the core workflow changes.
Why are scheduled results or SLA fields not updating?Confirm the cron worker is running, the module job is enabled, and any module setting gate used by the job is turned on.
Why is an API response different from the screen?API routes can have separate filters, scopes, examples, and serializers. Compare the API config files with the screen controller and confirm the same tenant, permission, and filter context.
Troubleshooting Checklist
- Confirm the current tenant, user role, module toggle, and permission keys.
- Reproduce the issue from the exact URL and record ID reported by the user.
- Compare administrator behavior with a role-limited test user.
- Review filters, deleted/archive flags, status, date ranges, and ownership fields.
- Check recent module changes in README, CHANGELOG, migrations, and routes.
- Check scheduled job status and whether the relevant job is enabled.
- Inspect API filters, scopes, and examples when the issue comes from an integration.
Glossary
- Module slug
- The stable key used by ERPat to enable, gate, and discover this module. For this module it is tools.
- Menu entry
- The sidebar label a user clicks to reach the module workspace.
- Permission key
- A named access rule assigned to roles so staff can view, create, update, delete, report, or configure module records.
- Route
- A URL mapping from a browser path to a module controller action.
- Seeder
- An operator-run script that creates sample or starter data. Seeders are not the same as schema migrations.
- Migration
- A database schema change that prepares tables or columns required by the module.
- Scheduled job
- A background process that can update records, send notifications, or refresh summaries without a user clicking a screen.
Escalation Notes
- Capture the exact user, tenant, URL, record ID, date range, and action attempted.
- Check whether the same action works for an administrator and for a role-limited user.
- Review module routes, permissions, settings, migrations, jobs, and logs before changing data manually.
- Document the final cause in the module README, CHANGELOG, or this guide if it changes how users should operate the module.