Settings

Settings → /settings (organisation) · Config Settings → /config-settings (engine)

Nyumba Zetu keeps configuration in one engine with one resolution rule, rather than scattering switches across modules. Understanding the rule explains most "I changed it and nothing happened" questions.

The scope chain

A setting is resolved by walking from the most specific scope to the least, and taking the first value found:

lease → unit → block → branch → organisation → platform default

The most specific scope wins. This is how one scheme runs a stricter collections ladder, a different billing day, or a different late-fee policy without duplicating everything else.

Definitions and overrides

The settings engine has two halves:

A definition without an override uses its default. An override without a definition cannot exist.

Reading the definitions list

Reading the overrides list

Changing settings in context

You rarely need the raw engine. Most screens with configurable behaviour carry a settings gear that opens the settings for that area, filtered to its category and set at the scope you are working in. Changing a collections threshold from the collections console is safer than finding the key in a list of hundreds.

Areas with their own settings panel today:

Editing from these panels requires the finance edit permission.

Reading the value ladder

Each setting shows where its effective value comes from, across the three levels, and which one won:

System <default> · Org <override> · Branch <override> → <effective> (<source>)

A level with no value shows —. Settings that offer a fixed set of choices show you the name of the choice, not the value stored behind it — so a template setting reads as the template's name rather than its reference. Structured settings collapse to a field count rather than printing raw data into the line.

Where an override exists at the scope you are editing, a revert button clears it and lets the level above take over again.

What the control looks like

Where each kind of configuration lives

Changing a setting safely

1. Decide the scope first

   Ask whether this should be true for the organisation, or only for one branch or scheme. Setting at too broad a scope is the most common configuration mistake.

2. Check for existing overrides

   A more specific override will win regardless of what you set.

3. Make the change, and say why

   From the contextual settings panel where one exists. Every change asks for a reason before it saves — a sentence is enough. The change is refused without one.

4. Verify against the behaviour, not the value

   Open the screen the setting affects and confirm it did what you expected.

Who changed this, and why

Every settings change is recorded: who made it, when, the value before and after, and the reason they gave. The reason is required — a change submitted without one is rejected, so there is no way to alter a setting and leave the record blank.

Open a setting override from Settings overrides and its Change History tab lists every change to that setting, newest first, across every scope. The trail is keyed to the setting rather than to the override row, so it survives an override being cleared and set again — clearing a branch override does not erase the history of that branch ever having had one.

Entries cannot be edited or deleted, including by the person who wrote them. This is deliberate: a justification that can be rewritten afterwards is not a record. If a reason turns out to be wrong, make a follow-up change explaining the correction rather than trying to amend the original.

Notes are a different thing. A note is a standing annotation on the override — what it is for — and can be rewritten at any time. A reason belongs to one change and is fixed.

A caution on inert settings

A setting only does something if a module reads it. When new configuration is introduced, its read-site is wired at the same time — a value that exists but is never read is worse than no setting, because it looks like a control and is not one.

If you set something and behaviour does not change, and there is no more specific override, raise it rather than assuming the value is wrong.

Feature flags versus settings

The two are converging onto one engine; today, module availability is managed under Feature flags.

Common problems