doc: add a new guide for the hooks (#173)

Signed-off-by: Nicolas Crocfer <nicolas.crocfer@ovhcloud.com>
ovh · Dec 8, 2022 · 8f17b18 · 8f17b18
1 parent bccd812
commit 8f17b18
Show file tree

Hide file tree

Showing 3 changed files with 34 additions and 0 deletions.
diff --git a/docs/docs/guides/trigger-hooks.md b/docs/docs/guides/trigger-hooks.md
@@ -0,0 +1,33 @@
+# Trigger Hooks
+
+Director allows you to define a success and an error tasks in your workflows definitions. These tasks are called **hooks**, and they will be executed at the end of your workflows depending on their result.
+
+You can define them in the `workflows.yml` file using the `hooks` key:
+
+```yaml
+example.ETL:
+  tasks:
+    - EXTRACT
+    - TRANSFORM
+    - LOAD
+  hooks:
+    failure: ERROR_HANDLER
+    success: SUCCESS_HANDLER
+```
+
+These hooks are normal Celery tasks:
+
+```python
+@task(name="ERROR_HANDLER")
+def error_handler(*args, **kwargs):
+    print("I'm executed because the workflow failed")
+
+
+@task(name="SUCCESS_HANDLER")
+def success_handler(*args, **kwargs):
+    print("I'm executed because the workflow succeeded")
+```
+
+Depending on the result of your workflows the corresponding hook will be called:
+
+![Hooks](../img/hooks.png)
diff --git a/docs/docs/img/hooks.png b/docs/docs/img/hooks.png
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
@@ -23,6 +23,7 @@ nav:
     - 'Error Tracking': 'guides/error-tracking.md'
     - 'Custom Configuration': 'guides/custom-configuration.md'
     - 'Use Flower': 'guides/use-flower.md'
+    - 'Trigger Hooks': 'guides/trigger-hooks.md'
   - API: 'api.md'
 
 extra_css: