Skip to main content

Mage2Plenty v3.12 - Product Mapping & Order Import Controls

· 5 min read
Soft Commerce Team
Soft Commerce Team
Mage2Plenty Development Team

Mage2Plenty v3.12 puts you in control of what syncs and when. Product-to-item mapping is now a first-class, reusable service you can run on a schedule, on demand from the admin, or from the CLI - and it finally reports the truth instead of claiming success while mapping nothing. Order import gains two gates so you can scope a sync to the PlentyONE statuses and creation window you actually care about. Rounding it out: a batch of catalog-import hygiene fixes (no more duplicate attribute options, manufacturer casing preserved) and three order-import correctness fixes - including order properties that now actually persist.

Product Mapping, on your terms​

Mapping links a Magento product/variation to its PlentyONE item + variation id - the foundation every downstream sync relies on. Until now it was a one-shot CLI command, and worse, the batch mapper joined on the wrong column and reported a blanket "success" while mapping nothing. v3.12 rebuilds this around a single service and makes it runnable from anywhere.

One service, three entry points​

The mapping logic is extracted into a reusable MapItemRelationService (API + model), now shared by:

  • Scheduled - a new plenty_item_map cron (config under plenty/item_config/item_mapping/*), gated behind an enable flag, keeps mappings fresh automatically.
  • On demand - Map and Unmap actions are surfaced on the item import and export listings; both redirect back to where you triggered them.
  • CLI - the MapItemRelationCommand is refactored onto the same service, so command, cron and admin buttons all share one code path.

Real counts, correct rows​

  • The batch mapper (BatchItemProductMapping / MapVariation) previously joined pve.sku (the wrong column) and reported success while mapping nothing - it now delegates to the service and reports actual mapped counts.
  • Added unmap() + BatchItemProductUnmapping so you can clear stale links.
  • The MapVariation action ACL now points at a valid resource (it referenced a non-existent one before).
  • The whole path is Adobe Commerce staging-aware: it writes keyed on entity_id (covers all staging versions) and de-duplicates reads with distinct().

Order Import Gating​

Two new guards let an order-import profile decide which PlentyONE orders are eligible - handy when you want to backfill a date range, or only pull orders that have reached a given status.

  • Status filter - IsClientOrderStatusAllowed gates imports by the PlentyONE order status_id (configured under status_config/status_filter).
  • Creation-date cutoff - IsClientOrderCreatedAtExternallyAllowed gates by the PlentyONE external creation date (created_at_externally) against a configurable order_created_at_externally_from cutoff. Orders created before the cutoff are marked skipped, even if they were updated recently.

Both run per order through a new OrderProcessorGuard, and the profile form gains a status filter field and a created-from date field (the date field follows the Enable Schedule toggle).

Catalog Import Hygiene​

  • No more duplicate attribute options (module-core) - option lookup now matches on a normalized label (case- and whitespace-insensitive) before creating, so re-imports stop spawning near-duplicate options on casing or trailing-space drift.
  • Manufacturer name casing preserved (module-plenty-attribute) - manufacturer names import trimmed but not re-cased, so "DeLonghi" no longer arrives as "Delonghi".
  • Config attribute language fallback hardened (module-plenty-item-profile) - configurable value names resolve default lang → en → first available instead of grabbing an arbitrary names[0].
  • URL key disambiguation (module-plenty-item-profile) - special characters are mapped (+ → plus, & → and, …), with a SKU-suffix fallback wired to the "Add SKU Suffix On Duplicate URL Error" setting.

Order Import Fixes​

  • Order properties now persist - mapped PlentyONE order properties are written with a targeted saveAttribute(). Previously setData() only mutated the in-memory order and nothing downstream flushed it, so the values silently vanished.
  • Correct MSI source on order import - resolveProduct now sets the product store id to the sales quote's store for every added item (simple and bundle). A bundle component in stock only in a non-default source (e.g. clinicCare) was wrongly rejected as "no source items with the in stock status"; resolving against the quote's store/sales-channel fixes it across every addProduct path.
  • Cron schedule fields cleaned up - dropped the stray Magento\Cron\Model\Config\Backend\Product\Alert backend model from the order cron-schedule fields, where it never belonged on a cron-expression input.

Release Summary​

ModuleVersionBumpKey Changes
module-plenty-item-profile3.5.1 → 3.6.0minorScheduled / on-demand / CLI product mapping via MapItemRelationService; Map+Unmap admin actions; staging-aware; config-attribute lang fallback & URL-key disambiguation
module-plenty-order-profile2.8.0 → 2.9.0minorOrder import gating by status & creation date; persist order properties; quote-store MSI stock check; cron-field cleanup
module-core2.5.0 → 2.5.1patchPrevent duplicate attribute options via normalized label matching
module-plenty-attribute2.0.5 → 2.0.6patchPreserve PlentyONE manufacturer name casing on import

Metapackage: softcommerce/mage2plenty-os 3.11.0 → 3.12.0

Upgrade Guide​

composer require softcommerce/mage2plenty-os:^3.12

bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

This release ships no schema changes. setup:di:compile is required - the item module gains a new mapping service, console command, cron and admin controllers, and the order-import pipeline gains new guard classes.

Behaviours worth noting on upgrade:

  • Scheduled mapping is opt-in. The plenty_item_map cron is gated behind its enable flag under plenty/item_config/item_mapping/*; existing installs keep their current behaviour until you enable it.
  • Order import gates are off until configured. With no status filter and no creation-date cutoff set, every order imports exactly as before - set the new profile fields to scope a sync.
  • Re-imports stop creating duplicate options from now on; existing duplicates created by earlier runs are not retroactively merged.

Resources​

Questions about the upgrade? Reach out to us at support@byte8.io.