SyncPIMSyncPIM
Documentation

Basic Concepts

Understand the core concepts behind Akeneo Exporter.

Configuration

A Configuration defines how to connect to your Akeneo PIM and where to export data.

What's in a Configuration?

Think of it as a reusable blueprint that can be executed multiple times to create individual Export jobs.

Source

Akeneo PIM connection details and authentication

Destination

MongoDB, PostgreSQL, or MySQL with connection settings

Enrichments

Optional transformation rules and filters

Key Features

  • Organization-scoped — All team members can view and use shared configurations
  • Reusable — Create once, run exports from it anytime
  • Channel-specific — Target a specific Akeneo scope (e.g., "ecommerce", "marketplace")
Configuration structure
interface Configuration {
  name: string
  source: {
    type: 'akeneo'
    url: string
    credentials: AkeneoCredentials
    scope?: string  // Channel (e.g., 'ecommerce', 'marketplace')
  }
  destination: {
    type: 'mongodb' | 'postgresql' | 'mysql'
    connectionString: string
    database: string
    collection?: string  // MongoDB only
    schema?: string      // PostgreSQL only
  }
  enrichers?: string[]   // IDs of enrichers to apply
  filters?: ProductFilters
}
[SCREENSHOT: Configuration creation form in the UI]

Enricher

An Enricher transforms or enriches product data during export.

What Can Enrichers Do?

→ Calculate discounted prices
→ Generate SEO-friendly URLs
→ Add computed fields
→ Validate data quality
→ Flag incomplete products
→ Compute stock status

Types of Enrichers

Conditional Enrichers

Follow an "if-then" logic pattern. Chain multiple conditions with AND/OR logic.

Example: Mark products on sale
{
  name: "Mark On Sale",
  type: "conditional",
  conditions: [
    { field: "attributes.price", operator: "<", value: 50 }
  ],
  actions: [
    { type: "setField", field: "on_sale", value: true }
  ]
}
Template Enrichers

Use Mustache templates for dynamic text generation (coming soon)

Built-in Enrichers

Pre-built enrichers for categories, attributes and entities

Sequential Processing
Enrichers execute in order. Each enricher sees the output of the previous one, allowing you to build sophisticated data pipelines.

Export

An Export is a job that fetches products from Akeneo, applies enrichers, and writes to your database.

Export Lifecycle

Each export is tracked independently with its own status, progress metrics, and execution logs.

queued
→
running
→
completed
|
failed
|
cancelled

Export Modes

Full Export

Exports all products from Akeneo. Replaces existing data in destination. Useful for initial setup or complete refreshes.

Incremental Export

Only syncs products changed since last run. Uses updatedSince filter. Optimized for daily updates.

Real-time Progress

During execution, exports display granular metrics:

  • Products fetched from Akeneo
  • Products enriched and transformed
  • Products written to destination
  • Processing rate (products/second)
Complete History
The dashboard maintains a complete history of all exports, including duration, product counts, and error logs for troubleshooting.

Product Structure & Flat Storage

Akeneo Exporter uses a flat storage architecture that optimizes for performance and scalability.

Akeneo Product Hierarchy

Akeneo supports up to 3 levels of product hierarchy:

Product Models

Parent products with variants. Define common attributes (description, brand, images).

Variants

Specific SKUs with variant attributes (size, color, EAN, price). Reference their parent.

Simple Products

Standalone products without variants—digital goods, services, unique items.

Flat Storage Architecture

