@cplace/mcp-server 1.6.0 → 1.6.1

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

@@ -1,421 +0,0 @@
-# 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