Search
Search fields let users select one record from another form. The stored value is the selected record identifier, while the runtime page shows the selected record by its readable identifier.
Use a search field when a record should point to one related record, such as an order selecting one customer, a task selecting one project, or an expense selecting one cost center.
Basic Settings
| Setting | Description |
|---|---|
| Name | The field label shown to users. It is required and should describe the relationship clearly |
| API Name | The stable technical name used by data APIs, scripts, formulas, imports, and integrations. It is required |
| Required | Requires users to select a related record before the record can be saved |
| Readonly | Shows the selected related record but prevents users from changing it |
| Disabled | Makes the field unavailable for normal use |
| Hidden | Stores the selected value while hiding it from normal form pages |
Search Field Config
| Setting | Description |
|---|---|
| Source Form | The target form that provides selectable records. It is required |
| Relation Data Scope | Optional Studio script that filters which target records users can select |
| Placeholder | Prompt text shown in the field before users select a record |
| Modal Title | Title shown in the record selection dialog |
| Search Placeholder | Prompt text shown in the search box inside the selection dialog |
| Validate Trigger | Controls when selection validation runs: when the value changes, when the field loses focus, or when the record is submitted |
| Input Status | Adds a visual status to the field, such as warning or error |
| Invalid Selection Message | Custom message shown when the selected record is invalid or unavailable |
| Field Color | Sets the display color used for the field |
| Help Text | Helper copy shown near the field. Use it to explain which related record users should choose |
Source Form
The source form controls which records users can select. Only enabled forms are shown as normal options. Department, organization, and member system forms are excluded from this field type because they have dedicated field types.
After a source form is selected, users search and choose records from that form at runtime. The search and display use the target form's identifier field.
Relation Data Scope
Use Relation Data Scope when this field should only allow a scoped set of records from the source form.
Examples:
- Only active customers
- Only products in the current row's category
- Only records visible to the current department
The script is bound to this source field and runs before the selection dialog loads target records. It returns a relationDataFilter condition that uses target-form field API names.
Do not configure this filtering rule on the target form's page events. See Relation Data Scope for the payload and response contract.
Common Examples
| Scenario | Source Form | Field Meaning |
|---|---|---|
| Order selects a customer | Customer | The order belongs to one customer |
| Task selects a project | Project | The task is linked to one project |
| Expense selects a cost center | Cost Center | The expense is charged to one cost center |
| Contract selects an account | Account | The contract is associated with one account |
Configuration Tips
| Tip | Description |
|---|---|
| Use a clear name | Name the field after the related business object, such as Customer or Project |
| Check the target identifier | The target form should have a clear identifier field so users can recognize records in the selection dialog |
| Add a useful placeholder | A placeholder such as "Search and select a customer" helps users understand the expected action |
| Add an invalid selection message | Use it when users need a business-specific reason for why a selected record is no longer valid |