Excel Init Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require akeneo/excel-init-bundle:3.0
   

   Enable the bundle in config/bundles.php (or AppKernel.php for older Akeneo versions):

   return [
       // ...
       Pim\Bundle\ExcelInitBundle\PimExcelInitBundle::class => ['all' => true],
   ];
   

2. Download the Template:

   • Copy the init.xlsx from the bundle’s fixtures:

     vendor/akeneo/excel-init-bundle/src/Resources/fixtures/minimal/init.xlsx
     

   • Place it in your project’s config/import/ directory (create if missing).

3. First Use Case:

   • Open init.xlsx in Microsoft Excel (not LibreOffice/OpenOffice).
   • Populate the sheets (families, categories, attributes, channels, etc.) with your catalog structure.
   • Run the import:

     php bin/console pim:import:execute --env=prod --file=config/import/init.xlsx
     

Where to Look First

• Documentation: Start with the Getting Started guide.
• Template: Study the init.xlsx structure (e.g., families sheet requires code, label, and channels columns).
• Logs: Check var/log/prod.log for errors during import.

Implementation Patterns

Workflows

1. Catalog Initialization:

   • Use init.xlsx to define families, categories, attributes, channels, and locales upfront.
   • Example: Define a family with code: "tshirts" and associate it with web_mobile channel.

2. Incremental Updates:

   • After initial setup, use the bundle to add new families/categories without re-importing everything.
   • Example: Append a new category row to the categories sheet and re-run the import.

3. Channel Management:

   • Ensure channel names match exactly across sheets (e.g., channels and families tabs).
   • Use the channels sheet to define channel types (e.g., ecommerce, mobile) and currencies.

4. Attribute Groups:

   • Group attributes by family in the attributes sheet using the family_variant column.
   • Example:

     code | type | family_variant
     size | pim_catalog_identifier | tshirts
     color| pim_catalog_text | tshirts
     

5. Locale Handling:

   • Define locales in the locales sheet (e.g., en_US, fr_FR).
   • Use these locales in families/categories sheets for labels (e.g., label_en_US).

Integration Tips

• Pre-Import Validation:

  php bin/console pim:import:validate --env=prod --file=config/import/init.xlsx
  

  Fix errors before executing the import.

• Custom Templates:

  • Extend the init.xlsx template by copying it to config/import/custom_init.xlsx and modifying sheets.
  • Reference it in commands:

    php bin/console pim:import:execute --file=config/import/custom_init.xlsx
    

• Automate with CI:

  • Add the import to your deployment pipeline (e.g., GitHub Actions) to ensure consistency across environments.

• Post-Import Actions:

  • Use Akeneo’s API or CLI to assign products to families post-import:

    php bin/console pim:product:assign-family --env=prod --family=tshirts --product=PRODUCT_SKU
    

Gotchas and Tips

Pitfalls

1. Excel Compatibility:

   • LibreOffice/OpenOffice: Corrupts the XLSX structure, causing validation failures. Always use Microsoft Excel.
   • Mac vs. Windows: Excel for Mac may introduce hidden formatting issues. Test on Windows if possible.

2. Channel Name Mismatches:

   • Typos in channel names (e.g., web_mobile vs. web-mobile) will silently fail during family/category assignment.
   • Debug: Run pim:import:validate to catch mismatches early.

3. Missing Sheets:

   • The bundle expects specific sheets (families, categories, attributes, etc.). Missing sheets cause errors.
   • Fix: Ensure all required sheets exist in the XLSX file.

4. Attribute Type Conflicts:

   • Reusing an attribute code (e.g., size) with different types (e.g., pim_catalog_text vs. pim_catalog_identifier) breaks imports.
   • Solution: Delete the attribute manually via Akeneo UI before re-importing.

5. Locale Labels:

   • Labels must match locales defined in the locales sheet (e.g., label_en_US for en_US).
   • Error: Missing locale codes (e.g., label_fr without fr_FR) will fail validation.

6. Currency Mismatches:

   • Channels must reference existing currencies (e.g., USD, EUR). Define currencies in the channels sheet first.

Debugging

• Dry Run:

  php bin/console pim:import:execute --dry-run --file=config/import/init.xlsx
  

  Simulates the import without changes.

• Log Level: Increase logging in config/packages/monolog.yaml:

  handlers:
      main:
          level: debug
  

• SQL Dumps: For complex issues, compare database states before/after import using:

  mysqldump -uUSER -pPASS DATABASE > pre_import.sql
  php bin/console pim:import:execute --file=init.xlsx
  mysqldump -uUSER -pPASS DATABASE > post_import.sql
  

Extension Points

1. Custom Sheets:

   • Extend the bundle by adding new sheets to init.xlsx and updating the importer (requires custom development).
   • Example: Add a product_templates sheet for pre-defined product structures.

2. Validation Rules:

   • Override validation logic by extending the bundle’s Validator class (e.g., add custom rules for attribute values).
   • Location: src/Validator/ExcelInitValidator.php.

3. Post-Import Scripts:

   • Use Akeneo’s post_import event to trigger actions after import:

     // config/services.yaml
     Pim\Bundle\ExcelInitBundle\EventListener\PostImportListener:
         tags:
             - { name: kernel.event_listener, event: pim_enrich.post_import, method: onPostImport }
     

4. Fixtures Overrides:

   • Replace the default init.xlsx with a custom version in config/import/ to enforce project-specific defaults.

Tips

• Backup Database: Always back up your database before running imports, especially in production.

• Test Incrementally: Start with a minimal init.xlsx (e.g., only families and channels), then expand.

• Use Akeneo’s UI for Manual Fixes: For one-off corrections, use the Akeneo admin panel instead of re-importing entire sheets.

• Version Alignment: Ensure your akeneo/excel-init-bundle version matches your Akeneo PIM version (see requirements).

• Performance: For large catalogs, split the init.xlsx into multiple files (e.g., families.xlsx, attributes.xlsx) and import sequentially.