Akeneo PIM mapping.

This guide shows how an Akeneo installation emits ULC records.

Akeneo data model in one page

Products are the core entity, identified by identifier (SKU).
Families group products that share an attribute set (downlight family vs linear-pendant family vs bollard family).
Attribute groups are a global organizational layer; families reference attributes that belong to those groups. The same electrical or photometry attribute group can serve multiple families (downlight, linear, bollard).
Variants and variant groups model SKU-level variation. Parent product-models hold shared attributes; variants carry per-SKU differences (CCT, distribution, finish).
Categories are a separate hierarchy from families, used for marketing navigation and channel filtering.
Channels define per-channel localization and completeness rules. A ULC emit channel can enforce that only records with complete photometric data ship.
Asset Manager (Enterprise Edition) holds cutsheet PDFs, IES files, and LDT files as Asset Families. Reference Entities (also Enterprise-only) model structured entities like brand or designer. Community Edition has neither: file and image attributes on the product itself are the only built-in option, and the emitter streams those directly.
API: REST with OAuth2 for both reads and writes.

Identity: a product's identifier (the SKU) is a user-editable attribute and can change, so anchor ULC emit integrations on Akeneo's stable internal product ID, and map the identifier to configuration.catalog_number.

Core mapping

Identity

Akeneo	ULC path
Product `identifier`	`configuration.catalog_number`
Product model code (parent)	`product_family.family_id`, `product_family.catalog_model`
Brand attribute	`product_family.manufacturer.slug`
Product line / series	`product_family.catalog_line`
Derived full slug	`record_id`

Family to primary category

Akeneo family	`primary_category`	`mounting_types`
`downlight_recessed`	`downlight`	`["recessed_ceiling"]`
`linear_pendant`	`linear`	`["pendant"]`
`wall_pack_exterior`	`bulkhead_wall_pack`	`["surface_wall"]`
`high_bay_industrial`	`high_bay`	`["pendant", "surface_ceiling"]`
`bollard_outdoor`	`bollard`	`["surface_floor"]`
`sconce_interior`	`sconce`	`["surface_wall"]`

Dimensional and photometric

Akeneo's pim_catalog_metric attribute type carries both value and unit ({amount: 113, unit: "MILLIMETER"}). The API also uses pim_catalog_simpleselect (enum), pim_catalog_file, and pim_catalog_image as exact type-code strings for filter queries. The emitter converts metric values to ULC dual-unit at emit time. Common mappings:

Akeneo attribute	ULC path
`overall_diameter` (`pim_catalog_metric`, MILLIMETER)	`product_family.physical_dimensions.overall_diameter`
`weight` (`pim_catalog_metric`, KILOGRAM)	`product_family.physical_dimensions.luminaire_mass`
`input_power_w`	`electrical.input_power_w.value`
`total_luminous_flux_lm`	`photometry.total_luminous_flux_lm.value`
`cct_k` (`pim_catalog_simpleselect`)	`colorimetry.nominal_cct_k`
`cri_ra`	`colorimetry.cri_ra.value`

Unit codes (MILLIMETER, KILOGRAM, CELSIUS) are typical defaults but Akeneo measurement families are user-configurable. The emitter's mapping table must record the actual unit code in use per attribute, not assume defaults.

Gotchas

Product-model vs variant split. Akeneo's 2-level model (parent product-model + variants) maps exactly onto ULC's product_family (shared) vs configuration (per-scenario) split.
Attribute completeness. Tie the ULC emit to a ulc_export channel's completeness so partially-populated SKUs don't ship as broken ULC records.
Metric unit drift. If variants store the same attribute in different units, normalize before computing the companion.
Reference entity depth (Enterprise). Attestations like UL-listed or DLC-qualified can be modeled as reference entities with structured attributes; walk these into attestations[].
Published vs draft. Never emit ULC from a draft product. Wait for the workflow to publish.

Full guide with emit-flow pseudocode, channel completeness configuration, and PHP transform skeleton: github.com/ulcspec/ULC/blob/main/mappings/pim/akeneo.md