This is an automated email from the ASF dual-hosted git repository.
weilee pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new d3727861c92 Import documentation with screenshots for HITL (#54618)
d3727861c92 is described below
commit d3727861c9261ab53c8b80bdc24258786fbe6070
Author: Wei-Yu Chen <[email protected]>
AuthorDate: Tue Aug 19 23:40:37 2025 -0400
Import documentation with screenshots for HITL (#54618)
---
airflow-core/docs/img/hitl_approve_reject.png | Bin 0 -> 527119 bytes
airflow-core/docs/img/hitl_branch_selected.png | Bin 0 -> 485113 bytes
airflow-core/docs/img/hitl_branch_selection.png | Bin 0 -> 451478 bytes
airflow-core/docs/img/hitl_wait_for_input.png | Bin 0 -> 493082 bytes
.../docs/img/hitl_wait_for_multiple_options.png | Bin 0 -> 524043 bytes
airflow-core/docs/img/hitl_wait_for_option.png | Bin 0 -> 493109 bytes
airflow-core/docs/tutorial/hitl.rst | 80 ++++++++++++++++++++-
.../standard/example_dags/example_hitl_operator.py | 8 +--
8 files changed, 83 insertions(+), 5 deletions(-)
diff --git a/airflow-core/docs/img/hitl_approve_reject.png
b/airflow-core/docs/img/hitl_approve_reject.png
new file mode 100644
index 00000000000..94963dbcc8e
Binary files /dev/null and b/airflow-core/docs/img/hitl_approve_reject.png
differ
diff --git a/airflow-core/docs/img/hitl_branch_selected.png
b/airflow-core/docs/img/hitl_branch_selected.png
new file mode 100644
index 00000000000..342a13c9376
Binary files /dev/null and b/airflow-core/docs/img/hitl_branch_selected.png
differ
diff --git a/airflow-core/docs/img/hitl_branch_selection.png
b/airflow-core/docs/img/hitl_branch_selection.png
new file mode 100644
index 00000000000..fb3fc472bcc
Binary files /dev/null and b/airflow-core/docs/img/hitl_branch_selection.png
differ
diff --git a/airflow-core/docs/img/hitl_wait_for_input.png
b/airflow-core/docs/img/hitl_wait_for_input.png
new file mode 100644
index 00000000000..3d0ba69ddb4
Binary files /dev/null and b/airflow-core/docs/img/hitl_wait_for_input.png
differ
diff --git a/airflow-core/docs/img/hitl_wait_for_multiple_options.png
b/airflow-core/docs/img/hitl_wait_for_multiple_options.png
new file mode 100644
index 00000000000..549b168318e
Binary files /dev/null and
b/airflow-core/docs/img/hitl_wait_for_multiple_options.png differ
diff --git a/airflow-core/docs/img/hitl_wait_for_option.png
b/airflow-core/docs/img/hitl_wait_for_option.png
new file mode 100644
index 00000000000..af348e5054c
Binary files /dev/null and b/airflow-core/docs/img/hitl_wait_for_option.png
differ
diff --git a/airflow-core/docs/tutorial/hitl.rst
b/airflow-core/docs/tutorial/hitl.rst
index c16decd0399..70de9df757b 100644
--- a/airflow-core/docs/tutorial/hitl.rst
+++ b/airflow-core/docs/tutorial/hitl.rst
@@ -23,7 +23,7 @@ HITLOperator (Human-in-the-loop)
Human-in-the-Loop (HITL) functionality allows you to incorporate human
decision-making directly into your workflows.
This powerful feature enables workflows to pause and wait for human input,
making it perfect for approval processes, manual quality checks, and scenarios
where human judgment is essential.
-In this tutorial, we will explore how to use the HITL operators in workflows.
+In this tutorial, we will explore how to use the HITL operators in workflows
and demonstrate how it would look like in Airflow UI.
An HITL Example Dag
-------------------
@@ -48,6 +48,14 @@ This is useful for workflows involving human guidance within
large language mode
:start-after: [START howto_hitl_entry_operator]
:end-before: [END howto_hitl_entry_operator]
+|
+
+You can click the task and find the Required Actions tab in the details panel.
+
+.. image:: /img/hitl_wait_for_input.png
+ :alt: Demo HITL task instance waiting for input
+
+|
Option Selection
----------------
@@ -61,6 +69,28 @@ Users can select one of the available options, which can be
used to direct the w
:start-after: [START howto_hitl_operator]
:end-before: [END howto_hitl_operator]
+|
+
+.. image:: /img/hitl_wait_for_option.png
+ :alt: Demo HITL task instance waiting for an option
+
+|
+
+Multiple options are also allowed.
+
+.. exampleinclude::
/../../providers/standard/src/airflow/providers/standard/example_dags/example_hitl_operator.py
+ :language: python
+ :dedent: 4
+ :start-after: [START howto_hitl_operator_multiple]
+ :end-before: [END howto_hitl_operator_multiple]
+
+|
+
+.. image:: /img/hitl_wait_for_multiple_options.png
+ :alt: Demo HITL task instance waiting for multiple options
+
+|
+
Approval or Rejection
---------------------
@@ -72,8 +102,15 @@ A specialized form of option selection, which has only
'Approval' and 'Rejection
:start-after: [START howto_hitl_approval_operator]
:end-before: [END howto_hitl_approval_operator]
+|
+
As you can see in the body of this code snippet, you can use XComs to get
information provided by the user.
+.. image:: /img/hitl_approve_reject.png
+ :alt: Demo HITL task instance waiting for approval or rejection
+
+|
+
Branch Selection
----------------
@@ -89,12 +126,53 @@ And remember to specify their relationship in the workflow.
:start-after: [START howto_hitl_branch_operator]
:end-before: [END howto_hitl_branch_operator]
+|
+
.. exampleinclude::
/../../providers/standard/src/airflow/providers/standard/example_dags/example_hitl_operator.py
:language: python
:dedent: 4
:start-after: [START howto_hitl_workflow]
:end-before: [END howto_hitl_workflow]
+|
+
+.. image:: /img/hitl_branch_selection.png
+ :alt: Demo HITL task instance waiting for branch selection
+
+|
+
+After the branch is chosen, the workflow will proceed along the selected path.
+
+.. image:: /img/hitl_branch_selected.png
+ :alt: Demo HITL task instance after branch selection
+
+Notifiers
+---------
+
+A notifier is a callback mechanism that allows you to handle HITL events, such
as when a task is waiting for human input, succeeds, or fails.
+The example uses a notifier ``LocalLogNotifier`` that logs messages for
demonstration.
+You can implement your own notifier for different functionalities.
+For more details, please refer to `Creating a notifier
<https://airflow.apache.org/docs/apache-airflow/stable/howto/notifications.html>`_
and `Notifications
<https://airflow.apache.org/docs/apache-airflow-providers/core-extensions/notifications.html>`_.
+
+In the example Dag, the notifier is defined as follows:
+
+.. exampleinclude::
/../../providers/standard/src/airflow/providers/standard/example_dags/example_hitl_operator.py
+ :language: python
+ :start-after: [START hitl_notifier]
+ :end-before: [END hitl_notifier]
+
+|
+
+You can pass a list of notifiers to HITL operators using the ``notifiers``
argument as follows.
+When the operator creates an HITL request that is waiting for a human
response, the ``notify`` method will be called with a single argument,
``context``.
+
+.. exampleinclude::
/../../providers/standard/src/airflow/providers/standard/example_dags/example_hitl_operator.py
+ :language: python
+ :dedent: 4
+ :start-after: [START howto_hitl_entry_operator]
+ :end-before: [END howto_hitl_entry_operator]
+
+
Benefits and Common Use Cases
-----------------------------
diff --git
a/providers/standard/src/airflow/providers/standard/example_dags/example_hitl_operator.py
b/providers/standard/src/airflow/providers/standard/example_dags/example_hitl_operator.py
index 682778dc97f..ca3ca4dc1ee 100644
---
a/providers/standard/src/airflow/providers/standard/example_dags/example_hitl_operator.py
+++
b/providers/standard/src/airflow/providers/standard/example_dags/example_hitl_operator.py
@@ -37,6 +37,7 @@ if TYPE_CHECKING:
# [START hitl_tutorial]
+# [START hitl_notifier]
class LocalLogNotifier(BaseNotifier):
"""Simple notifier to demonstrate HITL notification without setup any
connection."""
@@ -49,7 +50,6 @@ class LocalLogNotifier(BaseNotifier):
self.log.info(self.message)
-# [START htil_notifer]
hitl_request_callback = LocalLogNotifier(
message="""
[HITL]
@@ -65,7 +65,7 @@ hitl_success_callback = LocalLogNotifier(
message="{% set task_id = task.task_id -%}{{
ti.xcom_pull(task_ids=task_id) }}"
)
hitl_failure_callback = LocalLogNotifier(message="Request to response to '{{
task.subject }}' failed")
-# [END htil_notifer]
+# [END hitl_notifier]
with DAG(
dag_id="example_hitl_operator",
@@ -95,7 +95,7 @@ with DAG(
)
# [END howto_hitl_operator]
- # [START howto_hitl_operator_muliple]
+ # [START howto_hitl_operator_multiple]
wait_for_multiple_options = HITLOperator(
task_id="wait_for_multiple_options",
subject="Please choose option to proceed: ",
@@ -105,7 +105,7 @@ with DAG(
on_success_callback=hitl_success_callback,
on_failure_callback=hitl_failure_callback,
)
- # [END howto_hitl_operator_muliple]
+ # [END howto_hitl_operator_multiple]
# [START howto_hitl_operator_timeout]
wait_for_default_option = HITLOperator(
