Settings and credentials

DataMind Oda keeps its settings in documents it owns on this computer, and the values its connected services use as credentials beside them. This page is the reference for both: how a settings document opens, how a change lands, and how stored credentials are named, layered, reloaded and protected. For the everyday side, see Stored credentials; where the files live and how a save stays safe is on Oda's home folder and settings files. Company-wide rules and permissions around Oda are managed in DataMind OS: see Manage DataMind Oda for your company.

Opening a settings document

Oda can open the settings document it owns on this computer in your computer's normal text editor. It works in three steps:

1. Oda prepares the document. The document is the one Oda owns; the open never takes a file path from your side, so it cannot be pointed at a file Oda does not own.
2. Oda opens it in your editor. The prepared document opens in your computer's normal text editor.
3. Success is reported. When the open succeeds, Oda reports the document as opened ({ opened: true }).

• If you cancel while it opens, the call ends as cancelled (gateway/cancelled). The messages settings document open was aborted and settings document preparation was aborted cover the two points where a cancellation can land, and a cancellation during preparation never opens the editor.
• If the open fails, Oda reports the reason as gateway/internal: settings document preparation failed: <reason> when preparing the document went wrong, or path open failed: <reason> when your editor could not open the prepared file. Nothing is opened, so fix the cause and open it again.

The settings file a profile keeps on this computer is described on The Oda settings file.

How a settings change lands

A settings change reaches one settings area at a time, and each change answers with the area's new state, with secret values hidden. A change can be written in three ways:

• Merged (update). The change is merged into what the area already stores.
• Replaced (replace). The stored section is replaced as a whole.
• Path-addressed (mutate). The edits address exact paths, and they apply against what is stored rather than against what you last read.

More rules for a change:

• A change can carry the revision it read. If the stored revision has moved since it was read, the change is refused as settings/conflict and nothing is written. The refusal is its own outcome, not a malformed change: its details carry ns, expected and actual: the area, the revision you expected and the revision actually stored. Read the area again and apply the change again.
• A change with no revision is written unconditionally. There is nothing to compare, so it lands even when the area has moved.
• Other refusals are settings/rejected. The area is not served here, its owner is read-only, a value fails its checks, or storing fails. The refusal carries the area's name, and the message comes from the part that owns it.
• An empty value is refused before anything is stored.
• Missing parts are named. A call this copy of Oda cannot serve fails and says what is missing instead of failing silently.

The operations and codes behind these surfaces are listed in Operations and error codes; saving changes from the app's own forms is covered on Live plugin settings.

What a stored credential is

Oda keeps the credentials its connected services use as named entries on this computer. Two kinds arrive there:

• A key. A value saved for a name and used by every request that names it, such as a provider key saved from the app (Set up models and providers).
• A sign-in. What a completed sign-in stored for a connected service, kept so later requests can use the service; Authorizing services Oda connects to covers the sign-in conversation.

The rules that apply to both:

• Names match a simple form. A name starts with a letter or an underscore and continues with letters, digits and underscores. A name outside that form is refused before anything is stored.
• Reads never return a value. A secret travels in one direction only: it can be stored, and no read returns it. A check reports whether a value is set, where it comes from when that is known, and whether it can be changed here, and the answers are built field by field.
• An empty value is never stored. Blanking a name does not clear it; to clear a credential, remove it (an empty value cannot be stored for "<ref>"; use unset).
• A refused write is credential/rejected. The part that owns the value refused a valid write, for example because a read-only source supplies the name. The refusal carries the owner's own message and only the name, never the value.
• One check covers at most 64 names. A larger set is refused, and the bound is fixed rather than a setting.

Which value Oda uses

Oda resolves a name by looking in one order; the first place that has a value wins:

• The environment is read-only. Saving or removing a name it supplies is refused, and the message asks you to unset it in the environment DataMind Oda starts from instead.
• An empty value counts as not set. A name whose value is empty at a layer falls through as if that layer had nothing.

Reloading and rotation

