diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock index b66a578b..40418260 100644 --- a/docs/Gemfile.lock +++ b/docs/Gemfile.lock @@ -67,6 +67,8 @@ GEM sass-embedded (1.58.3) google-protobuf (~> 3.21) rake (>= 10.0.0) + sass-embedded (1.58.3-x86_64-darwin) + google-protobuf (~> 3.21) terminal-table (3.0.2) unicode-display_width (>= 1.1.1, < 3) unicode-display_width (2.4.2) @@ -74,6 +76,7 @@ GEM PLATFORMS x86_64-darwin-22 + x86_64-darwin-23 x86_64-linux DEPENDENCIES @@ -81,4 +84,4 @@ DEPENDENCIES just-the-docs BUNDLED WITH - 2.4.19 + 2.4.22 diff --git a/docs/architecture_and_customization.md b/docs/architecture_and_customization.md index 5766f3e4..899e7593 100644 --- a/docs/architecture_and_customization.md +++ b/docs/architecture_and_customization.md @@ -1,7 +1,7 @@ --- title: Architecture & customization layout: page -nav_order: 5 +nav_order: 6 --- # Architecture & customization @@ -9,12 +9,13 @@ nav_order: 5 > This plugin makes use of [Symfony Messenger](https://symfony.com/doc/current/messenger.html) component. It is highly > recommended to have a minimum knowledge of these component to understand how this integration works. -This plugin has basically two entry points: +This plugin has basically three entry points: * The UI admin import button, this will import only products * The Import CLI command, this will import both product, product associations and attribute options +* The Webhook controller, this will import product and product associations when created/updated on Akeneo -Both this entry points deals to identify entities to import from Akeneo. When they have collected them they dispatch +These entry points deals to identify entities to import from Akeneo. When they have collected them they dispatch an `Webgriffe\SyliusAkeneoPlugin\Message\ItemImport` message on the messenger default bus. By default, in the configuration this message is handled by the main bus, the same bus used as default by Sylius for catalog promotions. This means that, if you have configured the main bus to run synchronously the import will be diff --git a/docs/contributing.md b/docs/contributing.md index a3b15104..12d49e10 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,7 +1,7 @@ --- title: Contributing layout: page -nav_order: 6 +nav_order: 7 --- # Contributing @@ -175,6 +175,7 @@ WEBGRIFFE_SYLIUS_AKENEO_PLUGIN_CLIENT_ID=SAMPLE WEBGRIFFE_SYLIUS_AKENEO_PLUGIN_SECRET=SAMPLE WEBGRIFFE_SYLIUS_AKENEO_PLUGIN_USERNAME=SAMPLE WEBGRIFFE_SYLIUS_AKENEO_PLUGIN_PASSWORD=SAMPLE +WEBGRIFFE_SYLIUS_AKENEO_PLUGIN_WEBHOOK_SECRET=WEBHOOK_SECRET ``` Now, if you want you can import products from Akeneo to Sylius by launching the command: diff --git a/docs/images/akeneo-event-subscrition.png b/docs/images/akeneo-event-subscrition.png new file mode 100644 index 00000000..e28ca5da Binary files /dev/null and b/docs/images/akeneo-event-subscrition.png differ diff --git a/docs/index.md b/docs/index.md index 822b81a9..9c4c5dbe 100644 --- a/docs/index.md +++ b/docs/index.md @@ -31,6 +31,7 @@ new features that this plugin could add. So, let's start! 🚀 - [Installation](installation.html) - [Configuration](configuration.html) - [Usage](usage.html) +- [Webhook](webhook.html) - [Architecture & customization](architecture_and_customization.html) - [Contributing](contributing.html) - [Upgrade guide](upgrade.html) diff --git a/docs/upgrade/index.md b/docs/upgrade/index.md index 18859e45..5c105218 100644 --- a/docs/upgrade/index.md +++ b/docs/upgrade/index.md @@ -1,7 +1,7 @@ --- title: Upgrade layout: page -nav_order: 7 +nav_order: 8 has_children: true --- diff --git a/docs/upgrade/upgrade-2.0.md b/docs/upgrade/upgrade-2.*.md similarity index 98% rename from docs/upgrade/upgrade-2.0.md rename to docs/upgrade/upgrade-2.*.md index a64371f9..da0d8fbe 100644 --- a/docs/upgrade/upgrade-2.0.md +++ b/docs/upgrade/upgrade-2.*.md @@ -1,10 +1,15 @@ --- -title: Upgrade to 2.0 +title: Upgrade to 2.* layout: page nav_order: 0 parent: Upgrade --- +# Upgrade from `v2.2.0` to `v2.3.0` + +The v2.3.0 version introduces the support for webhooks. To enable check the new documentation [here](../webhook.html). +It is highly recommended to remove the import command that runs every minute from your crontab and use the webhook instead. + # Upgrade from `v1.17.0` to `v2.0.0` In the 2.0 version, we have introduced the Symfony Messenger component and removed all deprecations. diff --git a/docs/usage.md b/docs/usage.md index 44b36449..90674785 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -471,6 +471,9 @@ This will: * Import, every minute, all products that have been modified since the last execution, along with their associations * Reconcile Akeneo deleted products every 6 hours +> *NB*: The line that imports products and product associations every minute should be added only if you do not use the +> webhook feature (see next chapter). Otherwise, the products will be imported twice. + Import and Reconcile commands uses a [lock mechanism](https://symfony.com/doc/current/console/lockable_trait.html) which prevents running them if another instance of the same command is already running. {% endraw %} diff --git a/docs/webhook.md b/docs/webhook.md new file mode 100644 index 00000000..0105570d --- /dev/null +++ b/docs/webhook.md @@ -0,0 +1,58 @@ +--- +title: Webhook +layout: page +nav_order: 5 +--- + +{% raw %} + +# Webhook + +This plugin provides a webhook that can be used to automatically import products from Akeneo PIM to Sylius when they are +created or updated. +To use the webhook you need to: + +1. Import the routes needed for the plugin by adding the following to your `config/routes.yaml` file: + ```yaml + webgriffe_sylius_akeneo_plugin_webhook: + resource: "@WebgriffeSyliusAkeneoPlugin/config/webhook_routing.yaml" + prefix: '' + ``` + The url of the webhook can be anything you want but it must be the same you will configure in Akeneo PIM. The + imported resource will use /akeneo/webhook, but if you prefer you can add any prefix you want or you can completely + rewrite the url: + ```yaml + webgriffe_sylius_akeneo_plugin_webhook: + path: /akeneo/complete/url/rewrite/webhook + methods: [POST] + controller: webgriffe_sylius_akeneo.controller.webhook::postAction + ``` +2. Configure the webhook in Akeneo PIM. Remember that events API are available from Akeneo 5. You can find the webhook + configuration in the Akeneo PIM's + menu: `Connect > Connection settings`. Select the current data destination connection (the one used from the plugin). + Now, select Event subscription from the left menu. + Check Event subscription activation and leave unchecked Use product UUID instead of product identifier? (this is not + currently supported). Now is time to insert the full URL previously configurated. + When you click the Save button, a new secret token will be generated. Copy it and paste it in the plugin's + configuration (see next step). + ![akeneo-event-subscrition.png](images%2Fakeneo-event-subscrition.png) +3. In the plugin configuration (probably in the file config/packages/webgriffe_sylius_akeneo_plugin.yaml) add the + following: + ```yaml + webhook: + secret: 'YOUR_TOKEN_VALUE' + ``` + Replace YOUR_TOKEN_VALUE with the secret token generated previously by Akeneo PIM. As always, we suggest to add this + token by using an env variable to keep it secret from the repository ( + see [Symfony best practices doc](https://symfony.com/doc/current/best_practices.html#configuration)). +4. If you want, you can now TEST the webhook with the dedicated button on Akeneo event subscription page. If any error + occurs, you can debug the webhook by adjusting the monolog.logger.webgriffe_sylius_akeneo_plugin monolog level to + debug, so that you will see if there is something that is currently not working. +5. Finally, it is highly suggested that you remove the Product and ProductAssociations importer from the crontab to + avoid products imported twice: + ```diff + - * * * * * /path/to/sylius/bin/console -e prod -q webgriffe:akeneo:import --since-file=/path/to/sylius/var/storage/akeneo-import-sincefile.txt --importer="Product" --importer="ProductAssociations" + ``` + +{% endraw %} +