Akeneo4 0 Tessa Connector Laravel Package

Getting Started

Minimal Steps

1. Verify Akeneo API Readiness

   • Confirm Akeneo API is functional (test via GET /api/rest/v1/products).
   • Resolve Apache misconfigurations if headers are stripped (see Akeneo API Troubleshooting).

2. Install the Connector

   composer require eikona-media/akeneo4-0-tessa-connector
   

3. Register Routes Append to config/routes/routes.yml:

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

4. Configure TESSA Connection

   • Set TESSA API credentials in config/packages/eikona_tessa_connector.yaml:

     eikona_tessa_connector:
         api_url: 'https://your-tessa-instance.com/api'
         api_key: '%env(TESSA_API_KEY)%'
         api_secret: '%env(TESSA_API_SECRET)%'
     

5. First Use Case: Sync Product Media

   • Trigger a manual sync via CLI:

     php bin/console eikona:tessa:sync --entity=product --media-field=image
     

   • Verify assets appear in TESSA under the linked Akeneo product.

Implementation Patterns

Core Workflows

1. Media Synchronization

   • Automated Sync: Use cron to sync media fields (e.g., image, video) daily:

     # config/cron.yml
     sync_tessa_media:
         command: eikona:tessa:sync
         args: ['--entity=product', '--media-field=image']
         schedule: '0 3 * * *'
     

   • Selective Sync: Filter by product category or family:

     php bin/console eikona:tessa:sync --entity=product --family=electronics --media-field=image
     

2. Asset Linking

   • Product Media: Map Akeneo product fields (e.g., image, video) to TESSA asset IDs via the tessa_asset_id attribute.
   • Custom Fields: Extend the connector to link non-media fields (e.g., brochure) by overriding the MediaFieldMapper service.

3. Event-Driven Sync

   • Subscribe to Akeneo events (e.g., product.save) to trigger real-time syncs:

     // src/EventListener/TessaSyncListener.php
     public function onProductSave(ProductUpdateEvent $event)
     {
         $this->tessaSyncService->syncProductMedia($event->getProduct());
     }
     

     Register in services.yaml:

     App\EventListener\TessaSyncListener:
         tags:
             - { name: kernel.event_listener, event: product.save, method: onProductSave }
     

4. Bulk Operations

   • Use the bulk-sync command for large datasets:

     php bin/console eikona:tessa:bulk-sync --entity=product --batch-size=100
     

Integration Tips

• Akeneo UI Integration: Add a custom tab in Akeneo’s product form to display TESSA-linked assets:

  <!-- templates/product/_partials/tessa_assets.html.twig -->
  {% if product.tessaAssetId %}
      <div class="tessa-assets">
          <a href="{{ tessaAssetUrl(product.tessaAssetId) }}" target="_blank">
              View in TESSA
          </a>
      </div>
  {% endif %}
  

• Validation: Validate TESSA API responses in a custom validator:

  use Eikona\TessaConnectorBundle\Validator\Constraints as TessaAssert;
  
  /**
   * @TessaAssert\ValidTessaAsset()
   */
  private $tessaAssetId;
  

Gotchas and Tips

Pitfalls

1. API Rate Limits

   • TESSA may throttle requests. Implement exponential backoff in custom sync logic:

     try {
         $response = $this->tessaClient->upload($asset);
     } catch (RateLimitException $e) {
         sleep($e->getRetryAfter());
         retry();
     }
     

2. Field Mapping Mismatches

   • Ensure Akeneo’s media_field names match TESSA’s expected fields (e.g., image vs. product_image). Override the MediaFieldMapper to customize:

     # config/packages/eikona_tessa_connector.yaml
     eikona_tessa_connector:
         field_mapping:
             image: 'product_image'
             video: 'product_video'
     

3. Authentication Issues

   • Verify TESSA_API_KEY and TESSA_API_SECRET are correctly set in .env:

     TESSA_API_KEY=your_api_key_here
     TESSA_API_SECRET=your_api_secret_here
     

   • Debug with:

     php bin/console debug:container eikona_tessa_connector.client
     

4. Data Duplication

   • Use TESSA’s asset_id to avoid re-uploading identical assets. Extend the AssetUploader service:

     public function upload(Asset $asset)
     {
         if ($asset->getTessaAssetId()) {
             return $this->updateAsset($asset);
         }
         return $this->createAsset($asset);
     }
     

Debugging

• Enable Verbose Logging:

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

  Log TESSA API calls in a custom client:

  $this->logger->debug('TESSA API Request', [
      'url' => $url,
      'data' => $data,
      'response' => $response->getBody()->getContents(),
  ]);
  

• Test Locally: Use a TESSA sandbox environment (e.g., https://sandbox.tessa-dam.com) during development.

Extension Points

1. Custom Asset Types Extend the AssetType class to support non-standard media (e.g., 3D models):

   class CustomAssetType extends AssetType
   {
       public function getMimeTypes(): array
       {
           return ['model/vnd.collada+xml'];
       }
   }
   

   Register in services.yaml:

   App\CustomAssetType:
       tags:
           - { name: eikona_tessa_connector.asset_type }
   

2. Webhooks Implement TESSA webhook handlers to sync changes back to Akeneo:

   // src/EventListener/TessaWebhookListener.php
   public function onTessaWebhook(Request $request)
   {
       $data = json_decode($request->getContent(), true);
       $this->akeneoRepository->updateFromTessa($data['asset_id'], $data['changes']);
   }
   

   Route in routing.yml:

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

3. Performance Optimization

   • Batch API calls using TESSA’s bulk endpoints:

     $this->tessaClient->bulkUpload($assets, 50); // Batch size of 50
     

   • Cache TESSA API responses with Symfony’s cache system:

     $cache = $this->cachePool->getItem('tessa_assets_' . $productId);
     if (!$cache->isHit()) {
         $assets = $this->tessaClient->getAssetsForProduct($productId);
         $cache->set($assets);
     }