Skip to content

: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.

feat(workflows): apply team utm defaults to existing emails (#116419)

Daniel Marchuk3850b9202d49
diff --git a/frontend/src/generated/core/api.schemas.ts b/frontend/src/generated/core/api.schemas.ts
index 3cc8cf88b17c..f721cac84c30 100644
--- a/frontend/src/generated/core/api.schemas.ts
+++ b/frontend/src/generated/core/api.schemas.ts
@@ -1789,7 +1789,7 @@ export interface TeamWorkflowsConfigApi {
* * `opt_out` - Opt Out
* * `opt_in` - Opt In */
email_tracking_consent_mode?: EmailTrackingConsentModeEnumApi
- /** Whether new email steps and broadcasts start with UTM tags on their links. Each email can still change it. Existing emails keep their current values. */
+ /** Whether new email steps and broadcasts start with UTM tags on their links. Each email can still change it. Existing emails change only through apply_utm_defaults. */
email_utm_tags_enabled?: boolean
/** Default UTM values that new email steps and broadcasts copy. An empty value keeps the built-in default for that tag. */
email_utm_params?: EmailUtmParamsApi
diff --git a/posthog/api/team/team_config.py b/posthog/api/team/team_config.py
index 6074134a1b18..eb0b9bd87fcb 100644
--- a/posthog/api/team/team_config.py
+++ b/posthog/api/team/team_config.py
@@ -357,7 +357,7 @@ class TeamWorkflowsConfigSerializer(serializers.ModelSerializer, UserAccessContr
required=False,
help_text=(
"Whether new email steps and broadcasts start with UTM tags on their links. "
- "Each email can still change it. Existing emails keep their current values."
+ "Each email can still change it. Existing emails change only through apply_utm_defaults."
),
)
email_utm_params = EmailUtmParamsField(
diff --git a/products/notifications/backend/facade/api.py b/products/notifications/backend/facade/api.py
index 1a57632ec799..2d8390101494 100644
--- a/products/notifications/backend/facade/api.py
+++ b/products/notifications/backend/facade/api.py
@@ -7,13 +7,19 @@ from products.notifications.backend.facade.enums import (
SourceType,
TargetType,
)
-from products.notifications.backend.logic import create_notification, has_been_dispatched, publish_resource_edited
+from products.notifications.backend.logic import (
+ create_notification,
+ has_been_dispatched,
+ publish_resource_edited,
+ publish_resources_edited,
+)
from products.notifications.backend.resolvers import RecipientsResolver
__all__ = [
"create_notification",
"has_been_dispatched",
"publish_resource_edited",
+ "publish_resources_edited",
"NotificationData",
"NotificationResourceType",
"NotificationType",
diff --git a/products/notifications/backend/logic.py b/products/notifications/backend/logic.py
index 77a97a28f0aa..d761aedcd1ae 100644
--- a/products/notifications/backend/logic.py
+++ b/products/notifications/backend/logic.py
@@ -1,3 +1,5 @@
+from collections.abc import Sequence
+
from django.db import transaction
import structlog
@@ -119,6 +121,27 @@ def publish_resource_edited(
`resource_type` is the value the frontend matches on (e.g. "HogFlow"); `ac_resource_type` is the
access-control scope used to drop recipients without viewer access (e.g. "hog_flow").
"""
+ publish_resources_edited(
+ team=team,
+ resource_type=resource_type,
+ edits=[(resource_id, updated_at)],
+ actor_user_id=actor_user_id,
+ ac_resource_type=ac_resource_type,
+ )
+
+
+def publish_resources_edited(
+ *,
+ team: Team,
+ resource_type: str,
+ edits: Sequence[tuple[str, str]],
+ actor_user_id: int | None = None,
+ ac_resource_type: str | None = None,
+) -> None:
+ """`publish_resource_edited` for many resources of one type at once. `edits` holds (resource_id, updated_at)
+ pairs. The flag check and the recipients resolve once for the whole set, not once per resource."""
+ if not edits:
+ return
organization_id = team.organization_id
if not posthoganalytics.feature_enabled(
@@ -138,24 +161,32 @@ def publish_resource_edited(
if not recipient_user_ids:
return
- payload = {
- "organization_id": str(organization_id),
- "team_id": team.id,
- "notification_type": RESOURCE_EDITED_EVENT_TYPE,
- "resource_type": resource_type,
- "resource_id": str(resource_id),
- "updated_at": updated_at,
- "actor_user_id": actor_user_id,
- "resolved_user_ids": recipient_user_ids,
- "priority": "normal",
- }
+ payloads = [
+ {
+ "organization_id": str(organization_id),
+ "team_id": team.id,
+ "notification_type": RESOURCE_EDITED_EVENT_TYPE,
+ "resource_type": resource_type,
+ "resource_id": str(resource_id),
+ "updated_at": updated_at,
+ "actor_user_id": actor_user_id,
+ "resolved_user_ids": recipient_user_ids,
+ "priority": "normal",
+ }
+ for resource_id, updated_at in edits
+ ]
def _on_commit() -> None:
try:
producer = get_producer(topic=KAFKA_NOTIFICATION_EVENTS)
- producer.produce(topic=KAFKA_NOTIFICATION_EVENTS, data=payload, key=str(organization_id))
except Exception:
- logger.exception("notifications.resource_edited_publish_failed", resource_id=str(resource_id))
+ logger.exception("notifications.resource_edited_publish_failed", resource_id=edits[0][0])
+ return
+ for payload in payloads:
+ try:
+ producer.produce(topic=KAFKA_NOTIFICATION_EVENTS, data=payload, key=str(organization_id))
+ except Exception:
+ logger.exception("notifications.resource_edited_publish_failed", resource_id=payload["resource_id"])
transaction.on_commit(_on_commit)
diff --git a/products/notifications/backend/tests/test_logic.py b/products/notifications/backend/tests/test_logic.py
index dc501b26659b..9eaa7cb9c97e 100644
--- a/products/notifications/backend/tests/test_logic.py
+++ b/products/notifications/backend/tests/test_logic.py
@@ -19,7 +19,7 @@ from products.notifications.backend.facade.enums import (
SourceType,
TargetType,
)
-from products.notifications.backend.logic import create_notification, publish_resource_edited
+from products.notifications.backend.logic import create_notification, publish_resource_edited, publish_resources_edited
from products.notifications.backend.models import NotificationEvent
from products.notifications.backend.resolvers import RecipientsResolver
@@ -486,6 +486,26 @@ class TestPublishResourceEdited(BaseTest):
# Editor-state sync only — it must never become an inbox notification.
assert NotificationEvent.objects.count() == 0
+ @patch("products.notifications.backend.logic.posthoganalytics.feature_enabled", return_value=True)
+ @patch("products.notifications.backend.logic.get_producer")
+ @patch.object(RecipientsResolver, "resolve", return_value=[1, 2])
+ def test_many_edits_resolve_recipients_once(self, mock_resolve, mock_get_producer, mock_ff):
+ with self.captureOnCommitCallbacks(execute=True):
+ publish_resources_edited(
+ team=self.team,
+ resource_type="HogFlow",
+ edits=[("flow-1", "2026-06-16T00:00:00+00:00"), ("flow-2", "2026-06-16T00:01:00+00:00")],
+ ac_resource_type="annotation",
+ )
+
+ mock_resolve.assert_called_once()
+ mock_ff.assert_called_once()
+ payloads = [call.kwargs["data"] for call in mock_get_producer.return_value.produce.call_args_list]
+ assert [(p["resource_id"], p["resolved_user_ids"]) for p in payloads] == [
+ ("flow-1", [1, 2]),
+ ("flow-2", [1, 2]),
+ ]
+
@patch("products.notifications.backend.logic.posthoganalytics.feature_enabled", return_value=True)
@patch("products.notifications.backend.logic.get_producer")
@patch.object(RecipientsResolver, "filter_by_access_control")
diff --git a/products/workflows/backend/facade/api.py b/products/workflows/backend/facade/api.py
index 65e23a47179b..436294a9efa8 100644
--- a/products/workflows/backend/facade/api.py
+++ b/products/workflows/backend/facade/api.py
@@ -13,6 +13,7 @@ from products.workflows.backend.facade.contracts import (
EmailDomainCheck,
EmailDomainDnsRecord,
EmailDomainVerification,
+ FlowUtmUpdate,
RecentWorkflow,
TeamUtmDefaults,
TierDecision,
@@ -383,6 +384,10 @@ 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:
@@ -398,3 +403,13 @@ def release_edited_email_utm_keys(
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)
diff --git a/products/workflows/backend/facade/contracts.py b/products/workflows/backend/facade/contracts.py
index 40b56ca1fefd..4fc54ec3e0d7 100644
--- a/products/workflows/backend/facade/contracts.py
+++ b/products/workflows/backend/facade/contracts.py
@@ -529,6 +529,20 @@ class TeamUtmDefaults:
params: dict[str, str]
+@frozen
+class FlowUtmUpdate:
+ actions: list[dict[str, Any]] | None
+ draft_actions: list[dict[str, Any]] | None
+ emails_updated: int
+ emails_turned_on: int
+
+
+@frozen
+class UtmDefaultsWriteResult:
+ write: "WorkflowWriteResult"
+ plan: FlowUtmUpdate
+
+
@frozen
class MessageAsset:
invocation_id: str
diff --git a/products/workflows/backend/facade/writes.py b/products/workflows/backend/facade/writes.py
index 53edddd098a4..eecfee67bcd4 100644
--- a/products/workflows/backend/facade/writes.py
+++ b/products/workflows/backend/facade/writes.py
@@ -1,8 +1,10 @@
"""The workflow write path: live saves, staged drafts, surgical edits, publish and discard, each under
the workflow's row lock with its staleness fences, revision bump and post-commit follow-ups."""
+from products.workflows.backend.models.hog_flow.hog_flow import defer_hog_flow_reloads
from products.workflows.backend.services.hog_flow_writes import (
DRAFT_CONTENT_FIELDS,
+ apply_email_utm_defaults,
create_workflow,
destroy_workflow,
discard_draft,
@@ -17,8 +19,10 @@ from products.workflows.backend.services.publish_impact import build_publish_imp
__all__ = [
"DRAFT_CONTENT_FIELDS",
+ "apply_email_utm_defaults",
"build_publish_impact",
"create_workflow",
+ "defer_hog_flow_reloads",
"discard_draft",
"destroy_workflow",
"edit_workflow_content",
diff --git a/products/workflows/backend/models/hog_flow/hog_flow.py b/products/workflows/backend/models/hog_flow/hog_flow.py
index 0006761dd448..e22ce6c588d8 100644
--- a/products/workflows/backend/models/hog_flow/hog_flow.py
+++ b/products/workflows/backend/models/hog_flow/hog_flow.py
@@ -1,5 +1,7 @@
from collections.abc import Iterator
-from typing import TYPE_CHECKING, Any, Final
+from contextlib import contextmanager
+from contextvars import ContextVar
+from typing import TYPE_CHECKING, Any, Final, Optional
from django.db import models, transaction
from django.db.models.signals import post_delete, post_save
@@ -8,6 +10,7 @@ from django.utils.functional import Promise
import structlog
+from posthog.exceptions_capture import capture_exception
from posthog.helpers.encrypted_fields import EncryptedJSONStringField
from posthog.models.tagged_items_relation import Taggable
from posthog.models.team.team import Team
@@ -299,11 +302,51 @@ class HogFlow(Taggable, UUIDTModel):
return f"HogFlow {self.id}/{self.version}: {self.name}"
+# Every reload makes each worker drop the team's whole workflow list, so a bulk write sends a few large ones.
+RELOAD_BATCH_SIZE = 500
+_deferred_reloads: ContextVar[Optional[dict[int, set[str]]]] = ContextVar("hog_flow_deferred_reloads", default=None)
+
+
+@contextmanager
+def defer_hog_flow_reloads() -> Iterator[None]:
+ """Collect the worker reloads of the saves inside the block and send them together when it ends."""
+ if _deferred_reloads.get() is not None:
+ yield
+ return
+ pending: dict[int, set[str]] = {}
+ token = _deferred_reloads.set(pending)
+ try:
+ yield
+ finally:
+ _deferred_reloads.reset(token)
+ for team_id, hog_flow_ids in pending.items():
+ ordered = sorted(hog_flow_ids)
+ for start in range(0, len(ordered), RELOAD_BATCH_SIZE):
+ _reload_batch_on_workers(team_id, ordered[start : start + RELOAD_BATCH_SIZE])
+
+
+def _reload_batch_on_workers(team_id: int, hog_flow_ids: list[str]) -> None:
+ # The saves have already committed, so a failed publish must not fail the request that made them.
+ # Workers also expire their cached workflows on a timer, so a lost reload only delays the change.
+ for attempt in range(2):
+ try:
+ reload_hog_flows_on_workers(team_id=team_id, hog_flow_ids=hog_flow_ids)
+ return
+ except Exception as e:
+ if attempt == 1:
+ logger.exception("hog_flow_deferred_reload_failed", team_id=team_id, hog_flow_count=len(hog_flow_ids))
+ capture_exception(e)
+
+
@receiver(post_save, sender=HogFlow)
def hog_flow_saved(sender, instance: HogFlow, created, update_fields=None, **kwargs):
# Draft columns don't affect live execution, so workers don't need a config reload for them.
if update_fields and set(update_fields) <= {"draft", "draft_updated_at"}:
return
+ pending = _deferred_reloads.get()
+ if pending is not None:
+ pending.setdefault(instance.team_id, set()).add(str(instance.id))
+ return
reload_hog_flows_on_workers(team_id=instance.team_id, hog_flow_ids=[str(instance.id)])
diff --git a/products/workflows/backend/presentation/views/hog_flow.py b/products/workflows/backend/presentation/views/hog_flow.py
index aef760b3c2a6..77530fa7fa9d 100644
--- a/products/workflows/backend/presentation/views/hog_flow.py
+++ b/products/workflows/backend/presentation/views/hog_flow.py
@@ -5,7 +5,7 @@ import hashlib
import dataclasses
from collections.abc import Callable, Mapping, Sequence
from copy import deepcopy
-from datetime import timedelta
+from datetime import datetime, timedelta
from time import monotonic
from typing import Any, NamedTuple, Optional, TypeVar, cast
from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
@@ -132,7 +132,7 @@ from products.cdp.backend.presentation.serializers import (
from products.cohorts.backend.facade.api import get_cohort_ref
from products.messaging.backend.facade.categories import MessageCategoryMissing, get_category
from products.messaging.backend.presentation.views.serializers import DesignOperationSerializer
-from products.notifications.backend.facade.api import publish_resource_edited
+from products.notifications.backend.facade.api import publish_resource_edited, publish_resources_edited
from products.replay_vision.backend.facade.api import (
ObservationRequestRejected,
parse_workflow_scan_setup,
@@ -154,7 +154,10 @@ from products.workflows.backend.facade.activity import (
resume_workflow_email_sending,
)
from products.workflows.backend.facade.api import (
+ flow_ids_with_active_schedule,
+ is_utm_apply_eligible,
load_team_utm_defaults,
+ plan_flow_utm_update,
release_edited_email_utm_keys,
seed_new_email_steps_with_utm_defaults,
)
@@ -184,6 +187,8 @@ from products.workflows.backend.facade.contracts import (
EmailDesignRenderFailed,
EmailDesignRenderingNotConfigured,
StaffPausedError,
+ TeamUtmDefaults,
+ UtmDefaultsWriteResult,
Workflow,
WorkflowAccessDenied,
WorkflowActor,
@@ -327,7 +332,9 @@ from products.workflows.backend.facade.workflows import (
workflow_publish_impact,
)
from products.workflows.backend.facade.writes import (
+ apply_email_utm_defaults,
create_workflow,
+ defer_hog_flow_reloads,
destroy_workflow,
discard_draft,
edit_workflow_content,
@@ -549,6 +556,10 @@ def _reject_clock_based_wait(config: dict, team: Team) -> None:
)
+def live_secret_map(instance: WorkflowEditState, template_cache: Optional[TemplateCache] = None) -> dict[str, dict]:
+ return merge_secret_maps(plaintext_secret_map(instance.actions, template_cache), instance.encrypted_inputs)
+
+
def existing_secret_map(instance: WorkflowEditState, template_cache: Optional[TemplateCache] = None) -> dict[str, dict]:
# Every stored secret a masked re-save may need to recover, later sources winning: legacy
# plaintext (live, then draft), then the encrypted live map, then the encrypted draft map.
@@ -1128,6 +1139,47 @@ def _event_config_has_event_or_action(event_config: dict) -> bool:
return bool(filters.get("events") or filters.get("actions"))
+UTM_APPLY_BATCH_SIZE = 100
+# (workflow id, edited at) pairs for the realtime "edited" signal. An alias, because `list` is a method on the viewset.
+EditedWorkflows = list[tuple[str, str]]
+
+
+def _edited_at(updated_at: datetime, draft_updated_at: Optional[datetime]) -> str:
+ # Draft writes don't touch the live updated_at, so broadcast the newer of the two stamps;
+ # otherwise an open builder never hears about content staged from another channel.
+ if draft_updated_at and draft_updated_at > updated_at:
+ return draft_updated_at.isoformat()
+ return updated_at.isoformat()
+
+
+class ApplyUtmDefaultsRequestSerializer(serializers.Serializer):
+ dry_run = serializers.BooleanField(
+ default=True, help_text="When true, only count the emails the change would update. Nothing is saved."
+ )
+ enable_where_off = serializers.BooleanField(
+ default=False,
+ help_text="Also turn UTM tags on in emails that have them off. Off by default, so those emails keep sending untagged links.",
+ )
+
+
+class ApplyUtmDefaultsResponseSerializer(serializers.Serializer):
+ emails_updated = serializers.IntegerField(help_text="Email steps that get (or would get) the team defaults.")
+ workflows_updated = serializers.IntegerField(help_text="Workflows and broadcasts that contain those email steps.")
+ active_workflows_updated = serializers.IntegerField(
+ help_text="Of those, the ones that are live, so their next send uses the new values."
+ )
+ emails_turned_on = serializers.IntegerField(help_text="Email steps where UTM tags get (or would get) turned on.")
+ emails_off = serializers.IntegerField(
+ help_text="Email steps in scope that have UTM tags off. enable_where_off turns them on."
+ )
+ workflows_without_access = serializers.IntegerField(
+ help_text="Workflows with emails to update that you can't edit. They keep their old values."
+ )
+ workflows_failed = serializers.IntegerField(
+ help_text="Workflows that could not be saved, for example because they fail validation. They keep their old values."
+ )
+
+
class BlastRadiusRequestSerializer(serializers.Serializer):
filters = serializers.DictField(help_text="Property filters to apply")
group_type_index = serializers.IntegerField(
@@ -3514,7 +3566,12 @@ class HogFlowSerializer(HogFlowMinimalSerializer):
# maps (draft wins) so an in-progress draft edit recovers the value the client actually saw.
# Must be set before super() runs, since the nested action serializers validate inside it.
if instance is not None:
- self.context["existing_encrypted_inputs"] = existing_secret_map(instance, template_cache={})
+ # A server-side rewrite of the live actions sets live_secrets_only, so a staged credential
+ # rotation stays in the draft until someone publishes it.
+ secret_map = live_secret_map if self.context.get("live_secrets_only") else existing_secret_map
+ self.context["existing_encrypted_inputs"] = secret_map(
+ instance, template_cache=self.context.setdefault("_hogflow_template_cache", {})
+ )
# Stored sender overrides, keyed by action id, so child action validation only holds
# newly written custom sender addresses to the verified-domain rule. Draft wins over
# live for the same reason as secrets: it is the value the client last saw.
@@ -3619,7 +3676,8 @@ class HogFlowSerializer(HogFlowMinimalSerializer):
)
get_team = self.context.get("get_team")
- if isinstance(submitted_actions, list) and get_team is not None:
+ # The bulk apply writes the defaults it read once, so a newer team default must not mark them as custom edits.
+ if isinstance(submitted_actions, list) and get_team is not None and not self.context.get("utm_defaults_apply"):
# A test invocation passes the workflow through the context rather than as the instance.
stored_actions = stored.actions if stored and isinstance(stored.actions, list) else []
# A step saved only in the staged draft of an active workflow already exists too, so it is never seeded.
@@ -4975,6 +5033,7 @@ class HogFlowViewSet(
"approve_proposal",
"reject_proposal",
"bulk_update_tags",
+ "apply_utm_defaults",
]
queryset = HogFlow.objects.all()
bulk_update_tags_request_serializer_class = BulkUpdateTagsUUIDRequestSerializer
@@ -5437,16 +5496,16 @@ class HogFlowViewSet(
# Realtime "edited elsewhere" signal so an open builder (or another tab) can refresh instead of
# clobbering edits made via a different channel (UI/MCP/API). Fires for every channel; the
# frontend dedupes its own echo by comparing updated_at. Transient — no inbox notification.
- # Draft writes don't touch the live updated_at, so broadcast the newer of the two stamps;
- # otherwise an open builder never hears about content staged from another channel.
- edited_at = instance.updated_at
- if instance.draft_updated_at and instance.draft_updated_at > edited_at:
- edited_at = instance.draft_updated_at
+ self._publish_resource_edited(instance.id, instance.updated_at, instance.draft_updated_at)
+
+ def _publish_resource_edited(
+ self, workflow_id: uuid_mod.UUID, updated_at: datetime, draft_updated_at: Optional[datetime]
+ ) -> None:
publish_resource_edited(
team=self.team,
resource_type="HogFlow",
- resource_id=str(instance.id),
- updated_at=edited_at.isoformat(),
+ resource_id=str(workflow_id),
+ updated_at=_edited_at(updated_at, draft_updated_at),
actor_user_id=getattr(self.request.user, "id", None),
ac_resource_type=self.scope_object,
)
@@ -6534,6 +6593,199 @@ class HogFlowViewSet(
return Response(res.json())
+ @extend_schema(request=ApplyUtmDefaultsRequestSerializer, responses=ApplyUtmDefaultsResponseSerializer)
+ @action(methods=["POST"], detail=False)
+ def apply_utm_defaults(self, request: Request, **kwargs):
+ # Rewrites every workflow in the project, so object-level access to one workflow is not enough.
+ if not self.user_access_control.check_access_level_for_resource("hog_flow", "editor"):
+ raise exceptions.PermissionDenied("You need edit access to workflows to update their emails.")
+
+ params_serializer = ApplyUtmDefaultsRequestSerializer(data=request.data)
+ params_serializer.is_valid(raise_exception=True)
+ dry_run = params_serializer.validated_data["dry_run"]
+ enable_where_off = params_serializer.validated_data["enable_where_off"]
+
+ defaults = load_team_utm_defaults(self.team_id)
+ pending_schedule_flow_ids = flow_ids_with_active_schedule(self.team_id)
+ flow_ids = list(
+ HogFlow.objects.filter(team_id=self.team_id)
+ .exclude(status=HogFlow.State.ARCHIVED)
+ .order_by("id")
+ .values_list("id", flat=True)
+ )
+
+ result = {
+ "emails_updated": 0,
+ "workflows_updated": 0,
+ "active_workflows_updated": 0,
+ "emails_turned_on": 0,
+ "emails_off": 0,
+ "workflows_failed": 0,
+ "workflows_without_access": 0,
+ }
+ # Workflows that share an email template look it up once for the whole apply.
+ template_cache: TemplateCache = {}
+ edits: EditedWorkflows = []
+ # Workers reload once at the end instead of once per saved workflow.
+ with defer_hog_flow_reloads():
+ # Full rows hold every live and staged graph, so read them in bounded batches.
+ for start in range(0, len(flow_ids), UTM_APPLY_BATCH_SIZE):
+ batch = HogFlow.objects.filter(
+ team_id=self.team_id, id__in=flow_ids[start : start + UTM_APPLY_BATCH_SIZE]
+ )
+ for flow in batch.order_by("id"):
+ self._apply_utm_defaults_scan_flow(
+ flow,
+ defaults,
+ pending_schedule_flow_ids,
+ dry_run,
+ enable_where_off,
+ result,
+ template_cache,
+ edits,
+ )
+
+ if not dry_run:
+ self._publish_utm_defaults_edits(edits)
+ self._report_utm_defaults_applied(result, enable_where_off)
+ return Response(ApplyUtmDefaultsResponseSerializer(result).data)
+
+ def _apply_utm_defaults_scan_flow(
+ self,
+ flow: HogFlow,
+ defaults: TeamUtmDefaults,
+ pending_schedule_flow_ids: set[uuid_mod.UUID],
+ dry_run: bool,
+ enable_where_off: bool,
+ result: dict[str, int],
+ template_cache: TemplateCache,
+ edits: EditedWorkflows,
+ ) -> None:
+ if not is_utm_apply_eligible(flow, flow.id in pending_schedule_flow_ids):
+ return
+ all_on = plan_flow_utm_update(flow.actions or [], flow.draft, defaults, enable_where_off=True)
+ if all_on is None:
+ return
+ # Edit access to workflows in general can be narrowed on a single workflow.
+ if not self.user_access_control.check_access_level_for_object(flow, "editor"):
+ result["workflows_without_access"] += 1
+ return
+ result["emails_off"] += all_on.emails_turned_on
+ plan = all_on if enable_where_off else plan_flow_utm_update(flow.actions or [], flow.draft, defaults, False)
+ if plan is None:
+ return
+ status = flow.status
+ if not dry_run:
+ try:
+ applied = self._apply_utm_defaults_to_flow(flow, defaults, enable_where_off, template_cache, edits)
+ except serializers.ValidationError as e:
+ logger.warning("utm_defaults_apply_failed", hog_flow_id=str(flow.id), error=str(e.detail))
+ result["workflows_failed"] += 1
+ return
+ except Exception as e:
+ # The failed workflow rolled back, and the ones already saved stay saved, so report it and go on.
+ logger.exception("utm_defaults_apply_failed", hog_flow_id=str(flow.id))
+ capture_exception(e)
+ result["workflows_failed"] += 1
+ return
+ # Another request changed the workflow after the scan, so count what was saved under the lock.
+ if applied is None:
+ return
+ plan = applied.plan
+ status = str(applied.write.current["status"])
+ result["emails_updated"] += plan.emails_updated
+ result["emails_turned_on"] += plan.emails_turned_on
+ result["workflows_updated"] += 1
+ # A change only to the staged draft reaches live sends when someone publishes the draft.
+ if status == HogFlow.State.ACTIVE and plan.actions is not None:
+ result["active_workflows_updated"] += 1
+
+ def _apply_utm_defaults_to_flow(
+ self,
+ flow: HogFlow,
+ defaults: TeamUtmDefaults,
+ enable_where_off: bool,
+ template_cache: TemplateCache,
+ edits: EditedWorkflows,
+ ) -> Optional[UtmDefaultsWriteResult]:
+ def validate_live(state: WorkflowEditState, actions: list[dict]) -> dict:
+ serializer = self.get_serializer(
+ state,
+ data={"actions": actions},
+ partial=True,
+ context={
+ **self.get_serializer_context(),
+ "live_secrets_only": True,
+ "utm_defaults_apply": True,
+ "_hogflow_template_cache": template_cache,
+ },
+ )
+ serializer.is_valid(raise_exception=True)
+ return serializer.validated_data
+
+ result = apply_email_utm_defaults(
+ team_id=self.team_id,
+ user_id=self._actor_id(),
+ hog_flow_id=flow.id,
+ defaults=defaults,
+ enable_where_off=enable_where_off,
+ validate_live=validate_live,
+ template_cache=template_cache,
+ )
+ if result is None:
+ return None
+ # The bulk apply needs only the identity and timestamps, so it skips the full workflow read.
+ current = result.write.current
+ edits.append(
+ (
+ str(flow.id),
+ _edited_at(
+ cast(datetime, current["updated_at"]), cast(Optional[datetime], current["draft_updated_at"])
+ ),
+ )
+ )
+ try:
+ self._log_activity(
+ flow.id,
+ cast(Optional[str], current["name"]),
+ "updated",
+ previous=result.write.previous,
+ current=current,
+ )
+ except Exception as e:
+ # The write already committed, so it still counts as updated.
+ logger.exception("utm_defaults_apply_side_effect_failed", hog_flow_id=str(flow.id))
+ capture_exception(e)
+ return result
+
+ def _publish_utm_defaults_edits(self, edits: EditedWorkflows) -> None:
+ try:
+ publish_resources_edited(
+ team=self.team,
+ resource_type="HogFlow",
+ edits=edits,
+ actor_user_id=getattr(self.request.user, "id", None),
+ ac_resource_type=self.scope_object,
+ )
+ except Exception as e:
+ # The writes already committed, so a failed signal only means open builders do not refresh.
+ logger.exception("utm_defaults_apply_publish_failed")
+ capture_exception(e)
+
+ def _report_utm_defaults_applied(self, result: dict[str, int], enable_where_off: bool) -> None:
+ try:
+ report_user_action(
+ self.request.user,
+ "workflow utm defaults applied",
+ {**result, "enable_where_off": enable_where_off, "team_id": str(self.team_id)},
+ team=self.team,
+ request=self.request,
+ )
+ except Exception as e:
+ logger.warning(
+ "Failed to capture workflow usage event", event="workflow utm defaults applied", error=str(e)
+ )
+
@extend_schema(request=BlastRadiusRequestSerializer, responses=BlastRadiusSerializer)
@action(methods=["POST"], detail=False)
def user_blast_radius(self, request: Request, **kwargs):
diff --git a/products/workflows/backend/services/email_utm_defaults.py b/products/workflows/backend/services/email_utm_defaults.py
index c6e3ba72ba81..eb9ffde9847c 100644
--- a/products/workflows/backend/services/email_utm_defaults.py
+++ b/products/workflows/backend/services/email_utm_defaults.py
@@ -1,12 +1,17 @@
from collections.abc import Iterable
from typing import Any
+from uuid import UUID
-from products.workflows.backend.facade.contracts import TeamUtmDefaults
+from posthog.dataclasses import frozen
+
+from products.workflows.backend.facade.contracts import FlowUtmUpdate, TeamUtmDefaults
+from products.workflows.backend.models.hog_flow.hog_flow import HogFlow
+from products.workflows.backend.models.hog_flow_schedule import HogFlowSchedule
from products.workflows.backend.models.team_workflows_config import TeamWorkflowsConfig
UTM_KEYS = ("utm_source", "utm_medium", "utm_campaign", "utm_content")
-# Lists the utm_params keys that follow the team default, so a value someone typed into one email
-# stays apart from a copied default when the team defaults change.
+# Lists the utm_params keys that follow the team default. Bulk updates rewrite only these keys, so a
+# value someone typed into one email survives a change to the team defaults.
UTM_FROM_DEFAULT_KEY = "utm_params_from_default"
@@ -20,6 +25,32 @@ def load_team_utm_defaults(team_id: int) -> TeamUtmDefaults:
return TeamUtmDefaults(enabled=row["email_utm_tags_enabled"], params=clean_utm_params(row["email_utm_params"]))
+def flow_ids_with_active_schedule(team_id: int) -> set[UUID]:
+ # next_run_at can be empty while the scheduler recalculates it, so an active schedule is enough.
+ return set(
+ HogFlowSchedule.objects.filter(team_id=team_id, status=HogFlowSchedule.Status.ACTIVE).values_list(
+ "hog_flow_id", flat=True
+ )
+ )
+
+
+def flow_has_active_schedule(team_id: int, hog_flow_id: UUID) -> bool:
+ return HogFlowSchedule.objects.filter(
+ team_id=team_id, hog_flow_id=hog_flow_id, status=HogFlowSchedule.Status.ACTIVE
+ ).exists()
+
+
+def is_apply_eligible(flow: HogFlow, has_active_schedule: bool) -> bool:
+ if flow.status == HogFlow.State.ARCHIVED:
+ return False
+ # A broadcast that already went out keeps the links it was sent with.
+ return not (
+ flow.origin_product == HogFlow.OriginProduct.BROADCASTS
+ and flow.status != HogFlow.State.DRAFT
+ and not has_active_schedule
+ )
+
+
def clean_utm_params(params: Any) -> dict[str, str]:
if not isinstance(params, dict):
return {}
@@ -99,3 +130,74 @@ def release_edited_keys(
]
if kept != following or (UTM_FROM_DEFAULT_KEY not in config and UTM_FROM_DEFAULT_KEY in baseline):
config[UTM_FROM_DEFAULT_KEY] = kept
+
+
+def apply_defaults_to_email_config(
+ config: dict[str, Any], defaults: TeamUtmDefaults, enable_where_off: bool
+) -> dict[str, Any] | None:
+ """The email step config with the team defaults applied, or None when nothing changes."""
+ following = _keys_following_default(config.get(UTM_FROM_DEFAULT_KEY))
+
+ current = clean_utm_params(config.get("utm_params"))
+ updated = {key: value for key, value in current.items() if key not in following}
+ updated.update({key: value for key, value in defaults.params.items() if key in following})
+
+ enabled = config.get("utm_tags_enabled") is True
+ turn_on = enable_where_off and not enabled
+ if not enabled and not turn_on:
+ return None
+
+ if updated == current and not turn_on:
+ return None
+ new_config = {**config, "utm_params": updated, UTM_FROM_DEFAULT_KEY: following}
+ if turn_on:
+ new_config["utm_tags_enabled"] = True
+ return new_config
+
+
+@frozen
+class _ActionsUpdate:
+ actions: list[dict[str, Any]] | None
+ updated_ids: frozenset[str]
+ turned_on_ids: frozenset[str]
+
+
+def _apply_to_actions(actions: list[Any], defaults: TeamUtmDefaults, enable_where_off: bool) -> _ActionsUpdate:
+ updated_ids: set[str] = set()
+ turned_on_ids: set[str] = set()
+ new_actions: list[dict[str, Any]] = []
+ for action in actions:
+ if not is_email_action(action):
+ new_actions.append(action)
+ continue
+ new_config = apply_defaults_to_email_config(action["config"], defaults, enable_where_off)
+ if new_config is None:
+ new_actions.append(action)
+ continue
+ updated_ids.add(str(action.get("id")))
+ if new_config.get("utm_tags_enabled") is True and action["config"].get("utm_tags_enabled") is not True:
+ turned_on_ids.add(str(action.get("id")))
+ new_actions.append({**action, "config": new_config})
+ return _ActionsUpdate(
+ actions=new_actions if updated_ids else None,
+ updated_ids=frozenset(updated_ids),
+ turned_on_ids=frozenset(turned_on_ids),
+ )
+
+
+def plan_flow_update(
+ actions: list[Any], draft: dict[str, Any] | None, defaults: TeamUtmDefaults, enable_where_off: bool
+) -> FlowUtmUpdate | None:
+ live = _apply_to_actions(actions, defaults, enable_where_off)
+ draft_actions = draft.get("actions") if isinstance(draft, dict) else None
+ # A staged draft would undo the change on publish, so it gets the same edit.
+ staged = _apply_to_actions(draft_actions, defaults, enable_where_off) if isinstance(draft_actions, list) else None
+ if live.actions is None and (staged is None or staged.actions is None):
+ return None
+ return FlowUtmUpdate(
+ actions=live.actions,
+ draft_actions=staged.actions if staged else None,
+ # The live and staged copies of one email step count once.
+ emails_updated=len(live.updated_ids | (staged.updated_ids if staged else frozenset())),
+ emails_turned_on=len(live.turned_on_ids | (staged.turned_on_ids if staged else frozenset())),
+ )
diff --git a/products/workflows/backend/services/hog_flow_content.py b/products/workflows/backend/services/hog_flow_content.py
index 374a61bfe5f9..5463f3e2d290 100644
--- a/products/workflows/backend/services/hog_flow_content.py
+++ b/products/workflows/backend/services/hog_flow_content.py
@@ -1,7 +1,8 @@
from collections.abc import Mapping
+from typing import Optional
from products.workflows.backend.models.hog_flow.hog_flow import HogFlow
-from products.workflows.backend.services.hog_flow_secrets import strip_content_secrets
+from products.workflows.backend.services.hog_flow_secrets import TemplateCache, strip_content_secrets
# The content of a workflow: everything the draft cycle stages and publish promotes, and nothing
# else. Metadata (name, description) and lifecycle (status) always apply to the live row. The draft
@@ -33,7 +34,7 @@ def deep_merge(target: dict, patch: dict) -> dict:
return target
-def snapshot_content(values: Mapping[str, object]) -> dict:
+def snapshot_content(values: Mapping[str, object], template_cache: Optional[TemplateCache] = None) -> dict:
"""A workflow's content fields in the API shape, without secrets."""
snapshot = {field: values.get(field) for field in DRAFT_CONTENT_FIELDS}
# The model's legacy default for actions/edges is `{}`, but the API shape is a list — normalize
@@ -47,8 +48,8 @@ def snapshot_content(values: Mapping[str, object]) -> dict:
# secrets. New rows are already stripped, so this is a no-op for them. Every create takes a
# snapshot inside its transaction, so the cache resolves each template once instead of once per
# action.
- return strip_content_secrets(snapshot, template_cache={})
+ return strip_content_secrets(snapshot, template_cache=template_cache if template_cache is not None else {})
-def snapshot_flow_content(flow: HogFlow) -> dict:
- return snapshot_content({field: getattr(flow, field) for field in DRAFT_CONTENT_FIELDS})
+def snapshot_flow_content(flow: HogFlow, template_cache: Optional[TemplateCache] = None) -> dict:
+ return snapshot_content({field: getattr(flow, field) for field in DRAFT_CONTENT_FIELDS}, template_cache)
diff --git a/products/workflows/backend/services/hog_flow_writes.py b/products/workflows/backend/services/hog_flow_writes.py
index 782f63e410a0..59f9edffecbb 100644
--- a/products/workflows/backend/services/hog_flow_writes.py
+++ b/products/workflows/backend/services/hog_flow_writes.py
@@ -11,6 +11,8 @@ from posthog.api.tagged_item import cleanup_orphan_tags, current_tag_names, set_
from posthog.models.tag import tagify
from products.workflows.backend.facade.contracts import (
+ TeamUtmDefaults,
+ UtmDefaultsWriteResult,
WorkflowEditState,
WorkflowHasNoDraft,
WorkflowStale,
@@ -26,10 +28,16 @@ from products.workflows.backend.models.hog_flow.hog_flow import (
)
from products.workflows.backend.models.hog_flow_revision import HogFlowRevision
from products.workflows.backend.services.action_redirects import compute_action_redirects
+from products.workflows.backend.services.email_utm_defaults import (
+ flow_has_active_schedule,
+ is_apply_eligible,
+ plan_flow_update,
+)
from products.workflows.backend.services.hog_flow_content import DRAFT_CONTENT_FIELDS, snapshot_flow_content
from products.workflows.backend.services.hog_flow_reads import to_edit_state
from products.workflows.backend.services.hog_flow_secrets import (
TemplateCache,
+ rehydrate_flow_secrets,
strip_content_secrets,
strip_secrets_from_content,
)
@@ -112,13 +120,17 @@ def _parse_stamp(raw: Optional[str]) -> Optional[datetime]:
return stamp
-def _save_live(instance: HogFlow, validated_data: dict, **overrides: object) -> None:
+def _save_live(
+ instance: HogFlow, validated_data: dict, template_cache: Optional[TemplateCache] = None, **overrides: object
+) -> None:
# Move secret function inputs out of the live `actions` into
# encrypted_inputs when the write carries actions (a metadata-only update must not touch stored
# secrets), then save the whole row.
data = {**validated_data, **overrides}
if "actions" in data:
- data["encrypted_inputs"] = strip_secrets_from_content(data, template_cache={})
+ data["encrypted_inputs"] = strip_secrets_from_content(
+ data, template_cache=template_cache if template_cache is not None else {}
+ )
for attr, value in data.items():
setattr(instance, attr, value)
instance.save()
@@ -208,7 +220,9 @@ def _refresh_action_redirects(target: HogFlow, old: HogFlow, new_actions: Option
)
-def _stage_revision_bump(instance: HogFlow, before: HogFlow, validated_data: dict) -> bool:
+def _stage_revision_bump(
+ instance: HogFlow, before: HogFlow, validated_data: dict, template_cache: Optional[TemplateCache] = None
+) -> bool:
# Revision history: only live-content changes get a version. Compared pre-save so the bumped
# version lands in the same UPDATE (and worker reload) as the content it describes. The
# serializer injects derived fields (trigger, billable_action_types) into every validated
@@ -221,7 +235,8 @@ def _stage_revision_bump(instance: HogFlow, before: HogFlow, validated_data: dic
# Compare secret-free on both sides. `raw_new` still carries the plaintext secrets validation
# recovered into `actions` (stripping happens later in the save), while `before` is the persisted
# stripped snapshot; without this a secret-bearing flow would bump on every actions-carrying save.
- template_cache: TemplateCache = {}
+ if template_cache is None:
+ template_cache = {}
old_content = _without_bytecode_contracts(strip_content_secrets(raw_old, template_cache))
new_content = _without_bytecode_contracts(strip_content_secrets(raw_new, template_cache))
if new_content == old_content:
@@ -230,7 +245,13 @@ def _stage_revision_bump(instance: HogFlow, before: HogFlow, validated_data: dic
return True
-def _append_revisions(team_id: int, user_id: Optional[int], instance: HogFlow, before: HogFlow) -> None:
+def _append_revisions(
+ team_id: int,
+ user_id: Optional[int],
+ instance: HogFlow,
+ before: HogFlow,
+ template_cache: Optional[TemplateCache] = None,
+) -> None:
# Must run inside the same transaction as the content write it snapshots. On the first
# tracked write, also snapshot the outgoing live content so the state before any tracked
# change is always available to roll back to (there's no backfill).
@@ -239,14 +260,14 @@ def _append_revisions(team_id: int, user_id: Optional[int], instance: HogFlow, b
team_id=team_id,
hog_flow=instance,
version=before.version,
- content=snapshot_flow_content(before),
+ content=snapshot_flow_content(before, template_cache),
created_by=None,
)
HogFlowRevision.objects.create(
team_id=team_id,
hog_flow=instance,
version=instance.version,
- content=snapshot_flow_content(instance),
+ content=snapshot_flow_content(instance, template_cache),
created_by_id=user_id,
)
@@ -497,6 +518,46 @@ def edit_workflow_content(
)
+def apply_email_utm_defaults(
+ *,
+ team_id: int,
+ user_id: Optional[int],
+ hog_flow_id: UUID,
+ defaults: TeamUtmDefaults,
+ enable_where_off: bool,
+ validate_live: Callable[[WorkflowEditState, list[dict]], dict],
+ template_cache: TemplateCache,
+) -> Optional[UtmDefaultsWriteResult]:
+ """Rewrite the UTM keys that still follow the team defaults, in the live steps and the staged draft.
+ Returns None when nothing changes or the workflow is gone, archived or already sent. Pass one
+ `template_cache` across a batch, so workflows that share a template look it up once."""
+ with transaction.atomic():
+ locked = HogFlow.objects.select_for_update().filter(pk=hog_flow_id, team_id=team_id).first()
+ if locked is None or not is_apply_eligible(locked, flow_has_active_schedule(team_id, hog_flow_id)):
+ return None
+ plan = plan_flow_update(locked.actions or [], locked.draft, defaults, enable_where_off)
+ if plan is None:
+ return None
+ before_update = HogFlow.objects.get(pk=hog_flow_id, team_id=team_id)
+ if plan.draft_actions is not None:
+ locked.draft = {**(locked.draft or {}), "actions": plan.draft_actions}
+ locked.draft_updated_at = timezone.now()
+ locked.save(update_fields=["draft", "draft_updated_at"])
+ unstage_workflow_proposals(team_id=team_id, hog_flow_id=locked.pk)
+ if plan.actions is not None:
+ # Stored actions carry no secrets, and a lenient validation would save them without any.
+ actions = rehydrate_flow_secrets(plan.actions, locked.encrypted_inputs or {})
+ validated_data = validate_live(to_edit_state(locked), actions)
+ bump = _stage_revision_bump(locked, before_update, validated_data, template_cache)
+ _save_live(locked, validated_data, template_cache)
+ if bump:
+ _append_revisions(team_id, user_id, locked, before_update, template_cache)
+
+ return UtmDefaultsWriteResult(
+ write=WorkflowWriteResult(previous=field_values(before_update), current=field_values(locked)), plan=plan
+ )
+
+
def publish_draft(
*,
team_id: int,
diff --git a/products/workflows/backend/test/test_email_utm_defaults.py b/products/workflows/backend/test/test_email_utm_defaults.py
index 8d9df752675a..2c8acd3e5cab 100644
--- a/products/workflows/backend/test/test_email_utm_defaults.py
+++ b/products/workflows/backend/test/test_email_utm_defaults.py
@@ -8,6 +8,8 @@ from products.workflows.backend.facade.contracts import TeamUtmDefaults
from products.workflows.backend.services.email_utm_defaults import (
UTM_FROM_DEFAULT_KEY,
UTM_KEYS,
+ apply_defaults_to_email_config,
+ plan_flow_update,
release_edited_keys,
seed_new_email_actions,
)
@@ -22,6 +24,75 @@ def _email(action_id: str, **config: Any) -> dict[str, Any]:
class TestEmailUtmDefaults(SimpleTestCase):
+ @parameterized.expand(
+ [
+ (
+ "a step from before team defaults follows every default",
+ {"utm_tags_enabled": True, "utm_params": {"utm_source": "old"}},
+ False,
+ {"utm_source": "newsletter", "utm_campaign": "{{ person.properties.plan }}"},
+ True,
+ ),
+ (
+ "a value typed into the email survives",
+ {
+ "utm_tags_enabled": True,
+ "utm_params": {"utm_source": "partner"},
+ UTM_FROM_DEFAULT_KEY: ["utm_medium", "utm_campaign", "utm_content"],
+ },
+ False,
+ {"utm_source": "partner", "utm_campaign": "{{ person.properties.plan }}"},
+ True,
+ ),
+ (
+ "tags turn on when asked",
+ {},
+ True,
+ {"utm_source": "newsletter", "utm_campaign": "{{ person.properties.plan }}"},
+ True,
+ ),
+ ]
+ )
+ def test_apply_defaults_to_email_config(
+ self, _name: str, config: dict[str, Any], enable_where_off: bool, expected_params: dict, expected_on: bool
+ ) -> None:
+ updated = apply_defaults_to_email_config(config, DEFAULTS, enable_where_off)
+
+ assert updated is not None
+ assert updated["utm_params"] == expected_params
+ assert (updated.get("utm_tags_enabled") is True) == expected_on
+
+ @parameterized.expand(
+ [
+ (
+ "params already match the defaults",
+ {
+ "utm_tags_enabled": True,
+ "utm_params": {"utm_source": "newsletter", "utm_campaign": "{{ person.properties.plan }}"},
+ UTM_FROM_DEFAULT_KEY: list(UTM_KEYS),
+ },
+ True,
+ ),
+ ("tags are off and not being turned on", {"utm_tags_enabled": False}, False),
+ ]
+ )
+ def test_apply_defaults_to_email_config_returns_none_when_nothing_changes(
+ self, _name: str, config: dict[str, Any], enable_where_off: bool
+ ) -> None:
+ assert apply_defaults_to_email_config(config, DEFAULTS, enable_where_off) is None
+
+ def test_plan_flow_update_counts_each_email_once_across_live_and_staged(self) -> None:
+ custom = {"utm_tags_enabled": True, "utm_params": {"utm_source": "partner"}, UTM_FROM_DEFAULT_KEY: []}
+ follows = {"utm_tags_enabled": False, UTM_FROM_DEFAULT_KEY: list(UTM_KEYS)}
+ live = [_email("a", **follows), _email("b", **custom)]
+ staged = [_email("a", **custom), _email("b", **follows)]
+
+ plan = plan_flow_update(live, {"actions": staged}, DEFAULTS, enable_where_off=True)
+
+ assert plan is not None
+ assert plan.emails_updated == 2
+ assert plan.emails_turned_on == 2
+
def test_seed_new_email_actions_only_fills_new_steps_without_a_choice(self) -> None:
actions = [
_email("existing"),
diff --git a/products/workflows/backend/tests/api/test_hog_flow_utm_defaults.py b/products/workflows/backend/tests/api/test_hog_flow_utm_defaults.py
index d37f3b5e506a..1b8a39c1cb45 100644
--- a/products/workflows/backend/tests/api/test_hog_flow_utm_defaults.py
+++ b/products/workflows/backend/tests/api/test_hog_flow_utm_defaults.py
@@ -5,10 +5,25 @@ from unittest.mock import MagicMock, patch
from parameterized import parameterized
+from posthog.constants import AvailableFeature
+from posthog.models import OrganizationMembership
+from posthog.models.personal_api_key import PersonalAPIKey
+from posthog.models.utils import generate_random_token_personal, hash_key_value
+
+from products.access_control.backend.models.access_control import AccessControl
from products.cdp.backend.templates.hog_function_template import sync_template_to_db
+from products.workflows.backend.facade.contracts import TeamUtmDefaults
+from products.workflows.backend.facade.writes import apply_email_utm_defaults
from products.workflows.backend.models.hog_flow.hog_flow import HogFlow
+from products.workflows.backend.models.hog_flow_schedule import HogFlowSchedule
from products.workflows.backend.models.team_workflows_config import TeamWorkflowsConfig
-from products.workflows.backend.tests.api.test_hog_flow import _email_function_template, _valid_email_inputs
+from products.workflows.backend.models.workflow_proposal import WorkflowProposal
+from products.workflows.backend.tests.api.test_hog_flow import (
+ _SECRET_TEMPLATE_ID,
+ _email_function_template,
+ _secret_input_template,
+ _valid_email_inputs,
+)
TRIGGER = {
"id": "trigger_node",
@@ -36,6 +51,15 @@ class TestHogFlowUtmDefaults(APIBaseTest):
defaults={"email_utm_tags_enabled": True, "email_utm_params": {"utm_source": "newsletter"}},
)
+ def _flow(self, name: str, status: str, origin_product: str | None = None, **email_config: Any) -> HogFlow:
+ return HogFlow.objects.create(
+ team=self.team,
+ name=name,
+ status=status,
+ origin_product=origin_product,
+ actions=[TRIGGER, _email_action(**email_config)],
+ )
+
def _email_config(self, flow: HogFlow) -> dict[str, Any]:
flow.refresh_from_db()
return next(a for a in flow.actions if a["type"] == "function_email")["config"]
@@ -124,3 +148,304 @@ class TestHogFlowUtmDefaults(APIBaseTest):
email_config = next(a for a in saved if a["type"] == "function_email")["config"]
assert "utm_tags_enabled" not in email_config
assert "utm_params" not in email_config
+
+ @parameterized.expand([("tags on", True), ("tags off", False)])
+ def test_a_utm_value_supplied_with_an_explicit_choice_survives_a_later_apply(self, _name: str, on: bool) -> None:
+ created = self.client.post(
+ f"/api/projects/{self.team.id}/hog_flows",
+ {
+ "name": "New flow",
+ "actions": [TRIGGER, _email_action(utm_tags_enabled=on, utm_params={"utm_source": "partner"})],
+ },
+ format="json",
+ )
+ assert created.status_code == 201, created.json()
+ flow = HogFlow.objects.get(pk=created.json()["id"])
+
+ applied = self.client.post(
+ f"/api/projects/{self.team.id}/hog_flows/apply_utm_defaults",
+ {"dry_run": False, "enable_where_off": False},
+ format="json",
+ )
+
+ assert applied.status_code == 200, applied.json()
+ config = self._email_config(flow)
+ assert config["utm_tags_enabled"] is on
+ assert config["utm_params"] == {"utm_source": "partner"}
+
+ def test_apply_utm_defaults_previews_then_updates_only_emails_that_follow_the_defaults(self) -> None:
+ legacy_draft = self._flow("Legacy draft", HogFlow.State.DRAFT)
+ custom_live = self._flow(
+ "Custom live",
+ HogFlow.State.ACTIVE,
+ utm_tags_enabled=True,
+ utm_params={"utm_source": "partner"},
+ utm_params_from_default=["utm_medium", "utm_campaign", "utm_content"],
+ )
+ sent_broadcast = self._flow("Sent broadcast", HogFlow.State.ACTIVE, origin_product="broadcasts")
+ scheduled_broadcast = self._flow("Scheduled broadcast", HogFlow.State.ACTIVE, origin_product="broadcasts")
+ HogFlowSchedule.objects.create(
+ team=self.team,
+ hog_flow=scheduled_broadcast,
+ rrule="FREQ=DAILY;COUNT=1",
+ starts_at="2030-01-01T00:00:00Z",
+ next_run_at=None,
+ )
+ archived = self._flow("Archived", HogFlow.State.ARCHIVED)
+ legacy_version = legacy_draft.version
+
+ preview = self.client.post(
+ f"/api/projects/{self.team.id}/hog_flows/apply_utm_defaults", {"dry_run": True}, format="json"
+ )
+
+ assert preview.status_code == 200, preview.json()
+ assert preview.json() == {
+ "emails_updated": 0,
+ "workflows_updated": 0,
+ "active_workflows_updated": 0,
+ "emails_turned_on": 0,
+ "emails_off": 2,
+ "workflows_failed": 0,
+ "workflows_without_access": 0,
+ }
+ assert "utm_params" not in self._email_config(legacy_draft)
+
+ applied = self.client.post(
+ f"/api/projects/{self.team.id}/hog_flows/apply_utm_defaults",
+ {"dry_run": False, "enable_where_off": True},
+ format="json",
+ )
+
+ assert applied.status_code == 200, applied.json()
+ assert applied.json()["emails_turned_on"] == 2
+ legacy_config = self._email_config(legacy_draft)
+ assert legacy_config["utm_tags_enabled"] is True
+ assert legacy_config["utm_params"] == {"utm_source": "newsletter"}
+ assert HogFlow.objects.get(pk=legacy_draft.pk).version == legacy_version + 1
+ assert self._email_config(custom_live)["utm_params"] == {"utm_source": "partner"}
+ assert "utm_params" not in self._email_config(sent_broadcast)
+ assert self._email_config(scheduled_broadcast)["utm_params"] == {"utm_source": "newsletter"}
+ assert "utm_params" not in self._email_config(archived)
+
+ def test_a_utm_value_changed_through_the_api_survives_a_later_apply(self) -> None:
+ flow = self._flow(
+ "Seeded",
+ HogFlow.State.DRAFT,
+ utm_tags_enabled=True,
+ utm_params={"utm_source": "newsletter"},
+ utm_params_from_default=["utm_source", "utm_medium", "utm_campaign", "utm_content"],
+ )
+ edited_email = _email_action(
+ utm_tags_enabled=True,
+ utm_params={"utm_source": "partner"},
+ utm_params_from_default=["utm_source", "utm_medium", "utm_campaign", "utm_content"],
+ )
+ edited = self.client.patch(
+ f"/api/projects/{self.team.id}/hog_flows/{flow.id}", {"actions": [TRIGGER, edited_email]}, format="json"
+ )
+ assert edited.status_code == 200, edited.json()
+ TeamWorkflowsConfig.objects.filter(team=self.team).update(
+ email_utm_params={"utm_source": "newsletter", "utm_medium": "mail"}
+ )
+
+ applied = self.client.post(
+ f"/api/projects/{self.team.id}/hog_flows/apply_utm_defaults", {"dry_run": False}, format="json"
+ )
+
+ assert applied.status_code == 200, applied.json()
+ assert self._email_config(flow)["utm_params"] == {"utm_source": "partner", "utm_medium": "mail"}
+
+ def test_apply_utm_defaults_skips_workflows_the_user_cannot_edit(self) -> None:
+ self.organization.available_product_features = [
+ {"key": AvailableFeature.ADVANCED_PERMISSIONS, "name": AvailableFeature.ADVANCED_PERMISSIONS},
+ {"key": AvailableFeature.ACCESS_CONTROL, "name": AvailableFeature.ACCESS_CONTROL},
+ ]
+ self.organization.save()
+ self.organization_membership.level = OrganizationMembership.Level.MEMBER
+ self.organization_membership.save()
+ editable = self._flow("Editable", HogFlow.State.DRAFT, utm_tags_enabled=True)
+ restricted = self._flow("Restricted", HogFlow.State.DRAFT, utm_tags_enabled=True)
+ AccessControl.objects.create(
+ team=self.team, resource="hog_flow", resource_id=str(restricted.id), access_level="viewer"
+ )
+
+ response = self.client.post(
+ f"/api/projects/{self.team.id}/hog_flows/apply_utm_defaults", {"dry_run": False}, format="json"
+ )
+
+ assert response.status_code == 200, response.json()
+ assert response.json()["workflows_updated"] == 1
+ assert response.json()["workflows_without_access"] == 1
+ assert self._email_config(editable)["utm_params"] == {"utm_source": "newsletter"}
+ assert "utm_params" not in self._email_config(restricted)
+
+ def test_apply_utm_defaults_to_a_staged_draft_counts_it_as_not_live_and_requeues_its_proposal(self) -> None:
+ following: dict[str, Any] = {
+ "utm_tags_enabled": True,
+ "utm_params_from_default": ["utm_source", "utm_medium", "utm_campaign", "utm_content"],
+ }
+ flow = self._flow(
+ "Active with draft", HogFlow.State.ACTIVE, utm_params={"utm_source": "newsletter"}, **following
+ )
+ proposal = WorkflowProposal.objects.for_team(self.team.id).create(
+ team=self.team,
+ hog_flow=flow,
+ title="Tag the source",
+ rationale="Attribute clicks",
+ content={"actions": [{"id": "email_1", "config": {"utm_params": {"utm_source": "proposal"}}}]},
+ step_id="email_1",
+ base_version=flow.version,
+ status=WorkflowProposal.Status.APPROVED,
+ )
+ flow.draft = {"actions": [TRIGGER, _email_action(utm_params={"utm_source": "proposal"}, **following)]}
+ flow.save(update_fields=["draft"])
+ url = f"/api/projects/{self.team.id}/hog_flows/apply_utm_defaults"
+
+ preview = self.client.post(url, {"dry_run": True}, format="json")
+
+ assert preview.status_code == 200, preview.json()
+ assert preview.json()["workflows_updated"] == 1
+ assert preview.json()["active_workflows_updated"] == 0
+
+ applied = self.client.post(url, {"dry_run": False}, format="json")
+
+ assert applied.status_code == 200, applied.json()
+ flow.refresh_from_db()
+ assert flow.draft["actions"][1]["config"]["utm_params"] == {"utm_source": "newsletter"}
+ stored = WorkflowProposal.objects.for_team(self.team.id).get(id=proposal.id)
+ assert stored.status == WorkflowProposal.Status.SUGGESTED
+
+ def test_apply_utm_defaults_keeps_the_secrets_of_a_draft_whose_other_inputs_are_incomplete(self) -> None:
+ sync_template_to_db(_secret_input_template())
+ webhook = {
+ "id": "webhook_1",
+ "name": "Notify",
+ "type": "function",
+ "config": {"template_id": _SECRET_TEMPLATE_ID, "inputs": {}},
+ }
+ flow = HogFlow.objects.create(
+ team=self.team,
+ name="Half-built draft",
+ status=HogFlow.State.DRAFT,
+ actions=[TRIGGER, _email_action(), webhook],
+ encrypted_inputs={"webhook_1": {"api_key": {"value": "live-secret"}}},
+ )
+
+ applied = self.client.post(
+ f"/api/projects/{self.team.id}/hog_flows/apply_utm_defaults",
+ {"dry_run": False, "enable_where_off": True},
+ format="json",
+ )
+
+ assert applied.status_code == 200, applied.json()
+ assert applied.json()["workflows_updated"] == 1
+ flow.refresh_from_db()
+ assert self._email_config(flow)["utm_params"] == {"utm_source": "newsletter"}
+ assert flow.encrypted_inputs["webhook_1"]["api_key"]["value"] == "live-secret"
+
+ def test_apply_utm_defaults_keeps_live_and_staged_secrets_apart(self) -> None:
+ sync_template_to_db(_secret_input_template())
+ webhook = {
+ "id": "webhook_1",
+ "name": "Notify",
+ "type": "function",
+ "config": {"template_id": _SECRET_TEMPLATE_ID, "inputs": {"url": {"value": "https://example.com"}}},
+ }
+ flow = HogFlow.objects.create(
+ team=self.team,
+ name="Active with staged rotation",
+ status=HogFlow.State.ACTIVE,
+ actions=[TRIGGER, _email_action(), webhook],
+ encrypted_inputs={"webhook_1": {"api_key": {"value": "live-secret"}}},
+ draft={"actions": [TRIGGER, _email_action(), webhook]},
+ draft_encrypted_inputs={"webhook_1": {"api_key": {"value": "staged-secret"}}},
+ )
+
+ applied = self.client.post(
+ f"/api/projects/{self.team.id}/hog_flows/apply_utm_defaults",
+ {"dry_run": False, "enable_where_off": True},
+ format="json",
+ )
+
+ assert applied.status_code == 200, applied.json()
+ assert applied.json()["active_workflows_updated"] == 1
+ flow.refresh_from_db()
+ assert self._email_config(flow)["utm_params"] == {"utm_source": "newsletter"}
+ assert flow.encrypted_inputs["webhook_1"]["api_key"]["value"] == "live-secret"
+ assert flow.draft_encrypted_inputs["webhook_1"]["api_key"]["value"] == "staged-secret"
+
+ @parameterized.expand([("write scope", ["hog_flow:write"], 200), ("read scope", ["hog_flow:read"], 403)])
+ def test_apply_utm_defaults_with_a_personal_api_key(self, _name: str, scopes: list[str], expected: int) -> None:
+ key = generate_random_token_personal()
+ PersonalAPIKey.objects.create(label="utm", user=self.user, secure_value=hash_key_value(key), scopes=scopes)
+
+ response = self.client.post(
+ f"/api/projects/{self.team.id}/hog_flows/apply_utm_defaults",
+ {"dry_run": True},
+ format="json",
+ headers={"authorization": f"Bearer {key}"},
+ )
+
+ assert response.status_code == expected, response.json()
+
+ @parameterized.expand(
+ [
+ ("archived", HogFlow.State.ARCHIVED, None),
+ ("sent broadcast", HogFlow.State.ACTIVE, HogFlow.OriginProduct.BROADCASTS),
+ ("deleted", None, None),
+ ]
+ )
+ def test_apply_skips_a_workflow_that_left_scope_after_the_scan(
+ self, _name: str, status: str | None, origin_product: str | None
+ ) -> None:
+ flow = self._flow("Changed mid-batch", HogFlow.State.ACTIVE)
+ if status is None:
+ flow.delete()
+ else:
+ HogFlow.objects.filter(pk=flow.pk).update(status=status, origin_product=origin_product)
+
+ result = apply_email_utm_defaults(
+ team_id=self.team.id,
+ user_id=self.user.id,
+ hog_flow_id=flow.id,
+ defaults=TeamUtmDefaults(enabled=True, params={"utm_source": "newsletter"}),
+ enable_where_off=True,
+ validate_live=lambda _state, actions: {"actions": actions},
+ template_cache={},
+ )
+
+ assert result is None
+ if status is not None:
+ assert "utm_params" not in self._email_config(flow)
+
+ @parameterized.expand(
+ [
+ ("the reload succeeds", None, 1),
+ ("the reload fails once", [ConnectionError("redis down"), None], 2),
+ ("the reload keeps failing", ConnectionError("redis down"), 2),
+ ]
+ )
+ def test_apply_utm_defaults_reloads_workers_and_signals_editors_once_for_the_whole_apply(
+ self, _name: str, reload_side_effect: Any, expected_reload_calls: int
+ ) -> None:
+ flows = [self._flow(f"Flow {i}", HogFlow.State.ACTIVE, utm_tags_enabled=True) for i in range(3)]
+
+ with (
+ patch(
+ "products.workflows.backend.models.hog_flow.hog_flow.reload_hog_flows_on_workers",
+ side_effect=reload_side_effect,
+ ) as mock_reload,
+ patch("products.workflows.backend.presentation.views.hog_flow.publish_resources_edited") as mock_publish,
+ ):
+ applied = self.client.post(
+ f"/api/projects/{self.team.id}/hog_flows/apply_utm_defaults", {"dry_run": False}, format="json"
+ )
+
+ assert applied.status_code == 200, applied.json()
+ assert applied.json()["workflows_updated"] == 3
+ assert mock_reload.call_count == expected_reload_calls
+ mock_reload.assert_called_with(team_id=self.team.id, hog_flow_ids=sorted(str(flow.id) for flow in flows))
+ mock_publish.assert_called_once()
+ assert sorted(edit[0] for edit in mock_publish.call_args.kwargs["edits"]) == sorted(
+ str(flow.id) for flow in flows
+ )
diff --git a/products/workflows/frontend/generated/api.schemas.ts b/products/workflows/frontend/generated/api.schemas.ts
index 702386b55027..8497f8a8dcf9 100644
--- a/products/workflows/frontend/generated/api.schemas.ts
+++ b/products/workflows/frontend/generated/api.schemas.ts
@@ -1845,6 +1845,30 @@ export interface PatchedHogFlowScheduleApi {
readonly updated_at?: string
}
+export interface ApplyUtmDefaultsRequestApi {
+ /** When true, only count the emails the change would update. Nothing is saved. */
+ dry_run?: boolean
+ /** Also turn UTM tags on in emails that have them off. Off by default, so those emails keep sending untagged links. */
+ enable_where_off?: boolean
+}
+
+export interface ApplyUtmDefaultsResponseApi {
+ /** Email steps that get (or would get) the team defaults. */
+ emails_updated: number
+ /** Workflows and broadcasts that contain those email steps. */
+ workflows_updated: number
+ /** Of those, the ones that are live, so their next send uses the new values. */
+ active_workflows_updated: number
+ /** Email steps where UTM tags get (or would get) turned on. */
+ emails_turned_on: number
+ /** Email steps in scope that have UTM tags off. enable_where_off turns them on. */
+ emails_off: number
+ /** Workflows with emails to update that you can't edit. They keep their old values. */
+ workflows_without_access: number
+ /** Workflows that could not be saved, for example because they fail validation. They keep their old values. */
+ workflows_failed: number
+}
+
export interface BroadcastConversionCandidateApi {
/** Workflow id. */
readonly id: string
diff --git a/products/workflows/frontend/generated/api.ts b/products/workflows/frontend/generated/api.ts
index f73ac6665355..09a57a9494c6 100644
--- a/products/workflows/frontend/generated/api.ts
+++ b/products/workflows/frontend/generated/api.ts
@@ -11,6 +11,8 @@ import { apiMutator } from '../../../../frontend/src/lib/api-orval-mutator'
import type {
AppMetricsResponseApi,
AppMetricsTotalsResponseApi,
+ ApplyUtmDefaultsRequestApi,
+ ApplyUtmDefaultsResponseApi,
BlastRadiusApi,
BlastRadiusRequestApi,
BroadcastConversionCandidatesApi,
@@ -1249,6 +1251,23 @@ export const hogFlowsSchedulesDestroy = async (
})
}
+export const getHogFlowsApplyUtmDefaultsCreateUrl = (projectId: string) => {
+ return `/api/projects/${projectId}/hog_flows/apply_utm_defaults/`
+}
+
+export const hogFlowsApplyUtmDefaultsCreate = async (
+ projectId: string,
+ applyUtmDefaultsRequestApi?: ApplyUtmDefaultsRequestApi,
+ options?: RequestInit
+): Promise<ApplyUtmDefaultsResponseApi> => {
+ return apiMutator<ApplyUtmDefaultsResponseApi>(getHogFlowsApplyUtmDefaultsCreateUrl(projectId), {
+ ...options,
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json', ...options?.headers },
+ body: JSON.stringify(applyUtmDefaultsRequestApi),
+ })
+}
+
export const getHogFlowsBroadcastConversionCandidatesRetrieveUrl = (projectId: string) => {
return `/api/projects/${projectId}/hog_flows/broadcast_conversion_candidates/`
}
diff --git a/products/workflows/frontend/generated/api.zod.ts b/products/workflows/frontend/generated/api.zod.ts
index e4f6b52352d7..5242ef11b070 100644
--- a/products/workflows/frontend/generated/api.zod.ts
+++ b/products/workflows/frontend/generated/api.zod.ts
@@ -2842,6 +2842,22 @@ export const HogFlowsSchedulesPartialUpdateBody = /* @__PURE__ */ zod.object({
.describe('Variable value overrides merged with the workflow defaults on each run.'),
})
+export const hogFlowsApplyUtmDefaultsCreateBodyDryRunDefault = true
+export const hogFlowsApplyUtmDefaultsCreateBodyEnableWhereOffDefault = false
+
+export const HogFlowsApplyUtmDefaultsCreateBody = /* @__PURE__ */ zod.object({
+ dry_run: zod
+ .boolean()
+ .default(hogFlowsApplyUtmDefaultsCreateBodyDryRunDefault)
+ .describe('When true, only count the emails the change would update. Nothing is saved.'),
+ enable_where_off: zod
+ .boolean()
+ .default(hogFlowsApplyUtmDefaultsCreateBodyEnableWhereOffDefault)
+ .describe(
+ 'Also turn UTM tags on in emails that have them off. Off by default, so those emails keep sending untagged links.'
+ ),
+})
+
export const hogFlowsBulkDeleteCreateBodyNameMax = 400
export const hogFlowsBulkDeleteCreateBodyDescriptionDefault = ``
diff --git a/products/workflows/frontend/scenes/settings/WorkflowsUtmDefaultsApplyDialog.tsx b/products/workflows/frontend/scenes/settings/WorkflowsUtmDefaultsApplyDialog.tsx
new file mode 100644
index 000000000000..390a4232ab14
--- /dev/null
+++ b/products/workflows/frontend/scenes/settings/WorkflowsUtmDefaultsApplyDialog.tsx
@@ -0,0 +1,80 @@
+import { useActions, useValues } from 'kea'
+
+import { LemonButton, LemonCheckbox, LemonModal, Spinner } from '@posthog/lemon-ui'
+
+import { pluralize } from 'lib/utils/strings'
+
+import { workflowsUtmDefaultsApplyLogic } from './workflowsUtmDefaultsApplyLogic'
+
+export function WorkflowsUtmDefaultsApplyDialog(): JSX.Element {
+ const { isApplyDialogOpen, enableWhereOff, preview, previewLoading, isPreviewCurrent, applyResultLoading } =
+ useValues(workflowsUtmDefaultsApplyLogic)
+ const { closeApplyDialog, setEnableWhereOff, applyDefaults } = useActions(workflowsUtmDefaultsApplyLogic)
+
+ const nothingToUpdate = !!preview && preview.emails_updated === 0
+
+ return (
+ <LemonModal
+ isOpen={isApplyDialogOpen}
+ onClose={closeApplyDialog}
+ title="Update existing emails?"
+ description="Existing broadcasts and workflow emails keep their current values until you apply the new defaults. Values typed into a single email stay as they are, and sent broadcasts never change."
+ footer={
+ <>
+ <LemonButton type="secondary" onClick={closeApplyDialog} data-attr="workflows-utm-defaults-skip">
+ Not now
+ </LemonButton>
+ <LemonButton
+ type="primary"
+ onClick={applyDefaults}
+ loading={applyResultLoading}
+ disabledReason={
+ previewLoading || !preview || !isPreviewCurrent
+ ? 'Counting the emails to update'
+ : nothingToUpdate
+ ? 'No emails to update'
+ : undefined
+ }
+ data-attr="workflows-utm-defaults-apply"
+ >
+ {preview && isPreviewCurrent && !nothingToUpdate
+ ? `Update ${pluralize(preview.emails_updated, 'email')}`
+ : 'Update emails'}
+ </LemonButton>
+ </>
+ }
+ >
+ {previewLoading ? (
+ <Spinner />
+ ) : !preview || !isPreviewCurrent ? (
+ <p className="m-0">Couldn't count the emails to update. Close this and try again.</p>
+ ) : (
+ <div className="flex flex-col gap-3">
+ <p className="m-0">
+ {nothingToUpdate
+ ? preview.emails_off > 0
+ ? 'The emails left to update have UTM tags off.'
+ : 'Every email already uses these values.'
+ : `${pluralize(preview.emails_updated, 'email')} in ${pluralize(preview.workflows_updated, 'broadcast or workflow', 'broadcasts and workflows')} will use the new values.`}
+ {preview.active_workflows_updated > 0 &&
+ ` ${preview.active_workflows_updated} of them ${preview.active_workflows_updated === 1 ? 'is' : 'are'} live, so the next send uses the new values.`}
+ </p>
+ {preview.workflows_without_access > 0 && (
+ <p className="m-0 text-secondary">
+ {preview.workflows_without_access} more workflows have emails to update, but you don't have
+ edit access to them. They keep their current values.
+ </p>
+ )}
+ {preview.emails_off > 0 && (
+ <LemonCheckbox
+ checked={enableWhereOff}
+ onChange={setEnableWhereOff}
+ label={`Also turn on UTM tags in ${pluralize(preview.emails_off, 'email')} where they're off`}
+ data-attr="workflows-utm-defaults-enable-where-off"
+ />
+ )}
+ </div>
+ )}
+ </LemonModal>
+ )
+}
diff --git a/products/workflows/frontend/scenes/settings/WorkflowsUtmDefaultsSettings.tsx b/products/workflows/frontend/scenes/settings/WorkflowsUtmDefaultsSettings.tsx
index 16ffb06aed41..9e5326ab54d2 100644
--- a/products/workflows/frontend/scenes/settings/WorkflowsUtmDefaultsSettings.tsx
+++ b/products/workflows/frontend/scenes/settings/WorkflowsUtmDefaultsSettings.tsx
@@ -5,12 +5,15 @@ import { LemonButton, LemonSwitch } from '@posthog/lemon-ui'
import { teamLogic } from 'scenes/teamLogic'
import { UtmTagFields } from '../../Workflows/hogflows/steps/components/UtmTagFields'
+import { WorkflowsUtmDefaultsApplyDialog } from './WorkflowsUtmDefaultsApplyDialog'
+import { workflowsUtmDefaultsApplyLogic } from './workflowsUtmDefaultsApplyLogic'
import { workflowsUtmDefaultsSettingsLogic } from './workflowsUtmDefaultsSettingsLogic'
export function WorkflowsUtmDefaultsSettings(): JSX.Element {
const { currentTeam, currentTeamLoading } = useValues(teamLogic)
const { form, hasUnsavedChanges } = useValues(workflowsUtmDefaultsSettingsLogic)
const { setDraftEnabled, setDraftParams, saveDefaults } = useActions(workflowsUtmDefaultsSettingsLogic)
+ const { openApplyDialog } = useActions(workflowsUtmDefaultsApplyLogic)
return (
<div className="flex flex-col gap-2 max-w-160">
@@ -45,7 +48,17 @@ export function WorkflowsUtmDefaultsSettings(): JSX.Element {
>
Save
</LemonButton>
+ <LemonButton
+ type="secondary"
+ size="small"
+ disabledReason={hasUnsavedChanges ? 'Save your changes first' : undefined}
+ onClick={openApplyDialog}
+ data-attr="workflows-utm-defaults-apply-existing"
+ >
+ Apply to existing emails
+ </LemonButton>
</div>
+ <WorkflowsUtmDefaultsApplyDialog />
</div>
)
}
diff --git a/products/workflows/frontend/scenes/settings/workflowsUtmDefaultsApplyLogic.ts b/products/workflows/frontend/scenes/settings/workflowsUtmDefaultsApplyLogic.ts
new file mode 100644
index 000000000000..74ade19ef53d
--- /dev/null
+++ b/products/workflows/frontend/scenes/settings/workflowsUtmDefaultsApplyLogic.ts
@@ -0,0 +1,156 @@
+import { MakeLogicType, actions, connect, kea, listeners, path, reducers } from 'kea'
+import { loaders } from 'kea-loaders'
+
+import { lemonToast } from '@posthog/lemon-ui'
+
+import { pluralize } from 'lib/utils/strings'
+import { projectLogic } from 'scenes/projectLogic'
+
+import { hogFlowsApplyUtmDefaultsCreate } from '../../generated/api'
+import type { ApplyUtmDefaultsResponseApi } from '../../generated/api.schemas'
+
+// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
+export interface workflowsUtmDefaultsApplyLogicValues {
+ currentProjectId: number | null // projectLogic
+ applyResult: ApplyUtmDefaultsResponseApi | null
+ applyResultLoading: boolean
+ enableWhereOff: boolean
+ isApplyDialogOpen: boolean
+ isPreviewCurrent: boolean
+ preview: ApplyUtmDefaultsResponseApi | null
+ previewLoading: boolean
+}
+
+// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
+export interface workflowsUtmDefaultsApplyLogicActions {
+ applyDefaults: () => any
+ applyDefaultsFailure: (
+ error: string,
+ errorObject?: any
+ ) => {
+ error: string
+ errorObject?: any
+ }
+ applyDefaultsSuccess: (
+ applyResult: ApplyUtmDefaultsResponseApi,
+ payload?: any
+ ) => {
+ applyResult: ApplyUtmDefaultsResponseApi
+ payload?: any
+ }
+ closeApplyDialog: () => {
+ value: true
+ }
+ loadPreview: (_: void) => void
+ loadPreviewFailure: (
+ error: string,
+ errorObject?: any
+ ) => {
+ error: string
+ errorObject?: any
+ }
+ loadPreviewSuccess: (
+ preview: ApplyUtmDefaultsResponseApi,
+ payload?: void
+ ) => {
+ preview: ApplyUtmDefaultsResponseApi
+ payload?: void
+ }
+ openApplyDialog: () => {
+ value: true
+ }
+ setEnableWhereOff: (enableWhereOff: boolean) => {
+ enableWhereOff: boolean
+ }
+}
+
+export type workflowsUtmDefaultsApplyLogicType = MakeLogicType<
+ workflowsUtmDefaultsApplyLogicValues,
+ workflowsUtmDefaultsApplyLogicActions
+>
+
+export const workflowsUtmDefaultsApplyLogic = kea<workflowsUtmDefaultsApplyLogicType>([
+ path(['products', 'workflows', 'frontend', 'scenes', 'settings', 'workflowsUtmDefaultsApplyLogic']),
+ connect(() => ({
+ values: [projectLogic, ['currentProjectId']],
+ })),
+ actions({
+ openApplyDialog: true,
+ closeApplyDialog: true,
+ setEnableWhereOff: (enableWhereOff: boolean) => ({ enableWhereOff }),
+ }),
+ reducers({
+ isApplyDialogOpen: [
+ false,
+ {
+ openApplyDialog: () => true,
+ closeApplyDialog: () => false,
+ },
+ ],
+ enableWhereOff: [
+ false,
+ {
+ setEnableWhereOff: (_, { enableWhereOff }) => enableWhereOff,
+ openApplyDialog: () => false,
+ },
+ ],
+ // The loader keeps its last result when a reload fails, so a count only counts while it is current.
+ isPreviewCurrent: [
+ false,
+ {
+ loadPreview: () => false,
+ loadPreviewSuccess: () => true,
+ },
+ ],
+ }),
+ loaders(({ values }) => ({
+ preview: [
+ null as ApplyUtmDefaultsResponseApi | null,
+ {
+ loadPreview: async (_: void, breakpoint) => {
+ const preview = await hogFlowsApplyUtmDefaultsCreate(String(values.currentProjectId), {
+ dry_run: true,
+ enable_where_off: values.enableWhereOff,
+ })
+ // A reopened dialog or a toggled box starts a newer preview, so this count is stale.
+ breakpoint()
+ return preview
+ },
+ },
+ ],
+ applyResult: [
+ null as ApplyUtmDefaultsResponseApi | null,
+ {
+ applyDefaults: async () => {
+ return await hogFlowsApplyUtmDefaultsCreate(String(values.currentProjectId), {
+ dry_run: false,
+ enable_where_off: values.enableWhereOff,
+ })
+ },
+ },
+ ],
+ })),
+ listeners(({ actions }) => ({
+ openApplyDialog: () => actions.loadPreview(),
+ setEnableWhereOff: () => actions.loadPreview(),
+ applyDefaultsSuccess: ({ applyResult }) => {
+ actions.closeApplyDialog()
+ const skipped = (applyResult?.workflows_failed ?? 0) + (applyResult?.workflows_without_access ?? 0)
+ if (skipped > 0) {
+ lemonToast.warning(
+ `Updated ${pluralize(applyResult?.emails_updated ?? 0, 'email')}. ${pluralize(skipped, 'workflow')} kept their old values.`
+ )
+ } else {
+ lemonToast.success(
+ `Updated ${pluralize(applyResult?.emails_updated ?? 0, 'email')} with the new defaults`
+ )
+ }
+ },
+ applyDefaultsFailure: () => {
+ lemonToast.error("Couldn't update existing emails. Try again.")
+ },
+ loadPreviewFailure: () => {
+ lemonToast.error("Couldn't count the emails to update. Try again.")
+ },
+ })),
+])
diff --git a/products/workflows/frontend/scenes/settings/workflowsUtmDefaultsSettingsLogic.ts b/products/workflows/frontend/scenes/settings/workflowsUtmDefaultsSettingsLogic.ts
index 2d6fd440ec60..d92eb65138f4 100644
--- a/products/workflows/frontend/scenes/settings/workflowsUtmDefaultsSettingsLogic.ts
+++ b/products/workflows/frontend/scenes/settings/workflowsUtmDefaultsSettingsLogic.ts
@@ -11,6 +11,7 @@ import {
} from '../../Workflows/hogflows/steps/components/utmDefaults'
import type { UtmTagValues } from '../../Workflows/hogflows/steps/components/UtmTagFields'
import type { UtmTagKey } from '../../Workflows/hogflows/steps/components/UtmTagFields'
+import { workflowsUtmDefaultsApplyLogic } from './workflowsUtmDefaultsApplyLogic'
// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
export interface workflowsUtmDefaultsSettingsLogicValues {
@@ -23,6 +24,9 @@ export interface workflowsUtmDefaultsSettingsLogicValues {
// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
export interface workflowsUtmDefaultsSettingsLogicActions {
+ openApplyDialog: () => {
+ value: true
+ } // workflowsUtmDefaultsApplyLogic
resetDraft: () => {
value: true
}
@@ -57,6 +61,7 @@ export const workflowsUtmDefaultsSettingsLogic = kea<workflowsUtmDefaultsSetting
path(['products', 'workflows', 'frontend', 'scenes', 'settings', 'workflowsUtmDefaultsSettingsLogic']),
connect(() => ({
values: [teamLogic, ['currentTeam']],
+ actions: [workflowsUtmDefaultsApplyLogic, ['openApplyDialog']],
})),
actions({
setDraftEnabled: (enabled: boolean) => ({ enabled }),
@@ -97,6 +102,8 @@ export const workflowsUtmDefaultsSettingsLogic = kea<workflowsUtmDefaultsSetting
listeners(({ actions, values }) => ({
saveDefaults: async () => {
const form = values.form
+ const before = values.savedDefaults
+ const offerApply = !matchesTeamUtmDefaults(form.params, before) || (form.enabled && !before.enabled)
const params = cleanUtmParams(form.params)
if (!values.currentTeam?.workflows_config) {
return
@@ -117,6 +124,9 @@ export const workflowsUtmDefaultsSettingsLogic = kea<workflowsUtmDefaultsSetting
if (values.form.enabled === form.enabled && matchesTeamUtmDefaults(values.form.params, saved)) {
actions.resetDraft()
}
+ if (offerApply) {
+ actions.openApplyDialog()
+ }
},
})),
])
diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.ts
index 337ad4a0a45e..637cf2d06aae 100644
--- a/services/mcp/src/api/generated.ts
+++ b/services/mcp/src/api/generated.ts
@@ -13868,6 +13868,30 @@ export namespace Schemas {
marketing_analytics_config: unknown;
}
+ export interface ApplyUtmDefaultsRequest {
+ /** When true, only count the emails the change would update. Nothing is saved. */
+ dry_run?: boolean;
+ /** Also turn UTM tags on in emails that have them off. Off by default, so those emails keep sending untagged links. */
+ enable_where_off?: boolean;
+ }
+
+ export interface ApplyUtmDefaultsResponse {
+ /** Email steps that get (or would get) the team defaults. */
+ emails_updated: number;
+ /** Workflows and broadcasts that contain those email steps. */
+ workflows_updated: number;
+ /** Of those, the ones that are live, so their next send uses the new values. */
+ active_workflows_updated: number;
+ /** Email steps where UTM tags get (or would get) turned on. */
+ emails_turned_on: number;
+ /** Email steps in scope that have UTM tags off. enable_where_off turns them on. */
+ emails_off: number;
+ /** Workflows with emails to update that you can't edit. They keep their old values. */
+ workflows_without_access: number;
+ /** Workflows that could not be saved, for example because they fail validation. They keep their old values. */
+ workflows_failed: number;
+ }
+
export interface ApprovalPolicy {
readonly id: string;
/** @maxLength 128 */
@@ -89012,7 +89036,7 @@ export namespace Schemas {
* * `opt_out` - Opt Out
* * `opt_in` - Opt In */
email_tracking_consent_mode?: EmailTrackingConsentModeEnum;
- /** Whether new email steps and broadcasts start with UTM tags on their links. Each email can still change it. Existing emails keep their current values. */
+ /** Whether new email steps and broadcasts start with UTM tags on their links. Each email can still change it. Existing emails change only through apply_utm_defaults. */
email_utm_tags_enabled?: boolean;
/** Default UTM values that new email steps and broadcasts copy. An empty value keeps the built-in default for that tag. */
email_utm_params?: EmailUtmParams;
diff --git a/services/mcp/src/generated/core/api.ts b/services/mcp/src/generated/core/api.ts
index 00477155a719..beb82bec1635 100644
--- a/services/mcp/src/generated/core/api.ts
+++ b/services/mcp/src/generated/core/api.ts
@@ -2834,7 +2834,7 @@ export const OrganizationsProjectsCreateBody = () => zod
.boolean()
.optional()
.describe(
- 'Whether new email steps and broadcasts start with UTM tags on their links. Each email can still change it. Existing emails keep their current values.'
+ 'Whether new email steps and broadcasts start with UTM tags on their links. Each email can still change it. Existing emails change only through apply_utm_defaults.'
),
email_utm_params: zod
.object({
@@ -5723,7 +5723,7 @@ export const OrganizationsProjectsPartialUpdateBody = () => zod
.boolean()
.optional()
.describe(
- 'Whether new email steps and broadcasts start with UTM tags on their links. Each email can still change it. Existing emails keep their current values.'
+ 'Whether new email steps and broadcasts start with UTM tags on their links. Each email can still change it. Existing emails change only through apply_utm_defaults.'
),
email_utm_params: zod
.object({
diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/project-settings-update.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/project-settings-update.json
index bbeb336d8445..f27c46288b23 100644
--- a/services/mcp/tests/unit/__snapshots__/tool-schemas/project-settings-update.json
+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/project-settings-update.json
@@ -4437,7 +4437,7 @@
"type": "object"
},
"email_utm_tags_enabled": {
- "description": "Whether new email steps and broadcasts start with UTM tags on their links. Each email can still change it. Existing emails keep their current values.",
+ "description": "Whether new email steps and broadcasts start with UTM tags on their links. Each email can still change it. Existing emails change only through apply_utm_defaults.",
"type": "boolean"
},
"marketing_frequency_cap_max_messages": {