Settings and credentials reference

DataMind Oda's configuration surfaces read and write through two service namespaces on the Remote layer: settings and credentials. This page is the reference for both: the operations, the rules that decide when a write is refused, what stays redacted, the bounds, and the exact error codes. Company-wide rules and permissions around Oda are managed in DataMind OS: see Manage DataMind Oda for your company.

The settings surface

describe answers with the provider's writability, the local document's presence, and a redacted view of every namespace: the schema a form renders from, the values, which secret fields are set, and the revision. Three write operations change a namespace, and each answers with the namespace's new redacted view:

To edit the values a plugin exposes while Oda runs, see Live plugin settings; managing the plugins themselves is on Plugins and bundles.

Both surfaces are configuration only: they register no prompt, tool or session event.

Revisions and conflicts

A write can carry the revision you read; a write with no revision goes through unconditionally.

• A moved revision is a conflict. When the stored revision no longer matches the one you passed, the write is refused as settings/conflict. Its details carry ns, expected and actual: the namespace, the revision you expected and the revision actually stored. This is its own outcome, not a malformed request. Re-read the namespace and apply the change again.
• Other refusals are settings/rejected. That covers a namespace the service does not serve, a read-only provider, a value that fails the schema, and a storage failure. Its details carry the namespace, and the message is the provider's own.
• A disposed namespace fails after the write. If the namespace is disposed right after a write commits, the call answers as gateway/internal with settings namespace "<ns>" was disposed after the <mode>.

The settings document

Open the settings document. openSettingsDocument prepares the document the settings provider owns and opens it in the native text editor; on success it answers { opened: true }. No filesystem target comes from the caller: the document is the provider's own.

• A cancellation ends the call as gateway/cancelled, reporting settings document open was aborted or settings document preparation was aborted.
• A failure reports settings document preparation failed: <reason> or path open failed: <reason> as gateway/internal.

For the settings file a profile keeps on this computer, see The profile settings file.

The credentials surface

describe reads the references you name and answers one entry per name: whether the reference is configured, where its value comes from when that is known, and whether it is writable. set stores a value and requires it to be non-empty; unset removes the reference; a later describe reflects either change.

• A plain identifier. A reference name starts with a letter or an underscore and continues with letters, digits and underscores. A name outside that pattern, for example one with spaces, is refused before anything is stored, and one bad name fails the whole describe batch.
• A refused write is credential/rejected. The provider refused a valid write, for example because a read-only source shadows the reference. Its details carry only the reference, never the value.

Secrets travel one way

• One direction only. A secret can be written, and no call returns it.
• Every read is redacted. A field marked as a secret cannot appear in any answer.
• Answers are copied field by field. Extra fields a provider exposes do not travel with the answer.

Bounds

• 64 names per describe. A describe call takes at most 64 names at once; a batch over the bound is refused as a bad request. The bound is fixed: it is not a deployment field.
• Bad requests. An invalid namespace, an invalid name or an empty write value fails as a bad request (gateway/bad-request). The message reads invalid payload for settings.<mode> on a settings write and invalid payload for <method> on a credentials call.

When a service is missing

Both namespaces stay registered even when the service behind one is absent: the call fails instead of disappearing. 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. Both fail as gateway/internal.

Questions, answered

What is the difference between update, replace and mutate?

update merges your patch into the namespace'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 namespace's new redacted view.

Why did my write fail with settings/conflict?

The revision moved after you read it. Nothing is wrong with the call: re-read the namespace and apply the change again. The failure carries the namespace, the revision you expected and the revision actually stored.

What does settings/rejected mean?

The call was valid and the provider still refused it: a namespace the service does not serve, a read-only provider, a value that fails the schema, or a storage failure. The failure carries the namespace, and its message is the provider's own.

Can I read back a value I stored as a secret?

No. Secret values travel one way only: you can write one, and no call returns it. Every read is redacted, so a secret field cannot appear in an answer, and even a refused write names only the reference.

Why is my credential reference refused?

A reference name is a plain identifier: it starts with a letter or an underscore and continues with letters, digits and underscores. A name with spaces, for example, is a bad request, and one bad name fails the whole describe batch.

How many names can one describe call take?

64. The bound is fixed; it is not a deployment field.

What opens when I open the settings document?

The document the settings provider owns, in the native text editor. The call takes no filesystem target from the caller, and a success answers { opened: true }.

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.

I cancelled the settings document while it was opening. What happened?

The call ends as gateway/cancelled, reporting settings document open was aborted or settings document preparation was aborted. A cancellation that lands while the document is still being prepared never opens the editor.

What happens if the namespace is disposed after my write went through?

The write committed, and the call still fails: gateway/internal with settings namespace "<ns>" was disposed after the <mode>. Only a concurrent removal of the namespace produces it.