Dependent Reference

Dependent Reference Attributes create dynamic, context-aware selection lists where the available options change based on values in other fields. This feature supports complex data relationships and advanced filtering capabilities.

Overview

When a reference attribute is configured as dependent, its available options are filtered based on the values of one or more "parent" attributes. This creates cascading dropdown behavior commonly seen in scenarios like Project → Department → Employee selections.

Key Benefits

• Data Integrity: Prevents invalid combinations by filtering available options
• Improved User Experience: Users see only relevant choices
• Business Logic Enforcement: Implements complex business rules through configuration
• Dynamic Behavior: Options update automatically when parent values change
• Performance: Reduces data load by showing only applicable options

Configuration Steps:

Step 1: Set Up Query Definition

For details, see Query Definition Configuration.

• Configure Query Parameters: Add parameters with valid expressions for dynamic filtering.
• Add Parent Filters: Specify parent types in the Query Builder to enable dependency.
• Set Default Values:
  • If Dynamic Value is enabled, use query parameters as default values for parent filters.
  • If Static, select a specific parent instance as the default value to control dependent attribute changes.
• Add State/Attribute Filters: Apply additional filters as needed for precise control.

Step 2: Integrate Query Definition with Reference Attribute

• Assign the configured Query Definition to the reference attribute in its configuration settings.

Common Use Cases

• Geographic Hierarchies: Country → State → City
• Project Structure Categorization: Project → Building → Level
• Organizational Structure: Division → Department → Team → Employee

Each level filters the next based on hierarchy, ensuring only relevant options are shown at every step.

Detailed Behavior and Test Scenarios

Understanding how dependent reference attributes behave in different scenarios is crucial for proper implementation and testing.

Query Definition Compliance

All configured Query Definition filters must be honored:

Filter Type	Behavior	Example
Parent Filters	Options filtered based on parent field values	Department → Employee filtering
State Filters	Only instances in specified states are shown	Show only "Active" employees
Attribute Filters	Additional filtering based on attribute values	Show employees with "Manager" role

Value Management Rules

Note: The following examples focus on parent filters only. Applying state or attribute filters will further narrow the results.

Filtering Behavior Summary

• Parent Field: Departments
• Dependent Field: Employee

Scenario	Parent Field Value	Dependent Field Behavior
No Dependency	Any value	Show ALL available options
Parent Empty	null, undefined, or []	Show ALL available options
Single Parent	"Engineering"	Show options filtered by Engineering
Multi Parent	["Eng", "Sales"]	Show options from Engineering OR Sales
Parent Changed	"Eng" → "Sales"	Clear current value, show Sales options

Key Rule: Multi-select parent values use OR operation - dependent field shows options matching ANY of the selected parent values.

Parent Value Changes

1. Initial State: Parent = null, Dependent = null
2. Parent Selected: Parent = "Engineering", Dependent options filtered to Engineering employees
3. Dependent Selected: Parent = "Engineering", Dependent = "John Doe (Engineering)"
4. Parent Changed: Parent = "Sales", Dependent value is cleared automatically
5. New Selection: Parent = "Sales", Dependent can select from Sales employees

Multi-Level Configuration

Three-Level Cascade: Project → Department → Employee dependency chain

1. Initial State: All fields empty (Project = null, Department = null, Employee = null)
2. Level 1 Selection: Select Project = "Demo Project" → Department options show only departments from this project
3. Level 2 Selection: Select Department = "Engineering" → Employee options show only Engineering employees
4. Change Level 2: Change Department to "Sales" → Employee value clears automatically, dropdown updates to show Sales employees only
5. Change Level 1: Change Project to "Test Project" → Both Department and Employee values clear, cascading the dependency chain

No Dependency Configured

When no parent filters are configured:

• Show all available options regardless of other field values
• No automatic clearing of values
• Standard reference behavior applies

Context-Specific Testing

• Parent Field: Project
• Dependent Field: Technology

Create/Edit/View Layouts

Scenario: Creating new or editing existing instance with parent & dependent reference attributes configured
- User selects Project "Web Development" → Technology options show "React, Angular, Vue"
- User selects Project "Mobile Development" → Technology options show "React Native, Flutter, Swift"
- Verify dependent field clears when parent changes
- Save and verify data integrity

Worksheet Widget Testing

Inline Editing:

Test Case: Tasks worksheet with Project → Technology dependency
1. Change Project from "Web Development" to "Mobile Development"  
2. Verify Technology field clears and shows Mobile Development technologies only
3. Select new technology and save
4. Verify row updates correctly in worksheet

Insert New Row:

Test Case: Adding new employee via worksheet
1. Click "Insert New Row" 
2. Select Project = "Web Development"
3. Verify Technology dropdown shows only Web Development technologies
4. Complete other required fields and save
5. Verify new row appears with correct relationships

Edge Cases and Error Scenarios

• Parent Field: Departments
• Dependent Field: Employee

Data Integrity Scenarios

Orphaned References:

Test Case: Parent option is deleted after dependent selection
1. Create record with Department="IT", Employee="John (IT Employee)"
2. Delete "IT" department from system
3. Verify dependent field handling:
    - Department (parent) field is cleared
    - Employee (dependent) field retains its current value, and the options list displays all employees

Permission Changes:

Test Case: User loses edit permission for dependent field
1. User selects Department="Confidential", Employee="Jane (Confidential)"  
2. User permissions change to read-only for the Employee field
3. Expected behavior:
  - Both parent and dependent values remain unchanged
  - Employee field displays in read-only mode and cannot be edited
  - When Department field changes, Employee value is preserved (no auto-clearing)

Troubleshooting

Options Don't Update When Parent Changes

Symptoms: Reference options remain static despite parent field changes

Causes & Solutions:

• Browser Cache: Clear browser cache & retry
• Is Dynamic Value Not Set: Ensure Is Dynamic Value: true in parent filter configuration
• Query Definition Missing: Verify Query Definition is properly configured for dependent reference attribute
• Parameter Mapping Error:
  • Verify parameter names match between parent filters and attribute filter expressions
• Schema Configuration Error: Verify that required schema is properly deployed to the tenant