Pim Enhanced Connector Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation

   composer require akeneo-labs/pim-enhanced-connector:~1.4
   

   Enable the bundle in app/AppKernel.php:

   new Pim\Bundle\EnhancedConnectorBundle\PimEnhancedConnectorBundle(),
   

2. Clear Cache & Rebuild Assets

   php app/console cache:clear --env=prod
   php app/console pim:installer:assets --env=prod
   

3. First Use Case: Family Export

   • Navigate to Spread > Export in Akeneo PIM.
   • Select "Export families to CSV for PimGento" job.
   • Configure:
     • Delimiter (e.g., comma)
     • Enclosure (e.g., double quotes)
     • Language for family labels (match Magento admin locale).
     • File path (e.g., /var/exports/families.csv).

4. First Use Case: Attribute Export

   • Select "Export attributes to CSV for PimGento" job.
   • Configure:
     • Delimiter, enclosure, and file path.
     • Ensure the export includes family_code for PimGento compatibility.

Implementation Patterns

Workflows

1. Delta-Based Product Exports

   • Leverage the delta export feature to fetch only products modified since the last export.
   • Configure the export job with:

     # config.yml
     pim_enhanced_connector:
         reader:
             product:
                 delta: true
                 last_export_time: "%last_export_time%" # Use a parameter or env var
     

   • Useful for incremental syncs with external systems (e.g., Magento via PimGento).

2. Completeness and Enabled Filters

   • Filter products by completeness (e.g., complete, incomplete) and enabled status:

     pim_enhanced_connector:
         reader:
             product:
                 completeness: complete
                 enabled: true
     

   • Apply via Export Builder in the UI under job configuration.

3. Categorized/Uncategorized Products

   • Export only categorized or uncategorized products (or both):

     pim_enhanced_connector:
         reader:
             product:
                 categorized_only: true # or false
     

4. Order of Exports for PimGento Follow this sequence for PimGento compatibility:

   1. Categories: Standard Akeneo CSV export.
   2. Families: Enhanced bundle’s family export.
   3. Attributes: Enhanced bundle’s attribute export (with family_code).
   4. Attribute Options: Standard Akeneo CSV export.
   5. Products: Standard Akeneo product export (configured for delta/completeness).

5. Automated Exports with CRON

   • Schedule exports via CRON (e.g., daily delta exports):

     0 3 * * * php app/console pim:export:run --export=your_product_export_job --env=prod
     

   • Combine with SSH for remote transfers (e.g., to a Magento server).

Integration Tips

1. Custom Export Jobs Extend the bundle’s readers/processors for custom logic:

   // src/Akeneo/EnhancedConnector/Reader/ProductReader.php
   class CustomProductReader extends \Pim\Bundle\EnhancedConnectorBundle\Reader\ProductReader
   {
       protected function filterProducts(QueryBuilder $qb)
       {
           $qb->andWhere('p.enabled = :enabled')
               ->setParameter('enabled', true);
           // Add custom filters (e.g., by custom attribute)
       }
   }
   

   Register the service in services.yml:

   pim_enhanced_connector.reader.product: '@your_namespace.custom_product_reader'
   

2. Post-Export Processing Use Symfony’s event system to trigger actions after export:

   // src/Akeneo/EnhancedConnector/EventListener/ExportListener.php
   class ExportListener
   {
       public function onExportFinished(ExportFinishedEvent $event)
       {
           if ($event->getExport()->getJobCode() === 'your_product_export') {
               // Trigger SSH transfer, notify Slack, etc.
           }
       }
   }
   

   Bind to the event in services.yml:

   services:
       your_namespace.export_listener:
           tags:
               - { name: kernel.event_listener, event: pim_enhanced_connector.export.finished, method: onExportFinished }
   

3. Dynamic Configuration Use parameters for runtime configuration (e.g., last export time):

   # app/config/parameters.yml
   last_export_time: "%kernel.root_dir%/../var/last_export_time.txt"
   

   Read/write the file in your export job:

   file_put_contents($this->container->getParameter('last_export_time'), time());
   

Gotchas and Tips

Pitfalls

1. Deprecated Services

   • The bundle replaces core Akeneo services (e.g., pim_enhanced_connector.reader.orm.family → pim_base_connector.reader.orm.family).
   • Fix: Update service references in custom code to match the latest Akeneo version.

2. DataGrid Filter Bug

   • Using "Greater or equal" filters in the UI may break exports.
   • Workaround: Use SQL raw queries or avoid this operator in filters.

3. Product Detachment

   • Older versions detached products during processing, causing performance issues.
   • Fix: Updated in v1.0.3; ensure you’re on a recent version.

4. PimGento Order Dependencies

   • Exports must follow a strict order (categories → families → attributes → products).
   • Tip: Document the export sequence in your team’s runbook.

5. Delta Export Edge Cases

   • Delta exports may miss products if updated_at isn’t updated correctly.
   • Debug: Verify updated_at timestamps in the database for critical products.

Debugging

1. Export Logs Enable verbose logging in config.yml:

   monolog:
       handlers:
           main:
               level: debug
               channels: ["!event"]
   

   Check logs for SQL queries and export progress:

   grep -i "export" app/log/prod.log
   

2. Query Builder Debugging Dump the final query in your custom reader:

   $query = $qb->getQuery();
   $sql = $query->getSQL();
   file_put_contents('/tmp/export_query.sql', $sql);
   

3. CSV Validation Validate exports against PimGento’s requirements:

   • Families: Must include code and label (no spaces in codes).
   • Attributes: Must include code, type, and family_code.
   • Products: Ensure enabled, family, and categories are correctly formatted.

Tips

1. Performance Optimization

   • Batch Processing: For large product sets, use chunked exports:

     pim_enhanced_connector:
         reader:
             product:
                 batch_size: 1000
     

   • Indexing: Ensure updated_at is indexed in the pim_catalog_product table.

2. Testing Exports

   • Use the pim:export:run command with --dry-run to validate configurations:

     php app/console pim:export:run --export=your_job --dry-run
     

   • Test delta exports by manually updating updated_at:

     UPDATE pim_catalog_product SET updated_at = NOW() WHERE id = 123;
     

3. Custom Fields

   • Extend exports to include custom fields (e.g., pim_catalog_product_value):

     // In your custom reader
     $qb->leftJoin('p.productValues', 'pv')
        ->addSelect('pv.text as custom_field');
     

4. Backup Exports

   • Automate backup of export files:

     # In a post-export script
     tar -czvf /backups/exports-$(date +%Y%m%d).tar.gz /var/exports/
     

5. Documentation

   • Maintain a runbook with:
     • Export job configurations (screenshots of UI settings).
     • Troubleshooting steps for common failures (e.g., missing family_code).
     • Contact info for PimGento-specific issues.