> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nudj.cx/llms.txt
> Use this file to discover all available pages before exploring further.
# Configuring Data Hydration
> Step-by-step guide to enabling customer data hydration on question actions in the Nudj admin panel
Customer data hydration is configured per question action within a challenge. When enabled, every time a user answers that question, their response is captured as structured customer data.
Data hydration appears as a collapsible section on question action editors. It is only available for question-type actions (multiple choice, open-ended, rating, etc.).
## Prerequisites
Before configuring data hydration, ensure you have:
* **Admin access** to the Nudj control room with Manager role or above
* **An existing challenge** with at least one question-type action (multiple choice, open-ended, rating, date selection, etc.)
* **Shopify connection** (optional) — if you want to sync data to Shopify, your community must have a linked Shopify store with the `write_customers` scope
## Enabling Data Hydration
Navigate to **Engagement > Challenges** in the admin panel and open the challenge containing your question action.
Find the question action you want to hydrate and expand its configuration. Scroll to the **Customer Data** section.
Toggle **Enable Customer Data Collection** to on. This activates the generic custom data layer — answers will be stored on user profiles immediately.
Set up the field configuration:
* **Field Key** — A unique identifier for this data field. Auto-suggested from the question text. Must be lowercase alphanumeric with underscores (e.g., `favorite_color`).
* **Data Type** — How the value should be stored: Text, Integer, Decimal, Boolean, or Date.
* **Display Name** — A human-readable label for the field (e.g., "Favorite Color").
* **Description** — Optional description explaining what this field captures.
For questions where users can select multiple options, choose a multi-select mode:
* **None** — Single selection only.
* **Comma Separated** — All selections joined as text (e.g., `"Red, Blue, Green"`).
* **Boolean Expansion** — Each option becomes its own true/false field. Limited to 5 options.
For boolean expansion, you can also set a **Choices Override** to control exactly which options appear as boolean fields.
Save the challenge. If a platform sync is configured, definition sync jobs are queued automatically in the background.
## Field Key Best Practices
The field key is the most important configuration choice because it becomes immutable after the first sync.
* Use descriptive, stable names: `shirt_size`, `dietary_preference`
* Use snake\_case consistently
* Keep keys short but meaningful (max 64 characters)
* Reuse the same key across actions if they capture the same data point
* Use vague names: `q1`, `answer`, `data`
* Include action or challenge IDs in the key
* Change your mind after sync — the key locks permanently
* Use different keys for the same semantic data point across communities in your organization
Multiple actions can share the same field key if they use the same data type. The most recent answer overwrites the previous value. This is useful for re-asking preference questions — the user's latest answer is always the stored value.
## Data Type Selection
Choose the data type that best matches your question and how you plan to use the data downstream:
| Question Type | Recommended Data Type | Why |
| --------------------------------- | ---------------------- | ------------------------- |
| "What's your favorite color?" | Text | Free-form preference |
| "How many pets do you have?" | Integer | Whole number count |
| "Rate this product (1-5)" | Decimal | Allows fractional ratings |
| "Do you prefer morning delivery?" | Boolean | Yes/no question |
| "When is your birthday?" | Date | Calendar date |
| "Pick your top 3 interests" | Text + Comma Separated | Multi-select labels |
The data type cannot be changed after the first external platform sync. Choose carefully based on your downstream usage, not just the question format.
## Multi-Select Mode Details
### Comma Separated
Stores all selected labels as a single comma-delimited text value. Supports up to 50 choices.
```text theme={null}
Field: favorite_genres
Value: "Action, Comedy, Sci-Fi"
```
**Pros**: Simple, unlimited options, single field to manage.
**Cons**: Harder to filter on individual selections in some platforms.
### Boolean Expansion
Creates a separate boolean field for each option. Each field is `true` if the user selected that option, `false` otherwise.
```text theme={null}
Field: favorite_genres_action → true
Field: favorite_genres_comedy → true
Field: favorite_genres_scifi → false
Field: favorite_genres_drama → false
Field: favorite_genres_horror → false
```
**Pros**: Native boolean filtering on each option, works well with Shopify customer segments.
**Cons**: Limited to 5 options per action, uses more metafield definition capacity on external platforms.
Boolean expansion keys are generated from the parent field key plus the option ID. The expansion keys are managed automatically — you only configure the parent key.
## Immutability Rules
Once data has been synced to any external platform (indicated by a `firstSyncedAt` timestamp), certain fields lock:
| Field | After First Sync |
| --------------------------------------------------------- | ---------------- |
| Field Key | Locked |
| Data Type | Locked |
| Multi-Select Mode | Locked |
| Choices Override | Locked |
| Display Name | Editable |
| Description | Editable |
| Platform-specific settings (e.g., pin to customer detail) | Editable |
The admin UI shows a warning banner when fields are locked, and locked inputs are visually disabled.
You cannot remove a platform sync configuration after the first sync. This prevents orphaning definitions on the external platform. If you need to stop syncing, disable the data hydration toggle instead.
## Schema Consistency
Nudj enforces type consistency per field key within a community:
* If action A uses `shirt_size` as **Text**, action B cannot use `shirt_size` as **Integer**.
* If action A uses `shirt_size` with **Boolean Expansion**, action B cannot share the `shirt_size` key (boolean expansion keys are exclusive to one action).
* Multiple actions can share the same key with the same type and mode — the latest answer wins.
Conflicts are detected at save time and reported as validation errors.
## Capacity Limits
External platforms may have limits on field definitions:
| Platform | Limit | What Counts |
| -------- | --------------------------------------- | ----------------------------------------------------------------------------- |
| Shopify | 256 metafield definitions per namespace | Each field key = 1 definition. Boolean expansion: each option = 1 definition. |
The admin panel shows a warning when approaching the limit. New definitions that would exceed the limit are rejected at save time.
## Next Steps
Configure Shopify-specific sync settings including metafield pinning and customer detail visibility.
Review the full architecture and supported action types.