Icecat Connector Laravel Package

Getting Started

Minimal Steps to Begin

1. Install the Package

   composer require akeneo/icecat-connector 2.1.*
   

   Ensure compatibility with your Akeneo PIM version (e.g., >= v2.2 - < 3.0).

2. Register the Bundle Update app/AppKernel.php to include:

   new \Pim\Bundle\IcecatConnectorBundle\PimIcecatConnectorBundle(),
   new \Pim\Bundle\ExtendedAttributeTypeBundle\PimExtendedAttributeTypeBundle(),
   new \Pim\Bundle\ExtendedMeasureBundle\PimExtendedMeasureBundle(),
   

   Add routing in app/config/routing.yml:

   pim_icecat_connector:
       resource: "@PimIcecatConnectorBundle/Resources/config/routing.yml"
       prefix: /icecat
   

3. Set Up Database Schema Run:

   bin/console doctrine:schema:update --force
   

4. Configure Icecat Credentials Navigate to Akeneo Admin → Icecat Connector to input:

   • Icecat API credentials (username/password).
   • Unique EAN attribute (e.g., ean).
   • Fallback locale/channel for non-localized data.

5. First Use Case: Download Icecat Features Run the icecat_download_features import profile to generate a CSV mapping template (featuresList.csv). Example:

   bin/console akeneo:import:execute icecat_download_features
   

Implementation Patterns

Workflows

1. Attribute Mapping Setup

• Download Features: Use icecat_download_features to fetch Icecat’s feature list (CSV). Edit the CSV to map Icecat feature_id to Akeneo pim_attribute_code. Example:

  feature_id,pim_attribute_code,ignore_flag
  12345,weight,0
  67890,color,0
  

• Upload Mapping: Run icecat_import_features_mapping to validate and apply mappings.

  bin/console akeneo:import:execute icecat_import_features_mapping
  

2. Product Enrichment

• Manual Trigger: Use the icecat_enrich_products import profile via Akeneo UI or CLI:

  bin/console akeneo:import:execute icecat_enrich_products
  

• Automated (Cron Job): Schedule the job in Akeneo’s Job Queue or via system cron:

  0 3 * * * bin/console akeneo:import:execute icecat_enrich_products --env=prod
  

3. Handling Extended Measures

• Configure unit conversions in config.yml under measures_config:

  measures_config:
      Weight:
          standard: KILOGRAM
          units:
              KILOGRAM:
                  convert: [{'mul': 1}]
                  symbol: 'kg'
  

• Validate measures with:

  bin/console pim:measures:check
  

Integration Tips

• EAN Attribute: Ensure the EAN field is unique and indexed for API performance.
• Locale Mapping: Use the provided locale mapping table to align Icecat locales with Akeneo.
• Error Handling: Log API failures in PimIcecatConnectorBundle’s IcecatClient service for debugging.
• Batch Processing: For large catalogs, limit enrichment to specific channels or locales via job parameters.

Gotchas and Tips

Pitfalls

1. API Rate Limits

   • Icecat’s XML API has rate limits. Throttle requests in IcecatClient:

     // Example: Add delay between requests
     sleep(1); // 1-second delay
     

   • Monitor API calls in Akeneo logs (var/log/prod.log).

2. Mapping Errors

   • Type Mismatches: Icecat’s numeric features (e.g., weight) mapped to Akeneo text attributes will fail silently. Validate with:

     bin/console akeneo:import:execute icecat_import_features_mapping --validate-only
     

   • Missing EANs: Products without EANs are skipped. Use a mass edit action to populate missing EANs.

3. Locale Fallbacks

   • If fallback_locale is misconfigured, enriched data may default to INT (International), losing localization. Test with:

     bin/console akeneo:import:execute icecat_enrich_products --locale=en_US
     

4. Deprecated Commands

   • Older versions used csv-base-import commands. Update to xml-base-import (e.g., icecat-job-instance-xml-base-import-show).

Debugging

• API Connection Issues

  • Test credentials via the Icecat Connector admin UI ("Test Connection" button).
  • Check Guzzle logs:

    // In config/services.yaml
    Pim\Bundle\IcecatConnectorBundle\Client\IcecatClient:
        arguments:
            - '@logger'
            - !tagged 'icecat.client'
    

• Job Failures

  • Inspect job reports in Akeneo → Jobs.
  • Enable debug mode for detailed logs:

    APP_ENV=dev APP_DEBUG=1 bin/console akeneo:import:execute icecat_enrich_products
    

Extension Points

1. Custom Icecat Client Extend IcecatClient to add headers or retry logic:

   namespace App\Bundle\Client;
   use Pim\Bundle\IcecatConnectorBundle\Client\IcecatClient as BaseClient;
   
   class CustomIcecatClient extends BaseClient {
       public function fetchProductData($ean) {
           $this->client->setDefaultOption('headers', ['X-Custom-Header' => 'value']);
           return parent::fetchProductData($ean);
       }
   }
   

   Register as a service in services.yaml:

   Pim\Bundle\IcecatConnectorBundle\Client\IcecatClient: '@app.custom_icecat_client'
   

2. Post-Enrichment Processing Use Akeneo’s Mass Edit Actions to transform Icecat data (e.g., convert weight from grams to kg):

   // In a custom mass edit action
   $product->setValue('weight', $product->getValue('weight') / 1000);
   

3. Measure Unit Overrides Override default measures in config/packages/pim_measures.yaml:

   pim_measures:
       measures_config:
           Length:
               units:
                   CENTIMETER:
                       convert: [{'mul': 0.01}] # Override to meters
   

Performance Tips

• Batch Size: Limit icecat_enrich_products to 100–500 products per job to avoid timeouts.
• Caching: Cache Icecat API responses (e.g., features list) to reduce redundant calls:

  // In IcecatClient
  $cache = $this->container->get('pim_cache');
  $cachedFeatures = $cache->get('icecat_features');