Before you begin
You need an administrator session with the Surveys permission. It works on either database, and which one you are on decides what you are editing: on the main database you author the platform’s surveys, and inside a tenant workspace you author that tenant’s own. Same screens, different data — a banner at the top of each page says which.
1. Enable the module
Go to Settings → Manage Modules and switch Surveys on. If you upgraded from a build that had the old App Rating report, the upgrade already switched it on for you.
POST /v1/api/me/app-rating
answer 404 for every mobile client.
2. Create the tables
php erpat migrate:modules --allThis creates six tables on the main database and on every tenant, plus the module toggle each tenant needs to see the menu at all.
--all, not a bare run. Without it only the main database is
touched, and tenant administrators get no Surveys menu and no tables — with no error to
tell you why.
3. Grant access
In Roles, find the System: Surveys group and grant:
| Permission | Give it to |
|---|---|
| Surveys | Anyone who should read results. Without it the menu group is hidden. |
| Create / Edit / Delete | People who write surveys. |
| Publish / archive | Only those who may start interrupting real users. Keep this list short. |
| View / Change Survey Settings | Separate again, because Settings carries the limits that apply to every tenant. |
4. Decide what tenants may do
Open Surveys → Survey Settings → Tenant Policy. Two switches, both of which start on:
| Switch | Starts | While it is off |
|---|---|---|
| Let tenants create their own surveys | On | A tenant administrator can open the module but cannot author or publish anything. |
| Let tenants publish required surveys | On | They can publish optional surveys only — no blocking modals. |
Both start on because the module itself is switched on for every workspace — a tenant that has Surveys should be able to use it, consent notices included. Turn authoring off here if you would rather author everything centrally; the tenant keeps read access either way. The two are cumulative, so required does nothing while authoring is off.
These limits live on the main database only. Inside a tenant workspace the same controls appear greyed out with a “set by your provider” note, so a tenant administrator can see the constraint rather than wondering why the option is missing.
5. Load the demo data (optional but recommended)
php erpat db:seed SurveysDemoAdds a category, one optional survey, and one required consent survey. Both
surveys arrive as drafts — nothing is shown to anyone until you publish.
Add --tenant=<company key> to seed a workspace instead. Remove them again with
php erpat db:seed SurveysDemo --remove.
6. Publish your first survey
- Open Surveys in the left menu.
- Go to the Surveys page and choose New Survey.
- Give it a title, pick Optional, and write a short message.
- Add a question — try Star rating to begin with.
- Save. It is a draft; still nothing has happened to anyone.
- When you are ready, use the row menu and choose Publish.
Load any page in ERPat as a targeted user and the prompt appears. Answer it, then check the Responses page.
Then try a required one
Repeat the steps, but choose Required and paste some real policy text into the message. Publish it and reload a page. Notice that:
- Escape and clicking the background do nothing.
- There is no × and no Cancel.
- I Agree stays greyed out until the text has been scrolled to the end.
- I Disagree is always available — there is no dead end.
Answer it either way, and look at the response row: it carries the version, the time, your IP address, your browser, and a fingerprint of exactly the text you saw.
A sensible first week
- Publish one optional rating survey and leave it alone for a week.
- Read the acceptance and response rates on Overview.
- Only then try a required one, and start with a small audience — a single tenant.