What you need to know before using the connector

Summary

Overview

The Akeneo Connector does two things :

  1. Keep the SDM-PIM connected project up to date with its related PIM configuration
  2. Push products to the PIM once a job is completed.

Configuration Fetch

Configuration: It is the global structure of the PIM (Families, attribute groups… as listed below)

The configuration fetching process between SDM and PIM works by overriding the Project configuration in SDM (except for certain specific steps outlined below).

  • Changing a project configuration manually if it is linked to a connector is useless as manual changes will be overridden during the next sync.
  • The PIM sync overrides the project config only, not the step configs
  • The configuration is synchronized using a cron task.
 

Categories and Hierarchies Fetch

During the sync:

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

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

Note: 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 PIM.

Activating the split_categories option also changes the default project setup, adding a categorization step for each tree and a mapping step to combine different categories into the categories attribute during the push.

 

Attributes Fetch

SDM and PIM use different sets of attributes. In general:

  • Scopable attributes: SDM creates one version per channel targeted, naming them as ${attribute_name}-${channel_name}.
  • Localizable attributes: One version is created for each activated locale.
  • Scopable and localizable attributes: All combinations of channels and locales are created and named ${attribute_name}-${channel_name}-${locale}.

Unsupported attribute types

For clarity’s sake, here are the PIM attribute types not currently supported in SDM :

  • pim_catalog_date
  • pim_catalog_file

More info➡️ PIM Attribute Handling and Limitations

It is now possible to manually synchronize with the Akeneo connector directly from the SDM interface!  This means that when changes are made in the PIM, SDM users no longer need to wait until the next day's automatic sync or ask their SDM contact to fetch the PIM.

 

Product push

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

⚠️ SDM uses the mass update and creates an endpoint for the push, meaning that if there is any conflict, the connector will override existing data in the PIM.

 

Empty values are not pushed. This means that empty fields in SDM will not overwrite existing data in the PIM when pushing updates to an existing product.

 

Push Identifier

The identifier used for the push depends on the use_uuid_push option. If it is disabled (default behavior) then we will push to the /api/rest/v1/products PIM endpoint and will use the pim_catalog_identifier as identifier.

If instead the option is activated we will push to the /api/rest/v1/products-uuid PIM endpoint. By default we will do this by generating an UUID4 on our end. But this means that we won't handle product updates as we don't accept a UUID attribute so there is no way to match a product coming into SDM to a product in the PIM. This is the point of the use_uuid_memory option.

If activated, we will also need to provide a uuid_memory_reference_base and uuid_memory_keys. This argument allows SDM to store the generated UUID in a Reference Base using the uuid_memory_keys as unique columns. That way if a product is to be pushed and we match all the values of uuid_memory_keys with a row present in the uuid_memory_reference_base, we will used the store UUID instead of creating a new one and therefore update the product.

Push Identifier Example

The method used to identify products during the push process depends on the configuration options. There are two main 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

When using UUID push with the UUID memory option, the process enables product updates:

  • Options:
    • use_uuid_push is enabled
    • use_uuid_memory is enabled
    • Requires uuid_memory_reference_base and uuid_memory_keys
  • Process:
    1. Checks the Reference Base for existing UUIDs
    2. Uses uuid_memory_keys as unique columns to match products
    3. If a match is found, uses the stored UUID for updates
    4. If no match is found, generates a new UUID for the product and stores it in the Reference Base

3. UUID Push with Memory Process

  1. The system checks the Reference Base (UUID Memory) for an existing UUID based on the uuid_memory_keys.
  2. If a match is found, it uses the stored UUID for the product update.
  3. If no match is found, it generates a new UUID and stores it in the Reference Base for future reference.
  4. Finally, it pushes the product to the PIM using the appropriate UUID.

Push Assets

Assets are pushed to their asset families according to mapping.

Push Variants

When using variants, the push process (as well as the config sync) is different and described in details in the Variant documentation page.

Interface

Re-sync PIM configuration

From Configuration tab > Connector, it is now possible to launch a fetch of the latest version of the PIM structure from the SDM interface, overriding the next Cron task.

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