Field Mapping
Data Entity
Description
Defines how an internal data field maps to the corresponding field name and format in an external accounting or member management system. Stored as structured configuration within the organization_integration JSONB column. Used by the integration export pipeline to serialize expense claims correctly for Xledger or Dynamics.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Unique identifier for the field mapping entry. Generated on creation. | PKrequiredunique |
integration_id |
uuid |
Foreign key reference to the organization_integration record that owns this mapping. Used to scope mappings per integration instance. | required |
source_field |
string |
The canonical internal field name as used by the platform's data model (e.g., 'expense_amount', 'peer_mentor_id', 'activity_date'). Must match a known field in the internal schema. | required |
target_field |
string |
The field name or column key in the external system (e.g., 'AccountCode' in Xledger, 'ExpenseAmount' in Dynamics portal). Must be a non-empty string. | required |
transform_type |
enum |
Specifies how the source value is transformed before being written to the target field. Controls serialization behavior in the export pipeline. | required |
transform_config |
json |
Optional configuration object for the transform. For 'format': includes date/number format strings. For 'lookup': contains a key-value map. For 'computed': contains formula expression. For 'static': contains the constant value. Null for 'direct'. | - |
default_value |
string |
Fallback value to use when the source field is null or empty during export. Applied after transform. If null, missing source values cause a validation warning. | - |
is_required |
boolean |
Whether the external system requires this field to be non-empty. If true and no value can be resolved (source null, no default), the record is excluded from export with a skipped-claim reason. | required |
source_field_path |
string |
Dot-notation path for nested source fields (e.g., 'expense_line.km_distance'). Null for top-level fields. Allows extraction from nested objects in the internal data model. | - |
display_label |
string |
Human-readable label shown in the field mapping editor UI. Defaults to source_field if not set. | - |
sort_order |
integer |
Determines display order in the field mapping editor. Lower values appear first. Used purely for UI presentation. | - |
is_active |
boolean |
Soft-disable flag. Inactive mappings are ignored by the export pipeline but preserved for audit and rollback. | required |
created_at |
datetime |
UTC timestamp of when this mapping was created. | required |
updated_at |
datetime |
UTC timestamp of the most recent update to this mapping record. | required |
Database Indexes
idx_field_mapping_integration_id
Columns: integration_id
idx_field_mapping_integration_source_unique
Columns: integration_id, source_field
idx_field_mapping_is_active
Columns: integration_id, is_active
idx_field_mapping_sort_order
Columns: integration_id, sort_order
Validation Rules
source_field_snake_case
error
Validation failed
target_field_non_empty
error
Validation failed
transform_type_is_valid_enum
error
Validation failed
lookup_transform_config_is_non_empty_map
error
Validation failed
default_value_length_within_bounds
error
Validation failed
source_field_path_valid_dot_notation
error
Validation failed
coverage_check_before_export
error
Validation failed
sort_order_non_negative
error
Validation failed
Business Rules
unique_source_field_per_integration
A given source_field may only appear once per integration_id. Each internal field can map to exactly one external target field for a given integration, preventing ambiguous serialization during export.
source_field_must_exist_in_internal_schema
The source_field value must correspond to a known field in the platform's internal data model as declared by the integration-type-registry. Prevents mappings that would silently produce null during export.
required_fields_must_have_default_or_reliable_source
If is_required is true, either a non-null default_value must be set or the source_field must be a field that is guaranteed non-null in the platform schema. Export skips the entire record and logs a skipped-claim reason when a required field resolves to null.
transform_config_must_match_transform_type
The structure of transform_config must be valid for the selected transform_type. 'direct' requires null config. 'lookup' requires a non-empty key-value map. 'format' requires a format string. 'computed' requires an expression string. 'static' requires a value string.
single_active_mapping_set_per_integration
Only active (is_active = true) mappings are applied during export. Inactive mappings are skipped by the resolver and preserved solely for audit purposes. Deactivating all mappings for an integration produces a validation warning on next export attempt.
cascade_delete_on_integration_removal
When the parent organization_integration record is deleted, all associated field_mapping records must be deleted via cascade. Orphaned mappings with no parent integration are not permitted.
immutable_after_export_use
Mappings referenced in a completed export run should be treated as read-only to preserve audit integrity. Edits require creating a new mapping version rather than mutating the existing record.
CRUD Operations
Storage Configuration
Entity Relationships
An integration configuration contains multiple field mapping entries defining how internal fields map to the external system schema