Akeneo Rules Ui Laravel Package

Getting Started

Minimal Steps

1. Verify Compatibility Ensure your Akeneo PIM Enterprise Edition is 4.0.x (exact version may vary; check the package's releases). Run:

   composer require basecom/akeneo-rules-ui
   

2. Enable the Bundle Add to config/bundles.php:

   Basecom\Bundle\RulesEngineBundle\BasecomRulesEngine::class => ['all' => true],
   

3. Register Routes Include in config/routes/routes.yml:

   basecom_rules_routing:
       resource: "@BasecomRulesEngine/Resources/config/routing/rules.yml"
   

4. Clear Cache & Rebuild Assets Execute in order:

   bin/console cache:clear --no-warmup --env=prod
   bin/console pim:install:assets --env=prod
   yarn run less && yarn run webpack
   

5. First Use Case Navigate to the Rules section in Akeneo’s UI. You’ll now see an edit button in the rule overview (previously missing in the base Akeneo UI).

Implementation Patterns

Workflows

1. Rule Creation/Editing

   • The bundle extends Akeneo’s default rule editor with a graphical interface (no XML/JSON manual editing).
   • Supported Operators: Pre-filtered to exclude BETWEEN/NOT BETWEEN (see Akeneo’s docs).
   • Example Workflow:
     1. Go to Rules > Create Rule.
     2. Select a condition group (e.g., "Product" or "Family").
     3. Use the UI to drag-and-drop conditions (e.g., EQUAL, CONTAINS, IN CHILDREN).
     4. Save and test via Akeneo’s rule validation.

2. Rule Assignment

   • Assign rules to enrichment templates or product templates as usual.
   • The UI ensures rules are valid before assignment (reduces runtime errors).

3. Bulk Rule Management

   • Use the edit button in the rule list to modify multiple rules in bulk (if configured for batch operations).

Integration Tips

• Custom Conditions: Extend the bundle by overriding OverwriteRuleController.php to add new operators. Example:

  // app/Resources/config/basecom_rules_operators.yml
  custom_operators:
      - { name: "CUSTOM_OP", type: "string", description: "Custom logic" }
  

  Then clear cache and rebuild assets.

• Localization: Translate UI labels by extending the bundle’s translation files in translations/ (e.g., en.yaml).

• API Integration: Use Akeneo’s REST API to fetch/sync rules programmatically:

  curl -X GET {akeneo_url}/api/rest/v1/rules -H "Authorization: Bearer {token}"
  

• Testing: Test rules in sandbox mode (Akeneo’s pim-enrich context) before deploying to production.

Gotchas and Tips

Pitfalls

1. Operator Limitations

   • BETWEEN/NOT BETWEEN are hardcoded disabled. Workaround: Use IN with a predefined range or extend the bundle (see Akeneo’s docs).

2. Cache Dependencies

   • Forgetting yarn run webpack after cache clear will break the UI. Add to your deployment script:

     yarn install && yarn run less && yarn run webpack
     

3. Akeneo Version Lock

   • The package is archived and only supports Akeneo 4.0.x. Upgrading Akeneo may break compatibility. Test in a staging environment first.

4. Asset Conflicts

   • If the UI appears broken, check for JavaScript errors in the browser console. Common causes:
     • Missing webpack assets.
     • Conflicts with other Akeneo bundles (e.g., custom JavaScript overriding rule UI).

5. Permission Issues

   • Ensure users have ROLE_RULE_EDITOR or equivalent permissions in Akeneo’s security configuration.

Debugging

• Enable Debug Mode: Set APP_DEBUG=1 in .env to see detailed errors. Check:

  bin/console debug:config basecom_rules_engine
  

• Log Rule Validation: Enable Akeneo’s rule validation logs:

  bin/console debug:config pim_rule --show-private
  

• Database Schema: Verify the pim_rule and pim_rule_condition tables exist and match Akeneo’s schema. Run:

  bin/console doctrine:schema:validate
  

Extension Points

1. Custom Rule Templates Override the Twig templates in BasecomRulesEngine/Resources/views/ to modify the UI layout. Example:

   {# app/Resources/BasecomRulesEngine/views/Rule/index.html.twig #}
   {% extends 'BasecomRulesEngine:Rule:index.html.twig' %}
   {% block rule_actions %}
       {{ parent() }}
       <a href="{{ path('custom_rule_route') }}">Custom Action</a>
   {% endblock %}
   

2. Event Listeners Subscribe to Akeneo’s rule events to extend functionality:

   // src/EventListener/RulesListener.php
   namespace App\EventListener;
   
   use Basecom\Bundle\RulesEngineBundle\Event\RuleEvent;
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class RulesListener implements EventSubscriberInterface
   {
       public static function getSubscribedEvents()
       {
           return [
               RuleEvent::PRE_SAVE => 'onPreSave',
           ];
       }
   
       public function onPreSave(RuleEvent $event)
       {
           // Modify rule data before save
       }
   }
   

3. API Extensions Extend the rule API by creating a custom controller:

   // src/Controller/CustomRuleController.php
   use Basecom\Bundle\RulesEngineBundle\Controller\RuleController;
   
   class CustomRuleController extends RuleController
   {
       public function customAction()
       {
           // Add logic here
       }
   }
   

   Register the route in config/routes.yml.

Configuration Quirks

• Routing Conflicts: If basecom_rules_routing conflicts with existing routes, rename the YAML file or adjust priorities in config/routes.yml.

• Asset Pipeline: The bundle uses Webpack Encore. Ensure your webpack.config.js includes:

  Encore
      .enableSingleRuntimeChunk()
      .cleanupOutputBeforeBuild()
      .setOutputPath('public/build/')
      .setManifestKeyPrefix('build/');
  

• Translation Overrides: To override translations, create a file at translations/messages.en.yaml:

  basecom_rules:
      rule:
          edit: "Custom Edit Label"