Update actions.qmd

Author: rich-iannone

docs/user-guide/actions.qmd

@@ -22,7 +22,9 @@ could take the form of a console message).
 Let's look at an example on how this works in practice. The following validation plan contains a
 single step (using
 [`col_vals_gt()`](https://posit-dev.github.io/pointblank/reference/Validate.col_vals_gt.html)) where
-the `thresholds=` and `actions=` parameters are set:
+the `thresholds=` and `actions=` parameters are set using
+[`Thresholds`](https://posit-dev.github.io/pointblank/reference/Thresholds.html) and
+[`Actions`](https://posit-dev.github.io/pointblank/reference/Actions.html) calls:
 
 ```{python}
 import pointblank as pb
@@ -72,17 +74,55 @@ an action.
 
 There are a few options in how to define the actions:
 
-1. **String**: A message to be displayed in the console.
-2. **Callable**: A function to be called (which could do virtually anything).
-3. **List of Strings/Callables**: For execution of multiple messages or functions.
+1. **String**: a message to be displayed in the console
+2. **Callable**: a function to be called
+3. **List of Strings/Callables**: for execution of multiple messages or functions
 
 The actions are executed at interrogation time when the threshold level assigned to the action
 is exceeded by the number or proportion of failing test units. When providing a string, it will
 simply be printed to the console. A callable will also be executed at the time of interrogation.
 If providing a list of strings or callables, each item in the list will be executed in order.
 Such a list can contain a mix of strings and callables.
 
-Here's an example where we use a custom function as part of an action:
+Displaying console messages may be a simple approach, but it is effective. And the strings don't
+have to be static, there are templating features that can be useful for constructing strings for a
+variety of situations. The following placeholders are available for use:
+
+- `{type}`: The validation step type where the action is executed (e.g., ‘col_vals_gt’, etc.)
+- `{level}`: The threshold level where the action is executed (‘warning’, ‘error’, or ‘critical’)
+- `{step}` or `{i}`: The step number in the validation workflow where the action is executed
+- `{col}` or `{column}`: The column name where the action is executed
+- `{val}` or `{value}`: An associated value for the validation method
+- `{time}`: A datetime value for when the action was executed
+
+Here's an example where we prepare a console message with a number of value placeholders
+(`action_str`) and use it globally at `Actions(critical=)`:
+
+```{python}
+
+action_str = "[{LEVEL}: {TYPE}]: Step {step} has failed validation. ({time})"
+
+validation = (
+    pb.Validate(
+        data=pb.load_dataset(dataset="game_revenue", tbl_type="duckdb"),
+        thresholds=pb.Thresholds(warning=0.05, error=0.10, critical=0.15),
+        actions=pb.Actions(critical=action_str),
+    )
+    .col_vals_regex(columns="player_id", pattern=r"[A-Z]{12}\d{3}")
+    .col_vals_gt(columns="item_revenue", value=0.10)
+    .col_vals_ge(columns="session_duration", value=15)
+    .interrogate()
+)
+```
+
+What we get here are two messages in the console, corresponding to critical failures in steps 2 and
+3. The placeholders were replaced with the correct text for the context. Note that some of the
+resulting text is capitalized (e.g., `"CRITICAL"`, `"COL_VALS_GT"`, etc.) and this is because we
+capitalized the placeholder text itself. Have a look at the documentation article of
+[`Actions`](https://posit-dev.github.io/pointblank/reference/Actions.html) for more details on this.
+
+Aside from strings, any callable can be used as an action value. Here's an example where we use a
+custom function as part of an action:
 
 ```{python}
 def dq_issue():