AdvancedCsvConnector ou comment booster ses imports / exports Akeneo

Le PIM Akeneo nous permet nativement d'importer et d'exporter des produits au format CSV (qui peut être édité & généré depuis Excel). Ce connecteur natif est très efficace mais il nécessite toujours quelques lignes de code pour s'adapter aux fichiers de nos clients : entêtes différentes, prix au mauvais format, valeurs par défaut pour les colonnes non renseignées, etc.

Suite à plusieurs projets Akeneo en version 2.3, nous avions souvent l'impression d'avoir un code très similaire pour des clients différents. Le développement et la mise en place de notre bundle AdvancedCsvConnector nous a permis de gagner énormément en productivité et d'assurer une qualité optimiale sur tous les projets.

Ce dernier fonctionne sur un principe simple : il ajoute un nouveau connecteur CSV basé sur le natif avec un paramètre de job supplémentaire appelé "mapping". Ce mapping, au format JSON, permet de faire correspondre une entête de colonne avec un code attribut d'Akeneo et d'y ajouter de la "magie" si nécessaire (callback's, normalisation des valeurs, etc.). Nous n'avons pratiquement plus aucune ligne de PHP grâce à ce bundle !

Lien GitHub : https://github.com/ClickAndMortar/AdvancedCsvConnectorBundle

Installation

L'installation du bundle se réalise simplement via la commande Composer suivante :

composer require clickandmortar/advanced-csv-connector-bundle

Il faut ensuite charger le bundle dans votre fichier AppKernel.php :

<?php

// ...
class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = [
            // ...
            new ClickAndMortar\AdvancedCsvConnectorBundle\ClickAndMortarAdvancedCsvConnectorBundle(),
        ];

        // ...
    }

    // ...
}

Utilisation

Passons à la partie la plus intéressante, l'utilisation de ce bundle pour gérer vos imports et exports CSV

Import

Il faut commencer par créer une nouvelle instance du job. Dans la partie Imports, cliquer sur Créer un profil d'import et choisir la tâche Import des produits avancé (CSV) dans le connecteur Click And Mortar Advanced CSV Connector. Dans la partie Paramètres généraux, il est possible d'éditer ce fameux mapping :

Nous allons prendre un mapping d'exemple et détailler les différentes possibilités :

{
    "attributes": [
        {
            "attributeCode": "ean_code",
            "dataCode": "codeEan",
            "identifier": true
        },
        {
            "attributeCode": "lens_height",
            "dataCode": "hauteurVerre",
            "callback": "setMetricUnitAsSuffix",
            "deleteIfNull": true
        },
        {
            "attributeCode": "universe",
            "dataCode": "style",
            "onlyOnCreation": true,
            "locales": [
                "fr_FR",
                "en_GB"
            ]
        },
        {
            "attributeCode": "age_range",
            "dataCode": "trancheAge",
            "normalizerCallback": "getAgeRange"
        },
        {
            "attributeCode": "life_cycle",
            "dataCode": "idCycleVie",
            "defaultValue": "1"
        },
        {
            "attributeCode": "price-EUR",
            "dataCode": "prix"
        }
    ],
    "normalizers": [
            {
                "code": "getAgeRange",
                "values": [
                    {
                        "normalizedValue": "0-18",
                        "originalValues": [
                            "5",
                            "12"
                        ]
                    },
                    {
                        "normalizedValue": "18-35",
                        "originalValues": [
                            "19",
                            "26"
                        ]
                    },
                    {
                        "normalizedValue": "35-50",
                        "originalValues": [
                            "38"
                        ]
                    }
                ]
            }
        ],
    "completeCallback": "completeProductItem"
}
  • identifier (obligatoire) : Utilisé pour la colonne qui contiendra l'identifiant unique du produit (il pourra être utilisé pour rechercher un produit en base de données avant mise à jour)
  • attributes (obligatoire): C'est dans ce tableau qu'on va retrouver le mapping codes attributs / noms de colonnes
  • attributeCode (obligatoire) : Code attribut à mapper dans Akeneo
  • dataCode (obligatoire) : Nom de la colonne dans le fichier (la ligne d'entête doit être présente dans le fichier CSV)
  • callback : Chaîne de caractères correspondant au nom d'une méthode disponible dans le service ImportHelper (service qui peut être étendu dans votre projet). Il est ainsi possible de rajouter du code spécifique pour modifier une valeur récupérée dans le fichier CSV
  • normalizerCallback : Tout comme le callback mais en version simplifiée et sans PHP, le normalizerCallback permet d'indiquer un nom de normalizer à utiliser. La valeur lue sera comparée par rapport aux valeurs données dans originalValues et s'il y a une correspondance, on retournera la valeur normalizedValue)
  • defaultValue : Valeur par défaut pour l'attribut donné si la colonne du fichier est vide
  • onlyOnCreation : Booléen permettant d'indiquer si la valeur doit être ajoutée uniquement à la création du produit (très pratique dans le cas d'une description produit où cette dernière doit être mis à jour lors du premier import mais pas forcément mis à jour ensuite pour éviter d'écraser les contributions)
  • locales : Lorsqu'un attribut est localisable (valeur différente pour chaque locale), ce paramètre permet de "remplir" les différentes locales avec la même colonne
  • completeCallback: Chaîne de caractères correspondant à une méthode disponible dans le service ImportHelper. Cette méthode prendra en paramètre un tableau contenant toutes les valeurs récupérées depuis la ligne du fichier CSV. Il sera alors possible de créer de nouvelles valeurs ou d'éditer les existantes en fonction de conditions spécifiques à votre projet

