Defining a Field
The definition form control by control, the full walkthrough, the rules for keys, creating a field from inside a record, every rejection, and what can still be changed after saving.
Field definitions live on the Custom Fields screen in the Administration workspace. This page walks the whole form: every control, what reveals it, what it does, and what happens when a save is refused. Control names are given as they appear in the English interface.
Where the screen is
Custom fields are administered from four related screens.
- The Custom Fields screen itself, in the Administration workspace, is where definitions are created, edited, deactivated and deleted, and where a validator is attached.
- The Field Groups screen, reached from a link in that page's header, gathers a record type's fields under headings.
- The Value Types and Entity Types screens, also reached from that header, are read-only references. They have no sidebar entry of their own by design.
- The Add custom field link at the end of the Custom Fields section on a record form opens the same definition form in a side panel, without leaving the record.
The form, control by control
Not every control is always visible. Several appear only once a particular value type or scope is chosen, which is why the form looks shorter than this table on any given day.
| Control | What it does | When it appears |
|---|---|---|
| Entity Type | Chooses the kind of record the field belongs to. Record types with no screen in this app are listed after the rest and marked API only — a field on one of those is reachable through the API but has nowhere to render. | On create. Fixed and not editable when the form is opened from inside a record, and permanent after saving. |
| Key | Sets the machine name used in error messages, exports and the API. Lower case, must start with a letter, and may contain only letters, digits and underscores. | On create only. Permanent after saving. |
| Label (English) | The English label shown above the input on every form. Required. | Always. |
| Label (Arabic) | The Arabic label. Optional — an Arabic reader sees the English label when this is blank. | Always. |
| Value Type | Chooses one of the twenty-two types, deciding the control, the validation and the storage. Selecting it is what reveals the Options box, the Validator dropdown or the Target Entity Type dropdown. | On create only. Permanent after saving. |
| Placeholder (English) | Optional greyed-out hint shown inside the empty input, in English — for example "e.g. Enter your shirt size". | Only for the value types whose control has a placeholder at all. Boolean, Rating, Color, Date and the other picker-based types have none. |
| Placeholder (Arabic) | The same hint in Arabic. | Only for the value types whose control has a placeholder at all. Boolean, Rating, Color, Date and the other picker-based types have none. |
| Options | Holds the list of allowed answers, one row per option, with an English and an Arabic label for each. See the Options page. | Only when the value type is Select or MultiSelect. |
| Validator | Attaches one of the 13 built-in format checks. Defaults to no validator. See the Validators page. | Only when the value type is Text. It is never shown for the other twenty-one types. |
| Validator Parameter | Supplies the setting a parameterised check needs — a country dropdown for Postal Code, free text for the other five. | Only once one of the six parameterised validators is chosen. |
| Target Entity Type | Pins the field to one kind of record, so every value must point at a record of that kind. Its first option, Not pinned — any allowed type, is a real and permanent choice rather than a placeholder: leave it there and each value names its own kind of record instead. It is the only way to clear a pin, so it stays available even when the list of kinds is empty or fails to load, and the control is never disabled. | Only when the value type is Entity Reference. A User Reference field never shows it, because its one legal target is fixed by the platform and there is nothing to choose. Unlike the three permanent settings, this one can be changed later — read the warning on the edit form before you do. |
| Field Group | Puts the field under one of the record type's field groups, or under no group. Changing the record type clears the choice. | Only when you hold the field-groups view permission, and — on the main definitions screen — once a record type has been chosen; the inline panel shows it as soon as you have the permission, since it already knows the record type. Shown either way even when the chosen record type has no groups yet, offering only "no group" until one exists. |
| Required | Refuses a save that leaves the field blank. Whitespace-only counts as blank for every value type. | Always. |
| Sort Order | Positions the field relative to the other custom fields on the form. Lower numbers come first. | Always. |
| Sensitivity | Labels how the field's contents should be treated — Unclassified, Internal, Confidential or Restricted. Defaults to Unclassified. It is a label for reporting and export handling; it does not control who can see the field. | Always. |
| Include in exports | Marks whether this field's values should be included in exports. On by default. It is tidying rather than a permission — anybody who can already read the field can still read its values elsewhere — and it does not remove the field from the definitions export, which lists it either way. | Always. |
| Active | Whether the field is still offered on forms. Turning it off retires the field without touching the answers already stored against it. | On edit. A newly created field is active. |
| Global (all tenants) | Creates the field for every workspace on the platform rather than for one. Global fields skip the per-workspace quota, and only a platform administrator can edit or delete them afterwards. | Only for a platform Super Admin working with no workspace selected. On create only — a field's scope is permanent. |
Step by step
The whole flow, for the ordinary case of a workspace-scoped field.
Open the Custom Fields screen and choose Add
The screen lists every field your workspace can see, including any global fields inherited from the platform. Global rows carry a badge and offer no edit or delete controls.Pick the record type
Choose the kind of record the field belongs to. If your record type is marked API only, stop and reconsider — the field will save, but nothing in the interface will render it.Choose the value type
Pick from the twenty-two. This is the decision that cannot be undone later, and it is also what makes the Options box, the Validator dropdown or the Target Entity Type dropdown appear further down the form.Name the field
Enter the English label, an Arabic label if you have one, and the key. The key is permanent, so pick something you will still recognise in an error message a year from now.Fill in the type's own settings
For Select and MultiSelect, add the options. For Text, choose a validator if you want one and supply its setting. For Entity Reference, decide whether to pin a Target Entity Type. Add placeholders if the control takes them.Set behaviour and position
Turn Required on or off, set the Sort Order, and choose a Field Group if you use them. A group only offers itself if it belongs to the record type you chose.Set the classification
Sensitivity defaults to Unclassified and Include in exports defaults to on. Leave both alone unless you have a reason — the export default in particular exists so that fields are never quietly missing from a spreadsheet.Save, and read the message if it is refused
A refusal is always specific about what is wrong. The table further down this page lists every rejection you can hit and what it means.
Choosing a key
The key is the field's machine name. It appears in every error message, in the spreadsheet export, and in the API. It must be lower case, start with a letter, and contain only letters, digits and underscores — and it must be unique for that record type within your workspace.
| Key | What happens |
|---|---|
| shirt_size | Accepted. This is the shape to aim for. |
| preferred_foot_2 | Accepted. Digits and underscores are fine after the first character. |
| Shirt_Size | Refused. Keys are lower case. |
| 2nd_language | Refused. A key must start with a letter. |
| shirt-size | Refused. Hyphens are not part of the grammar — use an underscore. |
| shirt size | Refused. Spaces are not allowed. |
Adding a field from inside a record
You do not have to leave what you are doing to add a field. Every form that supports custom fields ends its Custom Fields section with an Add custom field link, gated behind the create permission.
Click Add custom field
The definition form opens in a side panel rather than a dialog on top of a dialog. The record form behind it stays visible and readable, and nothing you have already typed into it is lost.Note the record type is fixed
The record type is shown as context rather than as a dropdown — it is whatever screen you are already on. Every other control from the full screen behaves the same way here, validator picker included, with one addition this panel has that the full screen does not — see next.Optionally attach a shared Option Set
For Select or MultiSelect, this panel — and only this panel, not the main definitions screen's own form — offers an Option Set picker alongside the manual Options editor. Choosing one binds it to the field the moment it is created, in the same step: any manual options typed in above are kept, merged with the set's own rather than replaced by it. Shown only when you hold both the option-sets view and bind permissions.Fill in and save
The panel closes and the new field appears immediately in the still-open record form, empty and ready to fill in.Carry on with the record
Fill in the new field along with everything else and save the record once. The definition and the answer are two separate saves, in that order.
What gets rejected, and why
Every refusal at definition time carries a specific message. These are the ones you can actually hit from the form or from a request that bypasses it.
| Situation | What you see |
|---|---|
| A key that already exists for that record type | Refused as already existing. Keys are unique per record type within a workspace — the same key on a different record type is fine. |
| A record type that is not registered | Refused, naming the key: it is not a registered entity type. Only reachable by bypassing the dropdown. |
| A Select or MultiSelect field with no options | Refused: options are required for Select fields. |
| Options supplied for a type that does not take them | Refused: options are only allowed for Select fields. |
| A validator attached to a non-Text field | Refused, naming the type: a validator can only be attached to a Text field. The dropdown is not even shown for those types, so this is the server refusing the same thing a second time. |
| A parameterised validator with its setting left blank | Refused, naming the validator: it requires a parameter. |
| A setting supplied for a validator that takes none | Refused, naming the validator: it does not accept a parameter. |
| Marking a field required while a role or group restricts it | Refused, naming the field: it cannot be made required while it is restricted. Remove the restriction first, or leave the field optional. |
| A field group belonging to a different record type | Refused: the selected field group belongs to a different entity type. Changing the record type on the form clears the group choice for exactly this reason. |
| Pinning a target that is not a registered record type | Refused, naming the identifier: it is not a registered entity type. Only reachable by bypassing the dropdown, which offers nothing unregistered. |
| Pinning a User Reference field to anything but a user account | Refused, naming the value type and listing what it does allow. The dropdown is not shown for that type at all, so this is the server refusing what the form already declined to offer. |
| Creating a global field without being a platform Super Admin | Refused: only a platform Super Admin can create a global custom field. |
| Passing your plan's field limit | Refused on quota. The Free edition allows zero fields; every other plan has its own maximum per workspace. Global platform fields do not count against it. |
After saving: what can still change
Three things are permanent, and everything else is not. It is worth knowing which is which before you save rather than after.
Editable at any time
- Both labels, and both placeholders
- Required — unless a role or user group restricts the field
- Sort Order, and the Field Group
- Sensitivity, and Include in exports
- Active, which retires the field without touching its stored answers
- The options list — though renaming an option changes what existing records display
- The validator and its setting — though this never re-checks answers already saved
- The Target Entity Type on an Entity Reference field — answers already stored keep working, and the next save of one of the old kind is refused until it is picked again
Permanent once saved
- The record type
- The key
- The value type
- The scope — workspace or global
There is no migration path for any of the four permanent settings. Getting one wrong means deleting the field and starting again, which destroys the answers already recorded against it.
Checking it worked
Four quick checks that catch almost every mistake.
- Open a record of that type. The Custom Fields section should show your new field, empty, with the label and placeholder you set.
- Type a value and save. No error means the value was accepted; reopen the record and confirm it is still there.
- Clear the value and save again. On an optional field this should succeed and leave the field genuinely empty, not showing the old value.
- Check the record list. Your field should be an extra column there too, showing the answer for every record at once.