Live settings forms

Some values in DataMind Oda can be changed while it runs. Oda builds those settings forms from the configuration each plugin declares for itself: only the values a plugin marks as safe to change live appear, and a saved edit takes effect without a restart. This page covers how these forms behave: what they show, how a reset works, and what a refusal means. The walkthrough for opening one is on Live plugin settings.

The forms sit among Oda's other settings: Memory, skills and connectors maps those areas, and Advanced features covers the switches that give Oda extra capabilities.

How a form decides what to show

• A form shows only the values the plugin marks as safe to change while Oda runs; the plugin's other values stay hidden.
• A value written as an expression is kept whole. The form does not rewrite it, and edits to other fields leave it as it is.
• A plugin with a settings page of its own is configured there, not in a generated form.
• A form exists only for a plugin active in this installation; a plugin that is not loaded shows none.
• A form that cannot accept writing stays readable: its values remain visible, and the controls that would change them are disabled.
• A plugin with nothing to expose shows the form message This plugin has no configuration fields.

Change and save a value

A field shows the value in effect. Change what you need in the form and save; the change reaches the running app, so no restart is needed.

• The walkthrough for opening a plugin's form is on Live plugin settings; when a change must wait for the next start instead is on How changes apply and what start-up reports.
• A saved value is recorded in the settings file this computer keeps; The profile settings file describes what it holds.
• Every save carries the state the form was read at, so Oda can tell whether the setting changed in the meantime. When it did, Oda refuses the save instead of overwriting the newer change.

Secrets stay write-only

Some fields hold a secret, such as a key or a token.

• You can save a new secret, but Oda never shows the stored value back: the form shows only whether a value is set.
• Editing one value in a form does not disturb the stored secrets, including secrets the form did not receive.

Reset a value

Reset removes your change and restores the value beneath it, including the default.

• A field-level reset clears only what you set; it cannot delete a value that a layer beneath supplies.
• Removing an item from a list removes that item.

When a value cannot be saved

Oda checks every save before it writes and refuses one it cannot apply. Nothing is written when a save is refused; fix the cause and save again.

• The setting changed first. The save carries the state the form was read at. When another change landed in between, the save is refused with settings namespace "<name>" changed since it was read (expected revision <x>, now <y>); the refusal carries the code SETTINGS_CONFLICT. Reopen the form and apply your change again.
• A value set above the form wins. A value kept in this computer's settings file, or passed on the command line, outranks a form; a save that would be overridden by it is refused. Change the value where it is set, on The profile settings file and Command line and flags.
• The field is not offered live. A save that touches a value the plugin does not expose for live editing is refused: Config field "<path>" is not volatile.
• The plugin has no form to write to. No configurable plugin entry "<name>" means no settings form matches that plugin; Plugin entry "<name>" has no volatile fields means the plugin exposes nothing that can change while Oda runs.

Older settings files

A settings file left by an earlier version of Oda is imported once, after Oda is ready, and the old file is renamed settings.yaml.imported so the import never repeats. Its values carry over into Oda's settings; a section this build cannot use is left out, and its content stays only in the renamed file.

Questions, answered

What decides which fields a form shows?

The plugin itself: it marks the values that are safe to change while Oda runs, and the form offers only those. Everything else stays hidden. A plugin that ships a settings page of its own is configured there instead.

Why does a field show an expression instead of a value?

The value is written as an expression, and the form keeps it whole. Oda does not rewrite it, and editing other fields leaves it as it is.

Why was my save refused? The message mentions two revisions.

The form was read at the first revision, and the setting had already moved to the second when your save arrived, so Oda refused it rather than overwrite the newer change. Nothing was written; reopen the form and apply your change again.

I chose Reset, but the value did not become empty. Why?

Reset restores the value beneath your change, including the default, and clears only what you set. It cannot delete a value that a layer beneath supplies. Removing an item from a list removes that item.

What is the settings.yaml.imported file?

It is the settings file an earlier version of Oda left behind, renamed after Oda imported it once so the import never repeats. Its values carry over into Oda's settings; anything a section held that this build cannot use stays only in the renamed file.

What does Config field "<path>" is not volatile mean?

The save tried to change a value the plugin does not offer for live editing, so Oda refused it. The value is unchanged; live editing does not cover that field.

Can a form change a value that is set in the settings file?

No. A value kept in this computer's settings file, or passed on the command line, outranks the form, and a save that would be overridden is refused. Change the value where it is set: The profile settings file and Command line and flags.

What do No configurable plugin entry and no volatile fields mean?

Both are refusals of a save. No configurable plugin entry "<name>" means no settings form matches that plugin; Plugin entry "<name>" has no volatile fields means the plugin exposes nothing that can change while Oda runs, so there is nothing to save.