• Overview
  • Applicable versions
  • The basics of what this connector does
• Installation
  • Prerequisites
  • E-commerce API in Perfion
  • Installing the connector in Magento
    • Installing the connector on Magento Open Source
      • Require the necessary packages in the project and install the packages
    • Installing the connector on Magento Commerce / Magento Cloud
  • Updating the connector in Magento
    • Updating the connector on Magento Open Source
    • Updating the connector on Magento Commerce / Magento Commerce Cloud
• Configuring the connector
  • Configuration in Perfion
    • Set up a website feature for your Magento instance
    • Set up your category structure
    • Create E-commerce Channel
    • Create Ecommerce Search
    • Create E-commerce Mappings
      • Language Deviation Mapping
      • Category Mapping
      • Category Products Positioning
      • Product Mapping
      • Set up Stock Management in Perfion
      • Product attribute values fallback
      • Automatic Product Removal
      • Product Images Alt Text (labels)
  • Configuration in Magento
    • Set up channels in Magento
    • Setting up automatic cron jobs
      • Setting up automatic cronjobs
      • Purging old batches
    • CLI commands
      • Fetch data from Perfion
      • Process received data
      • Pruning unused attributes and options
      • Purging old batches
    • Optional: Setting up a message queue consumer
    • Manual Cron Jobs Setup
      • Example 1: Full import every hour
      • Example 2: Full import at night, incremental/delta import during the day
    • Batch storage location
    • Logging
    • Message Verbosity
• Additional mappings
  • Map media gallery for products
    • Custom image roles
  • Setting up variants
• Creating multiple shops
• Other settings
  • Attribute cleanup
• Troubleshooting appendix
  • Using the Perfion API Query analyzer to test the variant setup
  • Mapping variants
  • Mapping to multiple channels and multiple languages
  • Multi select attributes
  • Integration timeouts
  • PHP Insufficient memory issues
  • Attribute sets
  • Text field length in Magento is limited to 255 characters

 

Overview

Applicable versions

The following Magento version has currently been tested and approved for this version of the Perfion Connector:

• Magento Open Source 2.4.6, 2.4.7, 2.4.8
• Magento Commerce / Magento Commerce Cloud 2.4.6, 2.4.7, 2.4.8

The basics of what this connector does

The Perfion Connector for Magento facilitates the transfer of product data from Perfion PIM to Magento. Its core functionality is illustrated in Figure 1.

Magento requests data from Perfion based on the configured channels. Data can be attributes, categories, and products. Perfion will provide that data in the way that it has been mapped in Perfion for the given E-commerce Channel. The Perfion Connector will process the received data and create the attributes, categories, and products.

Installation

Prerequisites

Before installing the connector, make sure you have the following prerequisites set up:

