/
Best Practices and FAQs for Administrators on Custom Fields Management

Best Practices and FAQs for Administrators on Custom Fields Management

Best practices

Naming

  • Use a short, descriptive, machine-friendly internal name in lower camel case,
    e.g. localCaseIdentifier, icuAdmissionDate, exposureLocation.

  • The internal name must be unique within its context (enforced by the system).

  • Do not rename a field after data has been entered. The name is used by the
    REST API and integrations; renaming can break existing references. There is no
    migration mechanism for names.

  • Put the display label into the Translations section instead of relying on the
    internal name — that is what users see.

Planning the layout

  • Sketch the form layout before creating fields: which section (UI group), in which
    order, with which widths.

  • Use gaps in the Line Position (e.g. 10, 20, 30) so new fields can be inserted
    later without renumbering.

  • Only set a Line Weight below 1.0 when another field shares the same line —
    a half-width field alone on a row leaves an empty half of the form.

  • Verify the result on a real record after creating a field: open a case and check
    that the field appears in the right section, order and width.

Options and default values

  • Keep option values stable. When users edit old records, the previously stored
    value must still match one of the defined options for the field to display and
    validate correctly. Removing or renaming options can make old data hard to read.

  • If the default value is removed from the options, the default is cleared — set it
    again after changing the options.

  • Prefer YES_NO_UNKNOWN over CHECKBOX whenever "unknown" must be distinguished
    from "no".

Translations

  • Add a translation for every language used in your deployment, at least for
    the name (label); the description is optional.

  • If a translation is missing, users see the internal name — which looks technical.

  • Do not add two rows for the same language (the last one wins silently).

Visibility

  • Use Visible for Diseases to keep forms clean: define disease-specific fields
    only for the diseases that actually need them.

  • Remember: no disease selected = visible for all diseases.

  • The visibility check uses the record's disease at the time the form is opened.
    If the disease changes later, the field set is re-evaluated when the form is
    opened again.

Lifecycle

  • Disable (deactivate) a field to stop collecting data while keeping existing
    values — this is the safe "retire" option.

  • Delete only when you are sure the data is no longer needed: deletion removes
    all values of the field from all records.

  • Use Clone to create similar fields (e.g. the same field for another UI group);
    you only need to adjust a few settings afterwards.

FAQ

Can I change the field type after creating a field?

No. The Field Type selector is locked when editing an existing field. You must
create a new field (and, if needed, delete or deactivate the old one). The type
cannot be migrated automatically.

Can I rename a field?

The UI technically allows you to change the internal name when editing. However,
the name is a system identifier used by the REST API and integrations, and there is
no migration tooling for names — renaming can break integrations. Renaming is
therefore discouraged. The name must remain unique within the context.

What happens to entered values when I deactivate a field?

Nothing. Deactivation only hides the field from forms. All values remain in the
database and reappear if the field is reactivated.

What happens when I delete a field?

The field definition and all values entered for it are deleted. A confirmation
dialog warns about this; deletion also asks for a reason. This cannot be undone.

Why don't I see my custom field in a form?

Check in order:

  1. Is the field saved and Active?

  2. Is the record's disease one of the field's Visible for Diseases selections
    (or is the list empty = all diseases)?

  3. Is the field assigned to the UI group of the form section you are looking at?

  4. Does the context (Case / Epi Data / Exposure) match the form you opened?

What does the Required (*) marker mean?

The field is mandatory — the form cannot be saved until the field has a value.

Can I enter a value that is not in the option list of a Combo Box?

No. The Combo Box only offers the configured options; the value must be one of them.

Why is a field shown but greyed out?

The field is configured as Read Only — it displays a value but cannot be edited
by data-entry users.

How are values stored (do I need to worry about the database)?

No. The system stores field metadata and per-record values automatically. Adding
fields does not require any database administration. Metadata is stored in a
customizablefieldmetadata table; values are stored per entity in a
customizablefieldvalue table.

Are customizable fields available via the REST API?

Yes, for integration purposes there are REST endpoints:

  • /customizablefieldmetadata — manage field definitions (list, get by UUID,
    get by context, get by UI group, get by name+context, save, update, delete,
    clone, activate/deactivate).

  • /customizablefieldvalue — read and write field values for entities
    (get values for entity, save values for entity, delete values for entity, plus
    generic CRUD).

These endpoints are primarily intended for developers and external systems.

How many custom fields can I define?

There is no enforced limit in the implementation. As with standard fields, keep the
number per form reasonable — very large numbers of fields make forms long and slow
to review. Plan with the layout guide in mind.