Akeneo6 0 Tessa Connector Laravel Package

Getting Started

Minimal Steps

1. Verify Akeneo API Readiness

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

2. Install the Bundle

   composer require eikona-media/akeneo6-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:
             endpoint: 'https://your-tessa-instance.com/api'
             username: 'your_username'
             password: 'your_password'
         akeneo:
             api_token: 'your_akeneo_api_token'
     

5. First Use Case: Sync a Product Image

   • Upload an image to Tessa via its UI.
   • Link it to an Akeneo product using the Tessa Media tab in the Akeneo product editor (if UI integration is available).
   • Verify the asset appears in Akeneo’s product grid under the tessa_media attribute.

Implementation Patterns

Workflows

1. Asset Management Workflow

   • Upload to Tessa: Use Tessa’s UI/API to ingest assets (images, videos, docs).
   • Link to Akeneo: Manually or via API associate assets to Akeneo products using the tessa_media attribute.
   • Sync Metadata: Push Akeneo product metadata (e.g., family, categories) to Tessa for asset organization.

     // Example: Sync product metadata to Tessa (via custom command/service)
     $product = $this->akeneoProductRepository->find($productId);
     $this->tessaSyncService->syncProductMetadata($product);
     

2. Automated Asset Processing

   • Webhook Integration: Configure Tessa to trigger Akeneo updates on asset events (e.g., upload, delete).

     # config/packages/eikona_tessa_connector.yaml
     eikona_tessa_connector:
         webhooks:
             enabled: true
             secret: 'your_webhook_secret'
     

   • Queue-Based Processing: Offload heavy syncs to Laravel queues:

     // Dispatch a sync job
     SyncTessaAssetsJob::dispatch($productId);
     

3. Attribute Mapping

   • Define custom attribute mappings in config/packages/eikona_tessa_connector.yaml:

     eikona_tessa_connector:
         attribute_mapping:
             tessa_media: 'tessa_asset_id'
             product_name: 'akeneo_product_name'
     

Integration Tips

• Akeneo API Client: Use the bundle’s built-in AkeneoApiClient for programmatic access:

  $client = $this->container->get('eikona_tessa_connector.akeneo_api');
  $products = $client->getProducts(['limit' => 10]);
  

• Event Listeners: Extend functionality by subscribing to Akeneo events:

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

  Register in services.yaml:

  services:
      App\EventListener\TessaSyncListener:
          tags:
              - { name: kernel.event_listener, event: product.update, method: onProductUpdate }
  

• Custom Fields: Add Tessa-specific fields to Akeneo product forms via Twig:

  {% extends 'AkeneoPimEnrichBundle:Product:form.html.twig' %}
  {% block product_tabs %}
      {{ parent() }}
      {% include 'EikonaTessaConnectorBundle:Product:tessa_media_tab.html.twig' %}
  {% endblock %}
  

Gotchas and Tips

Pitfalls

1. API Authentication Issues

   • Symptom: 401 errors when syncing.
   • Fix: Verify akeneo.api_token in config and ensure the token has ROLE_API_USER.
   • Debug: Test the token manually:

     curl -X GET "http://akeneo/api/rest/v1/health-check" -H "Authorization: Bearer YOUR_TOKEN"
     

2. Missing Routes

   • Symptom: 404 on /tessa-media/* endpoints.
   • Fix: Ensure routes are loaded after Akeneo’s routes (order matters in routes.yml).

3. Attribute Not Found

   • Symptom: tessa_media attribute missing in Akeneo.
   • Fix: Install the bundle’s migration:

     php bin/console doctrine:migrations:execute --up
     

   • Manual Fix: Create the attribute via Akeneo UI (type: pim_catalog_identifier, code: tessa_media).

4. Webhook Failures

   • Symptom: Tessa webhooks return 500 errors.
   • Fix: Validate the X-Tessa-Signature header in your webhook endpoint:

     // src/Controller/TessaWebhookController.php
     public function handleWebhook(Request $request) {
         $signature = $request->headers->get('X-Tessa-Signature');
         if (!hash_equals($signature, hash_hmac('sha256', $request->getContent(), config('eikona_tessa_connector.webhooks.secret')))) {
             throw new \RuntimeException('Invalid signature');
         }
         // Process payload
     }
     

Debugging

• Enable API Logging Add to config/packages/eikona_tessa_connector.yaml:

  eikona_tessa_connector:
      debug: true
  

  Logs appear in var/log/dev.log.

• Test Connections Manually Use the tessa:test-connection command:

  php bin/console tessa:test-connection
  

Extension Points

1. Custom Sync Logic Extend the TessaSyncService:

   // src/Service/CustomTessaSyncService.php
   class CustomTessaSyncService extends TessaSyncService {
       protected function getAssetMetadata(ProductInterface $product) {
           // Custom logic here
           return parent::getAssetMetadata($product);
       }
   }
   

   Override in services.yaml:

   services:
       App\Service\CustomTessaSyncService:
           decorates: 'eikona_tessa_connector.tessa_sync_service'
           arguments:
               $inner: '@.inner'
   

2. Add New Asset Types Register custom asset handlers:

   // src/EventSubscriber/TessaAssetSubscriber.php
   public static function getSubscribedEvents() {
       return [
           TessaEvents::ASSET_UPLOADED => 'onAssetUploaded',
       ];
   }
   
   public function onAssetUploaded(AssetEvent $event) {
       if ($event->getAsset()->getType() === 'video') {
           $this->processVideoAsset($event->getAsset());
       }
   }
   

3. Override Templates Copy default templates from the bundle to your theme:

   mkdir -p templates/EikonaTessaConnectorBundle/Product
   cp vendor/eikona-media/akeneo6-0-tessa-connector/src/Resources/views/Product/tessa_media_tab.html.twig templates/EikonaTessaConnectorBundle/Product/
   

   Customize as needed.

Configuration Quirks

• Caching: Clear Akeneo and Laravel caches after config changes:

  php bin/console cache:clear
  php bin/console akeneo:cache:clear
  

• Environment Variables: Prefer .env for sensitive data:

  TESSA_API_USERNAME=your_username
  TESSA_API_PASSWORD=your_password
  

  Reference in config:

  eikona_tessa_connector:
      api:
          username: '%env(TESSA_API_USERNAME)%'
  

• Rate Limiting: Tessa may throttle requests. Implement exponential backoff in custom services:

  use Symfony\Component\HttpClient\RetryableHttpException;
  use Symfony\Contracts\HttpClient\Exception\ClientExceptionInterface;
  
  try {
      $response = $this->httpClient->request('GET', $url);
  } catch (RetryableHttpException $e) {
      sleep(2 ** $attempt); // Exponential backoff
      throw $e;
  }