@cplace/test-mcp-server 1.0.0 → 1.1.0

package/dist/widget-specifications/_research_from_ga_products/cf-cplace-dynamicCodeBlockWidget-dynamicCodeBlockWidget/research.md

@@ -0,0 +1,250 @@
+# Dynamic Code Block Widget Research
+
+## Widget Information
+
+- **Widget ID**: `cf.cplace.dynamicCodeBlockWidget.dynamicCodeBlockWidget`
+- **Widget Name**: Dynamic Code Block
+- **Repository**: `cplace-utility-widgets`
+- **Icon**: `fa-code`
+- **Definition Class**: `cf.cplace.dynamicCodeBlockWidget/src/main/java/cf/cplace/dynamicCodeBlockWidget/script/DynamicCodeBlockWidgetDefinition.java`
+
+## Purpose
+
+### Brief Description
+
+The Dynamic Code Block Widget visualizes dynamically generated code or text content that is produced by a cplaceJS script at runtime.
+
+### Detailed Description
+
+This widget provides a way to display code blocks where the content is not static but rather generated programmatically using cplaceJS. The widget evaluates a configured script and displays the resulting string content in a formatted code block with syntax highlighting. It's designed for scenarios where code snippets, configurations, or structured text need to be generated dynamically based on page data, searches, or other runtime conditions.
+
+## Core Functionality
+
+### How It Works
+
+1. **Script Evaluation**: The widget executes a cplaceJS script defined in its configuration
+2. **Content Generation**: The script must return a string value, which becomes the code block content
+3. **Dynamic Display**: The generated content is rendered in a `<pre><code>` block in the UI
+4. **Reload Support**: The widget can reload its content dynamically via a reload action in the widget header
+5. **Clipboard Integration**: Optionally provides a "Copy to Clipboard" button for easy code copying
+
+### Technical Architecture
+
+- **Backend**:
+  - `DynamicCodeGenerationHandler`: HTTP handler that evaluates the cplaceJS script and returns the generated code
+  - `DynamicCodeGenerationService`: Service layer that executes the script with proper bindings and context
+  - Executes scripts in a `SaferScriptEngine` with monitoring and logging support
+
+- **Frontend**:
+  - Angular controller (`DynamicCodeBlockWidgetCtrl`) manages widget state and actions
+  - Fetches generated content via HTTP from the backend handler
+  - Displays content in a formatted code block
+  - Handles copy-to-clipboard functionality using browser APIs
+
+- **Script Context**:
+  - Scripts have access to an `embeddingPage` variable (if the widget is embedded in a page)
+  - Scripts can use standard cplaceJS APIs like `Search` and `Filters`
+  - The script result is converted to a string via `toString()`
+
+## Configuration Options
+
+The widget supports the following configuration attributes:
+
+### 1. Title (Optional)
+- **Attribute**: `TITLE` (inherited from `BASE_MIXIN`)
+- **Type**: Localized String
+- **Purpose**: Custom title for the widget header
+- **Default**: Uses the widget's default name if not specified
+
+### 2. Height (Optional)
+- **Attribute**: `HEIGHT` (inherited from `BASE_MIXIN`)
+- **Type**: Number
+- **Purpose**: Fixed height for the widget in pixels
+- **Default**: Auto-height based on content
+
+### 3. Script (Required)
+- **Attribute**: `SCRIPT`
+- **Type**: String (cplaceJS script)
+- **Purpose**: The cplaceJS script that generates the code block content
+- **Constraint**: Must be a valid cplaceJS script (uses `scriptConstraint`)
+- **Return Value**: Must return a string that will be displayed in the code block
+
+### 4. Show Copy Button (Optional)
+- **Attribute**: `SHOW_COPY_BUTTON`
+- **Type**: Boolean
+- **Purpose**: Controls whether a "Copy to Clipboard" button appears in the widget header
+- **Default**: `true`
+
+## Use Cases
+
+### 1. Configuration Display
+**Scenario**: Display dynamically generated configuration files or settings
+**Example**: Show a JSON configuration based on current project settings
+```javascript
+const buildConfiguration = {
+  main: {
+    url: 'git@github.com:collaborationFactory/cplace.git',
+    branch: 'master'
+  }
+};
+
+return JSON.stringify(buildConfiguration, null, 2);
+```
+
+### 2. Code Snippet Generation
+**Scenario**: Generate code examples or snippets based on page data
+**Example**: Create API endpoint URLs or curl commands based on the current page's attributes
+
+### 3. Documentation Generation
+**Scenario**: Auto-generate documentation snippets from page properties
+**Example**: Create markdown or HTML documentation based on entity attributes
+
+### 4. Data Export Preview
+**Scenario**: Show how data would look when exported in various formats
+**Example**: Display CSV, JSON, or XML representations of page data
+
+### 5. Script/Query Preview
+**Scenario**: Preview SQL queries, search configurations, or other scripts
+**Example**: Show the actual search query that will be executed based on filter settings
+
+### 6. Template Preview
+**Scenario**: Display template outputs with substituted values
+**Example**: Show email templates or report templates with actual data filled in
+
+### 7. Debug Information
+**Scenario**: Display debug information or diagnostic data
+**Example**: Show page metadata, attribute values, or system configuration for troubleshooting
+
+## Key Features
+
+### 1. Dynamic Content Generation
+- Content is generated at runtime by executing a cplaceJS script
+- Scripts have access to the embedding page context
+- Can leverage full cplaceJS API including searches and filters
+
+### 2. Reload Capability
+- Widget header includes a reload action
+- Allows users to refresh the generated content without reloading the entire page
+- Useful when the underlying data changes
+
+### 3. Copy to Clipboard
+- Optional "Copy to Clipboard" button in widget header (enabled by default)
+- Single-click copying of the entire code block
+- Shows confirmation message on successful copy
+- Only visible when code content exists
+
+### 4. Error Handling
+- Displays warning alerts if script evaluation fails
+- Provides error messages that direct users to check the Low-Code log
+- Gracefully handles script exceptions without breaking the page
+
+### 5. Code Formatting
+- Content is displayed in a `<pre><code>` block
+- Preserves whitespace and line breaks
+- Suitable for displaying formatted code, JSON, YAML, XML, etc.
+
+## Context and Dependencies
+
+### Repository Context
+The widget is part of the `cplace-utility-widgets` repository, which contains various utility widgets including:
+- `cf.cplace.extendedTreeTableWidget`
+- `cf.cplace.qrCodeWidget`
+- `cf.cplace.treeTableWidget`
+- `cf.cplace.videoWidget`
+
+These widgets provide specialized visualization and interaction capabilities that extend the core platform.
+
+### Technical Dependencies
+- **cplaceJS Engine**: Requires the cplaceJS scripting engine for script execution
+- **WidgetLayout Framework**: Uses the standard cplace widget layout infrastructure
+- **Angular Framework**: Frontend implementation uses AngularJS
+- **cplace Platform**: Depends on core platform classes for widget definition and rendering
+
+### Prerequisites
+- **cplaceJS Knowledge**: Users configuring this widget need to know cplaceJS scripting
+- **Script Permissions**: Scripts execute with the permissions of the viewing user
+- **Page Context**: Most useful when embedded in a page (provides `embeddingPage` context)
+
+## Related Concepts
+
+### Similar Widgets
+- **Rich String Widget** (`cf.platform.richString`): Displays static or dynamic rich text content
+- **Iframe Widget** (`cf.platform.iframe`): Embeds external content via iframe
+- **Wiki Widget** (`cf.platform.wiki`): Displays wiki-formatted content
+
+### Differences from Similar Widgets
+- Unlike Rich String Widget, content is generated via script rather than stored directly
+- Unlike Iframe Widget, content is rendered directly in the page (not embedded)
+- Specifically designed for code/text blocks with copy functionality
+
+## Technical Notes
+
+### Script Execution Context
+- Scripts are evaluated with a `CplaceJSLogContext` for proper logging
+- Performance monitoring is enabled (logs if execution exceeds threshold)
+- The `embeddingPage` binding is only available if the widget is embedded in a page
+- Scripts return values are converted to strings (via `Object.toString()`)
+
+### Security Considerations
+- Scripts execute in a `SaferScriptEngine` with restricted capabilities
+- Access is controlled via widget configuration permissions
+- Scripts execute in the context of the viewing user's permissions
+
+### Performance Considerations
+- Script execution happens on-demand (when widget loads or reloads)
+- Long-running scripts may impact page load time
+- Consider caching strategies for expensive computations
+
+## Example Script Patterns
+
+### 1. Simple Static Content
+```javascript
+return "console.log('Hello, World!');";
+```
+
+### 2. JSON Configuration
+```javascript
+const config = {
+  environment: 'production',
+  apiUrl: 'https://api.example.com'
+};
+return JSON.stringify(config, null, 2);
+```
+
+### 3. Using Embedding Page
+```javascript
+if (embeddingPage) {
+  const pageName = embeddingPage.getName();
+  const pageType = embeddingPage.getType().getName();
+  return `Page: ${pageName}\nType: ${pageType}`;
+}
+return "No embedding page available";
+```
+
+### 4. Search-Based Generation
+```javascript
+// Note: This is a conceptual example
+// Actual implementation would use cplace.actions().search()
+const results = // ... perform search
+return `Found ${results.length} items\n` +
+       results.map(r => r.getName()).join('\n');
+```
+
+## Limitations and Considerations
+
+1. **Script Complexity**: Complex scripts may impact performance
+2. **Return Type**: Script must return a string (or value convertible to string)
+3. **No Syntax Highlighting**: The widget displays plain text code blocks without language-specific syntax highlighting
+4. **Read-Only**: The widget is for display only; the code block is not editable
+5. **Browser Compatibility**: Copy-to-clipboard uses `document.execCommand('copy')` which may have browser limitations
+6. **Error Visibility**: Script errors require checking the Low-Code log for details
+
+## Summary
+
+The Dynamic Code Block Widget is a utility widget that bridges the gap between cplaceJS scripting capabilities and code/text visualization. It's particularly valuable for:
+- Generating dynamic documentation
+- Displaying configuration examples
+- Creating debug views
+- Providing copy-friendly code snippets
+
+Its strength lies in combining the flexibility of cplaceJS scripting with a simple, focused presentation format optimized for code and structured text content.

