From a4810c198ce1f907808536f697b37653e11a16a1 Mon Sep 17 00:00:00 2001
From: "Nico Pfiffner (nipfif)" <n.pfiffner@ikmz.uzh.ch>
Date: Thu, 18 Jul 2024 09:42:59 +0200
Subject: [PATCH] docs(admin): Add description of extraction operators.

---
 docs/modules/ROOT/pages/for_researchers.adoc | 69 ++++++++++++++++++--
 1 file changed, 65 insertions(+), 4 deletions(-)

diff --git a/docs/modules/ROOT/pages/for_researchers.adoc b/docs/modules/ROOT/pages/for_researchers.adoc
index d643ad6..4440ca6 100644
--- a/docs/modules/ROOT/pages/for_researchers.adoc
+++ b/docs/modules/ROOT/pages/for_researchers.adoc
@@ -319,10 +319,71 @@ regular expression (regex). If the latter is the case, you must also select `reg
 
 Regex field:: Select if you use a regex expression in the `Field` setting of this rule.
 
-Extraction Operator:: Defines the main logic of the extraction step. If empty, this indicates
-that you want to keep the field in the donated data. For all non-regex operations,
-if an operations evaluates to True, the row will be deleted from the donated data
-(further explanations on the separate rules will follow).
+Extraction Operator:: Defines the main logic of the extraction step.
+
+====
+*Overview of available extraction operators*
+
+[%header,cols=3*]
+|===
+|Extraction Operator
+|Description
+|Note
+
+|Keep Field
+|Keep this field in the uploaded data.
+|–
+
+|Equal (==)
+|Delete row/entry if the value contained in the given `field` equals the `comparison value`.
+|Works for strings, integers, and dates^1^.
+
+|Not Equal (!=)
+|Delete row/entry if the value contained in the given `field` does not equal the `comparison value`.
+|Works for strings, integers, and dates^1^.
+
+|Greater than (>)
+|Delete row/entry if the value contained in the given `field` is greater than the `comparison value`.
+|Works for integers and dates^1^. String values are skipped and the row will be kept in the data.
+
+|Smaller than (<)
+|Delete row/entry if the value contained in the given `field` is smaller than the `comparison value`.
+|Works for integers and dates^1^. String values are skipped and the row will be kept in the data.
+
+|Greater than or equal (>=)
+|Delete row/entry if the value contained in the given `field` is greater than or equal to the `comparison value`.
+|Works for integers and dates^1^. String values are skipped and the row will be kept in the data.
+
+|Smaller than or equal (<=)
+|Delete row/entry if the value contained in the given `field` is smaller than or equal to the `comparison value`.
+|Works for integers and dates^1^. String values are skipped and the row will be kept in the data.
+
+|Delete match (regex)
+|Delete parts of the value contained in the given `field` that match the given `regular expression (regex)`
+      (e.g., if the `regular expression (regex)` = "^Watched " and a field contains the value "Watched video XY" the following
+      value will be kept in the uploaded data: "video XY").
+|All field values are converted to strings before this operation is applied.
+
+|Replace match (regex)
+|Replace parts of the value contained in the given `field` that match the given `regular expression (regex)`
+      (e.g., if the `regular expression (regex)` = "[\w-\.]+@([\w-]+\.)+[\w-]{2,4}" and
+      the `replacement value` = "_anonymized_" and a field contains the value "some text email@address.com" the following
+      value will be kept in the uploaded data: "some text _anonymized_").
+|All field values are converted to strings before this operation is applied.
+
+|Delete row when match (regex)
+|Delete row/entry if the value contained in the given `field` matches the given `regular expression (regex)` (e.g., if
+      `regular expression (regex)` = "^Watched " and a field contains the value "Watched video XY"
+      the row/entry will be deleted from the uploaded data).
+|All field values are converted to strings before this operation is applied.
+
+|===
+
+[small]#^1^Dates are inferred from string values if they are formatted according to ISO, RFC2822, or HTTP standards,
+and only if both the field value and the comparison value follow the same format.
+Otherwise, the entry will be treated as a regular string.#
+
+====
 
 Comparison Value:: The value against which the data contained in the indicated field will be compared according to the selected comparison logic.