Add webhook docs (#157)

webgriffe · Dec 5, 2023 · b162f51 · b162f51
1 parent 618f793
commit b162f51
Show file tree

Hide file tree

Showing 9 changed files with 79 additions and 7 deletions.
diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock
@@ -67,18 +67,21 @@ 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)
     webrick (1.8.1)
 
 PLATFORMS
   x86_64-darwin-22
+  x86_64-darwin-23
   x86_64-linux
 
 DEPENDENCIES
   jekyll (~> 4.3.2)
   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
@@ -1,20 +1,21 @@
 ---
 title: Architecture & customization
 layout: page
-nav_order: 5
+nav_order: 6
 ---
 
 # Architecture & customization
 
 > 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
@@ -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
diff --git 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
@@ -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 → docs/upgrade/upgrade-2.*.md b/docs/upgrade/upgrade-2.0.md → 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
@@ -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
@@ -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 %}
+