Foreign Key
Foreign key fields store one related record key from another form. They are used when the current record should keep a direct relationship to a target form record.
Use a foreign key field when the relationship needs a source form and a deletion rule, such as an invoice linked to a contract, a shipment linked to an order, or a service ticket linked to an asset.
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 |
Foreign Key Field Config
| Setting | Description |
|---|---|
| Source Form | The target form that provides selectable records. It is required |
| Delete Rule | Controls what happens to this field when the related target record is deleted |
| Relation Data Scope | Optional Studio script that filters which target records users can select |
| Validate Trigger | Controls when selection validation runs: when the value changes, when the field loses focus, or when the record is submitted |
| Placeholder | Prompt text shown before users select a related record |
| Modal Title | Title shown in the record selection dialog |
| Search Placeholder | Prompt text shown in the search box inside the selection dialog |
| 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 |
Delete Rules
| Rule | Meaning |
|---|---|
| Restrict Delete | The target record cannot be deleted while it is still referenced |
| Set Null | The field is cleared when the target record is deleted |
| Cascade Delete | The current record is deleted together with the target record |
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 master records
- Only contracts in the current customer account
- Only assets that are available for assignment
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 | Suggested Rule |
|---|---|---|
| Invoice links to contract | Contract | Restrict Delete |
| Shipment links to order | Order | Restrict Delete |
| Ticket links to asset | Asset | Set Null |
| Detail record belongs to master record | Master Form | Cascade Delete |
Configuration Tips
| Tip | Description |
|---|---|
| Choose the delete rule carefully | Use cascade only when the current record should not exist without the target record |
| Keep the source form stable | Changing the source form changes the meaning of stored relation keys |
| Write a specific placeholder | A placeholder such as "Select a contract" makes the relationship clear |
| Add an invalid selection message | Use it to explain why a previously selected target record can no longer be used |