## Overview

The Enum Mapping Table widget provides a specialized configuration interface for defining value-level mappings between enumeration attributes in cplace and their counterparts in external systems. It is a core component of the Enterprise Connect Foundation (ECF) framework, enabling administrators to configure how specific enum values should be translated during bidirectional synchronization.

This widget displays enum mapping records in a table format, showing pairs of cplace enum values and external system enum values. Each row represents a single value mapping that will be used during data synchronization to ensure consistent translation between systems.

## Primary Use Cases

### External System Integration

When integrating cplace with external systems (e.g., Jira, ServiceNow, custom REST APIs), enumeration attributes often have different value representations. 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 to cplace (INBOUND): "IN_PROGRESS" maps to "In Progress"
- When syncing FROM cplace to external (OUTBOUND): "Completed" maps to "DONE"

### Configuration Scenarios

**Enumeration Attribute Mapping**
- Map cplace enum attribute values to external system enum values
- Support for different value names and labels between systems
- Configure bidirectional mappings (inbound and outbound synchronization)

**Boolean Attribute Mapping**
- Special case of enum-like conversion for boolean attributes
- Maps True/False values between systems that may use different representations (e.g., "Yes"/"No", "1"/"0", "Active"/"Inactive")

**Synchronization Configuration**
- Embedded within enum conversion pages as part of the broader ECF attribute mapping configuration
- Enables attribute-level conversion rules for ECF connectors
- Part of the complete sync configuration hierarchy

## Design Considerations

### Strict Embedding Context

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 these embedding rules strictly and will throw a `NotEmbeddableException` if embedded elsewhere. This ensures the widget always has access to the parent enum conversion context it requires.

### Dynamic Value Population

The widget displays two primary columns with dynamically populated values:

**cplace Enum Values**
- Automatically populated based on the attribute type configured in the parent attribute mapping
- Supports custom attributes with enumeration constraints and built-in boolean attributes
- For boolean attributes, shows "True" and "False" options
- Values reflect the actual enum options available in cplace

**External Enum Values**
- Populated by external system connectors
- Specific to the connector and external attribute being mapped
- Reflects the actual enum options available in the external system

### Data Filtering

The widget automatically filters displayed mappings by:
- Space (workspace of the conversion page)
- Type (`cf.cplace.ecf.enumValueMapping`)
- Conversion reference (shows only mappings for the current conversion)

This ensures administrators only see mappings relevant to the current enum conversion being configured.

## Configuration 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 page
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 the dropdown
   - Select the corresponding external enum value from the dropdown
   - Save the mapping
7. Repeat until all values are mapped
8. Activate synchronization

## Important Constraints

**Manual Mapping Required**
- While enum conversions can be auto-created, individual value mappings must be manually configured
- No automatic value matching or suggestion is performed

**One-to-One Mappings**
- Each value can only map to one value in the opposite system
- Multiple mappings for the same source value will cause errors during synchronization

**Complete Mappings**
- All non-null values must have explicit mappings
- No default or fallback values are supported
- Missing mappings will cause errors during synchronization

**Immutability During Sync**
- Mappings should not be modified while synchronization is running
- Changes may not take effect until the next sync cycle

## Integration Context

### ECF Framework Integration

The widget is part of the Enterprise Connect Foundation (ECF), which provides:
- Common synchronization logic and UI configurations
- Bidirectional data sync between cplace and external systems
- Attribute mapping and conversion framework
- Validation and error handling during sync

### Widget Hierarchy

```
Sync Configuration Page
└── Attribute Mapping Table
    └── Attribute Mapping Page (for enum attribute)
        └── Enum Conversion Page
            └── Enum Mapping Table Widget
                └── Individual Enum Value Mapping Pages
```

### Synchronization Flow

**Configuration Phase** (uses this widget):
1. Administrator creates attribute mapping
2. System creates enum conversion page
3. Widget displays to configure value mappings

**Sync Execution Phase**:
1. ECF reads enum value mappings
2. Values are translated during sync using configured mappings
3. System validates mappings are complete and unambiguous

## Related Components

**Generic Search As Table Widget** (`cf.platform.embeddedSearchAsTable`)
- The Enum Mapping Table widget extends this base widget definition
- Inherits standard table features (sorting, filtering, column selection)
- Specializes the table for enum mapping configuration

**Attribute Mapping Widgets**
- Work alongside this widget in the broader ECF configuration
- Define which attributes to sync and their mapping rules
- Reference enum conversions when needed for enum/boolean attributes

## Common Pitfalls

**Incomplete Mappings**
- Forgetting to map all enum values leads to sync errors
- Ensure every non-null value has a corresponding mapping

**Modifying During Active Sync**
- Changing mappings while sync is running may cause inconsistent behavior
- Always pause synchronization before modifying value mappings

**Incorrect Embedding**
- Attempting to embed the widget outside enum conversion pages will fail
- The widget requires the parent enum conversion context to function

**Ambiguous Mappings**
- Creating multiple mappings for the same source value causes validation errors
- Each value must have exactly one target mapping