Skip to main content

​
Overview

Field mapping is the core of creating data pipelines in Entegrata. You define how data from your source systems maps to the standardized fields in your entities. This guide covers everything from simple direct mappings to understanding data type compatibility and handling common mapping scenarios.

​
Understanding Field Mapping

​
What is Field Mapping?

Field mapping creates a connection between:
  • Source Field: A column from your data source (e.g., customer_name from CRM)
  • Entity Field: A standardized field in your entity (e.g., Name)
When data flows through your pipeline, values are transformed from source fields to entity fields based on these mappings.
Visual representation of field mapping from source to entity

​
Direct Field Mapping (Visual View)

​
Basic Connection

1

Open the Mapping Editor

Navigate to your entity and open the mapping editor. Ensure you have at least one data source configured.
Mapping editor with source and entity nodes
2

Locate Source Field

Find the source field you want to map. You can add new fields to your source node through the Edit Source modal’s Fields tab, which lets you search and select from available columns.
Managing source fields in the Edit Source modal
3

Locate Target Entity Field

On the right side, find the entity field you want to map to. Entity fields are shown with their data types.
Entity node with field list
4

Drag to Connect

Click and hold on the source field, then drag to the entity field. Release to create the connection.An animated line appears showing the mapping relationship.
Dragging connection between source and entity field

​
Alternative: Edit Field Modal

Instead of dragging, you can configure mappings through the Edit Field modal:
1

Click Entity Field

Click on the entity field you want to map. This opens the Edit Field modal.
2

Open Data Source Tab

Switch to the Data Source tab in the modal.
3

Select Source and Field

Use the source and field dropdowns to select where the data comes from. The mapping is applied when you click Save.

​
Understanding Data Type Compatibility

​
Automatic Type Conversion

Entegrata automatically converts between compatible data types:
Source TypeCompatible Entity Types
String/TextString, Integer (if numeric), Decimal, Boolean, Date
IntegerString, Integer, Decimal, Boolean
Decimal/FloatString, Decimal, Integer (rounded)
BooleanString, Boolean, Integer (0/1)
Date/DateTimeString, Date, DateTime
JSONString, JSON

​
Mapping from Multiple Sources

When you have related sources, you can map fields from any of them:
1

Identify Field Sources

Each source node is labeled. Fields show which source they come from.
Multiple source nodes with color coding
2

Map from Any Source

Connect entity fields to fields from either:
  • Primary source
  • Any related source
3

Handle Null Values

When mapping from related sources (joined with LEFT JOIN), some records may have null values.Consider:
  • Using COALESCE to provide fallback values
  • Setting default values
COALESCE example with multiple sources

​
Common Mapping Patterns

​
Name Fields

Combining first and last name: Option 1: Use CONCAT transformation 
Source: FirstName, LastName
Combination: CONCAT(FirstName, ' ', LastName)
Entity Field: Name
Option 2: Map separate fields 
Source: FirstName -> Entity: FirstName
Source: LastName -> Entity: LastName

​
Address Fields

Mapping complete addresses: Single Field Address: 
Source: full_address -> Entity: Address
Multi-Field Address: 
Source: street_address -> Entity: Street
Source: city -> Entity: City
Source: state -> Entity: State
Source: zip_code -> Entity: ZipCode

​
Date and Time Fields

Common date/time mapping scenarios: Date Only: 
Source: created_date (DateTime) -> Entity: CreatedDate (Date)
(Time portion automatically truncated)
Timestamp to Date and Time: 
Source: timestamp -> Entity: Date (extract date)
Source: timestamp -> Entity: Time (extract time)

​
Boolean/Flag Fields

Mapping yes/no or true/false values: String to Boolean: 
Source: active (String: "Y"/"N") -> Entity: IsActive (Boolean)
Condition: "Y" = true, "N" = false
Integer to Boolean: 
Source: enabled (Integer: 1/0) -> Entity: IsEnabled (Boolean)
Condition: 1 = true, 0 = false
Complex Conditions: Use CASE expression for complex logic (see Multi-Field Mapping)
Boolean field mapping configurations

​
Numeric Fields

Mapping numbers with precision: Integer to Decimal: 
Source: quantity (Integer) -> Entity: Quantity (Decimal)
(Automatically converted with .00 decimal places)
Decimal Precision: 
Source: price (Decimal 10,4) -> Entity: Price (Decimal 10,2)
(Automatically rounded to 2 decimal places)

​
Unmapping Fields

To remove a field mapping:

​
Visual View

1

Select Connection Line

Click on the connection line between source and entity field.
Selected connection line
2

Delete Connection

Press Delete key, or right-click the connection line and select Delete.
Context menu with remove option
3

Confirm if Prompted

If the field is required, you’ll be asked to confirm removal.

​
Remapping Fields

To change an existing mapping:

​
Visual View

1

Delete Old Connection

Remove the existing connection as described above.
2

Create New Connection

Drag from the new source field to the entity field.

​
Troubleshooting

​
Cannot Map Field

Issue: Dragging a field doesn’t create a connection. Solutions:
  • Check if entity field is already mapped (unmap first)
  • Verify data types are compatible
  • Ensure source node is properly connected

​
Missing Fields in Dropdown

Issue: Expected source field doesn’t appear in dropdown. Solutions:
  • Refresh source schema
  • Verify you’re looking at the correct source
  • Check if field name has special characters (may be escaped)
  • Ensure source connection is active
  • Ensure field is enabled on the resource

​
Best Practices

Field Naming
  • Use consistent naming conventions
  • Match business terminology, not technical names
  • Document unusual mappings with comments
  • Consider future maintainability
Performance
  • Map only fields you need
  • Avoid complex transformations when simple mapping works
  • Use source-level filters to reduce data volume
  • Consider data types impact on storage

Data Mapping Editor

Learn about the visual mapping editor interface

Multi-Field Mapping

Advanced transformations with COALESCE, CONCAT, CASE

Field Management

Add, edit, and configure entity fields

Default Values

Set default values for entity fields