¶ Foreign Key Reference Field
A Foreign Key Reference Field is designed to act as a "foreign key" to another form, facilitating data relationships and integrity within the system. Foreign Keys on a form represent a single record in another form table. A reference field on your form is a "Foreign Key" that holds the "Primary Key" of one record from another table.
An example of a Reference Field form.
The reference field provides the following capabilities:
- Dynamic Filtering: Simply begin typing upon tabbing into the Reference Field to filter the list for entries containing the typed characters.
- Keyboard Navigation: Use the up and down arrow keys to navigate through the available options in the filtered list.
- Easy Selection: Click outside the field or press the Tab key to confirm the selection of the highlighted entry.
- Instant Preview: The "Show Preview" icon enables viewing a snapshot of the referenced record without leaving the current context.
- Extended Search: Clicking the search icon initiates a more comprehensive search dialog for locating specific records.
- Maximum Search Results: The menu will show a max of 100 records based on your search. If the value you want isn't in the list consider refining your search until fewer than 100 possibilities remain in the list.
¶ Form Designer
¶ Adding a reference field to a form
In Form Designer you can add a reference field by dragging the reference field icon onto the form from the toolbar. 
¶ Reference Field Properties
Double clicking a reference field in Form Designer will display the reference field's Properties, Security, and History.
¶ Field Details (Foreign Key/Reference)
In addition to the Default Field Properties Reference fields expose the following additional properties:
- Table:
The table whose Primary Key will be used in the field as a foreign key for the form being edited. In other words: The "Target" table for the reference field. - Search Style:
The type of search that is performed when users type search strings into the field.
-Contains (Default): List any record in the target table that contain the data entered so far.
-Starts With: List any record in the table that starts with the data entered so far.
-Ends With: List any record in the target table that end with the data entered so far.
-Literal: List any records that exactly match the text entered (including query characters) - FTS Index:
Allow the reference field to be indexed for full text search
¶ Reference Field Security
Other than the basic field security model Reference fields require that the user accessing the fields also have the appropriate access to the referenced form and field as well.
Details about field security are available here: Field Security
¶ Reference Field History
TODO: Link to the basic field history document that doens't exist yet (Probably nothing specific to reference fields here)
¶ Accessibility
Details about field accessibility are available here: Accessibility
¶ Scripting
¶ Setting the value in script.
In order to set the value of a reference field in any script, set the value directly to the system_id of the record in the target table.
Example: $current.people_reference = "b34ec2ce-c4b9-b538-08dc-3384462e8b4b"
¶ Reading the value in script.
When you retrieve a record that contains a reference field there are several values returned immediately:
"displayValue": "John Doe",
"id": "b34ec2ce-c4b9-b538-08dc-3384462e8b4b",
"table": "people",
"url": "https://<your API Server>/api/table/people/b34ec2ce-c4b9-b538-08dc-3384462e8b4b"