package/dist/widget-specifications/_research_from_ga_products/cf-cplace-ecf-attribute-conversion-widget-enumMappingTable/research.md

@@ -0,0 +1,260 @@
+# Enum Mapping Table Widget Research
+
+**Widget ID:** `cf.cplace.ecf.attribute.conversion.widget.enumMappingTable`
+
+**Repository:** `cplace-ecf`
+
+**Definition Class:** `cf.cplace.ecf/src/main/java/cf/cplace/ecf/attribute/conversion/enumeration/widget/EnumMappingTableWidgetDefinition.java`
+
+---
+
+## 1. Purpose
+
+### Brief Description
+The Enum Mapping Table widget displays and manages mappings between cplace enumeration values and external system enumeration values for data synchronization in the Enterprise Connect Foundation (ECF).
+
+### Core Functionality
+This widget provides a table interface for configuring value-level mappings between enumeration attributes in cplace and their counterparts in external systems. It extends `GenericSearchAsTableWidgetDefinition` to display enum mapping records that define how specific enum values should be translated during bidirectional synchronization.
+
+---
+
+## 2. Use Cases
+
+### Primary Use Case: External System Integration
+When integrating cplace with external systems (e.g., Jira, ServiceNow, custom REST APIs), enumeration attributes often need value-level translation. For example:
+
+**Scenario:** Syncing project status between cplace and an external project management tool
+- **cplace values:** "Not Started", "In Progress", "Completed", "On Hold"
+- **External system values:** "TODO", "IN_PROGRESS", "DONE", "BLOCKED"
+
+The Enum Mapping Table widget allows administrators to define these mappings so that:
+- When syncing FROM external → cplace (INBOUND): "IN_PROGRESS" → "In Progress"
+- When syncing FROM cplace → external (OUTBOUND): "Completed" → "DONE"
+
+### Key Scenarios
+
+1. **Enumeration Attribute Mapping**
+   - Map cplace enum attribute values to external system enum values
+   - Support for different value names and labels between systems
+   - Bidirectional mapping configuration (inbound and outbound sync)
+
+2. **Boolean Attribute Mapping**
+   - Special case of enum-like conversion for boolean attributes
+   - Maps True/False values between systems that may use different representations
+
+3. **Synchronization Configuration**
+   - Embedded within enum conversion pages
+   - Part of the broader attribute mapping configuration
+   - Enables attribute-level conversion rules for ECF connectors
+
+---
+
+## 3. Configuration Concepts
+
+### Widget Embedding Rules
+The widget can ONLY be embedded in:
+1. **Pages of Enum Conversion types** (`cf.cplace.ecf.enumConversion` or `cf.cplace.ecf.enumBooleanConversion`)
+2. **Type definitions for Enum Conversion types**
+
+The widget enforces strict embedding rules through `checkEmbeddableIn()` method, throwing `NotEmbeddableException` if embedded elsewhere.
+
+### Data Model
+
+The widget displays entities of type `cf.cplace.ecf.enumValueMapping` with the following attributes:
+
+1. **cplaceEnumValue** (`cf.cplace.ecf.cplaceEnumValue`)
+   - Type: Single string with dynamic enumeration constraint
+   - Values populated by `CplaceAttributeEnumValuesEnumerationProvider`
+   - Shows actual enum values from the mapped cplace attribute
+
+2. **externalEnumValue** (`cf.cplace.ecf.externalEnumValue`)
+   - Type: Single string with dynamic enumeration constraint
+   - Values populated by `ExternalEnumValuesEnumerationProvider`
+   - Shows enum values from the external system attribute
+
+3. **conversion** (hidden reference attribute)
+   - Back-reference to parent enum conversion configuration
+   - Hidden from table display (removed from default columns)
+   - Read-only, used for filtering mappings
+
+### Dynamic Value Population
+
+**cplace Enum Values:**
+- Automatically populated based on the attribute type configured in the parent attribute mapping
+- Supports custom attributes (with EnumerationConstraint) and built-in boolean attributes
+- For boolean attributes, shows "True" and "False" options
+- Values are serialized using CustomValueTagSerializationService
+
+**External Enum Values:**
+- Populated by external system connectors
+- Provided through `ExternalEnumValuesEnumerationProvider`
+- Specific to the connector and external attribute being mapped
+
+### Table Specification
+
+The widget uses `EnumMappingTableSpecificationHandler` which:
+- Filters enum mappings by:
+  - Space (workspace of the conversion page)
+  - Type (`cf.cplace.ecf.enumValueMapping`)
+  - Conversion reference (shows only mappings for current conversion)
+- Automatically removes the "conversion" column from display
+- Inherits standard table features (sorting, filtering, column selection)
+
+---
+
+## 4. Context and Dependencies
+
+### ECF (Enterprise Connect Foundation)
+- ECF is cplace's framework for synchronizing data with external systems
+- Provides common synchronization logic, UI configurations, and validations
+- The Enum Mapping Table widget is a core component of ECF's attribute conversion system
+
+### Related Components
+
+1. **ConversionRepository System**
+   - `AbstractEnumConversionRepository`: Base class for enum-like conversions
+   - `EnumConversionRepository`: Handles standard enum attribute conversions
+   - `BooleanConversionRepository`: Handles boolean attribute conversions
+
+2. **EnumValueMappings**
+   - Runtime representation of enum mappings
+   - Bidirectional lookup (inbound/outbound)
+   - Stored as pairs: `(cplaceValue, externalValue)`
+   - Validates that mappings are unique and complete
+
+3. **Attribute Mapping**
+   - Parent concept linking cplace attributes to external attributes
+   - Each attribute mapping may reference an enum conversion
+   - Enum conversions are only relevant for enum/boolean attributes
+
+4. **Sync Configuration**
+   - Top-level configuration for ECF connectors
+   - Contains multiple attribute mappings
+   - Defines workspace, entity types, and sync direction
+
+### Widget Hierarchy
+
+```
+Sync Configuration Page
+└── Attribute Mapping Table Widget
+    └── Attribute Mapping Page (for enum attribute)
+        └── Enum Conversion Page
+            └── Enum Mapping Table Widget (THIS WIDGET)
+                └── Individual Enum Value Mapping Pages
+```
+
+### Registration and Lifecycle
+
+- Widget is registered through `EnumMappingTableWidgetDefinition.KIND`
+- Automatically embedded in enum conversion type pages via `WidgetContainerDef`
+- Default layout: 12-column width, full-page table display
+- Part of the `EcfPlugin` (`cf.cplace.ecf` namespace)
+
+### Key Classes Referenced
+
+**From cplace-ecf:**
+- `cf.cplace.ecf.attribute.conversion.enumeration.widget.EnumMappingTableWidgetDefinition`
+- `cf.cplace.ecf.attribute.conversion.enumeration.widget.EnumMappingTableSpecificationHandler`
+- `cf.cplace.ecf.attribute.conversion.enumeration.common.repository.EnumerationConversionTypeContainer`
+- `cf.cplace.ecf.api.mapping.conversion.enumeration.AbstractEnumConversionRepository`
+- `cf.cplace.ecf.api.mapping.conversion.enumeration.EnumValueMappings`
+- `cf.cplace.ecf.attribute.conversion.common.repository.ConversionRepositoryRegistry`
+
+**From cplace-platform:**
+- `cf.cplace.platform.frontend.widgets.GenericSearchAsTableWidgetDefinition`
+- `cf.cplace.platform.frontend.handler.functions.GenericSearchAsTableSpecificationHandler`
+
+---
+
+## 5. Technical Implementation Details
+
+### Widget Definition Class Analysis
+
+**File:** `EnumMappingTableWidgetDefinition.java`
+
+Key methods:
+1. `getWidgetTitle()`: Returns the localized widget title
+2. `createTableSpecificationHandler()`: Creates the handler for table search and display
+3. `checkEmbeddableIn()`: Validates embedding context (only enum conversion pages)
+4. `getWidgetKind()`: Returns the unique widget identifier
+
+### Table Specification Handler
+
+**File:** `EnumMappingTableSpecificationHandler.java`
+
+Key methods:
+1. `constructTableSearch()`: Builds search query filtering by space, type, and conversion reference
+2. `getDefaultColumnNames()`: Returns column list with "conversion" column removed
+
+### Value Matching Logic
+
+The `EnumValueMappings` class provides bidirectional lookup:
+- **Inbound sync**: Matches external value (right side) → returns cplace value (left side)
+- **Outbound sync**: Matches cplace value (left side) → returns external value (right side)
+
+Error handling:
+- Throws exception if no mapping found for non-null source value
+- Throws exception if multiple mappings exist for same source value
+- Returns null if source value is null and no mapping exists
+
+---
+
+## 6. Integration Points
+
+### Auto-Configuration Support
+
+The `EnumConversionRepository` supports auto-configuration:
+```java
+public boolean isAutoConfigurationSupported(AttributeMapping mapping) {
+    return mapping.getInternalAttribute().isEnum()
+        && mapping.getExternalAttribute() instanceof EnumEntityAttribute;
+}
+```
+
+When both cplace and external attributes are enums, the system can automatically create an enum conversion configuration, which then displays this widget for manual value mapping.
+
+### Synchronization Flow
+
+1. **Configuration Phase** (uses this widget):
+   - Administrator creates attribute mapping
+   - System creates enum conversion page
+   - Widget displays to configure value mappings
+
+2. **Sync Execution Phase**:
+   - ECF reads enum value mappings
+   - `EnumValueMappings.getMappedValue()` translates values during sync
+   - Validates mappings are complete and unambiguous
+
+---
+
+## 7. Limitations and Constraints
+
+1. **Manual Mapping Required**: While enum conversions can be auto-created, individual value mappings must be manually configured
+2. **Strict Embedding**: Widget cannot be embedded outside enum conversion pages
+3. **One-to-One Mappings**: Each value can only map to one value in the opposite system
+4. **No Default/Fallback Values**: All non-null values must have explicit mappings
+5. **Immutable During Sync**: Mappings should not be modified while synchronization is running
+
+---
+
+## 8. User Workflow
+
+Typical configuration workflow:
+
+1. Create or edit a Sync Configuration
+2. Add an Attribute Mapping for an enum attribute
+3. System creates or references an Enum Conversion
+4. Navigate to the Enum Conversion page
+5. The Enum Mapping Table widget displays automatically
+6. For each value pair:
+   - Select a cplace enum value from dropdown
+   - Select corresponding external enum value from dropdown
+   - Save the mapping
+7. Repeat until all values are mapped
+8. Activate synchronization
+
+---
+
+## 9. Summary
+
+The Enum Mapping Table widget is a specialized configuration interface within the ECF framework that enables administrators to define value-level mappings between enumeration attributes in cplace and external systems. It ensures data consistency during bidirectional synchronization by providing a clear, table-based UI for mapping individual enum values, supporting the critical use case of integrating systems with different enumeration vocabularies.