• A rotated value applies to the next request. No restart and no configuration edit are needed.
• A change made outside Oda is picked up while Oda runs. Oda watches the store and applies the change, including a deletion, and it does not re-read its own writes.
• Both edits survive. If your edit and one of Oda's own writes land at the same time, both changes are kept.
• A broken edit keeps the last good content. If a change cannot be read, Oda keeps the last good content and warns that the reload failed at that file; a save that would overwrite a file Oda cannot read fails instead of replacing it.
• A refused value never reaches the file. Writes are checked before they reach the store, so the file never ends up in a shape the next start would reject.

How the store is protected

• Created for your account only. Oda creates the credential file so that only your user account can read it.
• Checked at load on macOS and Linux. Oda refuses to load a file that any other user can read; the message names the file and asks you to run chmod 600 <file> before starting again.
• On Windows the check does not apply. The file is still created for your account alone, and the load check for other readers is not run.
• Discretion, not a boundary. The protection rests on your computer's file permissions: other user accounts are kept out, but programs that run as you can read the file, and Oda's own work on this computer runs as you. Treat the store as a convenience, not as a boundary.

Operations and error codes

Oda's configuration surfaces read and write through two service namespaces on the Remote layer: settings and credentials. Both are configuration only: they register no prompt, tool or session event.

• Answers are copied field by field. Extra fields a provider exposes do not travel with the answer, and a field marked as a secret cannot appear in any answer.
• Bad requests. An invalid namespace, an invalid name or an empty write value fails as gateway/bad-request. The message reads invalid payload for settings.<mode> on a settings write and invalid payload for <method> on a credentials call. One bad name fails the whole describe batch, and a batch over 64 names is refused the same way.
• A namespace removed right after a write. The write committed, and the call still fails as gateway/internal with settings namespace "<ns>" was disposed after the <mode>. Only a concurrent removal of the namespace produces it.
• A missing service. Both namespaces stay registered even when the service behind one is absent, so the call fails instead of disappearing, as gateway/internal. For settings, the error tells you to mount the settings plugin together with the configuration editor in the profile; for credentials, it names the credentials plugin this installation is missing.

Questions, answered

Can I point Oda at my own settings document?

No. An open prepares the document Oda owns on this computer and opens that one; it never takes a file path from your side, so it cannot reach a file Oda does not own.

Why did opening the settings document fail?

Oda reports what stopped it: settings document preparation failed: <reason> when preparing the document went wrong, or path open failed: <reason> when your editor could not open the prepared file. Nothing is opened in either case; fix the cause and open it again.

What is the difference between update, replace and mutate?

update merges your change into the area's stored section, replace writes a whole replacement section, and mutate applies path-addressed edits against the section as stored, so it never depends on what you last read. All three answer with the area's new state, with secret values hidden.

What comes back after a settings change?

The area's new state as it stands after the change, with secret values hidden. You see the result without a second read, and a secret value can never appear in the answer.

The settings area changed before my change landed. Why was my change refused?

The change carried the revision it read, and the area moved after that. Nothing is wrong with the change: settings/conflict is its own outcome, not a malformed request. Read the area again, check it, and apply the change again; the refusal names the area and carries both revisions.

Can Oda tell me where a stored value comes from?

Yes, when it is known. A check reports, for each name, whether a value is set, where the value comes from, and whether it can be changed here. The places it can name are the environment Oda started in, the stored credential file, a .env file in the folder you launch Oda from, and a .env file in Oda's home folder.

How do I remove a stored credential?

Remove it, and later requests no longer see a value for that name. An empty value is never stored, so blanking the name would not clear it: a credential is removed by removing it.

The store refused my write even though the name looks right. Why?

A valid write can still be refused by the part that owns the value, for example when a read-only source supplies the name. The refusal arrives as credential/rejected and carries the owner's message with only the name, never the value. Fix what the message names; if the environment Oda starts from supplies the name, clear it there and start Oda again.

Why does a call say the settings service is absent?

This installation does not mount it. The namespaces stay registered, and the call fails with an error that tells you to mount the settings plugin together with the configuration editor in the profile. A missing credential provider fails the same way, naming the credentials plugin.

Is the permission check on the credential file the same on Windows?

No. Oda creates the credential file so that only your user account can read it, but the load check that refuses a file other users can read applies on macOS and Linux. On Windows the check does not apply.