Export

Le système d'export fonctionne exactement comme l'import (avec un mapping) pour lier un code attribut Akeneo à une colonne spécifique du fichier CSV en sortie. Il faut commencer par créer une nouvelle instance du job. Dans la partie Exports, cliquer sur Créer un profil d'export et choisir la tâche Export des produits avancé (CSV) dans le connecteur Click And Mortar Advanced CSV Connector. Dans la partie Paramètres généraux, on retrouve toujours notre paramètre mapping.

Comme pour l'import, voici un exemple d'un mapping d'export avec des explications pour chaque paramètre :

{
    "columns": [
        {
            "attributeCode": "sku",
            "columnName": "Code reference"
        },
        {
            "attributeCode": "ean_code",
            "columnName": "EAN Code",
            "forcedValue": "Same code"
        },
        {
            "attributeCode": "family_code",
            "columnName": "Family code",
            "normalizerCallback": "getNormalizedFamily"
        },
        {
            "attributeCode": "age_range",
            "columnName": "Age",
            "callback": "completeAgeRange"
        },
        {
            "attributeCode": "color",
            "columnName": "Couleur",
            "useLabel": true,
            "locale": "fr_FR"
        },
        {
            "attributeCode": "type",
            "columnName": "Type",
            "useReferenceLabel": "ClickAndMortarTypeBundle:Type",
            "locale": "fr_FR"
        },
        {
            "attributeCode": "brand",
            "columnName": "Marque",
            "capitalized": true
        },
        {
            "attributeCode": "label",
            "columnName": "Libellé",
            "maxLength": 50
        },
        {
            "attributeCode": "price-EUR",
            "columnName": "Prix (EUR)",
            "defaultValue": "0.00"
        }
    ],
    "normalizers": [
        {
            "code": "getNormalizedFamily",
            "values": [
                {
                    "normalizedValue": "Man",
                    "originalValues": [
                        "12",
                        "121",
                        "122"
                    ]
                }
            ]
        }
    ],
    "replacements": [
        {
            "values": [
                "!"
            ],
            "newValue": "!!!"
        }
    ],
    "additionalColumns": [
        {
            "columnName": "Additional column",
            "value": "Same content"
        }
    ],
    "additionalHeadersLine": {
        "Code reference": "My code reference",
        "EAN Code": "EAN technical code"
    },
    "completeCallback": "completeProductColumns"
}
  • columns (obligatoire) : Tableau contenant le mapping des codes attributs / noms de colonnes
    • attributeCode (obligatoire) : Code de l'attribut dans Akeneo
    • columnName : Nom de la colonne à créer dans le fichier CSV (si non présent, le code d'attribut sera utilisé de façon classique)
    • forcedValue: Permet simplement de forcer une valeur pour une colonne dans le fichier d'export (pratique pour des valeurs fixes nécessaires dans les outils internes chez nos clients)
    • normalizerCallback : Fonctionnement identique à l'import
    • callback : Fonctionnement identique à l'import mais la méthode doit se trouver dans le service ExportHelper
    • useLabel : Booléen utilisé pour les attributs liés à des options. Il permet d'exporter le libellé au lieu du code d'option
    • locale : En association avec le paramètre précédent, il permet de sélectioner une locale spécifique pour le libellé à exporter
    • useReferenceLabel : Comme pour le useLabel, ce paramètre permet d'exporter le libellé pour un attribut de type pim_reference_data_simpleselect (voir le bundle https://github.com/akeneo-labs/CustomEntityBundle). On doit indiquer le nom de l'entité dans ce paramètre
    • capitalized : Booléen permettant de forcer la valeur exportée en majuscules
    • maxLength : Entier permettant de restreindre la taille de la chaîne de caractères à exporter
    • defaultValue : Comme pour l'import, valeur par défaut si l'attribut n'est pas complété au niveau du PIM
  • normalizers : Liste des normalizers comme pour l'import
  • replacements : Système de remplacement global permettant de remplacer toutes les valeurs du paramètre values par newValue
  • additionalColumns : Permet l'ajout de colonnes "statiques" dans l'export CSV généré
  • completeCallback : Comme pour l'import mais au niveau du service ExportHelper

N'hésitez pas à nous contacter si vous souhaitez obtenir plus d'informatiions ou une démonstration de notre bundle spécifique à Akeneo.