Skip to content

Conversation

@cmarteepants
Copy link
Collaborator

This PR enhances HITLBranchOperator to accept an optional options_mapping dict that maps human-facing option labels to downstream task_ids. Previously, HITL branching required users to select raw task_ids, which isn’t user-friendly in business-facing workflows. With this change, a workflow can present clearer options (e.g., “Full Deploy” / “Canary”) while still resolving to valid downstream tasks.

Changes

  • New parameter: options_mapping: dict[str, str] | None
    • Keys: option labels (same as what's provided to options)
    • Values: task_ids of valid downstream tasks
  • Validation:
    • Ensures keys are valid options
    • Ensures values are strings (task_ids)
  • Execution:
    • Normalizes chosen options and applies mapping before branching
    • Falls back to the raw option if no mapping is provided
  • Tests:
    • Single and multiple mapped choices
    • Fallback to unmapped options
    • Error when mapping points to non-downstream tasks (AirflowException)
    • Error on invalid keys
    • Error on non-string mapping values

Rationale
This improves HITL usability for end-users by decoupling the labels people choose from the task_ids Airflow needs that may not necessarily be known by the approver, while keeping strong validation in place.

Example

op = HITLBranchOperator(
    task_id="choose",
    subject="Approval required",
    options=["Approve", "Reject"],
    options_mapping={"Approve": "publish", "Reject": "archive"},
)
op >> [EmptyOperator(task_id="publish"), EmptyOperator(task_id="archive")]

If the user selects Approve, the operator branches to the publish task.

cmarteepants and others added 4 commits September 1, 2025 21:10
This change introduces an optional `options_mapping` argument for
HITLBranchOperator, allowing human-facing option labels to be mapped
to specific downstream task_ids. This makes the operator more
business-friendly (e.g. "Approve" → "publish") while preserving
Airflow’s branch validation.

Also adds unit tests covering:
- valid mapping for single and multiple choices
- fallback to unmapped options
- error when mapping points to non-downstream task_ids
- invalid mapping keys
- invalid mapping value types
@Lee-W Lee-W force-pushed the update-hitlbranchoperator branch from 407a71e to a0bc195 Compare September 1, 2025 13:10
@Lee-W Lee-W merged commit 94febf2 into apache:main Sep 1, 2025
107 checks passed
@Lee-W Lee-W deleted the update-hitlbranchoperator branch September 1, 2025 14:39
@github-project-automation github-project-automation bot moved this from In review to Done in AIP-90 - Human in the loop Sep 1, 2025
nothingmin pushed a commit to nothingmin/airflow that referenced this pull request Sep 2, 2025
Co-authored-by: Wei Lee <weilee.rx@gmail.com>
abdulrahman305 bot pushed a commit to abdulrahman305/airflow that referenced this pull request Sep 30, 2025
Co-authored-by: Wei Lee <weilee.rx@gmail.com>
abdulrahman305 bot pushed a commit to abdulrahman305/airflow that referenced this pull request Oct 1, 2025
Co-authored-by: Wei Lee <weilee.rx@gmail.com>
abdulrahman305 bot pushed a commit to abdulrahman305/airflow that referenced this pull request Oct 2, 2025
Co-authored-by: Wei Lee <weilee.rx@gmail.com>
abdulrahman305 bot pushed a commit to abdulrahman305/airflow that referenced this pull request Oct 3, 2025
Co-authored-by: Wei Lee <weilee.rx@gmail.com>
abdulrahman305 bot pushed a commit to abdulrahman305/airflow that referenced this pull request Oct 4, 2025
Co-authored-by: Wei Lee <weilee.rx@gmail.com>
abdulrahman305 bot pushed a commit to abdulrahman305/airflow that referenced this pull request Oct 5, 2025
Co-authored-by: Wei Lee <weilee.rx@gmail.com>
abdulrahman305 bot pushed a commit to abdulrahman305/airflow that referenced this pull request Oct 5, 2025
Co-authored-by: Wei Lee <weilee.rx@gmail.com>
abdulrahman305 bot pushed a commit to abdulrahman305/airflow that referenced this pull request Oct 7, 2025
Co-authored-by: Wei Lee <weilee.rx@gmail.com>
abdulrahman305 bot pushed a commit to abdulrahman305/airflow that referenced this pull request Oct 8, 2025
Co-authored-by: Wei Lee <weilee.rx@gmail.com>
abdulrahman305 bot pushed a commit to abdulrahman305/airflow that referenced this pull request Oct 9, 2025
Co-authored-by: Wei Lee <weilee.rx@gmail.com>
abdulrahman305 bot pushed a commit to abdulrahman305/airflow that referenced this pull request Oct 10, 2025
Co-authored-by: Wei Lee <weilee.rx@gmail.com>
abdulrahman305 bot pushed a commit to abdulrahman305/airflow that referenced this pull request Oct 11, 2025
Co-authored-by: Wei Lee <weilee.rx@gmail.com>
abdulrahman305 bot pushed a commit to abdulrahman305/airflow that referenced this pull request Oct 12, 2025
Co-authored-by: Wei Lee <weilee.rx@gmail.com>
abdulrahman305 bot pushed a commit to abdulrahman305/airflow that referenced this pull request Oct 14, 2025
Co-authored-by: Wei Lee <weilee.rx@gmail.com>
abdulrahman305 bot pushed a commit to abdulrahman305/airflow that referenced this pull request Oct 15, 2025
Co-authored-by: Wei Lee <weilee.rx@gmail.com>
abdulrahman305 bot pushed a commit to abdulrahman305/airflow that referenced this pull request Oct 17, 2025
Co-authored-by: Wei Lee <weilee.rx@gmail.com>
abdulrahman305 bot pushed a commit to abdulrahman305/airflow that referenced this pull request Oct 19, 2025
Co-authored-by: Wei Lee <weilee.rx@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

3 participants