The settings file and stored credentials

Oda keeps a settings file for itself on this computer and stores some values you save, such as keys, as credentials. This page covers when the file may be edited, what Oda does with it, and how stored credentials behave; for the settings you change in the app itself, start from Memory, skills and connectors.

What the settings file is

Oda keeps one settings file for its setup on this computer, applied on top of the built-in defaults. It records only what is different, so you rarely need to open it: edit it only when DataMind support asks you to. The profile settings file describes where it lives and the copy Oda keeps beside it.

A current file starts with these two lines, and the body below them is a list of changes:

# DataMind Oda settings for this computer, applied on top of the built-in defaults.
# DataMind Oda keeps this file up to date; edit it only when DataMind support asks you to.
[]

• A new file is an empty list. [] is a list with no changes in it. Keep the body a valid list, because a file with no list is refused at start.
• The app keeps it in step. Changes you save in Oda's settings forms are recorded in the file, so use the app's own pages for your setup.

Edit the file when support asks

1. Open the settings file DataMind support points you to, and leave the two header lines in place.
2. Make exactly the change support describes, with the names they give you. Keep the body a valid list.
3. Save the file. Oda watches it and applies a valid change while it runs; if a change cannot be applied, Oda reports it and keeps the previous configuration. How changes apply and what start-up reports explains when a change applies while Oda runs and when it needs a restart.

• A warning about a name. A line that names an entry Oda does not have is skipped, with a warning: patch: entry "<name>" not found.

How Oda keeps the file up to date

Oda normalises the file when it updates it:

• Old headers and names are refreshed. A file written by an earlier version of Oda gets the current header, and Oda's own plugin names are rewritten to the @datamind/<name> form. Leave that spelling as it is.
• Preset instructions become additive. A row that carries instructions for one of your presets is adjusted so that what it says adds to Oda's base behaviour instead of replacing it.
• Your own text is kept. Comments and expressions outside the values Oda replaces are preserved.
• One copy is kept. The first rewrite leaves the file's earlier content beside it, with .before-update.bak added to its name; later rewrites never overwrite that copy.
• All or nothing. Oda replaces the file in one step. If it cannot update the file safely, the file is left as it is, and Oda reports that it was left unchanged, naming the file: Profile settings file <path> was left unchanged: <error>.

Saving settings in the app

When you save a change in one of Oda's settings forms, Oda answers with that area's state as it stands after the change, with secret values hidden.

• A save carries the state the form read. If another change landed after that, the save is refused and nothing is written: open the area again, check it, and apply the change again.
• Refusals come from the area. A refusal is reported against the settings area it belongs to, with that area's own message.
• Invalid saves are refused early. A save that names an area Oda does not serve, or carries an empty value, is refused before anything is stored.
• Missing parts are named. If a part of the settings surface is not available in this copy of Oda, the error says what is missing instead of failing silently.

Stored credentials

Some values Oda keeps for you are credentials: named entries, such as keys, that a setting or a connection uses. They are kept on this computer, and Oda treats them as write-only.

• Credentials have plain names. Oda can check a set of names and report, for each, whether a value is set, where the value comes from when that is known, and whether it can be changed here. One check covers at most 64 names; the bound is fixed.
• A value cannot be empty. Storing a credential with an empty value is refused before anything is stored, and so is a name that does not fit the plain name form.
• A refused store points at the name only. When the store refuses, the message comes from the part that owns the value and names only the credential's name, never its value.
• Setting and removing round-trip. After you remove a credential, a later check reports it as not set.
• A secret never comes back. You can store a secret value, and no read returns it: reads hide secret fields, so all you can see is whether a value is set.

The operations and error codes behind these surfaces are listed on Settings and credentials reference.

Questions, answered

Do I ever need to open the settings file?

Only when DataMind support asks you to. Oda keeps the file up to date on its own, and the app's own pages are the place to change your setup.

What happens if the settings file is empty?

Oda fails to start with it: a file with no list, empty or comments only, is refused. To turn off what the file adds, keep the two header lines and write an empty list: [].

What does a line that names something unknown do?

Oda skips it with a warning naming the entry, patch: entry "<name>" not found. The rest of the file still applies.

Why does the settings file look different after an update?

Oda normalises it: an older header is refreshed, Oda's plugin names are rewritten to the @datamind/<name> form, and a preset row is adjusted so its instructions add to Oda's base behaviour. The first rewrite leaves the earlier copy beside the file, with .before-update.bak in its name.

What happens if Oda cannot update the file?

It leaves the file as it is and reports that it was left unchanged, naming the file. Fix the file, or restore the .before-update.bak copy beside it.

Where do saved settings go?

Changes you save in the app's settings forms are recorded in the settings file, which holds what is different from Oda's built-in setup. Leave the file itself to Oda unless support asks otherwise.

Can I see a secret again after I set it?

No. A secret travels one way: you can set a value, and no read returns it. Oda's reads hide secret fields, so all you see is whether a value is set. To change one, set a new value.

Why was my saved setting refused?

Most often the area changed after the form read it: the save carries the state the form read, so a later change refuses it and nothing is written. Open the area again, check it, and apply the change again. A save that does not fit is refused before anything is stored.

Is there a limit on how many credential names Oda can check at once?

Yes: one check covers at most 64 names, and the bound is fixed. A larger set is refused, and one name that does not fit the plain name form fails the whole check.

What if a part of the settings surface is missing?

This copy of Oda is not set up with that part. Instead of failing silently, the error names what is missing, so it can be put right.