1. You have a running Magento 2 installation with the latest version of PHP 8.1, 8.2, 8.3 or 8.4 running. Please consult the official Magento 2 system requirements for your version: System requirements
2. Composer (https://getcomposer.org/) is installed and executable on the server.
3. You have a Perfion Database v. 5.0 (or newer).
4. You have a Perfion API set up on IIS Perfion running at least 5.0 (or newer). The Perfion API endpoint must be accessible from the Magento server.
   Please note: If a firewall protects your Perfion instance in your infrastructure setup, please put all Magento server IPs in the allow list of your firewall.
5. Your Perfion license must include licenses for the Perfion Ecommerce API with at least one Ecommerce Channel and the Magento 2 connector.

E-commerce API in Perfion

All configuration details for the E-commerce API can be found under “Feature Data” in Perfion. Go to “Feature Data”, then expand the “String”-features node and finally expand the “ECommerce Features” node. Here you will find seven selectable features, where some need to be filled out by you, and the rest can and should be left as is.

Below is an overview of what each of the E-commerce features on the left-hand side contains:

• E-commerce Channel: Here, you create all the channels you need. Roughly speaking, you will need a channel per output channel. For the Magento Connector, you will typically need either a single channel or multiple channels - one per website - if the catalog structure varies significantly between Magento websites.
• E-commerce Entity: The following entities are currently supported by the E-commerce API: Site, Category, Product, Variant, and Language Deviation. This is used internally by the connector and should not be modified.

• E-commerce Mapping: This section displays all mappings from Perfion to a specific channel (in this case, Magento). A mapping defines how a value or field in Perfion corresponds to its equivalent in Magento - for example, “X in Perfion is mapped to Y in Magento.”

  You can view and edit all mappings by selecting this node. This is the central area for configuring the connector, and we will cover the necessary steps in detail in Section 3.1.5.

• E-commerce Output Kind: This section lists all Output Kinds - these define how the target value (“Y”) should be generated or formatted based on the source value (“X”) from the previous mapping.
• E-commerce Settings: Here, you find the settings needed to set up the Connector.
• E-commerce System: Here you will find a list of e-commerce systems to pick from. Version 4.5.52 auto-creates four E-commerce systems: Shopify, Sana, and Magento, since these are the systems recognized by Perfion and the systems for which Perfion provides a connector. If you are making your own output from the E-commerce API, it makes good sense to add a new E-commerce System to this list. 
  Note: From version 4.5.52, when accessing the E-commerce API for data belonging to one of the known channels, it is checked that the Perfion license includes a license to the connector used.
• E-commerce Type: This is just a selectable feature that you will need if you want to use support for variants. The two values here, “Product” and “Variant,” should not be modified in any way. Support for variants is described in the section Mapping variants below.

Installing the connector in Magento

An installation via Composer is the only valid way to properly install and manage the connector in a Magento 2 instance.

For installation, please log in to your server via SSH on your command line interface (CLI) and navigate to the directory with the Magento installation.

Installing the connector on Magento Open Source

Require the necessary packages in the project and install the packages

composer require perfion/magento-connector-metapackage

See Manage third-party extensions for common 3rd party extensions installation guide.

Installing the connector on Magento Commerce / Magento Cloud

Require the necessary packages in the project and install the packages

composer require perfion/magento-connector-metapackage perfion/perfion-objectdata-importer-magento2-commerce

See Manage third-party extensions for common 3rd party extensions installation guide.

Updating the connector in Magento

Updating the connector in Magento 2 only requires a straightforward command after you’ve logged onto the server and navigated to the path of your Magento installation.

Updating the connector on Magento Open Source

composer require perfion/magento-connector-metapackage <a_new_version>,

e.g:.

composer require perfion/magento-connector-metapackage:^5.0.0,

Updating the connector on Magento Commerce / Magento Commerce Cloud

composer require perfion/magento-connector-metapackage <a_new_version>,

e.g:.

composer require perfion/magento-connector-metapackage:^5.0.0,

composer update perfion/perfion-objectdata-importer-magento2-commerce

Configuring the connector

This chapter guides you through all the necessary configurations for setting up the connector for the first time. The first section will take you through the necessary steps in the Magento backend interface. The next section will take you through the steps needed in Perfion.

Upon completing this chapter, you will have a basic setup of Magento 2 with the Perfion Connector.

Configuration in Perfion

The next sections will take you through all the necessary steps to set up an entire configuration for a connector for a website in Perfion.

Set up a website feature for your Magento instance

To get started, you need to create a dedicated feature for your Magento store.

You can simply name the new feature “Magento”. But if you plan to connect multiple Magento stores to your Magento store, it is recommended to name the feature based on the name of your store.

After that, click on the three dots at the main menu at the bottom and open the section designer menu. In the section “Website,” add a new option by clicking on the grey cell above “Sana Commerce” and create a new option either via right-click and “Add New” or by hitting CTRL+N on your keyboard.

After that, go to Channels in the Administration menu and create a new channel as below. Make sure that the appropriate users have access to the new channel.

Set up your category structure

While you could just use the default category structure for the Magento Connector, it is highly recommended to create your own category structure. It is required to set it up like this if you plan to connect your Perfion instance to more than one Magento store.

The following example shows the default category structure on the left-hand side at the top and a custom category structure on the left-hand side at the bottom.

After you’ve set up the category structure, you can simply add the products via drag and drop from the right-hand side to the category on the left-hand side.

Create E-commerce Channel

Usually, you need a single e-commerce channel per webshop instance. Please go to “Feature Data” - “String” - “ECommerce Features” - “ECommerce Channel” in Perfion and create a new channel for your Magento instance as shown below:

Create Ecommerce Search

For an ecommerce channel to only retrieve the products that are assigned to a specific store, you need to configure an ecommerce search beforehand.

The following example only retrieves the products from the new feature (Magento) that we just created:

Create E-commerce Mappings

The following mappings must be configured:

• Language Deviation
• Category
• Product

Important information for creating the E-commerce Mapping:

• Magento has fixed rules about the attribute code names, which will be created automatically based on the Perfion features. When you specify the field names in the E-commerce Mapping, please keep the following rules in mind:
  • Max. 60 characters
  • Start with a letter
  • Only contains letters and numbers
  • snake_case (same way as Magento attribute codes areusually named)
  • No whitespace
• These rules are essential, especially if you’re using the Wildcard selector in the Perfion Ecommerce Mapping, where Perfion will use the Feature name as the field name.
• If a Feature/Field name doesn’t match the criteria mentioned above, the connector will not create the attribute.
• Magento has a fixed set of default attributes that can be used in the E-commerce Mapping. If you plan to do that, please make sure that the data types match.
  • Example: In Magento, the “color” attribute is a single select attribute. If you have the same attribute in Perfion but as a “multi-value” feature, the data types won’t match, and there will be a conflict during import. In this case, do not map your “color” feature to the “color” attribute of Magento, but specify a custom field name (e.g., customername_color).
• Supported EAV Attribute Backend types are:
  • Text (Text features)
  • Decimal (Number features)
  • Int (Boolean and Dropdown-type features)
  • Varchar (All the rest)

Language Deviation Mapping

The Language Deviation mapping is used to store the product data for a specific store view in Magento. Please specify all Perfion-internal language codes that you want to use in Magento to the specific Magento store-view codes.

Please note:

• You must specify the store view code in the Ecommerce Mapping exactly the same as you created the store view codes in Magento.
• If you, for example, have multiple store views in Magento that should use the English language, you can map one language in Perfion to multiple store views. Please make sure to always map you’re default language to “admin” so that Magento has values on the global scope as well.
• If you only use one language in Perfion, please specify the mapping for “admin”, which represents the global scope of Magento.

Category Mapping

In the E-commerce Mapping, please create a new “Context” for E-commerce Entity Category” and add features/fields to the mapping.

Please make sure that you always map the following mandatory fields:

Also, recommended optional fields are:

Category Products Positioning

The category products position (sort order) is imported as well to reflect the same order as in the Perfion catalog.

Example:

Product Mapping

In the E-commerce Mapping, please create a new “Context” for E-commerce Entity “Product” and add features/fields to the mapping.

As feature name, please specify “Product/WebDetail/NAME_OF_YOUR_ECOMMERCE_SERACH” to receive only products in the mapping that are assigned to the categories for this store.

Mandatory fields:

Recommended optional fields:

To send more product information to your Magento store, simply add more fields to the e-commerce mapping. The Magento Connector will automatically create the attributes for the fields that are not known by default.

Note: please make sure the EcommerceTo mappings are named in a snake_case. This field is used to form Magento Attribute codes, so it’s important to have a proper format.

Optional fields:

Product attribute values fallback

Out of the box, Magento uses an admin(default) scope value when it is missing on a store or website level.

This way, in Magento/Adobe Commerce, you can:

• save an empty value,
• remove a value to use the default one.

In Perfion, you can only remove it, so as a result, the same behavior cannot be achieved due to differences between the platforms.

So, it order to remove feature value for some specific store (culture) you must make sure it is empty for admin scope, too.

Example:

Automatic Product Removal

This feature allows the connector to automatically clean up the Magento catalog by removing or disabling products that are no longer part of the Perfion synchronization. It is designed to ensure that the Magento store stays perfectly in sync with the source data in Perfion.

• How it works
  During a full (non-incremental) synchronization, the connector identifies products in Magento (linked via the perfion_id column) that are missing from the latest data feed for that specific channel. Depending on the configuration, these "orphaned" products are either disabled or completely deleted from Magento.
   
• How to manage
  1. Enable Channel Permission: Go to Perfion > Channels and edit the desired channel. Ensure the "Allow delete" checkbox is enabled.
  2. Select Removal Action: Navigate to Stores > Configuration > Services > Perfion > Connector. Under the Product Removal Action setting, choose between Disable (status set to "Disabled") or Delete (product entity completely removed).
  3. Execution: The removal process will trigger automatically during the next full synchronization of the enabled product channel.

Product Images Alt Text (labels)

Image alt text can be added as Attribute in Perfion mappings, and it has to be named <Field>@alt, there <Field> is your image type attribute name.

It will overwrite the existing alt text in Magento only if it is set in Perfion.

It is not localizable, like the images themselves.
Example:

 

Set up Stock Management in Perfion

This section is optional. You might want to provide the stock information for products through Perfion, in case stock management for your products does not happen in a 3^rd-party system (e.g., ERP system).

The connector currently supports the following fields:

If you’re using Magento Multi Source Inventory (https://docs.magento.com/user-guide/catalog/inventory-management.html) to manage multiple warehouses, stores, pickup locations, drop shippers, etc., you must provide one more field:

Configuration in Magento

After the connector has been installed, it needs to be configured to reach the Perfion API. This “connection to Perfion” is the only thing you need to configure in Magento. The rest of the configuration will be done in Perfion.

Set up channels in Magento

In the Magento Admin UI, go to Perfion > Channels. You will see an empty list of channels as shown below:

Simply click the 'Add channel' button. This will take you to the channel creation form as shown below:

 

Once you have made the necessary configuration settings, click “Save” to finalize the channel, which will then be ready to receive data. You can repeat this process to create additional channels for other data types.

Please create the channels in the following order:

1. Attribute
2. Category
3. Product

Setting up automatic cron jobs

By default, the connector does not automatically fetch data from your Perfion instance unless you enable it in Magento Admin -> Stores -> Configuration -> Services -> Perfion -> Scheduled Operations:

The synchronization via Cron can be enabled or disabled as needed, and the execution schedule is fully configurable.

When activated, the automated process will:

• Retrieve fresh data batches for each configured channel
• Process the received data accordingly

Setting up automatic cronjobs

By default, the connector does not automatically fetch data from your Perfion instance unless you enable it in Magento Admin -> Stores -> Configuration -> Services -> Perfion -> Scheduled Operations:

The synchronization via Cron can be enabled or disabled as needed, and the execution schedule is fully configurable.

When activated, the automated process will:

●        Retrieve fresh data batches for each configured channel

●        Process the received data accordingly

Purging old batches

The connector stores the received data from Perfion in the filesystem (var/perfion directory). To prevent the storage from filling up and potentially having no more disk space available, you may enable cleaning them up daily:

The batches will be deleted from the database and the filesystem nightly, according to their specified lifetime in days.

CLI commands

Fetch data from Perfion

php /path/to/bin/magento perfion:fetch CODE

The placeholder CODE reflects the auto-generated code for a given channel and data type combination, which the Perfion connector automatically generates. You can get the value from the channel list in the admin UI, as shown below.

Process received data

The fetch command only fetches the XML from Perfion and does not directly import it. To process the XML and import the data, you need to run the following command:

php /path/to/bin/magento perfion:process -vv

Additional remarks:

• Please note that the attributes import must run before the category/product import.
• Please note that categories always need to be imported before the product import. Otherwise, the automatic category assignment won’t work.
• It is recommended that you run the index process of Magento after the import as well.

Pruning unused attributes and options

Based on the Perfion attributes, it’s possible to remove attributes that are either empty or not being used on any products with the console command

 bin/magento perfion: prune-unused-attributes

Purging old batches

Except purging old batches by the configurable cron job, you can also do so manually using the `bin/magento perfion:purge` command.

You can also use the --more-than-days option to specify the age of the batch that you want to clean up.

Optional: Setting up a message queue consumer

If you want to fetch new data for a channel manually via the admin UI instead of (or in addition to) a cron job, you need to start a message queue consumer. Without a running consumer, the requests will not be handled, and no data will be fetched.

If default Magento cron jobs are set up correctly, no actions are required: the queue consumers will be started and maintained in a running state automatically: https://experienceleague.adobe.com/en/docs/commerce-operations/configuration-guide/message-queues/manage-message-queues#process-management

Manual Cron Jobs Setup

In case the default cron job is not flexible enough to fulfill the project-specific needs, the flow can be set up using manual system cron configuration.

Example 1: Full import every hour

Running a full import every hour requires a very simple cron job configuration:

# Purge
0 0 * * * php bin/magento perfion:purge > /dev/null 2>&1

# Full import every hour
0 * * * * php /path/to/bin/magento perfion:fetch channel_attribute > /dev/null 2>&1
5 * * * * php /path/to/bin/magento perfion:fetch channel_category > /dev/null 2>&1
10 * * * * php /path/to/bin/magento perfion:fetch channel_product > /dev/null 2>&1
15 * * * * php /path/to/bin/magento perfion:process > /dev/null 2>&1

Example 2: Full import at night, incremental/delta import during the day

If you have a large product catalogue, you might not want to do a full load every time, but rather incremental delta updates during daytime and a full load at night.

In this example, the full load is always done at midnight, and the incremental updates are done every full hour between 08:00 and 20:00.

Cronjob configuration:

# Purge
0 0 * * * php bin/magento perfion:purge > /dev/null 2>&1

# Full import
0 0 * * * php /path/to/bin/magento perfion:fetch channel_attribute > /dev/null 2>&1
5 0 * * * php /path/to/bin/magento perfion:fetch channel_category > /dev/null 2>&1
10 0 * * * php /path/to/bin/magento perfion:fetch channel_product > /dev/null 2>&1
15 0 * * * php /path/to/bin/magento perfion:process > /dev/null 2>&1

# Delta import
0 8-20 * * * php /path/to/bin/magento perfion:fetch channel_category_incremental > /dev/null 2>&1
5 8-20 * * * php /path/to/bin/magento perfion:fetch channel_product_incremental > /dev/null 2>&1
10 8-20 * * * php /path/to/bin/magento perfion:process > /dev/null 2>&1

Batch storage location

XML batches from Perfion are downloaded to your Magento directory, specifically in the var/batches/perfion folder.

Logging

The connector features an advanced logging system that enhances the default logging capabilities of Magento.

It offers two new log files that are specifically dedicated to the integration.

• perfion.debug.log – all records
• perfion.error.log – only errors or higher

Notification alerts

When an alert or critical log record is reported, it can be sent as an email notification.

It can be configured in the Admin -> Stores -> Configuration -> Services -> Perfion:

Such events are:

• Batch download failure (e.g., Perfion API inaccessible)
• Batch processing failure

Message Verbosity

To adjust the verbosity level in Perfion, go to: Stores > Settings: Configuration > Services > Perfion.

Add additional information in the Perfion Message grid of the individual batches:

Additional mappings

This section provides an overview of several additional mappings.

Map media gallery for products

If you want to add additional product images to the media gallery in Magento, you need to create a new feature in Perfion where you can select multiple images at once, as shown in the example below:

Once you have created the new feature, go to E-commerce Mapping and assign the new feature to the field name "gallery":

Custom image roles

 You may also import custom image roles as attributes.

Just configure the relevant mappings, and the new image attributes will be imported. In the example above, it is the ‘group_image’.

 

Setting up variants

The Magento 2 connector offers built-in support for variants. Please consult the E-commerce API manual for properly setting up variants in Perfion beforehand.

In the E-commerce Mapping, you need to map the following additional features for context “Product”:

• Feature: ECommerceType
  ECommerce Output Kind: ECommerceType
• Feature: ECommerceVariantDimensions
  ECommerceOutputKind: VariantDimension
  Field: VariantDimension

Next, create an E-commerce mapping for the context "Variant" and add all desired features to your Magento store. The image below demonstrates a complete example.

Creating multiple shops

The Magento 2 connector offers built-in support for multiple shops in one Magento installation. This feature is part of the E-commerce API.

To connect multiple shops, you just need to repeat all the steps outlined in the previous chapters.

Other settings

Attribute cleanup

In addition to cleaning up unused attributes, you have the option to also delete NULL-valued attributes in the database. This might sometimes be useful if you have data integrity issues.

You can enable this setting in: Stores->Configuration->Services->Perfion, where you can select “Delete options without a value”.

Troubleshooting appendix

In this section, you will find answers to common troubleshooting issues.

Using the Perfion API Query analyzer to test the variant setup

A helpful tool for configuring your Perfion integration is the Perfion API Query Analyzer.

In the Query Analyzer, you can right-click the text window and select "Validate query." In the XML text that appears, replace `value='Channel A'` with `Value=[YourMagentoStore]`, and then click "Execute." This process will provide you with hints about any mistakes in your eCommerce configuration or settings.

Example output:

Mapping variants

• Please note that when configuring the EcommerceVariantDimension in your product grid, the feature name you enter, is case sensitive, which means it must match the “Perfion Unique Name” of the feature exactly.
• The EcommerceVariantDimension feature must correspond to the relevant Magento attribute using the same naming convention.

For example, the feature "ColorVariation" expects the corresponding attribute in Magento to be named "colorvariation." Even if you map "ColorVariation" to a different name (such as "custom_color" in Ecommerce Mapping), that change will not be recognized.

Mapping to multiple channels and multiple languages

When mapping multiple channels, follow these guidelines:

1. On your primary channel, ensure that the primary language of the Language Deviation is mapped to "admin."

2. For your secondary channels, map the website's default language to "admin" and the store view language to the corresponding store view name.

Multi select attributes

When you use multiple languages, make sure that your multi-select attributes are translated as well, since attributes cannot be created with an empty value.

Integration timeouts

If you experience integration timeouts, often indicated by the message “error fetching HTTP headers,” you can adjust the timeout settings. When running the Perfion integration commands, either manually or through CRON jobs, you can specify a PHP timeout by prepending your command with the following:

`php -d default_socket_timeout=<SECONDS> <COMMAND>

In this command, `<SECONDS>` is the number of seconds you want to allow before a request times out (using -1 specifies no timeout), and `<COMMAND>` is the specific Perfion command you wish to execute.

For example, to fetch and process items for all channels, you would use:

php -d default_socket_timeout=-1 bin/magento perfion:run

PHP Insufficient memory issues

Depending on the server setup regarding the maximum PHP memory consumption, you might need to specify a higher memory limit when executing commands either manually or in CRON jobs.

To execute a command with a specific memory limit, you can prepend your commands with:

php -d memory_limit=<MAX_LIMIT_IN_BYTES> <COMMAND>, where <MAX_LIMIT_IN_BYTES> is the maximum allowed memory consumption in bytes (-1 is unlimited), and <COMMAND> is the perfion command you wish to execute.

For example, to fetch and process items for all channels, you would use:

php -d memory_limit=-1 bin/magento perfion:run

You can set multiple parameters when executing commands. For instance, if you need to specify both the timeout limit and the memory limit, it appears as follows::

php -d default_socket_timeout=-1 -d memory_limit=-1 bin/magento perfion:run

Attribute sets

If you wish to utilize attribute sets in Magento, you will need to create them and manually organize your attributes within Magento. However, you can assign products to specific attribute sets directly from Perfion.

We recommend starting with an initial product transfer from Perfion to Magento. This ensures that all attributes defined in your E-commerce mapping are created in Magento and ready to be grouped into attribute sets.

Once the attributes are in place, you can proceed to define your attribute sets and organize the attributes as desired using Magento’s editor.

Afterward, you can configure the attribute_set mapping in Perfion’s E-commerce Mapping section by selecting a field that determines the attribute set assignment within Perfion.

A suggested approach:

• Create a selectable string feature in Perfion and add it to your product configuration.
• In the E-commerce Mapping, map this feature from the FROM column to the attribute_set in the TO column (Type: Field).
• Define selectable values for the feature and assign them to products to specify their attribute set.

While attribute set groupings will not be altered during imports, any new attributes from Perfion will automatically be added to the corresponding Perfion grouping in Magento.

Selectable string feature
 

Mapping of selectable string feature

Selectable on product

Text field length in Magento is limited to 255 characters

When using Text features in Perfion, please be aware that Magento has a standard limit of 255 characters for varchar attribute values. If your text exceeds this length, it cannot be transferred to Magento using the default varchar type.

To ensure compatibility, make sure that:

• The Perfion feature type is set to “Text”.
• The corresponding attribute in Magento has the backend type set to “text”.

If the backend type in Magento is not correctly configured, you will need to recreate (reimport) the attribute to apply the correct type.