Settings and Permissions
Two complaints arrive at the support desk more often than almost anything else, and they are the same complaint: “before this I could, and now I can’t”, and “nobody changed anything”. Both are usually true at once. Somebody opened a settings screen for a perfectly good reason, pressed SAVE, and fourteen other toggles on that screen were written along with the one they came for.
This page is about the machinery underneath that: where an applet’s settings are kept, who they apply to, why a setting that has never been saved does not behave like a setting that is switched off, and how a setting differs from a permission when the two sit side by side on one screen governing adjacent fields. Ten minutes. It is true of every applet, so every applet page links here instead of explaining it again.
The short answer
An applet’s settings are one JSON document, one per applet, shared by everybody in your tenant. There is no per-user copy and no per-company copy. A permission is a different thing entirely: it is granted to a person or a team, it can only ever add something to what they see, and it is enforced in the browser rather than on the server.
So: if you want a rule that applies to the whole business, that is a setting. If you want two colleagues to see different things on the same screen, that is a permission. And if you change a setting, your colleague’s screen changes too — including the colleague on the other side of the country.
Where a setting lives, and who it applies to
Every applet you have installed carries a single settings record — a JSON document holding every toggle, default and threshold that applet knows about. When you open Settings › Application Settings, that document is what you are editing.
It is tenant-wide. Not per company, not per branch, not per user. If GadgetSphere’s group has three companies and twenty-two branches, there is still exactly one Sales Invoice settings document, and a change made from a branch terminal in Penang lands on the screen of the accounts clerk in Klang Valley. We checked this rather than assumed it: across all ninety production tenants, no tenant holds more than one Sales Invoice settings record.
Two things that look like applet settings and are not:
- Branch Settings (Settings › Branch Settings) saves onto the branch record, not into the applet’s document. That is genuinely per branch, and every applet that reads the branch sees it.
- Personalization › Default Selection saves against you — your login, in a separate table — and nobody else is affected. It is the only screen in this family that is genuinely yours. It is also a much shorter screen than people expect, because almost nothing is personalisable.
That division is the answer to the question readers actually ask, which is “will my change affect my colleague?” For Application Settings the answer is yes, everyone.
Absent is not off — and sometimes absent means on
Here is the part that makes “nobody changed anything” true and “it used to work” true at the same time.
A key exists in that JSON document only after somebody has opened the relevant settings screen and pressed SAVE. Until then it is simply not there, and the applet falls back to whatever its own code does when the value is missing. That fallback is written in the code that reads the setting — not on the settings screen — so the screen cannot show it to you, and a toggle sitting in the “off” position on a screen that has never been saved is not telling you what the system will do.
Most of the time the fallback is the harmless one: the key is missing, the feature is off, the field is shown. But not always, and the exception is worth knowing because it is expensive.
The worked example. Sales Invoice has a toggle labelled Disallow negative stock for basic item (validate stock balance). While the settings screen has never been saved, the applet sends nothing about stock validation to the server — and the server’s own default is to validate. So a brand-new tenant refuses to finalise an invoice for stock it does not have, with Not Enough Stock for item …, and nobody switched that on.
Then somebody opens Application Settings to change something else entirely, and presses SAVE. The toggle is sitting in its off position, so
falseis now written into the document, the applet starts sending it, and the server stops checking. A stock control was switched off by saving a settings panel. Nothing on the screen says so, and nothing is logged in a way a finance person would find.
This is the single best reason to treat a settings screen as a live control rather than a form. Which brings us to the next mechanism, which is the cause of it.
Saving one panel saves the whole screen
The settings screen is one form. Press SAVE anywhere on it and every control’s current value is written, not just the section you were looking at. The write is a merge, so a key already in the document is updated and keys not on the screen are left alone — but every key that is on the screen gets stamped with whatever it is showing.
And the merge never removes anything. A key written once stays in the document for good, even after a later release stops reading it. That is why a long-lived tenant’s settings document drifts larger than the list of settings the applet actually has, and why “this key is in our settings” is not evidence that the key still does anything.
The practical rule: before you press SAVE on a settings screen, look at the whole screen, not the panel you opened it for. If you are not sure what a section is currently doing, that is a reason to find out first, not a reason to save and see.
The settings menu is eight screens, not one
Settings is a menu, and each entry stores somewhere different. When somebody says “it’s in the settings”, this is the list they might mean:
| Screen | What it is for | What it is not for |
|---|---|---|
| Application Settings | The applet’s own toggles, defaults and thresholds — the JSON document above | Anything per user or per branch |
| Default Selection | The company, branch, location and pricing a new document opens with | A rule; it only pre-fills, and the user can change it |
| Printable Format Settings | Which print layout this applet uses, per company and branch | Changing what is printed on it |
| Branch Settings | Per-branch configuration, stored on the branch record | Anything applet-specific |
| Workflow Settings | Linking a company to a workflow process for this document type | Approvals — a workflow status is a label, and on its own it gates nothing |
| Email Template | Which message template this applet sends | Who receives it |
| Custom Resource Bundle Configuration | Renaming labels on the screen for your business | Changing behaviour — a renamed field is the same field |
| Custom Field Placement | Where your custom fields appear on the form | Creating the custom fields |
Alongside them sits Personalization, which is yours alone and, in every applet we have checked, holds a single entry — a personal Default Selection — and the permission listings — Feature Visibility, Client-Side Permission, Permission Set, User, Team and Role — which are the subject of the rest of this page.
Nearly everything our applet pages have historically called “applet settings” is the first of those eight.
A setting is not a permission
They sit on adjacent rows of one screen and govern adjacent fields, which is why nobody can tell them apart. They are not the same mechanism and they are not changed by the same person.
| Setting | Client-side permission | |
|---|---|---|
| Who it applies to | everybody in the tenant | the user, team or role you grant it to |
| Where you change it | Settings › Application Settings | Settings › Permission Set / User / Team / Role |
| What it can do | switch behaviour on or off for all | only add — there is no “deny” |
| Where it is enforced | usually the browser; occasionally the server | the browser |
| What “not set” means | the fallback in the consuming code — see above | not granted, so the control is hidden |
The pair that proves it. Finalise a sales invoice and every field in the header goes read-only — then exactly two of them come back, by two different mechanisms:
- The Sales Agent field is re-enabled by an applet setting. Switch it on and the agent is editable after finalising for everyone, which is usually what a business wants, because the commission is being corrected by whoever notices.
- The Transaction Date stays editable only for a user who holds a client-side permission — the ability to back-date a finalised invoice. That one you almost certainly do not want to give everyone, which is exactly why it is a permission and not a setting.
Same screen, same moment, two fields, two mechanisms, two different administrators. When a reader asks “why is the sales agent greyed out?”, the answer is a setting; when they ask “why can’t I change the date?”, the answer is a permission — and the applet page for each screen says which is which.
What a client-side permission actually does
Three facts, and the third one matters more than the other two.
It is grant-only. A permission code starts off absent, a grant turns it on, and nothing turns it back off except removing the grant. There is no “deny” that overrides a grant. So you cannot use permissions to take something away from one person while leaving it for the rest of their team — you take it away from everybody and grant it back to the people who should have it.
It is registered per applet. Across the platform there are 1,573 active client-side permission definitions covering 59 applets and 517 distinct codes; a big document applet declares dozens, a small one declares none at all. If an applet declares none, permissions are not the lever for it.
It hides a control. It does not withhold the data. This is the important one. When a permission hides a price column in a grid, the column is hidden — and the amount it was showing has still been fetched into the browser along with the rest of the row. In at least one screen the hidden column is computed from a value that is still present in the data. So:
Do not use a client-side permission as a confidentiality control. It is a tidiness control. It keeps a number off a screen where it does not belong and out of the way of people who do not need it. It does not stop a determined person from seeing that number, and it is not a defensible answer to “who can see our margins”.
If a number must genuinely be restricted, the control has to be a server-side one — the API permissions that decide what a request is allowed to return at all. Those are a different list, and the applet page names them for the actions that can fail with a 403.
How to find out what a setting is doing on your tenant, in thirty seconds
You cannot read the stored document from the screen, but you can do better than guessing:
- Open Settings › Application Settings on the applet and find the toggle.
- Change something harmless on the same screen and press SAVE. Every visible toggle is now written with the value you can see, so from this moment the screen and the stored document agree. Before that save, they may not have.
- Go and do the thing. If the behaviour matches the toggle, you now know. If it does not, the key is one the applet no longer reads — the applet page’s On the screen and doing nothing list is where we name those.
What settings will not do
- They are not an approval workflow. A workflow status is a label on the document. Unless a specific applet says otherwise, nothing refuses to post because a status has not been reached.
- They are not an audit trail. The document records who changed it. The settings document does not record who changed a toggle or when.
- Most of them do not change what the server accepts. The large majority are enforced in the browser, which means they shape what your staff can do through the screen and nothing about what an import, an API call or another applet can do to the same data. Where a setting really is enforced by the server, the applet page says so and cites where.
- They do not disappear when they stop working. A key can sit in the settings document, and sometimes on the screen, long after the code that read it has gone. That is not a hypothetical: applet pages under this standard carry a short On the screen and doing nothing list precisely because a reader who cannot find the switch assumes they are looking in the wrong place.
Where you meet it
Every applet page has a Configuration section with the same three parts: the handful of settings that change what the applet will let you do, the ones that are on the screen and do nothing, and who can change what. Three worked examples, deliberately different in shape:
And two neighbours in this section: How work actually runs for what happens after you press Finalise — which is where a server-enforced setting shows its teeth — and What a void undoes for the other half of that story.