Akeneo → Magento 2 Integration

Purpose

Synchronize product data from Akeneo to Magento 2 reliably. IEC first imports entities into a local schema (Products, Attributes, Families, Categories) and then emits mutations to the Magento 2 Driver to create/update products.

Ingestion from Akeneo

• Config: `config/akeneo.php` (`AKENEO_API_URL`, auth profile, `AKENEO_WEBHOOK_SECRET`).
• Webhooks: `App\Http\Controllers\Ingestion\Webhook\*` endpoints validate signatures via `ValidateWebhookSignature` and trigger imports for changed entities.
• Scheduled/API sync: `php artisan akeneo:import:data {entity} {--codes=} {--full}` uses repositories:

- `AkeneoProductRepository`, `AkeneoAttributeRepository`, `AkeneoFamilyRepository`, `AkeneoCategoryRepository`

- Actions map Akeneo payloads to local models (`ImportProductAction`, `ImportProductAttributeAction`, `ImportFamilyAction`, `ImportCategoryAction`).

- Akeneo webhooks: https://api.akeneo.com/documentation/webhooks.html

• Akeneo PHP client: https://github.com/akeneo/php-api-client

- Incremental filters are built via configured builders (e.g., `UpdatedDateBuilder`) and use ISO 8601 datetimes from settings.

Local Product Model (EAV)

• `products` table with EAV values in `product_attribute_values` keyed by (attribute_code, channel, locale).
• `Product::toIntegrationPayload()` composes identifier, flags, related categories, and flattened attribute values.

Mutation Creation

• `EntityObserver` listens to create/update/delete and computes changed fields:

- Direct attribute changes from Eloquent

- EAV changes tracked by `TracksEavChanges`

• Creates a `Mutation` + `MutationJob` per enabled Integration that accepts the entity type.

Driver Execution (Magento 2)

• `Magento2Driver::handle(MutationData)` logs and delegates to a rules-based payload builder for products.
• HTTP Client: `Magento2ClientBuilder` builds a Guzzle client using Bearer token and base URI. Endpoints under `rest/V1`.
• Mapping lookup to decide `POST` (create) vs `PUT` (update) by external ID.

Magento 2 Payload Builder

• Builder: `Modules/Magento2/Services/Builder/ProductBuilder` composes product payloads and applies modular rules.
• Example rules currently enabled:

- `StatusRule`, `ProductTypeRule`

- `CategoryRule`, `AssetsRule`, `WebsitesRule`, `GermanSpecialCharactersRule`

- `PriceRule` (new)

• `AttributesRule`: maps Akeneo values to Magento 2 `custom_attributes` with type casting. Now supports a configurable ignore list `config('magento2.product.attributes.mapping.ignore')` so attributes handled by specialized rules (price, assets, websites) are not duplicated.
• `WebsitesRule`: populates `extension_attributes.website_ids` from integration website mapping. Exposes its attribute key as a constant for reuse in config.
• `AssetsRule`: processes asset attributes. Exposes asset attribute codes as a constant for reuse in config.
• `PriceRule`: computes price using `automated_price` when present/valid, otherwise falls back to `selling_price_scope`. Runs only when one of those attributes is present in the change set.
• Store-scoped payloads: the builder can derive per-store requests using store mappings to respect channel/locale scoping. For store-scoped builds, diff-only updates are used only when a per-store mapping exists; otherwise a full payload is built (global "all" mapping).

Families & Categories

• Actions:

- `SyncFamilyAction` (`products/attribute-sets`) updates Magento attribute sets. For updates, the payload is augmented with `attribute_set_id`.

- `SyncCategoryAction` (`categories`) updates Magento categories. For updates, the payload is augmented with `id`.

• Response handlers:

- `FamilyResponse` sets `entityField = 'attribute_set_id'` for external ID extraction.

- `CategoryResponse` sets `entityField = 'id'` for external ID extraction.

• Category payloads include `labels` translations and `parent_id` from the local model.

Website/Store Mapping

• Configuration has moved under the Integration’s `field_mapping`:

- `integrations['<identifier>'].field_mapping.websites`

• Example shape:

- `field_mapping.websites = { code: { id, is_default?, channel, stores: [{ id, code, locale, is_default? }] } }`

Payloads

• IEC product payload closely resembles Akeneo output but normalized:

- `identifier`, `enabled`, `family`, `categories`, `values` (list of `{attribute_code, channel, locale, value, unit}`)

• Drivers are responsible for transforming to Magento 2’s expected schema.

Queues & Retries

• MutationJobs for product changes are prioritized via the Integration’s `priority_map` (e.g., price updates as high priority).
• Retries/backoff per Integration.

External References

• Akeneo Webhooks: https://api.akeneo.com/documentation/webhooks.html
• Akeneo PHP Client: https://github.com/akeneo/php-api-client
• Magento 2 REST API: https://developer.adobe.com/commerce/webapi/rest/use-rest/
• Laravel Horizon: https://laravel.com/docs/12.x/horizon

- Laravel: https://laravel.com/