@cplace/test-mcp-server 0.1.15 → 1.1.0

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

@@ -0,0 +1,421 @@
+# Attribute History Widget Research
+
+**Widget ID:** `cf.platform.attributeHistory`
+**Widget Name:** Attribute Versions
+**Repository:** main
+**Definition Class:** `cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/AttributeHistoryWidgetDefinition.java`
+
+---
+
+## 1. Purpose
+
+The Attribute History widget displays the complete change history (version history) of a single attribute on a custom entity page. It tracks and visualizes how the value of a specific attribute has evolved over time, showing what changed, when it changed, and who made the change.
+
+**Short Description:**
+The Attribute History widget shows the change history of a selected attribute, displaying old values, new values, timestamps, and editors in a chronological table format.
+
+---
+
+## 2. Core Functionality
+
+### What It Does
+
+The widget retrieves and displays the version history of a configured attribute by:
+
+1. **Querying ChangeSets**: Fetches all edit ChangeSets associated with the entity that contain changes to the specified attribute (cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/AttributeHistoryWidgetContentUtil.java:55-115)
+
+2. **Extracting Change Data**: For each relevant ChangeSet, extracts:
+   - Old value (before the change)
+   - New value (after the change)
+   - Timestamp (when the change occurred)
+   - Editor (who made the change)
+
+3. **Including Initial Value**: Adds the initial value set when the entity was first created (cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/AttributeHistoryWidgetContentUtil.java:117-147)
+
+4. **Presenting in Table Format**: Displays the history in a chronological table with columns for timestamp, old value, new value, and optionally the editor
+
+### Data Model
+
+The widget works with:
+- **CustomEntity**: The page whose attribute history is being tracked
+- **ChangeSet**: System versioning records that capture entity modifications (cf.cplace.platform/src/main/java/cf/cplace/platform/core/application/versioning/ChangeSet.java)
+- **CustomAttributeChange**: Specific changes to custom attributes within a ChangeSet
+- **AttributeDefinition**: The metadata defining the attribute being tracked
+
+### Version Compatibility Handling
+
+The widget handles version history from different cplace versions:
+- **Pre-4.54**: ChangeSets didn't store new values - the widget derives them from the next change's old values
+- **4.54-5.10**: New values weren't stored when empty - same derivation logic applies
+- **5.11+**: Full old and new value tracking (cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/AttributeHistoryWidgetContentUtil.java:69-80)
+
+When values are derived, the widget displays a question mark icon with tooltip: "New value is derived from later version."
+
+---
+
+## 3. Use Cases
+
+### Primary Use Cases
+
+1. **Audit Trail and Compliance**
+   - Track who changed critical attribute values and when
+   - Maintain compliance records for regulated industries
+   - Provide evidence for audits (quality management, financial compliance, etc.)
+
+2. **Troubleshooting and Root Cause Analysis**
+   - Investigate when a value was changed that led to an issue
+   - Identify who made a problematic change
+   - Understand the sequence of changes leading to the current state
+
+3. **Progress Tracking**
+   - Monitor how status fields evolved over time
+   - Track progression through workflow stages
+   - Observe trend changes in numeric or date fields
+
+4. **Collaboration and Transparency**
+   - Show team members the evolution of shared data
+   - Provide visibility into who contributed what changes
+   - Build trust through transparent change tracking
+
+5. **Data Recovery Insights**
+   - See previous values that might need to be restored
+   - Understand what was lost if incorrect changes were made
+   - Reference historical values for reporting
+
+### Example Scenarios
+
+- **Project Status Tracking**: Display how a project's status field changed from "Planning" → "In Progress" → "On Hold" → "Completed"
+- **Budget Evolution**: Show how a budget amount was adjusted over time by different team members
+- **Priority Changes**: Track when and by whom a task's priority was escalated
+- **Assignment History**: See who was assigned to a work item over time
+- **Risk Level Monitoring**: Track changes to risk assessment values
+
+---
+
+## 4. Configuration Options
+
+The widget provides the following configuration attributes (cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/AttributeHistoryWidgetDefinition.java:152-223):
+
+### Required Configuration
+
+1. **Attribute Name** (`cf.platform.attributeName`)
+   - **Type**: Dynamic string enumeration (single value)
+   - **Purpose**: Selects which attribute's history to display
+   - **Behavior**: Dropdown populated with all non-derived attributes from the target entity's type
+   - **Localization**: "The attribute whose change history should be displayed"
+
+### Optional Configuration
+
+2. **Page** (`cf.platform.entity`)
+   - **Type**: Page reference (single value)
+   - **Purpose**: Specifies which page's attribute history to show
+   - **Default**: Current page (if left empty)
+   - **Behavior**: Refreshes widget configuration when changed
+   - **Localization**: "The page of which the attribute versions are shown. Leave empty for current page."
+
+3. **Title** (`TITLE`)
+   - **Type**: Localized string (single value)
+   - **Purpose**: Custom widget title
+   - **Default**: Widget definition name ("Attribute Versions")
+   - **Localization**: "Widget Title"
+
+4. **Show Editor** (`cf.platform.showEditor`)
+   - **Type**: Boolean
+   - **Default**: false
+   - **Purpose**: Controls visibility of the "Editor" column showing who made each change
+   - **Localization**: "Determines if the editor column should be shown"
+
+5. **Default Filter** (`cf.cplace.platform.script.widgets.changeSetFilter`)
+   - **Type**: Enumeration (single value, required)
+   - **Default**: ALL
+   - **Options**:
+     - **ALL**: Show all changes (no time filtering)
+     - **DAY**: Show changes from today only
+     - **WEEK**: Show changes from the last 7 days
+     - **MONTH**: Show changes from the last 30 days
+     - **YEAR**: Show changes from the last 365 days
+   - **Purpose**: Sets the initial time range filter for displayed changes
+   - **Localization**: "Set the default filter"
+
+6. **Show Filter Button** (`cf.platform.showFilter`)
+   - **Type**: Boolean
+   - **Default**: false
+   - **Purpose**: Controls visibility of the filter dropdown button at the top of the widget
+   - **Behavior**: When enabled, users can dynamically switch between time range filters
+   - **Localization**: "Determines if the filter button should be shown on the top"
+
+### Configuration Validation
+
+The widget validates that (cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/AttributeHistoryWidgetDefinition.java:242-258):
+- The target entity has a valid type definition
+- The specified attribute name is not empty
+- The attribute exists in the type definition
+
+---
+
+## 5. Presentation and User Interface
+
+### Table Structure
+
+The widget displays a lean table with the following columns (cf.cplace.platform/src/main/resources/cf/cplace/platform/frontend/widgets/attributeHistoryWidgetContent.htm):
+
+1. **When** (always shown)
+   - Displays relative time ("2 hours ago", "yesterday")
+   - Tooltip shows detailed timestamp
+   - Sortable chronologically
+
+2. **Old Value** (always shown)
+   - Shows the attribute value before the change
+   - Formatted according to attribute type (text, enum with icon, number, date, etc.)
+   - Empty for the initial value row
+
+3. **New Value** (always shown)
+   - Shows the attribute value after the change
+   - Formatted according to attribute type
+   - May include question mark icon when value is derived from later versions
+
+4. **Editor** (optional, controlled by "Show Editor" config)
+   - Displays the name of the person who made the change
+   - Shows "Unknown User" if person information is unavailable
+   - Formatted as HTML-escaped text
+
+### Filter Interface
+
+When "Show Filter Button" is enabled (cf.cplace.platform/assets/ts/directives/cplaceAttributeHistoryFilter.ts):
+- Dropdown button appears at the top showing current filter
+- Clicking reveals filter options (All, Today, Last Week, Last Month, Last Year)
+- Selecting a filter reloads the widget content dynamically via AJAX
+- Filter selection is maintained in widget state
+
+### Special Display Elements
+
+1. **Derived Value Indicator**
+   - Question mark icon appears next to values that are derived (not stored in original ChangeSet)
+   - Tooltip: "New value is derived from later version."
+
+2. **Placeholder Row**
+   - Shows "(...)" row when filtered view doesn't include all changes
+   - Indicates there are older changes beyond the current filter
+
+3. **Initial Entry**
+   - Displays the first value set when the entity was created
+   - Shows creation timestamp and creator
+   - Old value column is empty (no previous value existed)
+
+### Limits
+
+- Maximum of 100 history items displayed (cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/AttributeHistoryWidgetContent.java:42)
+- Oldest changes are trimmed first when limit is exceeded
+
+---
+
+## 6. Related Widgets
+
+### Complementary Widgets
+
+1. **Version Info Widget** (`cf.platform.modificationInfo`)
+   - Shows overall entity modification metadata (created/modified dates and users)
+   - Attribute History shows detailed history of individual attributes
+   - Often used together for complete audit trail
+
+2. **Comments Widget** (`cf.platform.comments`)
+   - Provides manual annotations about changes
+   - Attribute History provides automatic tracking of actual data changes
+
+3. **Attributes Widget** (`cf.platform.attributes`)
+   - Displays current attribute values
+   - Attribute History shows how those values evolved
+
+### Feature Context
+
+The widget is part of the platform's **versioning and audit trail** capabilities:
+- Built on top of the ChangeSet system (cf.cplace.platform/src/main/java/cf/cplace/platform/core/application/versioning/ChangeSet.java)
+- Complements the system-wide version tracking
+- Provides user-facing visibility into the versioning backend
+
+---
+
+## 7. Technical Architecture
+
+### Backend Components
+
+1. **AttributeHistoryWidgetDefinition.java** (cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/AttributeHistoryWidgetDefinition.java)
+   - Widget definition class
+   - Configuration schema
+   - Validation logic
+   - Target entity resolution (handles embedded contexts)
+
+2. **AttributeHistoryWidgetContent.java** (cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/AttributeHistoryWidgetContent.java)
+   - Template substitution class
+   - Filters changes based on time range
+   - Prepares data for HTML rendering
+   - Handles initial entry and placeholder logic
+
+3. **AttributeHistoryWidgetContentUtil.java** (cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/AttributeHistoryWidgetContentUtil.java)
+   - Utility class for fetching change history
+   - Queries ChangeSet repository
+   - Extracts CustomAttributeChange objects
+   - Derives missing values from newer ChangeSets
+   - Formats values using attribute type renderers
+
+4. **AttributeHistoryDataHandler.java** (cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/handler/widget/AttributeHistoryDataHandler.java)
+   - POST handler for dynamic filter changes
+   - Returns JSON with updated HTML content
+   - Enables filter dropdown functionality
+
+### Frontend Components
+
+1. **attributeHistoryWidgetDefinition.htm**
+   - Main widget wrapper template
+   - Integrates filter directive and swappable content area
+
+2. **attributeHistoryWidgetContent.htm**
+   - Table structure template
+   - Conditional rendering for filter button and editor column
+   - Change row iteration
+
+3. **cplaceAttributeHistoryFilter.ts** (cf.cplace.platform/assets/ts/directives/cplaceAttributeHistoryFilter.ts)
+   - AngularJS directive for filter dropdown
+   - Handles filter selection
+   - AJAX reload on filter change
+   - Widget reload action integration
+
+---
+
+## 8. Constraints and Limitations
+
+### Embedding Requirements
+
+The widget can be embedded in (cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/AttributeHistoryWidgetDefinition.java:234-239):
+- Custom entity pages
+- Type definition layouts (for preview purposes)
+- App space contexts only (not embeddable in workspaces or global contexts)
+
+### Data Constraints
+
+1. **Only Non-Derived Attributes**
+   - The attribute dropdown only shows attributes that are not derived properties (cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/AttributeHistoryWidgetDefinition.java:105)
+   - Derived/computed attributes don't have stored change history
+
+2. **CustomEntity Only**
+   - Only works with custom entities (pages with custom types)
+   - Cannot track built-in system entity attributes
+
+3. **Edit ChangeSets Only**
+   - Only queries ChangeSets of type "edit" (cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/AttributeHistoryWidgetContentUtil.java:176)
+   - Other ChangeSet types (creation, deletion, etc.) are not included in attribute change tracking
+
+4. **No Access Control Filtering**
+   - Runs queries in "no read access check" mode (cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/AttributeHistoryWidgetContentUtil.java:173)
+   - Shows all changes regardless of current user's permissions on historical editors
+
+### Display Limitations
+
+1. **100 Item Maximum**
+   - Only the most recent 100 changes are displayed (cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/AttributeHistoryWidgetContent.java:42)
+   - Older changes beyond this limit are not visible
+
+2. **Single Attribute Only**
+   - Can only track one attribute per widget instance
+   - Requires multiple widget instances to track multiple attributes
+
+3. **No Export Functionality**
+   - Widget displays data in-page only
+   - No built-in CSV or Excel export
+
+---
+
+## 9. Implementation Notes
+
+### Dynamic Attribute Selection
+
+The widget uses a `DynamicEnumerationProvider` to populate the attribute dropdown (cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/AttributeHistoryWidgetDefinition.java:85-112):
+- Reads the target entity's type definition
+- Filters out derived properties
+- Returns attribute internal names and localized display names
+- Updates when target entity changes (due to `withRefreshAfterSetting(true)`)
+
+### Target Entity Resolution
+
+The widget uses complex logic to determine the target entity (cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/AttributeHistoryWidgetDefinition.java:129-150):
+1. Uses explicitly configured "Page" if set
+2. Falls back to widget's embedded context
+3. Handles special cases:
+   - Widget configurations embedded in other widgets
+   - Dummy widget containers (preview mode)
+   - Type definition layouts (returns null for display purposes)
+
+### Value Formatting
+
+The widget formats values using the attribute type's renderer (cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/AttributeHistoryWidgetContentUtil.java:184-186):
+- Uses `CustomValuesSubstitutions` template system
+- Respects attribute type (enum icons, date formats, number formats, etc.)
+- Renders as single-line HTML (suitable for table cells)
+- Does not fall back to other languages for localization
+
+---
+
+## 10. Key Source Code References
+
+### Core Classes
+- Definition: `cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/AttributeHistoryWidgetDefinition.java`
+- Content: `cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/AttributeHistoryWidgetContent.java`
+- Utility: `cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/AttributeHistoryWidgetContentUtil.java`
+- Data Handler: `cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/handler/widget/AttributeHistoryDataHandler.java`
+
+### Templates
+- Main Widget: `cf.cplace.platform/src/main/resources/cf/cplace/platform/frontend/widgets/attributeHistoryWidgetDefinition.htm`
+- Content Table: `cf.cplace.platform/src/main/resources/cf/cplace/platform/frontend/widgets/attributeHistoryWidgetContent.htm`
+- Value Rendering: `cf.cplace.platform/src/main/resources/cf/cplace/platform/frontend/widgets/attributeHistoryWidgetContent$values.htm`
+
+### Frontend
+- Filter Directive: `cf.cplace.platform/assets/ts/directives/cplaceAttributeHistoryFilter.ts`
+
+### Localization
+- English: `cf.cplace.platform/src/main/resources/cf/cplace/platform/messages_en.properties`
+- German: `cf.cplace.platform/src/main/resources/cf/cplace/platform/messages_de.properties`
+
+### Tests
+- Content Tests: `cf.cplace.platform/src/test/java/cf/cplace/platform/frontend/widgets/TestAttributeHistoryWidgetContent.java`
+- Util Tests: `cf.cplace.platform/src/test/java/cf/cplace/platform/frontend/widgets/TestAttributeHistoryWidgetContentUtil.java`
+
+---
+
+## 11. Configuration Example
+
+**Typical Configuration:**
+
+```
+Widget: Attribute Versions
+├─ Page: [Current Page]
+├─ Attribute Name: "status" (from dropdown)
+├─ Title: "Status Change History"
+├─ Show Editor: ✓ Enabled
+├─ Default Filter: Last Month
+└─ Show Filter Button: ✓ Enabled
+```
+
+**Resulting Display:**
+
+```
+[Last Month ▾]  (filter dropdown)
+
+| When           | Old Value | New Value    | Editor        |
+|----------------|-----------|--------------|---------------|
+| 2 hours ago    | In Review | Approved     | John Smith    |
+| yesterday      | Draft     | In Review    | Jane Doe      |
+| 5 days ago     | Planning  | Draft        | John Smith    |
+| (...)          |           |              |               |
+| 32 days ago    |           | Planning     | Jane Doe ⓘ    |
+```
+
+ⓘ = Derived value indicator
+
+---
+
+## 12. Related Documentation
+
+- ChangeSet Documentation: For understanding the underlying versioning system
+- Widget Layout Documentation: For embedding and layout configuration
+- Type Definition Documentation: For attribute metadata and constraints
+- Custom Values Rendering: For understanding how different attribute types are displayed