SIGNALS Docs
Reader View

Custom Fields

Define, validate, display, query, and automate typed custom data on Signals entities.

Overview

Custom fields add tenant-defined data without changing an entity's database table. Definitions live in custom_fields; values use typed columns in the custom_field_values EAV table. REST and MCP expose those values as a flat custom_fields object, so callers never need to understand EAV storage.

The registered modules are: Account, Vehicle, Facility, Equipment Test, CatalogueItem, CatalogueItemGroup, Repair, StockCheck, WarehouseTransfer, Asset, Activity, Warehouse, Rental, RentalLine, Invoice, Address, ApprovalChainDefinition, CreditNote, Document, EquipmentTestResult, InvoicePayment, PurchaseOrder, RentalProject, Report, Service, and Workflow.

Manage definitions in Studio

Open Admin → Data → Custom Fields at /admin/settings/custom-fields. Choose an entity in the left rail, then create or select a field. Studio protects unsaved edits when moving between fields or entities and shows validation errors beside the responsible control.

Each definition controls:

Setting Contract
Display name Human-readable label on forms and detail views.
Key Flat API/MCP key. Must start with a lowercase letter, contain only lowercase letters, numbers, and underscores, and not collide with a core schema field.
Module Registered entity type. It cannot change after creation.
Field type Typed editor, validation, storage, filtering, and sorting behavior. It is locked once a value row has existed.
Group Optional visual section. Drag fields in the rail to reorder them atomically.
List Required for Lists and MultiLists; forbidden for other types.
Required/default Server-enforced on create. Conditional required rules may depend on another core or custom schema field. Defaults are type-validated.
Visibility Conditional rules plus role visibility. Both UI and server write boundaries enforce them.
Placement create, edit, detail, and quick independently control where a field is available.
Searchable Enables documented custom_fields. filters and supported EAV sorting for the field.
Active Inactive definitions disappear from active forms, schema, filters, and agent value tools without deleting stored data.

The role selector is populated from the actual role registry. Rule fields are selected from the resolved module schema rather than entered as unchecked text.

Field types

The API and MCP use lowercase snake_case values for field_type (for example string, date_time, and multi_lists). Integer codes and PascalCase spellings are rejected. Responses also include the display name in field_type_label.

API value Editor and public value EAV storage
string Single-line string value_string
text Multi-line plain text value_text
number Decimal number value_decimal
boolean Boolean checkbox value_boolean
date_time ISO date and time value_datetime
date ISO date value_date
time Time value_time
email Valid email address value_string
website Valid URL value_string
lists One option; API/MCP read the option label value_integer list-entry ID
multi_lists Option labels array value_json list-entry IDs
auto_number Read-only generated value value_string
currency Decimal monetary value value_decimal
telephone Telephone string value_string
file_image Uploaded file/image metadata value_json
rich_text Markdown-formatted text value_text
json_key_value JSON object value_json
colour Colour value value_string
percentage Decimal percentage value_decimal

FileImage values are stored through the attachment service. EAV contains safe metadata (attachment_id, UUID, original name, MIME type, and size), not a filesystem path. Replacing or clearing the field deletes the preceding attachment. Caller-supplied attachment metadata is rejected unless it is the entity's existing value.

AutoNumber settings contain optional prefix and suffix, a pad_width from 1–20, and a positive starting_value. The number is assigned once on entity creation. Changing formatting never rewinds the persisted sequence or reuses issued values.

Groups and lifecycle safety

Groups are managed at /admin/settings/custom-field-groups. Deletion is blocked while any field remains assigned. Moving a field to a group or explicitly to no group uses patch semantics: an omitted group leaves it unchanged; null removes the assignment.

Studio shows the count of entities with non-empty values. A definition can be deleted only when that count is zero. If it has populated values, deactivate it instead. Deactivation preserves the definition and EAV history. A type remains locked after any value row has existed, even if its value was later cleared.

REST API

Definitions use /api/v1/custom_fields. Prefer a semantic type name:

{
  "name": "po_reference",
  "display_name": "PO reference",
  "module_type": "Rental",
  "field_type": "string",
  "is_searchable": true
}

Entity create/update endpoints accept the following custom_fields request fragment. Success responses return the field map at data.custom_fields within the resource:

{
  "custom_fields": {
    "po_reference": "PO-12345",
    "service_level": "Gold",
    "delivery_flags": ["Tail lift", "Timed slot"]
  }
}

Unknown, hidden, misplaced, invalid, or conditionally required values return HTTP 422. AutoNumber is generated by the server. List inputs accept public labels or valid list-entry IDs; responses return labels.

Filtering and sorting

Filter with ?filter[field][operator]=value:

?filter[custom_fields.po_reference][contains]=PO-
?filter[custom_fields.credit_score][gte]=700
?filter[custom_fields.service_level][eq]=Gold
?filter[custom_fields.delivery_flags][contains]=Tail%20lift

The schema advertises operators supported by each field type. Unary null, not_null, present, and blank require true (HTTP also accepts 1). An absent EAV row satisfies null and blank; JSON null and empty objects/arrays have field-specific presence rules. Invalid, unknown, non-searchable, or unsupported filters return a coded 422; see API Conventions.

Sort a supported searchable field with ?sort=custom_fields.po_reference or ?sort=-custom_fields.po_reference. Missing values sort last in both directions. Unsupported sorts are reported in meta.ignored_sorts. MultiLists, FileImage, and JsonKeyValue are not sortable.

MCP

Use describe-custom-field-schema before writing values. It reports active keys, semantic types, required and visibility rules, role/placement availability, list choices, filter operators, and sortability.

Definition workflow:

  1. list-custom-field-groups or create-custom-field-group when grouping is needed.
  2. create-custom-field with field_type=string (or another API value).
  3. get-custom-field / update-custom-field for inspection and patching.
  4. deactivate-custom-field rather than deleting a used definition; reactivate-custom-field restores it.

Value workflow:

  1. describe-custom-field-schema for the module.
  2. get-entity-custom-fields for current values.
  3. set-entity-custom-field-values with only the keys to patch.

The tools call the same guarded action and validator paths as REST and browser forms. They require custom-fields:read or custom-fields:write token abilities and the corresponding user permissions.

Schema and integration guidance

The module schema registry merges active custom definitions with core fields. A custom key can never overwrite a core schema key. Schema metadata is the source of truth for type, filter operator, sort, list binding (option_list_id), validation, visibility, roles, and placements.

Plugins and external apps should discover definitions rather than cache them indefinitely. Re-read the schema after administrators create, reorder, deactivate, or change a definition. See the machine-readable OpenAPI document at /docs/api.json and the agent guide in SKILL.md.

At a glance

Define custom data fields that extend entities with additional information. Fields can be filtered by module type.

Action Description
Create Define a new custom field with type, module, group, and validation
Edit Update field configuration
Delete Remove a field definition