Skip to main content
Apache Airflow can trigger Planasonix pipelines as tasks inside your existing DAGs. You keep Airflow as the control plane for cross-system workflows while Planasonix executes the ETL graph, surfaces run history, and applies workspace permissions.

​
Integration overview

Typical flow:
  1. Airflow schedules or sensors decide when work should run.
  2. A Planasonix operator (or HTTP task) calls the Planasonix API with pipeline id, parameters, and environment.
  3. Planasonix enqueues the run and returns a run id.
  4. The operator polls until the run reaches a terminal state, or you use deferrable mode to free worker slots.
You can also invert the pattern: Planasonix webhooks or chaining trigger Airflow DAGs when loads complete. Choose one primary orchestrator to avoid circular dependencies.

​
Planasonix Airflow operator

Install the provider package your platform team distributes (PyPI name and version appear in your internal wiki). The operator usually accepts:
  • pipeline_id or pipeline_name plus environment
  • parameters / variables dict passed into the run
  • wait_for_completion and timeout
  • api_key or connection id referencing stored credentials
Blocks an Airflow worker until Planasonix finishes. Simple to reason about; ties up a worker for long jobs.

​
Connection configuration

Create an Airflow HTTP or custom connection:
FieldValue
HostPlanasonix API host for your region
LoginService account identifier if required
Password / tokenAPI key or OAuth secret from API keys
Extra JSONorganization_id, default environment, optional agent_pool hints
Use a workspace-scoped service account with run permission on specific pipelines, not a human admin key.

​
DAG examples

​
Minimal synchronous task

from datetime import datetime
from airflow import DAG
from planasonix_provider.operators.planasonix import PlanasonixRunPipelineOperator

with DAG(
    dag_id="nightly_sales_to_warehouse",
    start_date=datetime(2025, 1, 1),
    schedule="0 2 * * *",
    catchup=False,
) as dag:
    run_planasonix = PlanasonixRunPipelineOperator(
        task_id="run_sales_pipeline",
        pipeline_id="pl_8f2a9c1d4e",
        environment="production",
        parameters={"business_date": "{{ ds }}"},
        wait_for_completion=True,
        planasonix_conn_id="planasonix_default",
    )

​
Sensor plus downstream warehouse task

from airflow import DAG
from airflow.operators.empty import EmptyOperator
from datetime import datetime
from planasonix_provider.operators.planasonix import PlanasonixRunPipelineOperator

with DAG(
    dag_id="after_planasonix_refresh",
    start_date=datetime(2025, 1, 1),
    schedule=None,
    catchup=False,
) as dag:
    start = EmptyOperator(task_id="start")

    load = PlanasonixRunPipelineOperator(
        task_id="planasonix_incremental_load",
        pipeline_id="pl_inventory_hourly",
        environment="production",
        parameters={"watermark": "{{ dag_run.conf.get('watermark') }}"},
        wait_for_completion=True,
        planasonix_conn_id="planasonix_default",
    )

    dbt_models = EmptyOperator(task_id="trigger_dbt_job_placeholder")

    start >> load >> dbt_models
Replace operator import paths with the package name your organization publishes.
Never embed API keys in DAG source. Always use Airflow connections or secrets backends.

​
Monitoring Airflow-triggered runs

In Planasonix run history, filter by trigger type (API / integration) and correlation metadata if your operator forwards dag_id and task_id as tags or parameters.
  • Failed Planasonix runs should fail the Airflow task so retries and alerting follow your existing DAG policies.
  • For long runs, align Airflow task timeout with Planasonix run timeout to avoid double-kill races.
Pass deterministic parameters (ds, hour, business keys) so retries do not duplicate loads unless your pipeline is designed for at-least-once semantics.
If Airflow lives in a different region than Planasonix, add slack to polling intervals to reduce API chatter.

API authentication

Token types and scopes for automation.

Webhooks

Event-driven triggers into or out of Planasonix.