@cplace/test-mcp-server 1.0.0 → 1.1.0

package/dist/widget-specifications/_research_from_ga_products/cf-platform-incomingReferences/research.md

@@ -0,0 +1,488 @@
+# Research: cf.platform.incomingReferences Widget
+
+## Widget Overview
+
+**Widget ID:** `cf.platform.incomingReferences`
+**Repository:** main (cf.cplace.platform)
+**Icon:** `fa-external-link fa-rotate-90`
+**Definition Class:** `cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/IncomingReferencesWidgetDefinition.java`
+
+## 1. Purpose
+
+### Short Description
+The Incoming References widget displays all formal reference attributes from other entities that point to the current entity, organized by source type, attribute, and space.
+
+### Detailed Description
+This widget provides a "backlinks" view showing where the current entity is referenced in the data model through structured reference attributes. It queries the database to identify all custom reference relationships pointing to the entity and presents them grouped by source type, attribute name, and workspace. The widget distinguishes between references with actual values (entities currently referencing this one) and available reference types without values (configured but unused references).
+
+## 2. Use Cases
+
+### Primary Use Cases
+
+1. **Dependency Discovery**
+   - **Scenario:** A user views a Product entity and wants to know which Projects reference it
+   - **Benefit:** Understand what depends on this entity before making changes or deletions
+   - **User Action:** Open the entity detail page and view the incoming references widget
+
+2. **Data Model Relationships**
+   - **Scenario:** A data model designer wants to understand how entities relate to each other
+   - **Benefit:** Visualize the actual usage of reference attributes in the system
+   - **User Action:** View type definition pages with the widget to see reference patterns
+
+3. **Impact Analysis**
+   - **Scenario:** Before deleting or archiving an entity, check if other entities reference it
+   - **Benefit:** Prevent broken references and data inconsistencies
+   - **User Action:** Review incoming references before performing destructive operations
+
+4. **Relationship Navigation**
+   - **Scenario:** Users need to navigate from a referenced entity back to referring entities
+   - **Benefit:** Bidirectional relationship navigation without manual searching
+   - **User Action:** Click on reference groups to view the list of referring entities
+
+5. **Cross-Space Visibility**
+   - **Scenario:** Entities in one workspace are referenced by entities in other workspaces
+   - **Benefit:** Understand cross-workspace dependencies
+   - **User Action:** View references marked with source space indicators
+
+### When to Use This Widget
+
+**Use this widget when:**
+- Your data model includes formal reference attributes between entity types
+- You need to track which entities reference a particular entity
+- You want to provide users with impact analysis capabilities
+- You need bidirectional relationship navigation
+- Your content model has complex interdependencies
+
+**Do NOT use this widget when:**
+- You only need to display outgoing references (use attribute widgets instead)
+- You want to track wiki-style hyperlinks in rich text (use `cf.platform.incomingLinks` instead)
+- The entity type doesn't support custom references (e.g., Person entities use a dedicated widget)
+
+## 3. Configuration Concepts
+
+### Widget Configuration
+
+**Configuration Type:** EMPTY (no user-configurable parameters)
+
+The widget does not expose direct configuration options in the widget settings UI. Instead, customization happens through:
+
+### 1. Attribute-Level Configuration
+
+**Inverse Role Names:**
+- Configure on the `AttributeDefinition` using `_localizedInverseRoleName()`
+- Provides meaningful labels for bidirectional relationships
+- Example: If "Project -> Products" uses "products" attribute, the inverse role might be "relatedProjects"
+- These custom labels appear in the incoming references display
+
+**Attribute Localization:**
+- Use `AttributeDefinition._localizedName()` for feature labels
+- Supports multi-language displays
+
+**Access Restrictions:**
+- Configure via `RestrictedReadAndSearchAccessOnCustomAttributeExtension`
+- Restricted attributes are automatically excluded from incoming references
+- Ensures users only see references they have permission to view
+
+### 2. Type-Level Configuration
+
+**Type Display Names:**
+- Use `TypeDefinition._localizedNamePlural()` for source type labels
+- Controls how reference sources are labeled in the widget
+
+**Available References:**
+- Defined by `TypeDefinition.getAllAvailableIncomingReferencesToType()`
+- Determines which reference types appear in the "without values" section
+
+### 3. Display Modes
+
+The widget automatically organizes references into two sections:
+
+**With Values (Expanded by Default):**
+- Shows reference types that have at least one referring entity
+- Each group displays:
+  - Inverse role name or attribute name
+  - Source type (pluralized)
+  - Reference count
+  - Space indicator (if cross-space reference)
+
+**Without Values (Collapsed by Default):**
+- Shows configured reference types with zero referring entities
+- Useful for understanding available but unused relationships
+- Helps users discover potential reference opportunities
+
+### 4. Embeddability
+
+**Can be embedded in:**
+- CustomEntity detail pages
+- TypeDefinition pages
+- TypeDefinitionLayout pages
+
+**Cannot be embedded in:**
+- Person entities (use dedicated "myElements" widget instead)
+
+## 4. Context and Related Widgets
+
+### Relationship to Other Widgets
+
+#### cf.platform.incomingLinks
+**Key Differences:**
+
+| Aspect | Incoming References | Incoming Links |
+|--------|---------------------|----------------|
+| **Tracks** | Formal reference attributes | Rich text hyperlinks |
+| **Data Source** | CustomReferenceInDb entities | RichStringLink entities |
+| **Relationship Type** | Schema-defined, structured | User-created, wiki-style |
+| **Creation Method** | Via reference fields in forms | Via hyperlink insertion in rich text |
+| **Use Case** | Data model relationships | Knowledge base cross-references |
+| **Icon** | `fa-external-link fa-rotate-90` | `fa-link` |
+
+**When to use which:**
+- Use **Incoming References** for formal data model relationships (e.g., "Products related to this Project")
+- Use **Incoming Links** for informal content relationships (e.g., wiki pages linking to this page)
+- Use **both** for comprehensive relationship visibility (formal + informal)
+
+#### Related Widget Ecosystem
+
+**Attribute Display Widgets:**
+- `cf.platform.singleAttribute` - Display individual attribute values (including outgoing references)
+- `cf.platform.customRichStringAttribute` - Display rich text that may contain links
+- `cf.platform.connectedSingleAttribute` - Display attributes from related entities
+
+**Search and Filter Widgets:**
+- `cf.platform.embeddedSearchAsList` - Display filtered entity lists
+- `cf.platform.embeddedSearchAsTable` - Display filtered entities in table format
+- `cf.platform.connectedTableFilter` - Filter by relationship criteria
+
+**Visualization Widgets:**
+- `cf.platform.connectedBarChart` - Visualize relationship distributions
+- `cf.platform.connectedMatrix` - Show two-dimensional relationships
+- `cf.platform.connectedPieChart` - Show categorical relationship patterns
+
+### Typical Usage Patterns
+
+**Pattern 1: Basic Relationship Discovery**
+```
+Page Layout:
+1. Entity Header
+2. Core Attributes (singleAttribute widgets)
+3. Incoming References Widget (show who references this)
+```
+
+**Pattern 2: Complete Relationship View**
+```
+Page Layout:
+1. Entity Header
+2. Outgoing References (via attribute widgets)
+3. Incoming References Widget (formal relationships)
+4. Incoming Links Widget (informal relationships)
+```
+
+**Pattern 3: Impact Analysis Dashboard**
+```
+Page Layout:
+1. Entity Summary
+2. Incoming References Widget (dependencies)
+3. Embedded Search (find related content)
+4. Connected Chart (visualize relationship patterns)
+```
+
+### Prerequisites and Dependencies
+
+**Data Model Prerequisites:**
+- Entity types must support custom reference attributes
+- Reference attributes must be defined in the type definitions
+- Target entity must be a CustomEntity or compatible type
+
+**Permission Prerequisites:**
+- User must have read access to the target entity
+- User must have read access to source entity types
+- Restricted attributes are filtered based on `RestrictedReadAndSearchAccessOnCustomAttributeExtension`
+
+**Technical Dependencies:**
+- CustomReferenceInDb table (stores reference relationships)
+- Search API (for counting and filtering referrers)
+- IncomingReferencesUtil (processes and groups references)
+- ObjectFunctions template system (renders the widget)
+
+## 5. Technical Implementation
+
+### Core Components
+
+**Widget Definition:**
+- File: `IncomingReferencesWidgetDefinition.java`
+- Minimal configuration (EMPTY type)
+- Delegates rendering to template functions
+
+**Data Processing:**
+- File: `IncomingReferencesUtil.java`
+- Main method: `getReferenceKey2NumberOfReferrers()`
+- Queries CustomReferenceInDb table
+- Groups by attribute name, type, and space
+- Applies permission filtering
+- Returns IncomingLinkKeyAndCount objects
+
+**Display Logic:**
+- File: `incomingReferencesWidget.htm`
+- Two-section layout (with values / without values)
+- Expandable groups for detailed reference lists
+- Uses IncomingLinkKey for grouping
+- Sorts alphabetically by label
+
+**Label Generation:**
+- File: `IncomingLinkKeyAndCount.java`
+- Priority order:
+  1. Custom inverse role name (if defined)
+  2. Type plural + feature name
+  3. Type plural only
+  4. Entity kind label
+- Includes space indicator for cross-space references
+- Appends reference count
+
+### Data Flow
+
+```
+1. User views entity page
+   ↓
+2. Widget template calls ObjectFunctions.incomingReferencesWidget()
+   ↓
+3. IncomingReferencesUtil.getReferenceKey2NumberOfReferrers()
+   ↓
+4. SQL query on CustomReferenceInDb table
+   ↓
+5. For each source attribute:
+   - Resolve AttributeDefinition
+   - Check access restrictions
+   - Get owning TypeDefinition
+   - Count referrers via Search API
+   ↓
+6. Get available references (getAllAvailableIncomingReferencesToType)
+   ↓
+7. Merge and sort by label
+   ↓
+8. Split into "with values" and "without values"
+   ↓
+9. Render template with grouped references
+   ↓
+10. User clicks group to expand and view referrers
+```
+
+### Performance Considerations
+
+**Optimization Strategies:**
+- Uses Search API hit counts (not full entity loading)
+- SQL query groups by attribute to minimize database calls
+- Permissions checked once per attribute, not per referrer
+- Template uses lazy loading for expanded reference lists
+
+**Scalability:**
+- Handles large numbers of incoming references
+- Groups similar references to reduce visual clutter
+- Collapsed sections minimize initial render overhead
+- On-demand loading when expanding groups
+
+## 6. Key Features
+
+### Access Control
+- Respects attribute-level read restrictions
+- Filters by space permissions
+- Extension point for custom access logic
+- Users only see references they can access
+
+### Localization
+- All labels support multi-language via Message system
+- Custom role names localized per language
+- Type names use localized plural forms
+- Automatically adapts to user's language preference
+
+### Space Awareness
+- Identifies and marks cross-space references
+- Displays source space name when relevant
+- Filters by user's space access permissions
+- Supports multi-tenancy scenarios
+
+### Sorting and Grouping
+- Alphabetical sorting by display label
+- Custom role names appear first
+- Groups by source type and attribute
+- Clear separation of used vs unused references
+
+### Interactive Features
+- Expandable reference groups
+- Click to view full list of referrers
+- Collapse/expand state persisted per session
+- Smooth transitions between states
+
+## 7. Common Scenarios
+
+### Scenario 1: Product Manager Reviewing Dependencies
+**Context:** Before deprecating a product, check what references it
+**Steps:**
+1. Navigate to Product detail page
+2. Scroll to Incoming References widget
+3. Review "Projects" group showing 12 references
+4. Click group to see specific projects
+5. Decide whether to proceed with deprecation
+
+**Result:** Informed decision based on actual dependencies
+
+### Scenario 2: Data Architect Understanding Model Usage
+**Context:** Review how reference attributes are used in practice
+**Steps:**
+1. Navigate to TypeDefinition page for "Product"
+2. View Incoming References widget
+3. See both used and unused reference types
+4. Identify unexpected reference patterns
+5. Refine data model based on actual usage
+
+**Result:** Data model improvements based on real usage patterns
+
+### Scenario 3: End User Navigating Relationships
+**Context:** Find all requirements linked to a feature
+**Steps:**
+1. Open Feature detail page
+2. View Incoming References widget
+3. See "Requirements" group with 8 references
+4. Click to expand and view requirement list
+5. Click specific requirement to navigate
+
+**Result:** Bidirectional relationship navigation without manual search
+
+### Scenario 4: Cross-Space Collaboration
+**Context:** Understand how products in different workspaces relate
+**Steps:**
+1. View Product in "Engineering" workspace
+2. See Incoming References widget
+3. Notice references from "Marketing" workspace
+4. Identify cross-team dependencies
+5. Coordinate changes across workspaces
+
+**Result:** Better cross-team collaboration and coordination
+
+## 8. Comparison with Alternatives
+
+### vs. Manual Search
+**Incoming References Widget:**
+- ✓ Automatic aggregation and grouping
+- ✓ Real-time counts
+- ✓ Permission-aware filtering
+- ✓ Direct navigation to referrers
+
+**Manual Search:**
+- ✗ Requires knowing which attributes to search
+- ✗ Must construct complex queries
+- ✗ No automatic grouping
+- ✗ Time-consuming for multiple reference types
+
+### vs. Incoming Links Widget
+**Incoming References Widget:**
+- ✓ Structured, schema-defined relationships
+- ✓ Data model integrity
+- ✓ Formal dependencies
+
+**Incoming Links Widget:**
+- ✓ Organic, user-created relationships
+- ✓ Flexible, ad-hoc connections
+- ✓ Knowledge base cross-references
+
+**Best Practice:** Use both for complete relationship visibility
+
+### vs. Attribute Display Widgets
+**Incoming References Widget:**
+- ✓ Shows bidirectional relationships (who references me)
+- ✓ Aggregated view across all reference types
+- ✓ Automatic discovery
+
+**Attribute Widgets:**
+- ✓ Shows unidirectional relationships (who I reference)
+- ✓ Detailed attribute values
+- ✓ Attribute-specific configuration
+
+**Best Practice:** Combine for full relationship context
+
+## 9. Best Practices
+
+### Configuration
+1. **Define Inverse Role Names** - Provide meaningful bidirectional labels
+2. **Use Localization** - Support multi-language environments
+3. **Configure Access Restrictions** - Hide sensitive references appropriately
+4. **Test Cross-Space Scenarios** - Verify permissions work correctly
+
+### Page Design
+1. **Place Below Core Attributes** - Show incoming references after main content
+2. **Combine with Incoming Links** - Provide complete relationship view
+3. **Consider Widget Order** - Incoming references before less important widgets
+4. **Group Related Widgets** - Keep relationship widgets together
+
+### Performance
+1. **Monitor Reference Counts** - High counts may need pagination
+2. **Review Access Restrictions** - Overly permissive access impacts performance
+3. **Consider Caching** - For frequently viewed entities
+4. **Optimize Data Model** - Reduce unnecessary reference types
+
+### User Experience
+1. **Educate Users** - Explain difference between references and links
+2. **Customize Labels** - Use domain-specific terminology
+3. **Provide Context** - Help users understand relationship types
+4. **Support Navigation** - Ensure expanded lists are actionable
+
+## 10. Limitations and Considerations
+
+### Known Limitations
+1. **No Outgoing References** - Only shows incoming relationships
+2. **No Configuration UI** - Customization requires code/data model changes
+3. **Person Entities** - Not supported (use myElements widget)
+4. **No Filtering** - Cannot filter by specific reference types
+5. **No Sorting Options** - Fixed alphabetical sort
+
+### Performance Considerations
+1. **Large Reference Counts** - Many referrers may slow rendering
+2. **Complex Permissions** - Extensive access checks add overhead
+3. **Cross-Space Queries** - Multi-tenant filtering adds complexity
+4. **Available References** - Computing unused references requires type analysis
+
+### Design Trade-offs
+1. **Simplicity vs. Flexibility** - No configuration keeps it simple but limits customization
+2. **Automatic vs. Manual** - Automatic grouping may not match user expectations
+3. **Completeness vs. Performance** - Showing all references vs. pagination
+4. **Bidirectional vs. Unidirectional** - Only incoming view requires separate outgoing widgets
+
+## 11. Future Considerations
+
+### Potential Enhancements
+1. **Configurable Display Options** - Allow users to customize grouping and sorting
+2. **Filtering Capabilities** - Filter by reference type, source space, or count
+3. **Pagination Support** - Handle large numbers of references more efficiently
+4. **Outgoing References** - Combine incoming and outgoing in single widget
+5. **Visual Relationship Maps** - Graph-based visualization of relationships
+6. **Reference Quality Metrics** - Show relationship strength or relevance
+
+### Integration Opportunities
+1. **Analytics Integration** - Track which relationships are most accessed
+2. **Workflow Integration** - Trigger workflows based on reference changes
+3. **Notification Integration** - Alert when new references are created
+4. **Export Capabilities** - Export relationship data for analysis
+
+## 12. Summary
+
+The `cf.platform.incomingReferences` widget is a core component of cplace's relationship discovery system, providing automatic, permission-aware visibility into how entities are referenced throughout the data model. It serves as a critical tool for understanding dependencies, navigating relationships bidirectionally, and performing impact analysis before making changes.
+
+**Key Strengths:**
+- Automatic discovery of incoming relationships
+- Permission-aware filtering
+- Clear organization by type and attribute
+- Support for cross-workspace scenarios
+- Minimal configuration required
+
+**Primary Use Cases:**
+- Dependency discovery and impact analysis
+- Bidirectional relationship navigation
+- Data model usage analysis
+- Cross-team collaboration visibility
+
+**Best Used With:**
+- `cf.platform.incomingLinks` for complete relationship view
+- Attribute widgets for outgoing reference context
+- Embedded search widgets for relationship-based queries
+- Connected visualization widgets for pattern analysis
+
+This widget is essential for any cplace solution that uses structured entity relationships and requires users to understand how entities connect to each other within the data model.