package/dist/widget-specifications/_research_from_ga_products/cf-cplace-ecf-configuration-widget-attributeMappingTable/research.md

@@ -0,0 +1,148 @@
+# Attribute Mapping Table Widget Research
+
+## Widget Identification
+
+- **Widget ID**: `cf.cplace.ecf.configuration.widget.attributeMappingTable`
+- **Widget Kind**: `cf.cplace.ecf.configuration.widget.attributeMappingTable`
+- **Repository**: `cplace-ecf`
+- **Definition Class**: `cf.cplace.ecf/cf.cplace.ecf/src/main/java/cf/cplace/ecf/configuration/extension/widget/AttributeMappingTableWidgetDefinition.java`
+- **Display Name**: "Attribute Mappings" (EN) / "Attributzuordnungen" (DE)
+- **Icon**: `cf-attribute-selection`
+
+## Purpose and Summary
+
+The Attribute Mapping Table widget displays all attribute mappings associated with a synchronization configuration in the Enterprise Connect Foundation (ECF) plugin. It provides a table view of how cplace attributes are mapped to external system attributes for data synchronization purposes.
+
+**One-sentence description**: Displays a table of attribute mappings that define how data fields are synchronized between cplace and external systems within a synchronization configuration.
+
+## Core Functionality
+
+### What It Does
+
+The widget:
+1. Queries for all `Attribute Mapping` entities that reference the current synchronization configuration page
+2. Displays them in a table format showing the configured attribute mappings
+3. Automatically excludes the redundant "Configuration" column from display (since it's embedded in the configuration page)
+4. Uses the default columns defined by the attribute mapping type
+
+### Data Model
+
+The widget displays entities of type `cf.cplace.ecf.attributeMapping` which have the following attributes:
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `cf.cplace.ecf.configuration` | Page Reference | Link to the synchronization configuration (read-only) |
+| `cf.cplace.ecf.cplaceAttribute` | String (Enumeration) | The cplace attribute being mapped |
+| `cf.cplace.ecf.externalAttribute` | String (Enumeration) | The external system attribute being mapped |
+| `cf.cplace.ecf.syncDirection` | Enumeration | INBOUND or OUTBOUND direction for this mapping |
+| `cf.cplace.ecf.conversionParameters` | Page Reference | Optional conversion configuration for data transformation |
+
+### Inheritance Hierarchy
+
+```
+GenericSearchAsTableWidgetDefinition
+  └── AbstractSyncConfigTableWidgetDefinition
+        └── AttributeMappingTableWidgetDefinition
+```
+
+The `AbstractSyncConfigTableWidgetDefinition` base class ensures this widget can only be embedded in ECF synchronization configuration pages (`cf.cplace.ecf.syncConfiguration` type).
+
+## Use Cases
+
+### Primary Use Case: Configuring Data Synchronization
+
+When administrators set up data synchronization between cplace and an external system (like Jira, SAP, or other enterprise systems), they need to define which attributes should be synchronized and how. The Attribute Mapping Table widget provides a central view of all these mappings within a configuration.
+
+**Scenario**: An administrator is configuring a Jira integration to synchronize task data. They use this widget to:
+- View all existing attribute mappings at a glance
+- Understand which cplace fields map to which Jira fields
+- See the synchronization direction for each mapping
+- Identify which mappings have custom conversions applied
+
+### Supporting Use Cases
+
+1. **Configuration Review**: Review all attribute mappings for a synchronization configuration before enabling it
+2. **Troubleshooting**: When data isn't synchronizing correctly, use the table to verify mappings are configured as expected
+3. **Documentation**: Serves as a quick reference for what data flows between systems
+4. **Auditing**: Administrators can audit the complete attribute mapping setup for compliance
+
+## Configuration Concepts
+
+### Widget Configuration
+
+The widget has minimal configuration options:
+- No custom configuration type is defined (uses base table configuration)
+- Height can be controlled via standard widget height settings
+
+### Context Requirements
+
+**Embedding Constraint**: This widget can ONLY be embedded in pages of type `cf.cplace.ecf.syncConfiguration` (ECF Synchronization Configuration). The base class `AbstractSyncConfigTableWidgetDefinition` enforces this constraint and throws `NotEmbeddableException` if placed elsewhere.
+
+### Default Layout Integration
+
+The widget is automatically included in the **Configuration tab** of synchronization configuration pages via `SyncConfigurationWidgetDefinitions`:
+- The Configuration tab contains: Attributes widget + Attribute Mappings Table widget
+- The Synchronization tab contains: Sync Metadata Table widget
+
+Layout structure in Configuration tab:
+```
+Row 1: Attributes Widget (12 columns)
+Row 2: AttributeMappingTableWidget (12 columns)
+```
+
+## Related Components
+
+### Sibling Widgets in ECF
+
+| Widget | Purpose | Location |
+|--------|---------|----------|
+| `SyncMetadataTableWidgetDefinition` | Shows synchronization metadata entities | Synchronization tab |
+| `AttributeMappingTableWidgetDefinition` | Shows attribute mappings (this widget) | Configuration tab |
+
+### Related ECF Components
+
+- **`SyncConfiguration`**: Interface representing a synchronization configuration that contains attribute mappings
+- **`AttributeMapping`**: Interface representing individual attribute mapping entries
+- **`Conversion`**: Optional conversion logic that can be attached to attribute mappings for data transformation
+- **`SyncDirection`**: Enum defining INBOUND (external→cplace) or OUTBOUND (cplace→external) synchronization
+
+### Dependencies
+
+- Requires the ECF plugin (`cf.cplace.ecf`) to be installed
+- Requires a connector app to provide the synchronization configuration types
+- Works with the Layout Tabs Widget (`cf.cplace.layoutTabsWidget`) for the tabbed UI
+
+## Technical Details
+
+### Search Construction
+
+The `AttributeMappingTableSpecificationHandler` constructs the search as:
+```java
+new Search()
+    .add(Filters.type(ATTRIBUTE_MAPPING.TYPE))
+    .add(Filters.customAttribute(ATTRIBUTE_MAPPING.CONFIGURATION, configPage))
+    .add(Filters.space(configPage.getSpaceNotNullWithoutReadAccessCheck()))
+```
+
+This finds all attribute mappings that:
+1. Are of the attribute mapping type
+2. Reference the current configuration page
+3. Are in the same workspace as the configuration
+
+### Column Display
+
+The handler removes the Configuration column from display since it would be redundant (the widget is already embedded in the configuration page):
+```java
+defaultColumnNames.remove(CustomAttribute.getNameFromSimpleName(ATTRIBUTE_MAPPING.CONFIGURATION.name));
+```
+
+## Source Files Reference
+
+| File | Purpose |
+|------|---------|
+| `AttributeMappingTableWidgetDefinition.java` | Main widget definition |
+| `AttributeMappingTableSpecificationHandler.java` | Table search and column configuration |
+| `AbstractSyncConfigTableWidgetDefinition.java` | Base class with embedding validation |
+| `AttributeMappingTypeContainer.java` | Attribute mapping type definition |
+| `SyncConfigurationWidgetDefinitions.java` | Default layout configuration |
+| `messages_en.properties` / `messages_de.properties` | Localized labels |