Ergonode PIM¶
Ergonode is the Product Information Management (PIM) system used by Zwerfkei to master all product catalogue data. It is used as a SaaS solution and serves as the single source of truth for products, variants, categories, attributes and images.
Architecture Decision
The decision to adopt Ergonode as the PIM platform is documented in ADR-0008 — PIM: Ergonode.
What Is Managed in Ergonode¶
| Data Type | Description |
|---|---|
| Categories | Hierarchical product categorisation tree. |
| Attribute Groups | Logical groupings of product attributes (e.g. "Dimensions", "Material"). |
| Attribute Types | Typed product properties: text, number, select, multi-select, boolean, image, etc. |
| Attribute Options | Selectable values for select and multi-select attributes. |
| Products | Product records with SKU, title, descriptions and attribute values. |
| Product Variants | Variant-level data (SKU, attribute values specific to the variant). |
| Product Images | Original product and variant images. |
Integration with Zwerfkei API¶
Ergonode PIM ──(API)──► Zwerfkei API (sync job) ──► MySQL Database
A scheduled sync job in the Zwerfkei API polls the Ergonode API for updated products, categories and attributes. Changed records are upserted into the Zwerfkei database.
Image handling
Only original images are stored in Ergonode. Image variants (thumbnails, resized versions) are generated by the CMS. Do not reference Ergonode image URLs directly in the frontend.
Data ownership
Ergonode is the master for all catalogue data. Changes to product data must always be made in Ergonode, not directly in the Zwerfkei database.
Category Structure (Third Axis)¶
Work in progress
Products are categorised along three axes: an overarching category, a group, and a subgroup. The third axis (subgroup) is currently filled in manually for a limited set of products only.
The goal is to configure the import process so that products are automatically mapped to the correct category on all three axes, based on data already present in NAV/source feeds. Manual assignment is not feasible at the scale of Zwerfkei's catalogue (~60,000 articles) — this is the main driver behind the automation effort.
- Existing legacy menu items (e.g. "Campé", "Divers") are being used as the starting point for a mapping to the new three-axis categorisation.
- The intent is to anchor this mapping more rigorously in the system — not only as menu items, but as real product characteristics/attributes.
- Templates are linked to the third axis to control which attributes are shown for a product. Today, attribute templates are not yet reliably linked to the third axis, which causes irrelevant attributes (e.g. "normvallen", "carabinersluiting") to appear on products they don't apply to. Assigning the correct attributes per section still requires manual work and product knowledge from the internal team.
Category model impact
The category model documented in ERD and docs/domains/erd.md currently represents Category as a single self-referencing tree. This may need to be revisited once the three-axis structure is fully implemented — not yet confirmed.
Attribute Sections¶
Product attributes are grouped into sections so that products within the same category can be compared more easily. Section names are also intended to be readable and manageable via the API.
This is the concept referenced by the mapping-extend-template-sections.csv file under Attribute Mapping below — that file maps which attribute sections apply to which products/templates. Determining which attributes belong to which section (and which third-axis category) is ongoing work that requires input from the product departments.
Data Completeness¶
Ergonode is expected to support completeness sets/views to help identify incomplete product data:
- Filtering on missing attributes or images, per product or per section.
- Completeness scores per section, to quickly identify which products still need to be enriched.
Current state
Completeness validation is not yet set up. Larger categories (e.g. clothing, bags) tend to have relatively complete data; smaller items (e.g. camping accessories such as tweezers) often have two or fewer images and missing attributes.
Under consideration
Using AI to auto-generate texts and attributes for small/low-value products is being considered to reduce manual enrichment effort. This is not a confirmed decision.
Product Workflow Statuses¶
Proposed, not yet implemented
A product lifecycle workflow with statuses new → in progress → published → offline has been proposed for Ergonode, to give better visibility into new/incomplete products and prevent incomplete products from going live.
Do not confuse with webshop status
This is a separate status system from the legacy webshop article status (offline / online / discontinued) described in Stock Statuses & Orderability. The Ergonode workflow status governs the PIM enrichment lifecycle; the webshop status governs customer-facing visibility.
Variant Consistency¶
- A product should always be shown as a variant product in Ergonode whenever NAV holds variants for it, to avoid a product switching between "simple" and "variant" product types when, for example, a colour is added.
- The variant code, combined with the article number, is used as the unique identifier for a variant.
Known sync issue
Variants are not always correctly pulled from NAV, which can result in products appearing in Ergonode without their variants. This is a known, unresolved reliability issue in the NAV → Ergonode sync — see also K3 Data Models for how variants are modelled on the NAV side.
Color Management¶
Zwerfkei's colour data is highly unstructured: there are 9,000+ distinct colours in the system (see K3_colour_theme for the current vendor/brand colour code mapping), with hundreds of new colours added per year and no standardisation from suppliers.
Planned improvements:
- Clean up and group colours into a set of roughly 50 general colours to simplify filtering, via scripts.
- Add new custom fields for colour text, hex code, and colour group — these are back-office fields, not shown to customers.
- New colours are linked to a brand prefix to prevent naming conflicts between suppliers.
No automatic colour extraction
Deriving colour automatically from product images (e.g. average image colour) was considered but judged too difficult. Colour management remains largely manual for now and depends on agreements with suppliers.
Image Upload & API Throttling¶
A background process handles uploading images and other data to Ergonode. API calls are throttled to a maximum rate of one call per 200 milliseconds to protect performance.
Setup & Entity Relationship Diagram¶
The Ergonode product domain ERD and setup documentation lives in the zwerfkei-backend repository:
Source Data: NextWebShop¶
The NextWebShop OneDrive directory (maintained by Olaf) contains product data files, import sheets and related assets used during the migration to the new platform.
Attribute Mapping (Deprecated)¶
Deprecated
This section is deprecated and kept for reference only. It may be removed in the future. See Attribute Mapping below for the current source.
The mapping-pim-attributes spreadsheet maps the Zwerfkei product attributes to Ergonode PIM attribute definitions. It is the reference for which attributes exist, their types, and how they correspond between the legacy platform and the new PIM setup.
Open mapping-pim-attributes (Excel)
Attribute Mapping¶
The current attribute and category mapping files are maintained in the zwerfkei Bitbucket repository, under pim_export/ on the feature/pim-export-articles branch:
| File | Description |
|---|---|
mapping-pim-attributes_new.csv |
Maps Zwerfkei product attributes to Ergonode PIM attribute definitions. |
mapping-extend-template-sections.csv |
Maps attribute (extend template) sections used in the PIM export. |
productcategorieen.csv |
Maps product categories between the legacy platform and Ergonode. |
Open mapping-pim-attributes_new.csv Open mapping-extend-template-sections.csv Open productcategorieen.csv