Field mapping

Every connector - Google Sheets, webhooks, and REST API - needs to know how incoming data maps to your dataset columns. Field mapping is where you define that relationship: which source field goes to which column, what type it is, and whether any transforms should be applied.

How field mapping works

When Genuics receives data from a connector, it follows this flow:

1. Extract - Genuics reads the incoming data (spreadsheet rows, JSON payloads, or API responses).
2. Map - Each source field is matched to a target column in your dataset based on your mapping rules.
3. Transform - Optional transforms (like trimming whitespace or parsing dates) run on the mapped values.
4. Insert - The processed rows are written to your dataset.

You configure steps 2 and 3 in the field mapping screen.

Access field mapping

1. Go to Setup > Connectors and click on the connector you want to configure.
2. Open the Field mapping tab.
3. You'll see a table with source fields on the left and target columns on the right.

Source and target fields

Each row in the mapping table represents one field:

Column	What it shows
Source field	The name of the field in the incoming data (e.g., a spreadsheet column header, a JSON key, or an API response field)
Target column	The dataset column this field maps to. Choose from existing columns or create a new one.
Type	The data type: Metric, Dimension, Date, Open-end, or ID
Transform	Optional processing applied before the value is stored
Enabled	Toggle to include or skip this field

Mapping nested JSON fields

For webhook and REST API connectors, source data often arrives as nested JSON. Genuics flattens nested objects using dot notation:

JSON structure	Source field name
{ "customer": { "name": "Alice" } }	customer.name
{ "scores": [8, 9, 7] }	scores.0, scores.1, scores.2
{ "meta": { "tags": ["vip"] } }	meta.tags.0

You can map any of these flattened fields to a dataset column.

Auto-detection

When you first set up a connector or receive the first payload, Genuics automatically:

• Detects field types by analyzing the sample data. Numbers become Metrics, dates become Date fields, short text becomes Dimensions, and longer text becomes Open-end.
• Suggests target columns by matching source field names to existing dataset columns. If a source field name matches an existing column name, Genuics maps them automatically.

Available transforms

Transforms let you clean and normalize incoming data before it reaches your dataset. Apply one or more transforms to any field:

Transform	What it does	Example
Lowercase	Converts the value to lowercase	"HAPPY" becomes "happy"
Trim	Removes leading and trailing whitespace	" Alice " becomes "Alice"
Parse date	Converts a text value to a proper date using a format you specify	"04/10/2026" with format MM/DD/YYYY becomes a date object

To add a transform:

1. Click the Transform cell for the field you want to modify.
2. Select a transform from the dropdown.
3. If the transform requires a parameter (like a date format), enter it in the field that appears.
4. You can chain multiple transforms - they run in the order listed.

Handling missing fields

Not every incoming record will contain every field. Here's how Genuics handles missing data:

Scenario	What happens
A mapped field is missing from the payload	The column value is set to null for that row
An entire column is missing from a spreadsheet sync	All rows get null for that column. Check if the column was renamed or removed in the source.
A required field is missing	If you've marked a field as required, the row is skipped and logged in the sync history

Update mappings for existing connections

You can change field mappings at any time without recreating the connector:

1. Go to Setup > Connectors and click on the connector.
2. Open the Field mapping tab.
3. Make your changes - add new mappings, change types, update transforms, or disable fields.
4. Click Save mapping.

Changes take effect on the next sync. Previously imported data is not retroactively updated - only new data uses the updated mapping.

Tips for effective mapping

• Name your target columns clearly. Use names your team will recognize in dashboards and reports - "Customer Satisfaction Score" is better than "field_q7."
• Use the ID type for unique identifiers. This keeps IDs out of metric calculations and enables upsert matching.
• Mark open-text fields as Open-end. This triggers automatic theme and sentiment analysis, giving you richer insights from freeform responses.
• Disable noisy fields. If the source sends metadata you don't need (timestamps, internal IDs, debug info), toggle those fields off to keep your dataset clean.

Next steps

With your fields mapped, learn about field types in more detail, or go back to the connectors overview to set up another data source.