From 9e92a0af3ac1a9f7eb4cbf9a06e60ff6d60acd96 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Cl=C3=A9ment=20OUDOT?= <clement@oodo.net>
Date: Wed, 30 Oct 2024 08:40:28 +0100
Subject: [PATCH] Doc for unlock hooks

---
 docs/hook.rst | 53 +++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 43 insertions(+), 10 deletions(-)

diff --git a/docs/hook.rst b/docs/hook.rst
index 260ff145..40b01df1 100644
--- a/docs/hook.rst
+++ b/docs/hook.rst
@@ -1,26 +1,34 @@
 Hook
 ====
 
-Hook feature allows to run a script before or after the password modification.
+Hook feature allows to run a script before or after an action:
+* Password reset
+* Password unlock
 
-The script is called with two parameters: login and new password.
+The script must return 0 if no error occured. Any text printed on STDOUT
+will be displayed as an error message (see options).
 
-Parameters
-----------
+Login
+-----
 
-Define prehook or posthook script (and enable the feature):
+Define which attribute will be used as login in prehook and posthook scripts:
 
 .. code-block:: php
 
-    $prehook = "/usr/share/service-desk/prehook.sh";
-    $posthook = "/usr/share/service-desk/posthook.sh";
+    $prehook_login = "uid";
+    $posthook_login = "uid";
 
-Define which attribute will be used as login:
+Password reset
+--------------
+
+The script is called with two parameters: login and new password.
+
+Define prehook or posthook script (and enable the feature):
 
 .. code-block:: php
 
-    $prehook_login = "uid";
-    $posthook_login = "uid";
+    $prehook = "/usr/share/service-desk/prehook.sh";
+    $posthook = "/usr/share/service-desk/posthook.sh";
 
 You can choose to display an error if the script return code is greater
 than 0:
@@ -48,3 +56,28 @@ if it fails, but still try to update password in the directory.
 .. code-block:: php
 
     $ignore_prehook_error = true;
+
+Password unlock
+---------------
+
+The script is called with one parameter: login.
+
+Define prehook or posthook script (and enable the feature):
+
+.. code-block:: php
+
+    $prehook_unlock = "/usr/share/service-desk/prehook_unlock.sh";
+    $posthook_unlock = "/usr/share/service-desk/posthook_unlock.sh";
+
+To display hook error:
+
+.. code-block:: php
+
+   $display_prehook_unlock_error = true;
+   $display_posthook_unlock_error = true;
+
+To ignore prehook error:
+
+.. code-block:: php
+
+    $ignore_prehook_unlock_error = true;