You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@airflow.apache.org by "Jasperora (via GitHub)" <gi...@apache.org> on 2025/08/18 14:42:56 UTC
[PR] add notifier doc [airflow]
Jasperora opened a new pull request, #54618:
URL: https://github.com/apache/airflow/pull/54618
## Why
Related Issue: #52206.
## What
Add doc for HITL.
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
<!--
Thank you for contributing! Please make sure that your code changes
are covered with tests. And in case of new features or big changes
remember to adjust the documentation.
Feel free to ping committers for the review!
In case of an existing issue, reference it using one of the following:
closes: #ISSUE
related: #ISSUE
How to write a good git commit message:
http://chris.beams.io/posts/git-commit/
-->
<!-- Please keep an empty line above the dashes. -->
---
**^ Add meaningful description above**
Read the **[Pull Request Guidelines](https://github.com/apache/airflow/blob/main/contributing-docs/05_pull_requests.rst#pull-request-guidelines)** for more information.
In case of fundamental code changes, an Airflow Improvement Proposal ([AIP](https://cwiki.apache.org/confluence/display/AIRFLOW/Airflow+Improvement+Proposals)) is needed.
In case of a new dependency, check compliance with the [ASF 3rd Party License Policy](https://www.apache.org/legal/resolved.html#category-x).
In case of backwards incompatible changes please leave a note in a newsfragment file, named `{pr_number}.significant.rst` or `{issue_number}.significant.rst`, in [airflow-core/newsfragments](https://github.com/apache/airflow/tree/main/airflow-core/newsfragments).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add documentation for HITL [airflow]
Posted by "Jasperora (via GitHub)" <gi...@apache.org>.
Jasperora commented on code in PR #54618:
URL: https://github.com/apache/airflow/pull/54618#discussion_r2286664744
##########
airflow-core/docs/tutorial/hitl.rst:
##########
@@ -95,6 +117,38 @@ And remember to specify their relationship in the workflow.
: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.
Review Comment:
Sure, adding links would be definitely helpful.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add documentation for HITL [airflow]
Posted by "Jasperora (via GitHub)" <gi...@apache.org>.
Jasperora commented on PR #54618:
URL: https://github.com/apache/airflow/pull/54618#issuecomment-3203330096
For the second point, I can make the screenshot of the situation if needed.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add documentation for HITL [airflow]
Posted by "Jasperora (via GitHub)" <gi...@apache.org>.
Jasperora commented on PR #54618:
URL: https://github.com/apache/airflow/pull/54618#issuecomment-3197236062
I'll keep on working on the documentation for the UI part.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Import documentation with screenshots for HITL [airflow]
Posted by "Lee-W (via GitHub)" <gi...@apache.org>.
Lee-W commented on PR #54618:
URL: https://github.com/apache/airflow/pull/54618#issuecomment-3204076478
Built locally. Looks awesome. Thanks for helping out!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add documentation for HITL [airflow]
Posted by "Jasperora (via GitHub)" <gi...@apache.org>.
Jasperora commented on code in PR #54618:
URL: https://github.com/apache/airflow/pull/54618#discussion_r2286666826
##########
airflow-core/docs/tutorial/hitl.rst:
##########
@@ -61,6 +66,20 @@ 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 option
Review Comment:
Sure! Thanks for pointing out.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Import documentation with screenshots for HITL [airflow]
Posted by "Lee-W (via GitHub)" <gi...@apache.org>.
Lee-W merged PR #54618:
URL: https://github.com/apache/airflow/pull/54618
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add documentation for HITL [airflow]
Posted by "Jasperora (via GitHub)" <gi...@apache.org>.
Jasperora commented on code in PR #54618:
URL: https://github.com/apache/airflow/pull/54618#discussion_r2286665224
##########
airflow-core/docs/tutorial/hitl.rst:
##########
@@ -95,6 +117,38 @@ And remember to specify their relationship in the workflow.
: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.
+
+In the example DAG, the notifier is defined as follows:
Review Comment:
Sorry about the miss. Have fixed it.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add documentation for HITL [airflow]
Posted by "guan404ming (via GitHub)" <gi...@apache.org>.
guan404ming commented on code in PR #54618:
URL: https://github.com/apache/airflow/pull/54618#discussion_r2285807602
##########
airflow-core/docs/tutorial/hitl.rst:
##########
@@ -61,6 +66,20 @@ 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 option
Review Comment:
```suggestion
:alt: Demo HITL task instance waiting for an option
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add documentation for HITL [airflow]
Posted by "Lee-W (via GitHub)" <gi...@apache.org>.
Lee-W commented on code in PR #54618:
URL: https://github.com/apache/airflow/pull/54618#discussion_r2285430728
##########
airflow-core/docs/tutorial/hitl.rst:
##########
@@ -95,6 +117,38 @@ And remember to specify their relationship in the workflow.
: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.
+
+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 reaches certain states, the ``notify`` method will be called.
Review Comment:
```suggestion
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`.
```
##########
airflow-core/docs/tutorial/hitl.rst:
##########
@@ -95,6 +117,38 @@ And remember to specify their relationship in the workflow.
: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.
Review Comment:
https://airflow.apache.org/docs/apache-airflow/stable/howto/notifications.html
https://airflow.apache.org/docs/apache-airflow-providers/core-extensions/notifications.html
We probably could mentione these 2 links here
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add documentation for HITL [airflow]
Posted by "Lee-W (via GitHub)" <gi...@apache.org>.
Lee-W commented on code in PR #54618:
URL: https://github.com/apache/airflow/pull/54618#discussion_r2285415573
##########
airflow-core/docs/tutorial/hitl.rst:
##########
@@ -95,6 +117,38 @@ And remember to specify their relationship in the workflow.
: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.
+
+In the example DAG, the notifier is defined as follows:
Review Comment:
```suggestion
In the example Dag, the notifier is defined as follows:
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add documentation for HITL [airflow]
Posted by "Jasperora (via GitHub)" <gi...@apache.org>.
Jasperora commented on code in PR #54618:
URL: https://github.com/apache/airflow/pull/54618#discussion_r2286664002
##########
airflow-core/docs/tutorial/hitl.rst:
##########
@@ -95,6 +117,38 @@ And remember to specify their relationship in the workflow.
: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.
+
+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 reaches certain states, the ``notify`` method will be called.
Review Comment:
I use double backticks for `notify` and `context ` since double backtick is needed for code in RST files.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org