Skip to main content

Control - Foreign Field

A foreign field is an extension of a relationship field. It allows you to reference fields from records in another worksheet and either:

  • Store the referenced values in the current worksheet and keep them synchronized, or
  • Display them dynamically when opening the record

Example:
An Order worksheet is linked to a Contacts worksheet. You may want to display the contact’s phone number and job title directly in the Order worksheet.

Since foreign fields depend on relationship fields, please first understand how to use relationship fields.

Field Configuration​

1. Add a Foreign Field​

In the form editor, select the Foreign Field control from the left panel and drag it to the desired position.

2. Configure the Target Field to Display​

For example, to display the phone number from the Contacts worksheet in the Order worksheet:

  • A: Set the display name of the field in the current worksheet
  • B: Select an existing relationship field (e.g., "Contacts")
  • C: Select the target field from the related worksheet (e.g., "Phone Number")

The same configuration applies to other fields such as job title.

Result​

Cannot Select Relationship Field?​

If you cannot select a relationship field during configuration:

Please first add and configure a relationship field in the current worksheet, and ensure it is set to single record.

3. Choose Field Type​

Foreign fields support two types:

Display Only​

  • Retrieves values only when the form is loaded (e.g., opening a view or record detail)
  • Does not store data
  • Cannot be used for search, filtering, sorting, aggregation, formulas, or concat field

Store Data​

  • Stores the referenced value as a field in the current worksheet

  • Supports search, filtering, sorting, aggregation, formulas, and concat field

  • Pinyin Sorting Support:
    When enabled, Chinese content can be sorted alphabetically (A–Z by Pinyin).
    Note: Sorting index will not take effect when this option is enabled. Disable it if not needed.

Potential Synchronization Issues​

  • Data synchronization may have delays (not real-time)

  • When the source field changes, updates will sync to a maximum of 1,000 related records

    For example:

    • A contact is linked to 1,500 order records
    • If the contact’s phone number changes
    • Only 1,000 order records will be updated; the remaining 500 will not sync

How to Choose Between “Display Only” and “Store Data”​

  • Use Display Only if:

    • The field is not needed for search, filtering, or concatenation
    • You want real-time display with lower system overhead

  • Use Store Data if:

    • The number of related records is less than 1,000
    • You need full functionality (search, filtering, aggregation, etc.)

Foreign Field vs Dynamic Default Value​

Both foreign fields and dynamic default values can display values from related records, but they behave differently:

  • Foreign Field:
    Always stays in sync with the related record. Updates automatically when the source data changes.

  • Dynamic Default Value:
    Only retrieves the value at the time of record editing. After that, it does not stay linked.

When NOT to Use a Foreign Field

Example:
Product prices change frequently. When creating an order, the price should remain fixed once confirmed.

If a foreign field is used, historical order prices will change whenever the product price is updated.

Instead, use a currency field with a dynamic default value to capture the price at the time of creation.

Comparison Illustration

Was this document helpful?