Akeneo3 1 Tessa Connector Laravel Package

Getting Started

Minimal Steps to Begin

1. Verify Akeneo API Readiness Ensure Akeneo's API is functional (test via GET /api/rest/v1/product-models). Debug Apache if headers are stripped (see Akeneo API Troubleshooting).

2. Install the Bundle

   composer require eikona-media/akeneo3-1-tessa-connector
   

3. Register Routing Append to app/config/routing.yml:

   tessa_media:
       resource: "@EikonaTessaConnectorBundle/Resources/config/routing.yml"
   

4. Configure TESSA Connection Create a config/packages/eikona_tessa_connector.yaml:

   eikona_tessa_connector:
       api_url: "https://your-tessa-instance.com/api"
       api_key: "%env(TESSA_API_KEY)%"
       akeneo_api_url: "%env(AKENEO_API_URL)%"
       akeneo_api_token: "%env(AKENEO_API_TOKEN)%"
   

5. First Use Case: Sync a Product Image Use the CLI command to push an Akeneo product image to TESSA:

   php bin/console tessa:media:sync --product-id=1 --media-file=path/to/image.jpg
   

Implementation Patterns

Workflows

1. Media Synchronization

   • Automated Sync: Schedule via cron to sync product media daily:

     0 3 * * * php bin/console tessa:media:sync --batch
     

   • Manual Sync: Trigger per product:

     php bin/console tessa:media:sync --product-id=123
     

2. Event-Driven Integration Listen for Akeneo product updates and auto-sync media:

   // src/EventListener/TessaSyncListener.php
   namespace App\EventListener;
   
   use Eikona\TessaConnectorBundle\Service\TessaSyncService;
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   use Akeneo\Tool\Component\Storage\Event\ProductUpdateEvent;
   
   class TessaSyncListener implements EventSubscriberInterface
   {
       private $tessaSyncService;
   
       public function __construct(TessaSyncService $tessaSyncService)
       {
           $this->tessaSyncService = $tessaSyncService;
       }
   
       public static function getSubscribedEvents()
       {
           return [
               'product.update' => 'onProductUpdate',
           ];
       }
   
       public function onProductUpdate(ProductUpdateEvent $event)
       {
           $this->tessaSyncService->syncProductMedia($event->getProduct()->getId());
       }
   }
   

3. Custom Field Mapping Extend the bundle to map Akeneo fields (e.g., image, document) to TESSA metadata:

   # config/packages/eikona_tessa_connector.yaml
   eikona_tessa_connector:
       field_mapping:
           image: "product_image"
           document: "product_document"
   

Integration Tips

• Akeneo API Token: Store in .env:

  AKENEO_API_TOKEN=your_jwt_token_here
  

• Batch Processing: Use --limit=50 to control sync batch size:

  php bin/console tessa:media:sync --batch --limit=50
  

• Logging: Enable debug mode for sync logs:

  # config/packages/monolog.yaml
  handlers:
      tessa:
          type: stream
          path: "%kernel.logs_dir%/tessa_sync.log"
          level: debug
  

Gotchas and Tips

Pitfalls

1. API Header Issues

   • Symptom: 401 errors or missing auth headers.
   • Fix: Ensure Akeneo’s authentication_header is not stripped by Apache. Add to .htaccess:

     RequestHeader set X-AUTH-TOKEN "Bearer %env(AKENEO_API_TOKEN)%"
     

2. Media File Paths

   • Symptom: FileNotFoundException during sync.
   • Fix: Verify paths are absolute and accessible:

     $filePath = $this->getParameter('kernel.project_dir') . '/public/media/' . $media->getPath();
     

3. Duplicate Media

   • Symptom: TESSA rejects files with duplicate filenames.
   • Fix: Append UUIDs to filenames:

     $uniqueFilename = uniqid() . '_' . $media->getOriginalFilename();
     

Debugging

• Enable Verbose Output:

  php bin/console tessa:media:sync --verbose
  

• Check TESSA API Response: Use Guzzle middleware to log raw responses:

  // config/packages/eikona_tessa_connector.yaml
  eikona_tessa_connector:
      debug: true
  

Extension Points

1. Custom Sync Logic Override the sync service:

   // src/Service/CustomTessaSyncService.php
   namespace App\Service;
   
   use Eikona\TessaConnectorBundle\Service\TessaSyncService as BaseSyncService;
   
   class CustomTessaSyncService extends BaseSyncService
   {
       protected function processMedia($media)
       {
           // Custom logic (e.g., resize images before upload)
           return parent::processMedia($media);
       }
   }
   

   Register as a service:

   services:
       App\Service\CustomTessaSyncService:
           decorates: 'eikona_tessa_connector.sync_service'
   

2. Webhook Integration Expose an endpoint to receive TESSA webhooks for real-time updates:

   // src/Controller/TessaWebhookController.php
   namespace App\Controller;
   
   use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
   use Symfony\Component\HttpFoundation\Request;
   use Eikona\TessaConnectorBundle\Service\TessaWebhookHandler;
   
   class TessaWebhookController extends AbstractController
   {
       public function handle(Request $request, TessaWebhookHandler $handler)
       {
           $handler->process($request->getContent());
           return new Response('OK');
       }
   }
   

   Add to routing.yml:

   tessa_webhook:
       path: /tessa/webhook
       methods: [POST]
       controller: App\Controller\TessaWebhookController::handle
   

3. Configuration Validation Validate TESSA API credentials on bundle load:

   // src/DependencyInjection/Compiler/TessaConfigPass.php
   namespace App\DependencyInjection\Compiler;
   
   use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
   use Symfony\Component\DependencyInjection\ContainerBuilder;
   use Eikona\TessaConnectorBundle\Validator\TessaApiValidator;
   
   class TessaConfigPass implements CompilerPassInterface
   {
       public function process(ContainerBuilder $container)
       {
           $validator = $container->get('eikona_tessa_connector.validator');
           if (!$validator->validateConfig($container->getParameter('eikona_tessa_connector'))) {
               throw new \RuntimeException('Invalid TESSA configuration');
           }
       }
   }