Oro Api Connector Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require agencednd/oro-api-connector-bundle
   

   Ensure your project uses OroCommerce Community Edition v1.x.

2. Enable Bundle: The bundle auto-enables after installation.

3. Regenerate API Docs: Clear the API documentation cache to expose new endpoints:

   php app/console oro:api:doc:cache:clear -e prod
   

4. Expose WSSE Script: Copy the authentication script to your web directory:

   cp -R vendor/agencednd/oro-api-connector-bundle/Resources/public/scripts/ web/scripts
   

   Update web/scripts/generate-wsse-header.php with your OroCommerce API key (found in oroUrl/admin/user/profile/view).

First Use Case: Alexa Integration

This bundle bridges OroCommerce’s REST API with Amazon Alexa via AWS Lambda. Follow these steps to enable voice commands for e-commerce actions:

1. Protect the WSSE Script:

   • Generate a .htpasswd entry (e.g., user:passwd) using htpasswd tools.
   • Update web/scripts/.htaccess to point to the .htpasswd file:

     AuthUserFile /srv/www/orocommerce/web/scripts/.htpasswd
     

2. Deploy AWS Lambda:

   • Use the provided index.js and intents.json (from vendor/agencednd/oro-api-connector-bundle/Resources/public/alexa/).
   • Replace oroHost (Line 23) with your OroCommerce domain.
   • Update auth credentials (Line 28) with the .htpasswd user:pass.

3. Test Alexa Skill: Configure your Alexa skill to trigger the Lambda function. Example intent:

   "Alexa, ask [YourSkill] to check my cart total."

Implementation Patterns

Workflows

1. API Extension for Alexa

• Endpoint Exposure: The bundle adds custom API routes (e.g., /api/alexa/orders) to fetch data for Alexa responses.
• WSSE Authentication: All requests from Alexa must include a WSSE header, generated via generate-wsse-header.php.

  // Example AWS Lambda call to OroCommerce API
  const wsseHeader = await getWsseHeader(); // Calls generate-wsse-header.php
  const response = await fetch(`${oroHost}/api/rest/v1/orders`, {
    headers: { 'Authorization': wsseHeader }
  });
  

2. Data Transformation

• Intent Handling: Map Alexa intents (e.g., GetCartTotalIntent) to OroCommerce API endpoints.

  // Example intents.json snippet
  {
    "intents": [
      {
        "intent": "GetCartTotalIntent",
        "slots": [],
        "apiEndpoint": "/api/rest/v1/orders/summary"
      }
    ]
  }
  

• Response Formatting: Convert OroCommerce JSON responses into Alexa-compatible SSML for voice output.

  // index.js snippet
  const cartTotal = response.data.total;
  const speechOutput = `<speak>Your cart total is ${cartTotal} ${currency}.</speak>`;
  

3. Event-Driven Actions

• Webhooks (Roadmap): Future versions may support OroCommerce order events (e.g., order.placed) to trigger Alexa notifications.
• Current Workaround: Poll OroCommerce API periodically (e.g., via Lambda’s scheduled events) for new orders.

Integration Tips

OroCommerce-Specific

• API Key Management: Regenerate API keys in oroUrl/admin/user/profile/view if the script fails. Avoid hardcoding keys in Lambda.
• CORS Configuration: Ensure OroCommerce’s config.yml allows requests from your Alexa domain:

  oro_api:
      api:
          enabled: true
          cors_origins:
              - 'https://your-alexa-skill-domain.com'
  

AWS Lambda

• Environment Variables: Store oroHost and .htpasswd credentials as Lambda environment variables (not in code).

  const oroHost = process.env.ORO_HOST;
  const auth = process.env.ALEXA_AUTH;
  

• Error Handling: Log Lambda errors to CloudWatch for debugging:

  console.error('OroCommerce API Error:', error);
  

Development

• Local Testing: Use ngrok to expose generate-wsse-header.php locally for testing:

  ngrok http 80 --host-header=localhost
  

  Update Lambda’s oroHost to your ngrok URL (e.g., https://abc123.ngrok.io).

Gotchas and Tips

Pitfalls

1. WSSE Deprecation:

   • OroCommerce plans to replace WSSE with OAuth2. Monitor OroCommerce updates for migration guidance.
   • Workaround: Cache WSSE tokens in Lambda to reduce script calls (but avoid long-term storage due to security risks).

2. Script Path Hardcoding:

   • The generate-wsse-header.php script assumes it’s in web/scripts/. If moved, update .htaccess and Lambda calls accordingly.

3. API Rate Limiting:

   • Alexa skills may trigger rapid API calls. Implement exponential backoff in Lambda:

     const retry = require('async-retry');
     await retry(async () => {
       const response = await fetch(oroHost, { headers: { Authorization: wsseHeader } });
       if (response.status === 429) throw new Error('Rate limited');
       return response.json();
     }, { retries: 3 });
     

4. HTTPS Requirements:

   • OroCommerce’s API must use HTTPS. If testing locally, use a tool like mkcert to generate trusted certificates.

Debugging

1. WSSE Header Issues:

   • Verify the script returns a valid header:

     curl -X GET http://your-orocommerce/web/scripts/generate-wsse-header.php
     

   • Expected output:

     WSSE realm="OroCommerce", profile="UsernameToken", type="AppSpecific", created="1234567890", nonce="abc123", username="api_user", passwordDigest="hashed_password"
     

2. Lambda Logs:

   • Check CloudWatch for errors like:
     • 401 Unauthorized: Invalid WSSE header or API key.
     • 404 Not Found: Incorrect API endpoint or missing route.

3. OroCommerce Logs:

   • Enable debug mode in app/config/config.yml:

     oro_api:
         api:
             enabled: true
             debug: true
     

   • Check var/log/dev.log for API request details.

Extension Points

1. Custom API Endpoints:

   • Extend the bundle by creating new controllers in AgenceDnD\OroApiConnectorBundle\Controller.
   • Example: Add a /api/alexa/products endpoint to fetch product recommendations.

2. Intent Expansion:

   • Add new intents to intents.json and update index.js to handle them:

     {
       "intent": "AddToCartIntent",
       "slots": [
         { "name": "productId", "type": "AMAZON_NUMBER" }
       ],
       "apiEndpoint": "/api/rest/v1/cart/items"
     }
     

3. OAuth2 Migration:

   • Once OroCommerce supports OAuth2, replace WSSE calls with:

     const token = await getOAuthToken(); // New endpoint
     const response = await fetch(oroHost, { headers: { Authorization: `Bearer ${token}` } });
     

4. Multi-Currency Support:

   • Extend the GetCartTotalIntent to convert amounts to a default currency:

     const currency = response.data.currency;
     const convertedTotal = (cartTotal * exchangeRate).toFixed(2); // Requires exchangeRate API