What you need to know before using the connector

Summary

The Supplier Data Manager (SDM) Akeneo PIM connector does two things:

  1. Keeps the SDM project configuration in sync with the connected Akeneo PIM structure (Families, Attribute groups, Categories, Attributes).
  2. Pushes enriched products from SDM back to Akeneo PIM once a job is completed.

Configuration fetch

Configuration refers to the global structure of Akeneo PIM — Families, Attribute groups, Categories, Attributes, and related metadata — that SDM imports to build its own project structure.

The configuration fetch process works by overriding the project configuration in SDM with data pulled from Akeneo PIM. Manual changes to a project's configuration are overwritten on the next sync.

  • Changing a project configuration manually when it is linked to an Akeneo connector is ineffective — manual changes are overridden during the next sync.
  • The PIM sync overrides the project config only, not the step configs.
  • The configuration is synchronized on a schedule using a cron task.

Categories and hierarchies fetch

During the SDM configuration sync with Akeneo PIM:

  • Attribute groups in Akeneo PIM are converted to display groups in SDM.
  • Families and categories are modeled as hierarchies in SDM.
  • Attributes are converted according to their type.

By default, all synced categories are embedded into a single hierarchy called categories.

For customers who need separate steps for each category tree, the split_categories option can be activated. This creates one hierarchy per category tree in Akeneo PIM.

Activating split_categories also changes the default project setup: SDM adds one categorization step per tree and one mapping step to combine the different categories into the categories attribute during the push.

Attributes fetch

SDM and Akeneo PIM use different attribute models. During the sync, SDM expands scopable and localizable attributes as follows:

  • Scopable attributes: SDM creates one version per channel targeted, named ${attribute_name}-${channel_name}.
  • Localizable attributes: SDM creates one version per activated locale.
  • Scopable and localizable attributes: SDM creates all combinations of channels and locales, named ${attribute_name}-${channel_name}-${locale}.

Unsupported attribute types

SDM does not support the following Akeneo PIM attribute types — these attributes are skipped during the configuration fetch:

  • pim_catalog_file
  • pim_catalog_product_link

For a full list of supported and partially supported attribute types, see PIM Attribute Handling and Limitations.

Manual synchronization

You can manually trigger a configuration sync from the SDM interface at any time. When changes are made in Akeneo PIM, SDM users no longer need to wait for the next scheduled sync. See Re-sync PIM configuration below.

Limitations

SDM does not support using the same code for both a Family and a Family variant. With this configuration, the fetch operation fails and the project cannot be updated.

Product push

Once the final step of a job is completed, the SDM Akeneo connector attempts to push the enriched products to Akeneo PIM using the PIM's public API.

SDM uses the mass update (upsert) endpoint for the push. If there is a conflict, the connector overrides existing data in Akeneo PIM.

Empty values are not pushed. Empty fields in SDM do not overwrite existing data in Akeneo PIM when updating an existing product.

Push identifier

The identifier used during the push depends on the use_uuid_push option configured on the Akeneo connection.

Standard identifier push (default):

  • use_uuid_push is disabled
  • SDM pushes to the /api/rest/v1/products endpoint
  • Products are identified using the pim_catalog_identifier attribute

UUID push:

  • use_uuid_push is enabled
  • SDM pushes to the /api/rest/v1/products-uuid endpoint
  • SDM generates a UUID4 for each product

UUID push without UUID memory cannot handle product updates — there is no way to match a product in SDM with an existing product in Akeneo PIM, because SDM does not store or accept a UUID attribute by default.

UUID push with UUID memory:

To enable product updates when using UUID push, activate use_uuid_memory and provide:

  • uuid_memory_reference_base — the Reference Base where UUIDs are stored
  • uuid_memory_keys — the fields used as unique columns to match products

SDM stores generated UUIDs in the Reference Base using the uuid_memory_keys columns. When the same product is pushed again, SDM looks up the stored UUID and reuses it instead of generating a new one.

For uuid_memory_keys to work correctly, each key field must be required and must exist in all Family groups. There is no need to add a Match History step to the project — the connector connects to the Reference Base automatically.

Push identifier example

The method used to identify products during the push depends on the configuration options. There are three approaches:

1. Standard identifier push (default)

  • Option: use_uuid_push is disabled
  • Endpoint: /api/rest/v1/products
  • Identifier: Uses pim_catalog_identifier

2. UUID push

  • Option: use_uuid_push is enabled
  • Endpoint: /api/rest/v1/products-uuid
  • Identifier: Uses UUID generated by SDM (no product update support without UUID memory)

3. UUID push with UUID memory

  • Options: use_uuid_push enabled, use_uuid_memory enabled, uuid_memory_reference_base and uuid_memory_keys configured
  • Process:
    1. SDM checks the Reference Base (UUID Memory) for an existing UUID based on the uuid_memory_keys.
    2. If a match is found, SDM uses the stored UUID to update the existing product in Akeneo PIM.
    3. If no match is found, SDM generates a new UUID, stores it in the Reference Base for future reference, and creates the product in Akeneo PIM.
    4. SDM pushes the product to Akeneo PIM using the appropriate UUID.

Diagram showing the UUID push with memory process: check Reference Base, use stored UUID if found, otherwise generate and store a new UUID, then push to PIM.

The diagram above shows the UUID push with memory flow: SDM checks the Reference Base for an existing UUID using the configured uuid_memory_keys. If a match is found, the stored UUID is used to update the product. If not, a new UUID is generated, stored, and used to create the product in Akeneo PIM.

Push assets

Assets are pushed to their asset families in Akeneo PIM according to the SDM mapping configuration.

Push variants

When using product variants, the push process and the configuration sync follow a different flow. See the Variants documentation for details on how SDM handles Akeneo PIM Family variants during push.

Re-sync PIM configuration

You can manually trigger a synchronization to update the Akeneo PIM configuration in SDM at any time, without waiting for the next scheduled cron sync.

  1. In SDM, go to Workflows.
  2. Click the workflow you want to synchronize.
  3. Click Settings in the left sub-navigation, then click Connector.
  4. Click Synchronize.

SDM fetches the latest Akeneo PIM structure immediately.

Once you click Synchronize, the status changes to In progress:

SDM Connector settings page showing the Synchronize button and the sync status displaying "In progress".

The screenshot above shows the SDM Connector settings page after clicking Synchronize, with the sync status set to "In progress".

When the synchronization is complete, the page automatically refreshes to display the new last sync date and the status Done:

SDM Connector settings page showing the sync status as "Done" and an updated last sync date.

The screenshot above shows the SDM Connector settings page after a successful sync, with the status "Done" and the updated last sync date.

Want to find out more? Take a look at these related articles