Instead of embedding variants inside parent products (which causes MongoDB's 16MB document limit issues), we use flat storage with two separate collections:

MongoDB Collections
// Collection: product_parents
// Contains configurable products (Product Models)
{
  _id: "nike-air-max",
  code: "nike-air-max",
  family: "shoes",
  familyVariant: "shoes_size_color",
  name: "Nike Air Max 90",
  attributes: {
    brand: "Nike",
    description: "Classic running shoe...",
    images: [...]
  },
  categories: ["shoes", "running"],
  metadata: { created: "...", updated: "..." }
}

// Collection: products
// Contains variants AND simple products
{
  _id: "nike-air-max-blue-42",
  code: "nike-air-max-blue-42",
  parent: "nike-air-max",  // Reference to parent
  familyVariant: "shoes_size_color",
  attributes: {
    color: "blue",
    size: "42",
    ean: "1234567890123",
    price: 129.99
  },
  metadata: { level: 3, type: "product" }
}

// Simple product (no parent)
{
  _id: "gift-card-50",
  code: "gift-card-50",
  parent: null,  // No parent = simple product
  family: "digital",
  attributes: {
    value: 50,
    currency: "EUR"
  },
  metadata: { type: "simple-product" }
}

Benefits of Flat Storage

✓
No document size limit

Products with thousands of variants work perfectly

✓
Indexable variant attributes

Create indexes on attributes.size, attributes.color

✓
Efficient updates

Update one variant without rewriting parent document

✓
Better query performance

Direct queries on variants without array unwinding

Querying Your Data

Example queries
// Find a product parent with all its variants
const parent = await db.product_parents.findOne({ code: "nike-air-max" })
const variants = await db.products.find({ parent: "nike-air-max" })

// Find variants by attribute (now indexable!)
db.products.createIndex({ "attributes.size": 1 })
const size42 = await db.products.find({ "attributes.size": "42" })

// Find all simple products
const simpleProducts = await db.products.find({ parent: null })

// Reconstruct full product with variants (application-level join)
const fullProduct = {
  ...parent,
  variants: await db.products.find({ parent: parent.code }).toArray()
}
Application-Level Joins
With flat storage, you'll perform "joins" in your application code. This is a trade-off for unlimited scalability—but modern applications handle this efficiently with simple queries.

Data Flow

Akeneo Exporter acts as a data pipeline, not a data warehouse. Your product data flows through the system in real-time—we never persist it.

1Fetch

Authenticate with Akeneo PIM, query products via REST API, handle pagination automatically.

2Process

Apply enrichers in sequence, transform data according to your rules. No permanent storage.

3Write

Upsert to your database with batch writes. Query immediately after export completes.

text
┌─────────────────┐
│  Akeneo PIM     │  ← Source (your products)
└────────┬────────┘
         │ Fetch via API
         ▼
┌─────────────────┐
│  Akeneo         │  ← Processing (apply enrichers)
│  Exporter       │
└────────┬────────┘
         │ Write
         ▼
┌─────────────────┐
│  Your Database  │  ← Destination (MongoDB/PostgreSQL)
└─────────────────┘
Your Data Stays With You
Akeneo Exporter never stores your product data. We only connect and transform it before writing to your own database.

Scopes & Locales

Understanding Scopes (Channels)

In Akeneo PIM, a scope (also called channel) represents a sales channel with its own set of attribute values. For example, your "ecommerce" scope might have web-optimized product descriptions and online prices, while your "marketplace" scope has Amazon-specific content. Scopes allow you to maintain different views of the same product catalog.

1 Configuration = 1 Scope
Each export configuration targets exactly one Akeneo scope. This clean separation ensures your exported data contains only the attribute values relevant to that specific channel.

Multi-Channel Isolation Strategies

When you have multiple scopes in Akeneo, you have two strategies to organize your exported data:

Strategy A: Database per Scope

Create separate configurations, each targeting a different database.

  • ✓ Physical isolation between channels
  • ✓ No scope filtering in queries
  • ✓ Independent scaling per channel

Strategy B: Custom Table/Collection Names

Use the same database with prefixed table or collection names.

  • ✓ Single database to manage
  • ✓ Cross-channel queries possible
  • ✓ Simpler infrastructure
Strategy A: Database per Scope
// Configuration for E-commerce
{
  name: "E-commerce Export",
  scope: "ecommerce",
  destination: {
    database: "ecommerce"  // Separate database
  }
}

// Configuration for B2B
{
  name: "B2B Export",
  scope: "b2b",
  destination: {
    database: "b2b"  // Separate database
  }
}
Strategy B: Custom Table/Collection Names
// Configuration for E-commerce (same database, prefixed collections)
{
  name: "E-commerce Export",
  scope: "ecommerce",
  destination: {
    database: "products",
    productParentsName: "ecommerce_product_parents",
    productsName: "ecommerce_products"
  }
}

// Configuration for B2B (same database, different prefix)
{
  name: "B2B Export",
  scope: "b2b",
  destination: {
    database: "products",
    productParentsName: "b2b_product_parents",
    productsName: "b2b_products"
  }
}

Understanding Locales

Akeneo supports localizable attributes—attributes that have different values per language (e.g., product name in English, French, German). When exporting, you configure which locales to include and which one is the default.

How Locales Are Exported

The exporter embeds all locale translations directly in each document:

  • Default locale at root: The default locale's values are placed in the root attributes object for fast queries.
  • Other locales in locales object: Additional translations are nested under locales.<locale_code>.attributes.
  • Atomic documents: All locale data is embedded in the same document—no joins needed to get translations.
Product with embedded locales
{
  "_id": "nike-air-max",
  "code": "nike-air-max",
  "attributes": {
    "name": "Nike Air Max 90",        // en_US (default locale)
    "description": "Classic running shoe with Air cushioning.",
    "price": { "amount": 129.99, "currency": "USD" }
  },
  "locales": {
    "fr_FR": {
      "attributes": {
        "name": "Nike Air Max 90",
        "description": "Chaussure de course classique avec coussin d'air."
      }
    },
    "de_DE": {
      "attributes": {
        "name": "Nike Air Max 90",
        "description": "Klassischer Laufschuh mit Air-Dämpfung."
      }
    }
  }
}
Querying Localized Data
To get a product in French, read attributes for non-localized fields and locales.fr_FR.attributes for localized fields. Most applications merge these at query time or in application code.

Multi-Tenant Architecture

Akeneo Exporter is built with multi-tenancy at its core. All resources (configurations, enrichers, exports) are scoped to your organization using an orgId. Teams within the same company share resources, but different organizations are completely isolated—you'll never see another company's configurations or data.

This architecture scales naturally as your business grows. Need to add a new sales channel? Create a new configuration with the appropriate scope and destination. Want to apply different enrichment rules per channel? Attach channel-specific enrichers to each configuration. All exports from all channels are tracked in a unified dashboard.