Why DAG level parameters are shown in HTIL Operator Required Action UI form?

[abodaka]

Apache Airflow version

3.1.6 (latest)

Deployment

docker compose from apache-airflow/3.1.6/docker-compose.yaml

Deployment details
Python: 3.12
airflow-airflow-dag-processor
airflow-airflow-worker

Database: Postgres
Browser: Chrome

The problem

tl;dr: HITLOperator shows all params, even from DAG-level ones in Airflow UI in Required Action panel, while only operator's params are desired.

Hi everyone,

I would like to ask you for help, as I am a bit desperate. I would like to declare a HTIL operator (e.g. an Approval one or Entry one) that in the Requested Action would show only chosen set of new parameters from the operator level only.

Here's my example declaration:

from airflow.providers.standard.operators.hitl import ApprovalOperator
from airflow.sdk import dag, task, task_group, Param

confirm_maintenance_schedule = ApprovalOperator(
    task_id="confirm_maintenance_schedule",
    task_display_name="Confirm maintenance",
    subject="Confirm maintenance schedule",
    body=(
        "Maintenance: {{ ti.xcom_pull(task_ids='scheduling_and_notification.render_switchover_context', key='maintenance_start_utc') }}"
        " to {{ ti.xcom_pull(task_ids='scheduling_and_notification.render_switchover_context', key='maintenance_end_utc') }}"
    ),
    defaults="Approve",
    params={
        "approval_note": Param(
            default="",
            type="string",
            title="Approval note",
            description="Optional note for the approval decision",
        ),
    },
)

While running this DAG, I declare other parameters that I would like the actor to fill-out during the run declaration, thus, I have multiple parameters provided in @dag decorator:

@dag(
    schedule=None,
    start_date=pendulum.datetime(2026, 1, 1, tz="UTC"),
    catchup=False,
    tags=["production", "switchover"],
    max_active_runs=1,
    is_paused_upon_creation=True,
    auto_register=True,
    dag_display_name="Portal Switchover",
    params={
        "target_env": Param(
            enum=SITES,
            type="string",
            description="Target environment for the switchover",
            default=SITES[0],
            title="Target Environment",
        ),
        "dry_run": Param(
            default=True,
            type="boolean",
            description="Perform a dry run without making changes to the systems",
            title="Dry run mode",
        ),
[...]

While the task is running, instead of showing only the Approval note, just like indicated in any tutorial for HITL or documentation, it instead shows whole form with every section from DAG-level:

How can I prevent this?

The imported ApprovalOperator inherits from HITLOperator and actually does have method that should clear the parameters in its constructor:

        self.params: ParamsDict = params if isinstance(params, ParamsDict) else ParamsDict(params or {})
        if hasattr(ParamsDict, "filter_params_by_source"):
            # Params that exist only in Dag level does not make sense to appear in HITLOperator
            self.params = ParamsDict.filter_params_by_source(self.params, source="task")
        elif self.params:
            self.log.debug(
                "ParamsDict.filter_params_by_source not available; HITLOperator will also include Dag level params."
            )

The comment clearly states that my reasoning is the expected behaviour, but it simply does not do the job.

What am I missing?
Do I have to declare all of the params in another HITL operator and leave DAG-level params blank? Although, I would like to access their values in templates and avoid pulling them from XComs all the time.

Maybe it is a bug that I have managed somehow to reproduce.

Thank you!

[potiuk]

This code you quoted has been added in #58615 and this is scheduled to be released in 3.2.0 (see the milestone) - so what you see is expected in 3.1.x

[abodaka]

That would be the answer. Thank you so much!