Working With Reference Controls

[Navigation] Global Search > Utilities > Form Builder

[Accordion] Overview

A Reference Control is not a standalone field type. Instead, it is a property that can be applied to many fields within Form Builder, allowing those fields to reference existing data (instead of, or in addition to, capturing new input). Reference Controls can be used with the following field types:

• Text Box / Multi-Line Text Box
• Dropdown & List Box
• Date & Time Picker
• Checkbox
• Repeating List & Grid View

A Reference Control allows you to display the value of a field from another form directly within your current form. It provides a controlled way to mirror information from a source field into a target field, ensuring consistency without requiring duplicate data entry.

This makes Reference Controls a more advanced option than the Data Source property, as they support two-way interaction rather than simply displaying data.

[Warning] Reference Controls are one of the most powerful ways to make Form Builder behave like a connected workflow tool rather than a standalone form. When configured intentionally, they reduce manual data entry, keep information current, and eliminate discrepancies between forms.

However, since they can overwrite data, use write-back selectively, and always test on a sample patient record first.

[Warning] Never allow more than one active form to overwrite the same field. This is the number one cause of unexpected demographic changes.

[Accordion] Where Reference Controls Are Used

Reference Controls are most commonly applied when a clinic wants to:

• Prefill patient information in a form
• Mirror data between forms without double entry
• Sync values from a master form to a workflow form

Common scenarios include:

• Patient demographic updates
• Consent & onboarding paperwork
• Intake/registration packets
• Periodic information reviews (address, SSN, DOB, emergency contacts)

[Accordion] How Reference Controls Work

1. Reference Only (Read-Only Mirror) When you set a Reference Control but do not enable Write Back to Reference Control, the field behaves like a window: “Show me what is stored there, but don’t change it”
   Example: Preferred Contact Method on the custom Patient Form > references > Patient Demographics: Preferred Contact Method. The form displays the value, but edits in your custom form do not change the original.
2. Reference + Write-Back (Two-Way Sync) When you enable Write Back to Reference Control, the field becomes a data bridge: “Show me the value, and if I edit it, then update it at the source as well.” This creates a workflow where the custom form both displays and updates the original record.

[Accordion] Field Property Synchronization and Structure Considerations

When a field is set as a Reference Control, it mirrors all properties from the source field, including:

• Field type (dropdown, text box, etc.)
• Dropdown or list options
• Column structure for repeating lists

[Warning] Changing the structure of the source or target field can break the reference and cause errors.

[Accordion] Example Scenario Goal: Display Preferred Mode of Contact from demographics in a Text Box on a Patient Intake Form.

Configuration

Result

• Form Load: The text box prefills with the existing demographic value
• Patient Update: If the patient edits the field and submits the form, the value is written back to Demographics
• Staff Workflow: Staff does not need to manually update the patient chart

This is a common workflow when sending forms through the Patient Portal

[Accordion] Practical Use Cases in Mental Health Clinics

Important Considerations

• Use Write Back intentionally: Only enable Write Back when updates are truly needed. Avoid using it on critical or historical fields that should not be overwritten
• Be cautious with patient-facing forms: Not all fields are appropriate for updates by patients, such as diagnoses, clinical status, or legal documentation
• Watch for unexpected updates: If a value changes unexpectedly, check whether another form references the same field with Write Back enabled
• Maintain field structure: Referenced fields must keep the same structure, as changing columns or options can break the reference
• Reference Controls are live links, not snapshots: Changes in this field affect all connected forms

[Accordion] Best Practices

• Use Reference Controls sparingly: Apply them only when you need to display or update existing data. Overuse can make forms harder to manage and troubleshoot
• Be intentional with Write Back: Enable Write Back only when updates are required; avoid using it on critical, historical, or legally-sensitive fields
• Protect clinical and legal data: Do not allow patient-facing forms to write back to fields such as diagnoses, clinical status, consent, or legal records
• Clearly label referenced fields: Make it obvious to users when a value is being pulled from another form to prevent confusion or accidental changes
• Avoid multiple write-back sources: Ensure only one form writes back to a specific field. Multiple write-back references can cause unexpected overwrites
• Test all reference behavior: Verify that values display correctly and write back only when intended, especially after form updates
• Plan for historical integrity: Consider whether the referenced data should reflect the current value or remain fixed at the time of the encounter
• Document your references: Keep internal notes on which fields use Reference Controls and Write Back to simplify maintenance and future updates
• Do not change referenced field structure after deployment: Structural changes can break syncing

[Accordion] When Not to Use Reference Controls

• Historical or audit-sensitive data: Avoid Reference Controls on fields that should remain unchanged over time, such as past diagnoses, clinical assessments, or signed documentation
• Patient-editable clinical fields: Do not use Reference Controls with Write Back on fields that patients should not update, including diagnoses, treatment decisions, or clinical status
• When a snapshot is required: If you need to capture the value as it existed at the time of the visit, use a standard field instead of a Reference Control
• When multiple forms write to the same field: Using Reference Controls with Write Back in multiple places can lead to unexpected overwrites and data conflicts
• Complex or derived data: Avoid referencing fields that are calculated, conditional, or dependent on layered logic, as this can cause confusion or unintended results
• When simplicity is preferred: If displaying or collecting new data is sufficient, a standard field is often clearer and easier to maintain than a Reference Control