Skip to main content

Create an Option Set

Goal​

Create an Option Set — a named list of choices, such as an invoice's status — and bind a field to it, so users pick from the list instead of typing free text.

Prerequisites​

  • You are signed in as a maker with permission to edit the solution.
  • An environment and a solution are selected.

Steps​

  1. Open the solution and select Option Sets in the left navigation.

  2. Select New.

  3. Enter a display name (for example, Invoice Status) and a logical name. The publisher's prefix is shown as a fixed label — type only the part after it (for example, invoicestatus).

  4. Optionally enter a description of what the set is for.

  5. Under Options, enter each choice's name (for example, Draft, Sent, Paid). Select Add option for each additional one. The order you enter them is the order users see.

  6. To change that order, drag an option by the grip at the start of its row. Without a mouse: move focus to the grip, press Space to pick the option up, the arrow keys to move it, and Space again to drop it.

    Reordering never renumbers: each option keeps the value it was allocated, so records already holding it are unaffected.

  7. Optionally give an option a colour and an icon, using the swatch and the icon button beside its name. Both are optional and independent — an option may have a colour, an icon, both, or neither.

    The colour swatch opens a small panel: pick one of the twelve quick colours, or use the spectrum below them for any colour at all — drag across the square for shade and along the strip for hue, or type (or paste) a hex code in the box. Clear colour, at the bottom of the same panel, removes it. The icon button opens the searchable icon picker, whose Clear icon sits in its footer. In both cases the clear lives inside the picker — there is no separate ✕ beside the control.

  8. Select Save. Each option's value appears next to it once saved.

Colour and icon​

A colour and an icon are what let a status be read at a glance rather than read word by word: "Overdue" in red among a hundred rows finds itself.

They are presentation only. What a record stores is the option's value, so recolouring an option changes no data and breaks nothing that depends on it — and they travel with the solution, so a set imported into Test looks the way it was designed rather than arriving plain.

Where a set gives any of its options a colour or an icon, the dropdown on a form shows them — both the icon and the label take the colour, so an option with a colour but no icon still stands out. A set whose options have neither keeps the browser's own dropdown, which is what gives a phone its usual picker.

Bind a field to the set​

  1. Open the table in Tables and go to the Fields tab.
  2. Select New, enter the field's display and logical names, and set its Data type to Option set.
  3. Choose the Option set the field's values come from.
  4. Select Save. The field is live at once.

The field now appears as a dropdown of the set's options wherever it is placed on a form, and views show the option's name rather than its stored value.

What happens behind the scenes​

Each option is given a value — a number the platform assigns, which is what the database actually stores against a record.

The values are large numbers starting from a range that belongs to your publisher (for example, 270150000, 270150001, …) rather than counting from zero. That is deliberate: if every publisher's choices started at zero, importing two publishers' solutions into one environment would make one publisher's "Draft" mean another's "Cancelled". Giving each publisher its own range makes that impossible.

Two things follow from this, and they are worth knowing:

  • You cannot type a value, and you do not need to. The platform assigns it. You can see it — it matters if an external system reads your data — but it is not yours to pick.
  • Renaming an option is safe. Its value never changes. Records hold the value, not the name, so correcting "Sent" to "Issued" leaves every existing record meaning exactly what it meant before.

When the solution is exported and imported elsewhere, the values travel with it, so Test and Prod agree with Dev about what each number means. The option set is part of the solution package, and it is imported before the tables whose fields use it — so promoting a table with a choice field brings the choices along rather than arriving with a field bound to nothing.

You do not need to add the option set to the solution separately for this to work: a set you create while a solution is selected belongs to it, the same way a table does.

Troubleshooting​

  • "An option set needs at least one option." — a set nobody can pick from is not usable. Add at least one option before saving.

  • "Option … appears more than once in this set." — two options share a name, which makes them indistinguishable to whoever picks one. Rename or remove one.

  • "Option … cannot be removed: records still hold this value." — records are using that option. Change those records to another option first; removing it would leave them holding a value that no longer means anything.

  • "Field … still uses this option set." — a field is bound to the set. Remove or re-point the field before deleting the set.

  • "No option sets exist yet" when adding an Option set field. — create the set first; a field can only bind to a set that already exists in this environment.

  • A saved record is rejected with "must be one of the … option set's values". — the value being written is not one of the set's options. This is the server refusing a value it cannot explain; pick an option from the dropdown.

  • An import fails with "targets option set … which is not in the package". — a table in the solution has a choice field whose option set is neither in the package nor already in the target environment. Add the option set to the solution and export a new version. Nothing was imported, so the target environment is untouched.

  • An import fails with "…already exists here, numbered from … but the imported one is numbered from …". — the target already has a set with that logical name, but it belongs to a different publisher, so the two are different sets that happen to share a name. They cannot be merged: the imported options are numbered from a range the existing records know nothing about. Rename one of the two sets, or import into an environment that does not have the other.

  • An import fails with "Option … cannot be removed: records still hold this value". — the imported set no longer has an option that records in this environment are still using. Importing brings an existing set up to date, but it will not delete an option out from under the records holding it. Change those records to another option first, or put the option back in the set being imported.

    (An option set already present in the target is otherwise updated, not refused: labels are refreshed, new options added, and unused removed options dropped. Options are matched by their assigned value, so renaming an option upstream updates it here rather than creating a second one.)

  • An import fails with "Option value … is outside the publisher's range". — the definition carries values belonging to a different publisher's range, which usually means the file was hand-edited. Values are the platform's to assign; export the set again rather than adjusting them by hand.