Hyperfold AI

Integration Map

Configure data mappings between external systems and Hyperfold.

Overview

The hyperfold integrate map command defines how data flows between connected integrations and your Hyperfold project. Field mappings transform external data formats into Hyperfold's unified schema, enabling agents to work with consistent data regardless of source.

Field Mapping

# Create a field mapping
$ hyperfold integrate map shopify \
  --source="product" \
  --target="catalog"

Mapping fields from Shopify products to Hyperfold catalog...

AUTO-DETECTED MAPPINGS
  title           →   name            (string)
  body_html       →   description     (html → text)
  vendor          →   brand           (string)
  product_type    →   category        (string)
  variants.price  →   base_price      (decimal)
  variants.sku    →   sku             (string)
  images.src      →   images          (array)

Accept auto-mappings? [Y/n] y

Additional mappings needed:
  ? Map 'tags' to:
    1. semantic_tags (recommended)
    2. categories
    3. Skip this field

> 1

✓ Field mappings saved

Custom Mappings

# Define custom field mappings
$ hyperfold integrate map salesforce \
  --source="Contact" \
  --target="customer" \
  --mapping='[
    {"source": "FirstName", "target": "first_name"},
    {"source": "LastName", "target": "last_name"},
    {"source": "Email", "target": "email"},
    {"source": "Account.Name", "target": "company"},
    {"source": "Account.AnnualRevenue", "target": "metadata.annual_revenue"},
    {"source": "Loyalty_Tier__c", "target": "tier"}
  ]'

# Map with computed fields
$ hyperfold integrate map salesforce \
  --source="Contact" \
  --target="customer" \
  --computed='[
    {
      "target": "full_name",
      "expression": "{{FirstName}} {{LastName}}"
    },
    {
      "target": "lifetime_value",
      "expression": "sum(Opportunities.Amount)"
    }
  ]'

Viewing Mappings

# View current mappings
$ hyperfold integrate map shopify --show

FIELD MAPPINGS: Shopify → Hyperfold
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

SOURCE: product
TARGET: catalog

SOURCE FIELD         TARGET FIELD        TYPE        TRANSFORM
title                name                string      none
body_html            description         html        strip_html
vendor               brand               string      none
product_type         category            string      normalize
variants.price       base_price          decimal     cents_to_dollars
variants.sku         sku                 string      uppercase
variants.weight      weight_kg           decimal     oz_to_kg
images.src           images              array       none
tags                 semantic_tags       array       split(',')
metafields.custom    metadata            object      flatten

COMPUTED FIELDS
full_description     "{{title}} - {{body_html}}"
search_text          concat(title, tags, vendor)

# View mapping for specific integration
$ hyperfold integrate map salesforce --show

FIELD MAPPINGS: Salesforce → Hyperfold
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

SOURCE: Contact
TARGET: customer

SOURCE FIELD              TARGET FIELD       TRANSFORM
FirstName                 first_name         none
LastName                  last_name          none
Email                     email              lowercase
Account.Name              company            none
Account.AnnualRevenue     metadata.revenue   none
Loyalty_Tier__c           tier               map_enum

ENUM MAPPING: Loyalty_Tier__c → tier
  "Gold"      → "gold"
  "Silver"    → "silver"
  "Bronze"    → "bronze"
  "Platinum"  → "platinum"
  null        → "standard"

Transformations

Transformations modify data during sync:

# Apply transformations during mapping
$ hyperfold integrate map shopify \
  --source="product" \
  --target="catalog" \
  --transform='[
    {
      "field": "body_html",
      "transform": "strip_html",
      "options": {"preserve": ["b", "i", "ul", "li"]}
    },
    {
      "field": "variants.price",
      "transform": "currency_convert",
      "options": {"from": "cents", "to": "dollars"}
    },
    {
      "field": "tags",
      "transform": "split",
      "options": {"delimiter": ",", "trim": true}
    },
    {
      "field": "vendor",
      "transform": "lookup",
      "options": {
        "table": "brand_aliases",
        "fallback": "source"
      }
    }
  ]'

# Available transformations
$ hyperfold integrate map --list-transforms

AVAILABLE TRANSFORMATIONS

STRING
  uppercase        Convert to uppercase
  lowercase        Convert to lowercase
  trim             Remove whitespace
  truncate         Limit to N characters
  regex_replace    Replace via regex pattern

ARRAY
  split            Split string to array
  join             Join array to string
  filter           Filter array elements
  flatten          Flatten nested arrays

NUMERIC
  round            Round to N decimals
  currency_convert Convert currency formats
  unit_convert     Convert units (oz→kg, etc.)

DATE
  format           Format date/time
  timezone         Convert timezone
  relative         Convert to relative time

SPECIAL
  strip_html       Remove HTML tags
  lookup           Map via lookup table
  default          Set default if null
  hash             Hash value (SHA256, MD5)

Sync Rules

Configure how and when data synchronizes:

# Configure sync rules
$ hyperfold integrate map shopify \
  --sync-direction=bidirectional \
  --conflict-resolution=newest_wins

# Set sync frequency
$ hyperfold integrate map shopify \
  --sync-schedule="*/5 * * * *" \
  --batch-size=100

# Configure selective sync
$ hyperfold integrate map shopify \
  --sync-filter='[
    {"field": "status", "operator": "eq", "value": "active"},
    {"field": "updated_at", "operator": "gt", "value": "{{last_sync}}"}
  ]'

# View sync status
$ hyperfold integrate map shopify --sync-status

SYNC STATUS: Shopify → Hyperfold
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Direction:          Bidirectional
Schedule:           Every 5 minutes
Last Sync:          2 minutes ago
Next Sync:          3 minutes

LAST SYNC SUMMARY
  Records Processed:  847
  Created:            12
  Updated:            156
  Unchanged:          679
  Errors:             0
  Duration:           4.2s

PENDING CHANGES
  To Hyperfold:       23 records
  To Shopify:         5 records

Conflict Resolution Strategies

StrategyBehavior
newest_winsMost recently updated record takes precedence
source_winsExternal system is always authoritative
hyperfold_winsHyperfold data takes precedence
manualFlag conflicts for manual review
mergeMerge non-conflicting fields from both

Validation

Test and validate mappings before deploying:

# Test field mappings
$ hyperfold integrate map shopify --test

Testing Shopify → Hyperfold mapping...

Sample source record:
{
  "title": "Running Shoes Pro",
  "body_html": "<p>Professional <b>running shoes</b></p>",
  "vendor": "Nike",
  "variants": [{"price": "12999", "sku": "shoe-001"}]
}

Transformed result:
{
  "name": "Running Shoes Pro",
  "description": "Professional running shoes",
  "brand": "Nike",
  "base_price": 129.99,
  "sku": "SHOE-001"
}

✓ All field mappings valid
✓ Transformations working correctly
✓ No data type mismatches

# Validate with production data
$ hyperfold integrate map shopify --validate --sample=100

Validating 100 sample records...

VALIDATION RESULTS
  Valid:              97
  Warnings:           3
  Errors:             0

WARNINGS
  Record 23: 'tags' is empty, semantic_tags will be null
  Record 45: 'body_html' contains script tag (will be stripped)
  Record 78: 'variants.price' is 0, may indicate data issue