:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
from collections.abc import Collection, Iterable, Iterator
from typing import Any
from uuid import UUID
from django.db.models import F
from posthog.helpers.full_text_search import build_rank
from posthog.ingress.contracts import WebhookDelivery
from products.access_control.backend.facade.user_access_control import UserAccessControl
from products.workflows.backend.facade.contracts import (
CohortDependentWorkflow,
EmailDomainCheck,
EmailDomainDnsRecord,
EmailDomainVerification,
FlowUtmUpdate,
RecentWorkflow,
TeamUtmDefaults,
TierDecision,
TwilioAccount,
TwilioPhoneNumber,
WorkflowAccessDenied,
WorkflowActivitySummary,
WorkflowArchived,
WorkflowNotFound,
WorkflowSummary,
WorkflowTaskDailyLimits,
WorkflowViewAccess,
WorkflowVisionScanDailyLimits,
)
from products.workflows.backend.models import HogFlow, TeamWorkflowsConfig
from products.workflows.backend.models.hog_flow.hog_flow import opt_out_category_ids, static_cohort_ids
from products.workflows.backend.services import email_utm_defaults
from products.workflows.backend.services.batch_jobs import create_batch_job
from products.workflows.backend.services.default_email_sender import (
clear_default_email_sender,
set_default_email_sender_if_unset,
)
from products.workflows.backend.services.email_sending_controls import (
ensure_workflows_config,
get_email_sending_state,
set_email_sending_tier,
suspend_email_sending,
unsuspend_email_sending,
)
from products.workflows.backend.services.existing_email_tools import (
lookup_existing_email_tools as _lookup_existing_email_tools,
)
from products.workflows.backend.services.integration_usage import get_active_hog_flows_using_integration
from products.workflows.backend.services.owned_workflow_health import list_owned_workflow_health
from products.workflows.backend.services.template_input_usage import (
filter_hog_flow_references_by_access_level,
get_hog_flows_referencing_template_input_keys,
)
from products.workflows.backend.utils.email_sending_tiers import (
MIN_EMAIL_SENDING_TIER,
get_email_sending_tier_limits,
max_email_sending_tier,
)
from products.workflows.backend.utils.rrule_utils import compute_next_occurrences, validate_rrule
__all__ = [
"WorkflowAccessDenied",
"WorkflowArchived",
"WorkflowNotFound",
"MIN_EMAIL_SENDING_TIER",
"clear_default_email_sender",
"compute_next_occurrences",
"create_batch_job",
"ensure_workflows_config",
"filter_hog_flow_references_by_access_level",
"get_email_sending_state",
"get_email_sending_tier_limits",
"get_viewable_workflow_ids",
"get_workflow_view_access",
"get_hog_flows_referencing_template_input_keys",
"list_owned_workflow_health",
"max_email_sending_tier",
"set_default_email_sender_if_unset",
"set_email_sending_tier",
"suspend_email_sending",
"unsuspend_email_sending",
"validate_rrule",
]
def search_workflows(
*,
project_id: int,
query: str | None,
access_control: UserAccessControl,
limit: int,
offset: int = 0,
include_archived: bool = False,
with_access_levels: bool = False,
include_count: bool = True,
) -> tuple[list[dict[str, Any]], int]:
"""Ranked full-text search over a project's workflows, in the result shape of core search.
``with_access_levels`` adds ``user_access_level``, the user's resolved level for each workflow.
``include_count=False`` skips the count query and reports a total of 0.
"""
statuses = [HogFlow.State.DRAFT, HogFlow.State.ACTIVE]
if include_archived:
statuses.append(HogFlow.State.ARCHIVED)
queryset = access_control.filter_queryset_by_access_level(
# nosemgrep: environment-model-scoped-by-project -- keeps the project-wide scope core /api/search used for workflows before the facade move; owners decide whether search narrows to one environment
HogFlow.objects.filter(team__project_id=project_id, status__in=statuses)
)
if query:
queryset = queryset.annotate(rank=build_rank({"name": "A", "description": "C"}, query, config="simple"))
queryset = queryset.filter(rank__gt=0.05).order_by("-rank")
else:
queryset = queryset.order_by(F("name").asc(nulls_first=True))
total_count = queryset.count() if include_count else 0
fields = ["id", "name", "description", "status", "created_by_id"]
if query:
fields.append("rank")
rows = list(queryset[offset : offset + limit].values(*fields))
access_levels = (
access_control.bulk_object_access_levels("hog_flow", [(str(row["id"]), row["created_by_id"]) for row in rows])
if with_access_levels
else {}
)
results: list[dict[str, Any]] = []
for workflow in rows:
result: dict[str, Any] = {
"type": "hog_flow",
"result_id": str(workflow["id"]),
"extra_fields": {
"name": workflow["name"],
"description": workflow["description"],
"status": workflow["status"],
},
}
if query:
result["rank"] = workflow["rank"]
if with_access_levels:
result["user_access_level"] = access_levels.get(str(workflow["id"]))
results.append(result)
return results, total_count
def get_workflow_owner_id(*, team_id: int, workflow_id: UUID) -> int | None:
try:
return HogFlow.objects.values_list("created_by_id", flat=True).get(team_id=team_id, id=workflow_id)
except HogFlow.DoesNotExist:
raise WorkflowNotFound() from None
def get_workflow_static_cohort_ids(*, team_id: int, workflow_id: UUID) -> set[int]:
try:
actions = HogFlow.objects.values_list("actions", flat=True).get(team_id=team_id, id=workflow_id)
except HogFlow.DoesNotExist:
raise WorkflowNotFound() from None
return static_cohort_ids(actions)
def get_workflow_opt_out_category_ids(*, team_id: int, workflow_id: UUID) -> set[str]:
try:
actions = HogFlow.objects.values_list("actions", flat=True).get(team_id=team_id, id=workflow_id)
except HogFlow.DoesNotExist:
raise WorkflowNotFound() from None
return opt_out_category_ids(actions)
def workflow_exists(*, team_id: int, workflow_id: UUID) -> bool:
return HogFlow.objects.filter(team_id=team_id, id=workflow_id).exists()
def get_workflow_task_daily_limits(*, team_id: int) -> WorkflowTaskDailyLimits:
config = (
TeamWorkflowsConfig.objects.filter(team_id=team_id)
.only("workflow_task_rate_limit_per_day", "workflow_task_team_rate_limit_per_day")
.first()
)
if config is None:
return WorkflowTaskDailyLimits(per_workflow=None, per_team=None)
return WorkflowTaskDailyLimits(
per_workflow=config.workflow_task_rate_limit_per_day,
per_team=config.workflow_task_team_rate_limit_per_day,
)
def get_workflow_vision_scan_daily_limits(*, team_id: int) -> WorkflowVisionScanDailyLimits:
config = (
TeamWorkflowsConfig.objects.filter(team_id=team_id)
.only("replay_vision_scan_rate_limit_per_day", "replay_vision_scan_team_rate_limit_per_day")
.first()
)
if config is None:
return WorkflowVisionScanDailyLimits(per_workflow=None, per_team=None)
return WorkflowVisionScanDailyLimits(
per_workflow=config.replay_vision_scan_rate_limit_per_day,
per_team=config.replay_vision_scan_team_rate_limit_per_day,
)
def accept_github_event(delivery: WebhookDelivery) -> None:
"""The inbound GitHub App webhook enters workflows here, so its consumer needs no internal import."""
# Deferred to keep the Kafka producer off the facade import path.
from products.workflows.backend.github_workflow_events import emit_github_event # noqa: PLC0415
emit_github_event(delivery.event_type, dict(delivery.payload), delivery.delivery_id or "")
def accept_ses_event(delivery: WebhookDelivery) -> None:
"""The inbound SES events SNS topic enters workflows here, so its consumer needs no internal import."""
# Deferred to keep the Celery task and the SNS callback client off the facade import path.
from products.workflows.backend.services.ses_tenant_events import handle_ses_tenant_event # noqa: PLC0415
handle_ses_tenant_event(delivery)
def get_workflow_names(*, team_id: int, workflow_ids: Iterable[str]) -> dict[str, str]:
"""Names keyed by the workflow id as a string. Deleted workflows are left out."""
return {
str(pk): (name or "")
for pk, name in HogFlow.objects.filter(team_id=team_id, id__in=list(workflow_ids)).values_list("id", "name")
}
def get_viewable_workflow_ids(*, team_id: int, user_access_control: UserAccessControl) -> set[str]:
"""The ids, as strings, of the team's workflows the reader may view."""
return {
str(pk)
for pk in user_access_control.filter_queryset_by_access_level(
HogFlow.objects.filter(team_id=team_id)
).values_list("id", flat=True)
}
def get_workflow_view_access(*, team_id: int, user_access_control: UserAccessControl) -> WorkflowViewAccess:
"""What the reader may view, for records that outlive their workflow. A denial outlives the workflow it names, so a
deleted workflow stays hidden from a reader denied it, and otherwise follows their access to workflows as a whole."""
viewable = get_viewable_workflow_ids(team_id=team_id, user_access_control=user_access_control)
existing = {str(pk) for pk in HogFlow.objects.filter(team_id=team_id).values_list("id", flat=True)}
return WorkflowViewAccess(
viewable_ids=frozenset(viewable),
blocked_ids=frozenset(
(existing | user_access_control.blocked_resource_ids_by_scope.get("hog_flow", frozenset())) - viewable
),
can_view_deleted=user_access_control.has_resource_access("hog_flow"),
)
def get_workflow_summary(*, team_id: int, workflow_id: str) -> WorkflowSummary:
row = HogFlow.objects.filter(team_id=team_id, id=workflow_id).values("id", "name", "status").first()
if row is None:
raise WorkflowNotFound()
return WorkflowSummary(id=str(row["id"]), name=row["name"] or "", status=row["status"])
def has_active_workflows(*, team_id: int) -> bool:
return HogFlow.objects.filter(team_id=team_id, status=HogFlow.State.ACTIVE).exists()
def has_active_workflow_for_warehouse_table(*, team_id: int, trigger_source: str, table_name: str) -> bool:
return HogFlow.objects.filter(
team_id=team_id,
status=HogFlow.State.ACTIVE,
trigger__type=trigger_source,
trigger__table_name=table_name,
).exists()
def active_workflow_warehouse_table_names(
*, team_id: int, trigger_source: str, table_names: Collection[str]
) -> set[str]:
"""The given warehouse table names that an active workflow triggers on."""
return set(
HogFlow.objects.filter(
team_id=team_id,
status=HogFlow.State.ACTIVE,
trigger__type=trigger_source,
trigger__table_name__in=list(table_names),
).values_list("trigger__table_name", flat=True)
)
def get_workflow_activity_summary(*, team_id: int, recent_limit: int) -> WorkflowActivitySummary:
"""Total and non-archived workflow counts, plus the most recently updated workflows."""
qs = HogFlow.objects.filter(team_id=team_id)
recent = qs.order_by("-updated_at")[:recent_limit].values("id", "name", "status", "updated_at")
return WorkflowActivitySummary(
total_count=qs.count(),
active_count=qs.exclude(status=HogFlow.State.ARCHIVED).count(),
recent=tuple(
RecentWorkflow(
id=str(row["id"]), name=row["name"] or "", status=row["status"], updated_at=row["updated_at"]
)
for row in recent
),
)
def get_active_workflows_using_integration(*, team_id: int, integration_id: int) -> list[WorkflowSummary]:
return [
WorkflowSummary(id=str(flow.id), name=flow.name or "", status=flow.status)
for flow in get_active_hog_flows_using_integration(team_id=team_id, integration_id=integration_id)
]
def get_active_workflows_using_realtime_cohort(
*, team_id: int, cohort_ids: Collection[int]
) -> list[CohortDependentWorkflow]:
# Deferred to keep the cdp filter compiler, and the HogQL schema it loads, off the django.setup() path.
from products.workflows.backend.services.cohort_usage import ( # noqa: PLC0415
get_active_hog_flows_using_realtime_cohort,
)
return [
CohortDependentWorkflow(id=str(flow.id), name=flow.name or "", status=flow.status)
for flow in get_active_hog_flows_using_realtime_cohort(team_id=team_id, cohort_ids=cohort_ids)
]
def team_has_active_workflows_using_cohorts(*, team_id: int) -> bool:
"""Cheap pre-check: False means no active workflow in the team can rely on any cohort."""
# Deferred for the same reason as get_active_workflows_using_realtime_cohort.
from products.workflows.backend.services.cohort_usage import ( # noqa: PLC0415
team_has_active_hog_flows_mentioning_cohorts,
)
return team_has_active_hog_flows_mentioning_cohorts(team_id)
def recompute_email_sending_tier(
team_id: int, *, user_id: int | None = None, was_impersonated: bool = False
) -> TierDecision | None:
# Deferred to keep the ClickHouse metrics client off the facade import path.
from products.workflows.backend.services.email_sending_tier import ( # noqa: PLC0415
recompute_email_sending_tier_for_team,
)
return recompute_email_sending_tier_for_team(team_id, user_id=user_id, was_impersonated=was_impersonated)
# The provider helpers look the provider class up on the providers package at call time, which
# also keeps boto3 and the Twilio client off the facade import path.
def create_ses_email_domain(
domain: str, *, mail_from_subdomain: str, team_id: int, org_team_ids: Iterable[int] | None = None
) -> None:
from products.workflows.backend import providers # noqa: PLC0415
providers.SESProvider().create_email_domain(
domain, mail_from_subdomain=mail_from_subdomain, team_id=team_id, org_team_ids=org_team_ids
)
def update_ses_mail_from_subdomain(domain: str, *, mail_from_subdomain: str) -> None:
from products.workflows.backend import providers # noqa: PLC0415
providers.SESProvider().update_mail_from_subdomain(domain, mail_from_subdomain=mail_from_subdomain)
def verify_ses_email_domain(domain: str, *, mail_from_subdomain: str, team_id: int) -> EmailDomainVerification:
from products.workflows.backend import providers # noqa: PLC0415
return providers.SESProvider().verify_email_domain(domain, mail_from_subdomain=mail_from_subdomain, team_id=team_id)
def get_ses_email_domain_status(domain: str, *, mail_from_subdomain: str, team_id: int) -> EmailDomainCheck:
from products.workflows.backend import providers # noqa: PLC0415
return providers.SESProvider().get_email_domain_status(
domain, mail_from_subdomain=mail_from_subdomain, team_id=team_id
)
def get_maildev_email_domain_status(domain: str, *, mail_from_subdomain: str) -> EmailDomainCheck:
from products.workflows.backend import providers # noqa: PLC0415
return providers.maildev_email_domain_status(domain, mail_from_subdomain=mail_from_subdomain)
def lookup_existing_email_tools(root_domain: str) -> list[str]:
return _lookup_existing_email_tools(root_domain)
def delete_ses_identity(identity: str) -> None:
from products.workflows.backend import providers # noqa: PLC0415
providers.SESProvider().delete_identity(identity)
def list_ses_bounce_suppressions() -> Iterator[list[str]]:
"""Yield the addresses on the SES account-level suppression list for a bounce, one page at a time."""
from products.workflows.backend import providers # noqa: PLC0415
yield from providers.SESProvider().list_bounce_suppressions()
def get_maildev_mock_dns_records() -> list[EmailDomainDnsRecord]:
from products.workflows.backend import providers # noqa: PLC0415
return providers.MAILDEV_MOCK_DNS_RECORDS
def get_twilio_phone_numbers(*, account_sid: str, auth_token: str) -> list[TwilioPhoneNumber]:
from products.workflows.backend import providers # noqa: PLC0415
return providers.TwilioProvider(account_sid=account_sid, auth_token=auth_token).get_phone_numbers()
def get_twilio_account_info(*, account_sid: str, auth_token: str) -> TwilioAccount:
from products.workflows.backend import providers # noqa: PLC0415
return providers.TwilioProvider(account_sid=account_sid, auth_token=auth_token).get_account_info()
def load_team_utm_defaults(team_id: int) -> TeamUtmDefaults:
return email_utm_defaults.load_team_utm_defaults(team_id)
def flow_ids_with_active_schedule(team_id: int) -> set[UUID]:
return email_utm_defaults.flow_ids_with_active_schedule(team_id)
def seed_new_email_steps_with_utm_defaults(
actions: list[dict[str, Any]], existing_action_ids: Iterable[str], defaults: TeamUtmDefaults
) -> None:
email_utm_defaults.seed_new_email_actions(actions, existing_action_ids, defaults)
def release_edited_email_utm_keys(
actions: list[dict[str, Any]],
stored_actions: list[Any],
stored_draft: dict[str, Any] | None,
defaults: TeamUtmDefaults,
*,
saving_draft: bool,
) -> None:
email_utm_defaults.release_edited_keys(actions, stored_actions, stored_draft, defaults, saving_draft=saving_draft)
def is_utm_apply_eligible(flow: HogFlow, has_active_schedule: bool) -> bool:
return email_utm_defaults.is_apply_eligible(flow, has_active_schedule)
def plan_flow_utm_update(
actions: list[Any], draft: dict[str, Any] | None, defaults: TeamUtmDefaults, enable_where_off: bool
) -> FlowUtmUpdate | None:
return email_utm_defaults.plan_flow_update(actions, draft, defaults, enable_where_off)