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, 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 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
// app/AppKernel.php

// ...
class AppKernel extends Kernel
{
    protected function registerProjectBundles()
    {
        return [
            // ...
            new \Pim\Bundle\CustomEntityBundle\PimCustomEntityBundle(),
            new \ClickAndMortar\AdvancedCsvConnectorBundle\ClickAndMortarAdvancedCsvConnectorBundle(),
        ];
      }
    // ...
}

Mettre à jour votre fichier de routing (app/config/routing.yml) :

pim_customentity:
        prefix: /reference-data
        resource: "@PimCustomEntityBundle/Resources/config/routing.yml"
        
candm_advanced_csv_connector:
    prefix: /candm-advanced-csv-connector
    resource: "@ClickAndMortarAdvancedCsvConnectorBundle/Resources/config/routing.yml"

Et enfin lancer une mise à jour de votre base de données :

php bin/console doctrine:schema:update --force

Utilisation

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

Import

Avant de créer notre profil d'import, nous allons créer notre mapping qui utilise une entité référentielle. Dans la partie Référenciel / Mappings d'import, cliquer sur Créer en haut à droite.

Un mapping d'import est composé des propriétés suivantes :

  • Libellé : Utilisé uniquement pour le distinguer des autres mappings
  • Code : Code unique lié au mapping
  • Mapping attributs / colonnes : Tableau dynamique qui permet d'ajouter toutes les lignes de mapping souhaitées. Il est possible d'ajouter autant de lignes que nécessaire via le bouton Ajouter une ligne
  • Méthode de transformation après mapping : 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

Le tableau de mapping contient les colonnes suivantes :

  • Attribut : Code de l'attribut à cibler dans Akeneo (suffixé par la devise dans le cas d'un attribut de type prix)
  • Nom de la colonne : Nom de la colonne à lire dans le fichier CSV
  • Transformation : Nom d'une fonction de transformation LUA. Les scripts LUA permettent de transformer dynamiquement une valeur via un script éditable dans l'interface d'Akeneo. Nous détaillerons ce point par la suite
  • Valeur par défaut : Appliquer une valeur par défaut si la valeur est vide dans le fichier CSV
  • Identifiant : Permet de cibler la colonne qui servira d'identifiant unique dans le fichier. Cet identifiant est important pour l'utilisation de la colonne suivante
  • Uniquement à la création : Permet d'importer la valeur du fichier uniquement si le produit n'existe pas dans Akeneo (on utilise ici l'identifiant pour rechercher le produit dans la base de données)
  • Effacer si nul : Cette option permet d'éviter l'effacement d'une valeur dans Akeneo dans le cas d'une colonne vide dans le fichier CSV
  • Supprimer : Permet d'effacer une ligne de mapping

Une fois le mapping enregistré, il peut être sélectionné au niveau du profil d'import :

Export

Le système d'export fonctionne exactement comme l'import pour lier un code attribut Akeneo à une colonne spécifique du fichier CSV en sortie. Dans la partie Référenciel / Mappings d'export, cliquer sur Créer en haut à droite.

Un mapping d'export est composé des mêmes propriétés qu'un mapping d'import. Seuls les colonnes du tableau sont différentes :

  • Attribut : Permet de cibler l'attribut source dans Akeneo (il est possible d'utiliser un suffixe de devise pour un attribut de type prix)
  • Nom de la colonne : Nom de la colonne dans le fichier CSV qui sera généré
  • Valeur forcée : Permet de forcer une valeur manuellement dans la colonne (ce paramètre peut être utile si le fichier CSV doit comporter des colonnes statiques)
  • Transformation : Comme pour l'import, cette option permet de spécifier un script de transformation LUA
  • Utiliser le libellé : Permet d'indiquer à l'export d'utiliser le libellé de l'attribut souhaité plutôt que son code (dans le cas d'un attribut de type liste avec options par exemple)
  • Langue : Cette option complète la colonne précédente en permettant de choisir la langue à utiliser pour le libellé (par exemple fr_FR)
  • Longueur max. : Permet de "couper" la valeur exportée de l'attribut si la valeur doit être limitée dans le fichier CSV
  • Valeur par défaut : Permet d'indiquer une valeur par défaut si l'attribut est vide dans Akeneo
  • Supprimer : Permet de supprimer la ligne de mapping

Script LUA

Les scripts LUA peuvent être créés dans la partie Référenciel / Scripts LUA. Ils permettent de créer des transformations dynamiques sur des chaînes de characters, des entiers, etc. On peut par exemple imaginer un script permettant de forcer une valeur en majuscule :

Le script peut être rédigé directement dans l'interface d'Akeneo (la référence sur le langage LUA est disponible ici : https://www.lua.org/manual/) et testé aussi via le bouton Tester. Une fois le script enregistré, il peut être utilisé dans les différents mappings d'import ou d'export. Voici quelques exemples de scripts :

  • Concaténation d'une valeur d'attribut avec une extension
newValue = attributeValue .. ".xlsx"

return attributeValue;
  • Passage d'une valeur en majuscules
return string.upper(attributeValue);
  • Multiplication d'un entier
return attributeValue*12;

 

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