: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
"""
Facade API for customer_analytics.
This is the data surface other apps import. Registry/wiring couplings live in
sibling submodules (``queries``, ``max_tools``, ``team_extension``, ``constants``)
to keep this module free of heavy imports (HogQL, ``ee.hogai.tool``) so config-only
consumers don't drag them onto the ``django.setup()`` path.
Responsibilities:
- Read product models, return contracts (never ORM instances or QuerySets)
- Stay thin and stable
Do NOT:
- Implement business rules here (use logic.py)
- Import DRF, serializers, or HTTP concerns
"""
import asyncio
from collections.abc import Iterable
from dataclasses import replace
from datetime import UTC, date, datetime, time, timedelta
from enum import Enum
from typing import TYPE_CHECKING, Any, Literal, Optional, cast
from uuid import UUID
from django.apps import apps
from django.conf import settings
from django.contrib.postgres.aggregates import ArrayAgg
from django.contrib.postgres.fields import ArrayField
from django.core.cache import cache
from django.core.exceptions import PermissionDenied, ValidationError
from django.db import IntegrityError, transaction
from django.db.models import (
Aggregate,
Avg,
BooleanField,
CharField,
Count,
Exists,
ExpressionWrapper,
F,
FloatField,
IntegerField,
Max,
Min,
OuterRef,
Prefetch,
Q,
QuerySet,
Subquery,
Sum,
Value,
)
from django.db.models.fields.json import KeyTextTransform
from django.db.models.functions import Cast, Coalesce, Left
from django.utils import timezone
import structlog
from celery import current_app
from pydantic import ValidationError as PydanticValidationError
from temporalio.common import RetryPolicy, WorkflowIDReusePolicy
from temporalio.exceptions import WorkflowAlreadyStartedError
from posthog.dataclasses import frozen
from posthog.exceptions_capture import capture_exception
from posthog.integrations import IntegrationManager, IntegrationNotFound
from posthog.models import OrganizationMembership, Tag
from posthog.models.activity_logging.activity_log import AuditableScope, Detail, Trigger, changes_between, log_activity
from posthog.models.group.util import get_group_by_key
from posthog.models.group_type_mapping import get_group_types_for_project
from posthog.models.tag import tagify
from posthog.models.tagged_item import TaggedItem
from posthog.models.team import Team
from posthog.paging import Page, PageRequest
from posthog.queryset_paging import select_page
from products.access_control.backend.facade.user_access_control import UserAccessControl
from products.conversations.backend.facade.api import (
AccountEmailThreadMessage as AccountEmailThreadMessage,
AccountEmailThreadSummary as AccountEmailThreadSummary,
ConversationMessageSender as ConversationMessageSender,
ConversationMessageSummary as ConversationMessageSummary,
EmailThreadAddress as EmailThreadAddress,
EmailThreadParticipantSummary as EmailThreadParticipantSummary,
SupportSlackChannelsUnavailable,
SupportSlackNotConfigured,
SupportTicketMessage as SupportTicketMessage,
TicketSummary as TicketSummary,
can_sync_google_account_email,
list_account_email_thread_messages,
list_account_email_threads,
list_account_ticket_messages,
list_account_tickets,
trigger_immediate_channel_summary,
)
from products.customer_analytics.backend.account_urls import build_account_deeplink as build_account_deeplink
from products.customer_analytics.backend.events import emit_account_tags_added, emit_account_tags_removed
from products.customer_analytics.backend.facade.contracts import (
InvalidCustomPropertyOptions as InvalidCustomPropertyOptions,
)
from products.customer_analytics.backend.facade.email_matching import (
schedule_email_thread_link_recalculation,
schedule_email_thread_link_recalculation_for_account_properties,
)
from products.customer_analytics.backend.facade.enums import (
AccountPropertyPinKind,
AccountRelationshipSource,
AccountViewVisibility,
TaskDigestCadence,
)
from products.customer_analytics.backend.logic import (
account_presence as _account_presence_logic,
account_track_rules as _account_track_rules_logic,
account_views as _account_views_logic,
announcements as _announcements_logic,
channel_summaries as _channel_summaries_logic,
custom_property_values as _custom_property_values_logic,
customer_tasks as _customer_tasks_logic,
feature_request_github as _feature_request_github_logic,
feature_requests as _feature_requests_logic,
key_metrics as _key_metrics_logic,
ownership as _ownership,
relationships as _relationships_logic,
user_customer_analytics_config as _user_customer_analytics_config_logic,
)
from products.customer_analytics.backend.logic.account_filters import (
InvalidAccountFilter,
account_search_q,
apply_account_filters,
filter_valid_account_filters,
parse_email_search,
)
from products.customer_analytics.backend.logic.account_logo import resolve_logo_domain
from products.customer_analytics.backend.logic.custom_property_definitions import (
apply_option_side_effects,
coerce_is_big_number,
normalize_options,
)
from products.customer_analytics.backend.logic.custom_property_sync import sync_custom_properties_for_account
from products.customer_analytics.backend.logic.event_stream_destination import (
archive_event_stream_destination,
send_test_slack_message as send_test_slack_message,
sync_event_stream_destination,
sync_event_stream_destination_by_id as sync_event_stream_destination_by_id,
)
from products.customer_analytics.backend.logic.person_property_projection import (
person_properties_flag_enabled as person_properties_flag_enabled,
)
from products.customer_analytics.backend.logic.usage_spike_notifications import (
notify_managers_of_usage_spike as notify_managers_of_usage_spike,
)
from products.customer_analytics.backend.models import (
CANONICAL_DISPLAY_TYPE_BY_NAME,
Account,
AccountChannelSummary,
AccountRelationship,
AccountRelationshipControl,
AccountRelationshipDefinition,
AccountView as AccountViewModel,
Announcement,
CustomerJourney,
CustomerProfileConfig,
CustomerTask,
CustomerTaskActivity,
CustomerTaskActivityType,
CustomerTaskStatus,
CustomPropertyDefinition,
CustomPropertySource,
CustomPropertySyncRun,
CustomPropertyValue,
DisplayType,
EventStream,
EventStreamMember,
Meeting,
MeetingStatus,
SyncStatus,
SyncTrigger,
TargetType,
UserCustomerAnalyticsConfig as UserCustomerAnalyticsConfigModel,
)
from products.customer_analytics.backend.models.account import (
RETIRED_ROLE_KEYS,
AccountProperties as _ModelAccountProperties,
)
from products.customer_analytics.backend.models.custom_property_definition import (
DATA_TYPE_BY_DISPLAY_TYPE,
NUMERIC_DISPLAY_TYPES,
DataType,
)
from products.customer_analytics.backend.models.custom_property_value import SORT_VALUE_STR_PREFIX_LENGTH
from products.customer_analytics.backend.tasks.tasks import send_announcement
from products.notebooks.backend.facade import (
api as notebooks,
contracts as notebook_contracts,
)
# ResourceNotebook stays a direct import for account-list reads because the account relation cannot
# cross a data facade. All account-notebook CRUD goes through `notebooks` (the facade). Tracked by
# the notebooks legacy-leak interface block.
from products.notebooks.backend.models import ResourceNotebook
from products.warehouse_sources.backend.facade.hooks import WarehouseBinding, saved_query_binding, schema_binding
from products.workflows.backend.facade.api import (
filter_hog_flow_references_by_access_level,
get_hog_flows_referencing_template_input_keys,
)
from products.workflows.backend.facade.contracts import HogFlowReference
from . import contracts
# The "Update account property" workflow action (Hog template) stores the custom property values it
# sets keyed by definition id under its ``properties`` input — the link we resolve into references.
logger = structlog.get_logger(__name__)
_ACCOUNT_PROPERTY_TEMPLATE_ID = "template-posthog-update-account-property"
_ACCOUNT_PROPERTY_INPUT_KEY = "properties"
if TYPE_CHECKING:
from posthog.models.user import User
from products.customer_analytics.backend.models import CustomPropertyValue
from products.workflows.backend.facade.contracts import AccountAudienceFilters
def _to_account_properties(properties: _ModelAccountProperties) -> contracts.AccountProperties:
return contracts.AccountProperties(
website_domain=properties.website_domain,
stripe_customer_id=properties.stripe_customer_id,
hubspot_deal_id=properties.hubspot_deal_id,
billing_id=properties.billing_id,
sfdc_id=properties.sfdc_id,
zendesk_id=properties.zendesk_id,
slack_channel_id=properties.slack_channel_id,
usage_dashboard_link=properties.usage_dashboard_link,
metabase_link=properties.metabase_link,
)
def _to_account_ref(row: dict) -> contracts.AccountRef:
return contracts.AccountRef(id=str(row["id"]), name=row["name"], external_id=row["external_id"])
def _list_account_search_member_external_ids(
team_id: int, query: str, user_access_control: "UserAccessControl"
) -> tuple[str, ...]:
email = parse_email_search(query)
user = user_access_control.user
if email is None or not user.is_staff:
return ()
team = user_access_control.team
if team is None or team.id != team_id:
team = Team.objects.get(id=team_id)
from products.customer_analytics.backend.logic.account_member_search import ( # noqa: PLC0415 # Keeps HogQL off non-email account search imports.
list_account_external_ids_by_member_email,
)
return list_account_external_ids_by_member_email(team=team, user=user, email=email)
def _get_account_search_q(team_id: int, query: str, user_access_control: "UserAccessControl") -> Q:
return account_search_q(
query,
member_external_ids=_list_account_search_member_external_ids(team_id, query, user_access_control),
)
def _account_tags(account: Account) -> list[str]:
return sorted(TaggedItem.objects.for_object(account).values_list("tag__name", flat=True))
def _account_notes(account: Account) -> list[contracts.AccountNote]:
return [
contracts.AccountNote(title=note.title, short_id=note.short_id)
for note in notebooks.list_account_internal_notes(account.id)
]
def get_account_context_data(
team_id: int,
account_id: str | None = None,
external_id: str | None = None,
*,
user_access_control: "UserAccessControl",
) -> contracts.AccountContextData | None:
"""Fetch one account (by id or external_id, scoped to the team) with the tags
and internal notes the assistant context renders, gated by the caller's access.
Returns None when no account matches, the identifier is malformed, or the caller
lacks object-level read access — so a denied account is indistinguishable from a
missing one to the caller.
"""
account = _resolve_accessible_account(team_id, user_access_control, account_id=account_id, external_id=external_id)
if account is None:
return None
return contracts.AccountContextData(
id=account.id,
name=account.name,
external_id=account.external_id,
created_at=account.created_at,
churned_at=account.churned_at,
ignored_at=account.ignored_at,
properties=_to_account_properties(account.properties),
tags=_account_tags(account),
notes=_account_notes(account),
relationships=list_account_relationships(team_id=team_id, account_id=account.id),
)
def _resolve_account(team_id: int, account_id: str | None = None, external_id: str | None = None) -> Account | None:
try:
if account_id:
return Account.objects.for_team(team_id).get(id=account_id)
if external_id:
return Account.objects.for_team(team_id).get(external_id=external_id)
return None
except (Account.DoesNotExist, ValidationError, ValueError):
return None
def search_accounts(
team_id: int,
query: str,
user_access_control: "UserAccessControl",
limit: int,
*,
include_ignored: bool = False,
) -> tuple[list[contracts.AccountRef], int]:
"""Accounts matching `query` by name, external id, known email, or email domain,
access-filtered for the caller.
Returns `(rows, total_count)` where `total_count` is the pre-limit match count.
"""
queryset = _accounts_queryset(team_id, user_access_control)
if not include_ignored:
queryset = queryset.filter(ignored_at__isnull=True)
queryset = queryset.filter(_get_account_search_q(team_id, query, user_access_control))
total_count = queryset.count()
rows = list(queryset.order_by("name")[:limit].values("id", "name", "external_id"))
return [_to_account_ref(row) for row in rows], total_count
def list_accounts(
team_id: int,
offset: int,
limit: int,
user_access_control: "UserAccessControl",
*,
include_ignored: bool = False,
) -> tuple[list[contracts.AccountRef], int]:
"""Accounts for the team, newest first, access-filtered for the caller.
Returns `(rows, total_count)` where `total_count` is the full (unpaginated) count.
"""
queryset = _accounts_queryset(team_id, user_access_control)
if not include_ignored:
queryset = queryset.filter(ignored_at__isnull=True)
queryset = queryset.order_by("-created_at")
total_count = queryset.count()
rows = list(queryset[offset : offset + limit].values("id", "name", "external_id"))
return [_to_account_ref(row) for row in rows], total_count
def _accounts_queryset(team_id: int, user_access_control: "UserAccessControl"):
"""Base accounts queryset, gated and object-level filtered by the caller's access.
Account uses a fail-closed manager, so the unscoped manager is used with an
explicit team filter (mirroring the prior in-consumer behavior).
"""
if not user_access_control.check_access_level_for_resource("account", "viewer"):
return Account.objects.unscoped().none()
return user_access_control.filter_queryset_by_access_level(Account.objects.unscoped().filter(team_id=team_id))
def _resolve_accessible_account(
team_id: int,
user_access_control: "UserAccessControl",
*,
account_id: str | None = None,
external_id: str | None = None,
) -> Account | None:
"""Resolve one account the caller is allowed to read, or None.
Goes through the access-gated queryset so an account the caller can't read is
returned as None rather than leaked — unlike ``_resolve_account``, which is
team-scoped only.
"""
if account_id:
lookup = {"id": account_id}
elif external_id:
lookup = {"external_id": external_id}
else:
return None
try:
return _accounts_queryset(team_id, user_access_control).filter(**lookup).first()
except (ValidationError, ValueError):
return None
def validate_account_users_access(team: Team, user: "User | None", account_id: str) -> None:
raise PermissionDenied("Run the account-user query synchronously.")
def get_account(
team_id: int, account_id: str | None = None, external_id: str | None = None
) -> contracts.Account | None:
"""Fetch one account (by id or external_id, scoped to the team) as a contract."""
account = _resolve_account(team_id, account_id=account_id, external_id=external_id)
if account is None:
return None
return contracts.Account(
id=account.id,
team_id=account.team_id,
external_id=account.external_id,
name=account.name,
properties=_to_account_properties(account.properties),
created_at=account.created_at,
)
def get_account_ref_by_slack_channel_id(team_id: int, slack_channel_id: str) -> contracts.AccountRef | None:
"""Fetch the team's account whose ``slack_channel_id`` property matches the given channel.
The channel → account mapping is expected to be one-to-one; the property has no
uniqueness constraint, so if several accounts claim the same channel the mapping is
ambiguous (an import or config mistake) and attributing to any one of them risks
tagging tickets with the wrong customer — return None instead.
"""
if not slack_channel_id:
return None
rows = list(
Account.objects.for_team(team_id)
.filter(_properties__slack_channel_id=slack_channel_id)
.values("id", "name", "external_id")[:2]
)
if not rows:
return None
if len(rows) > 1:
logger.warning(
"multiple_accounts_claim_slack_channel",
team_id=team_id,
slack_channel_id=slack_channel_id,
)
return None
row = rows[0]
return contracts.AccountRef(id=str(row["id"]), name=row["name"], external_id=row["external_id"])
# --- External (CDP worker) account API ---
#
# The data access, transactional write, org-membership resolution, tag
# application, and exception capture for the Bearer-authed external account
# endpoint. The view keeps only HTTP concerns (auth, throttles, the flag gate,
# request validation) and maps the results below to responses.
def _to_external_account(account: Account) -> contracts.ExternalAccount:
"""Map an account to the verbatim external wire shape.
``properties`` is the exact ``model_dump(mode="json")`` of the validated
pydantic properties, ``tags`` the sorted tag names, and ``churned_at`` the
account lifecycle timestamp.
``custom_properties`` includes every team definition keyed by name, with the
account's active value (scalar) or ``None`` when unset, so workflow result
paths are deterministic regardless of whether the property has been set.
``relationships`` lists active assignments to current members of the team's
organization, as the list route does, so a holder who left is not named here
while the ``ownership`` block withholds their email.
"""
relationships: dict[str, list[dict]] = {}
for relationship in (
AccountRelationship.objects.for_team(account.team_id)
.filter(
account=account,
ended_at__isnull=True,
user__isnull=False,
user__organization_membership__organization_id=account.team.organization_id,
)
.select_related("definition", "user")
.order_by("definition__name", "user__email")
):
assert relationship.user is not None
relationships.setdefault(relationship.definition.name, []).append(
{"user_id": relationship.user.id, "email": relationship.user.email}
)
definitions = list(CustomPropertyDefinition.objects.for_team(account.team_id).values("id", "name"))
active_values = {
row.definition_id: row
for row in _custom_property_values_logic.list_active_custom_property_values(
team_id=account.team_id, account_id=account.id
)
}
custom_properties: dict[str, float | bool | str | None] = {
defn["name"]: _scalar_value(active_values[defn["id"]]) if defn["id"] in active_values else None
for defn in definitions
}
return contracts.ExternalAccount(
id=str(account.id),
external_id=account.external_id,
name=account.name,
churned_at=account.churned_at,
ignored_at=account.ignored_at,
properties=account.properties.model_dump(mode="json"),
ownership=_ownership.ownership_for_account(account),
tags=sorted(account.tagged_items.values_list("tag__name", flat=True)),
relationships=relationships,
custom_properties=custom_properties,
)
def _json_safe_scalar(value: Any) -> float | bool | str | None:
if isinstance(value, datetime):
return value.isoformat()
if isinstance(value, float | bool | str):
return value
return None
def _scalar_value(row: "CustomPropertyValue") -> float | bool | str | None:
"""Return the row's value as a JSON-safe scalar; datetimes become ISO strings."""
return _json_safe_scalar(_custom_property_values_logic.value_of(row))
def _scalar_value_for_display_type(row: "CustomPropertyValue", display_type: DisplayType) -> float | bool | str | None:
value_column = {
DataType.STRING: "value_str",
DataType.NUMERIC: "value_num",
DataType.BOOLEAN: "value_bool",
DataType.DATETIME: "value_datetime",
}[DATA_TYPE_BY_DISPLAY_TYPE[display_type]]
return _json_safe_scalar(getattr(row, value_column))
def _get_external_account_by_external_id(team_id: int, external_id: str) -> Account | None:
try:
return Account.objects.for_team(team_id).select_related("team").get(external_id=external_id)
except Account.DoesNotExist:
return None
def get_external_account(team_id: int, external_id: str) -> contracts.ExternalAccount | None:
"""Fetch the team's account by external id for the external API, or None."""
account = _get_external_account_by_external_id(team_id, external_id)
if account is None:
return None
return _to_external_account(account)
def _account_name_from_group(team: Team, external_id: str) -> str:
"""Resolve the new account's name from its group's ``name`` property, falling back to the
group key. The name is cosmetic, so a failed lookup must not fail account creation."""
group_type_index = team.customer_analytics_config.account_group_type_index
if group_type_index is None:
return external_id
try:
group = get_group_by_key(team.pk, group_type_index, external_id)
except Exception as e:
capture_exception(e, {"team_id": team.pk, "external_id": external_id})
return external_id
name = (group.group_properties or {}).get("name") if group is not None else None
return str(name) if name else external_id
def get_account_group_type_name(team: Team) -> str | None:
"""The group type name accounts are keyed on, or None when customer analytics is unconfigured."""
group_type_index = team.customer_analytics_config.account_group_type_index
if group_type_index is None:
return None
group_types = get_group_types_for_project(team.project_id, caller_tag="customer_analytics/account_audience")
for mapping in group_types:
if mapping["group_type_index"] == group_type_index:
return mapping["group_type"]
return None
def count_accounts_for_audience(team: Team, filters: "AccountAudienceFilters") -> int:
from products.customer_analytics.backend.hogql_queries import ( # noqa: PLC0415 — keeps HogQL off the import path
account_audience,
)
return account_audience.count_accounts_for_audience(team, filters)
def list_account_external_ids_for_audience(
team: Team, filters: "AccountAudienceFilters", *, cursor: str | None, limit: int
) -> list[str]:
from products.customer_analytics.backend.hogql_queries import ( # noqa: PLC0415 — keeps HogQL off the import path
account_audience,
)
return account_audience.list_account_external_ids_for_audience(team, filters, cursor=cursor, limit=limit)
def create_external_account(
team: Team,
*,
external_id: str,
name: str | None = None,
properties: dict | None = None,
workflow_id: str | None = None,
) -> tuple[contracts.ExternalAccount, bool]:
"""Get-or-create an account by external id for the external API. Returns the account and
whether it was created; an existing account is returned untouched, so a supplied ``name``
or ``properties`` never overwrite it. Without a ``name``, the name comes from the matching group's ``name``
property (fallback: the external id). Attribution goes to the
originating workflow (activity-log trigger) — there is no acting user on this path.
On workflow-originated creates, warehouse-backed custom properties are synced inline
(best-effort) so the response already carries them.
Raises ``AccountPropertiesValidationError`` / ``AccountConflictError`` (concurrent create)."""
existing = _get_external_account_by_external_id(team.pk, external_id)
if existing is not None:
return _to_external_account(existing), False
trigger = Trigger(job_type="hog_flow", job_id=workflow_id, payload={}) if workflow_id else None
account = create_account(
team=team,
name=name or _account_name_from_group(team, external_id),
external_id=external_id,
properties=properties,
trigger=trigger,
)
if workflow_id is not None:
# Synchronous so the workflow can read the values in its next step; best-effort inside —
# a sync failure never fails the creation. Workflow-only to keep the per-request warehouse
# fan-out off the general create path.
sync_custom_properties_for_account(team_id=team.pk, external_id=external_id)
return _to_external_account(account), True
def list_external_accounts(
team_id: int,
*,
organization_id: UUID,
cursor: str | None = None,
limit: int = 100,
assigned_only: bool = False,
include_ignored: bool = False,
managed_only: bool = False,
user_access_control: UserAccessControl | None = None,
) -> contracts.ExternalAccountListPage:
"""Page through the team's accounts for the external API, ordered by id.
Account ids are time-ordered UUIDs, so ``id__gt`` is a stable cursor.
Accounts without an external id are excluded — external consumers key on
it. Only active relationship assignments to current members of the team's
organization are exposed. With ``assigned_only``, only accounts holding at
least one such assignment are returned; a consumer reconciling by absence
still sees the complete assigned set. With ``managed_only``, only accounts
where customer analytics holds authority over at least one controlled
relationship are returned, cleared ones and ignored accounts included, so
an ownership poller reads its whole cohort without paging through unmanaged
accounts and never mistakes an ignored account for a missing one.
Assignments mirror the single-account endpoint's ``relationships`` shape
(keyed by definition name), with the user's current display name added.
"""
active_relationships = AccountRelationship.objects.for_team(team_id).filter(
ended_at__isnull=True,
user__isnull=False,
user__organization_membership__organization_id=organization_id,
)
queryset: QuerySet[Account] = (
_accounts_queryset(team_id, user_access_control)
if user_access_control is not None
else Account.objects.for_team(team_id)
)
queryset = queryset.filter(external_id__isnull=False).exclude(external_id="")
if not include_ignored and not managed_only:
queryset = queryset.filter(ignored_at__isnull=True)
queryset = queryset.order_by("id")
if assigned_only:
queryset = queryset.filter(Exists(active_relationships.filter(account=OuterRef("pk"))))
if managed_only:
queryset = queryset.filter(
Exists(AccountRelationshipControl.objects.for_team(team_id).filter(account=OuterRef("pk")))
)
if cursor:
queryset = queryset.filter(id__gt=cursor)
page_accounts = list(queryset[: limit + 1])
accounts = page_accounts[:limit]
ownership_by_account = _ownership.ownership_for_accounts(team_id, organization_id, accounts)
relationships_by_account: dict[UUID, dict[str, list[contracts.ExternalAccountAssignment]]] = {}
for relationship in (
active_relationships.filter(account__in=accounts)
.select_related("definition", "user")
.order_by("definition__name", "user__email")
):
user = relationship.user
assert user is not None
relationships_by_account.setdefault(relationship.account_id, {}).setdefault(
relationship.definition.name, []
).append(
contracts.ExternalAccountAssignment(
user_id=user.id,
email=user.email,
name=f"{user.first_name} {user.last_name}".strip() or None,
)
)
results = [
contracts.ExternalAccountListItem(
external_id=cast(str, account.external_id),
name=account.name,
churned_at=account.churned_at,
ignored_at=account.ignored_at,
ownership=ownership_by_account[account.id],
relationships=relationships_by_account.get(account.id, {}),
)
for account in accounts
]
next_cursor = str(accounts[-1].id) if accounts and len(page_accounts) > limit else None
return contracts.ExternalAccountListPage(results=results, next_cursor=next_cursor)
def _apply_external_tags(account: Account, tags: list[str], mode: str, workflow_id: str | None = None) -> None:
normalized = list({tagify(t) for t in tags})
if mode == "remove":
removed_tags = [
tagged_item.tag
for tagged_item in account.tagged_items.filter(tag__name__in=normalized).select_related("tag")
]
account.tagged_items.filter(tag__name__in=normalized).delete()
_schedule_account_tags_removed(account, removed_tags, actor=None, workflow_id=workflow_id)
elif mode == "set":
_set_tags(normalized, account, workflow_id=workflow_id)
else:
added_tags: list[Tag] = []
for tag_name in normalized:
tag, _ = Tag.objects.get_or_create(name=tag_name, team_id=account.team_id)
_, created = account.tagged_items.get_or_create(tag_id=tag.id)
if created:
added_tags.append(tag)
_schedule_account_tags_added(account, added_tags, actor=None, workflow_id=workflow_id)
def _apply_external_relationship_assignments(
account: Account, assignments: dict[str, int | None], workflow_id: str | None = None
) -> contracts.ExternalAccountUpdateResult | None:
"""Apply provided relationship assignments, keyed by definition UUID (None ends the
active assignment). Each non-None user id is resolved against an
``OrganizationMembership`` in the account's org so assignees are always trusted.
Everything is validated before the first write — the caller's ``atomic()`` block
returns (commits) on an error result rather than rolling back. A workflow is an
autonomous writer, so a controlled relationship the account manages raises
``ManagedRolePolicyError`` from the relationship service and rolls the block back.
"""
keys_to_ids: dict[str, UUID] = {}
for key in assignments:
try:
keys_to_ids[key] = UUID(key)
except ValueError:
return contracts.ExternalAccountUpdateResult(
error=contracts.ExternalAccountUpdateError.RELATIONSHIP_DEFINITION_NOT_FOUND,
error_field=key,
)
definitions = {
definition.id: definition
for definition in AccountRelationshipDefinition.objects.for_team(account.team_id).filter(
id__in=keys_to_ids.values()
)
}
resolved: list[tuple[AccountRelationshipDefinition, User | None]] = []
for key, user_id in assignments.items():
definition = definitions.get(keys_to_ids[key])
if definition is None:
return contracts.ExternalAccountUpdateResult(
error=contracts.ExternalAccountUpdateError.RELATIONSHIP_DEFINITION_NOT_FOUND,
error_field=key,
)
if user_id is None:
resolved.append((definition, None))
continue
membership = (
OrganizationMembership.objects.select_related("user")
.filter(organization_id=account.team.organization_id, user_id=user_id)
.first()
)
if membership is None:
return contracts.ExternalAccountUpdateResult(
error=contracts.ExternalAccountUpdateError.USER_NOT_IN_ORGANIZATION,
error_field=key,
)
resolved.append((definition, membership.user))
actor = _relationships_logic.Actor(source=AccountRelationshipSource.WORKFLOW, workflow_id=workflow_id)
for definition, assignee in resolved:
if assignee is None:
_relationships_logic.end_active(
team_id=account.team_id, account=account, definition=definition, actor=actor
)
else:
_relationships_logic.assign(
team_id=account.team_id, account=account, definition=definition, user=assignee, actor=actor
)
return None
def update_external_account(
team_id: int,
external_id: str,
*,
relationship_assignments: dict[str, int | None],
tags: list[str] | None,
tags_mode: str,
churned_at: datetime | None = None,
churned_at_provided: bool = False,
workflow_id: str | None = None,
) -> contracts.ExternalAccountUpdateResult:
"""Apply relationship assignments, tags, and churn state to an account,
transactionally, for the external API.
All changes are all-or-nothing — a tag failure must not leave relationship or churn
changes committed. Returns a result the view maps to the exact HTTP
status/body: not found, a per-assignment failure (unknown definition, non-member
user), a generic write failure, or success carrying the re-serialized account.
"""
account = _get_external_account_by_external_id(team_id, external_id)
if account is None:
return contracts.ExternalAccountUpdateResult(error=contracts.ExternalAccountUpdateError.NOT_FOUND)
# Stored properties are re-serialized onto the success response, so reject accounts
# whose stored JSON no longer validates before writing anything.
try:
_ = account.properties
except PydanticValidationError:
return contracts.ExternalAccountUpdateResult(error=contracts.ExternalAccountUpdateError.INVALID_PROPERTIES)
try:
with transaction.atomic():
error_result = _apply_external_relationship_assignments(
account, relationship_assignments, workflow_id=workflow_id
)
if error_result is not None:
return error_result
if tags is not None:
_apply_external_tags(account, tags, tags_mode, workflow_id=workflow_id)
if churned_at_provided:
update_account(account, churned_at=churned_at)
except _relationships_logic.ManagedRolePolicyError:
return contracts.ExternalAccountUpdateResult(error=contracts.ExternalAccountUpdateError.ROLE_MANAGED)
except Exception as e:
capture_exception(e, {"team_id": team_id, "external_id": external_id, "account_id": str(account.id)})
return contracts.ExternalAccountUpdateResult(error=contracts.ExternalAccountUpdateError.UPDATE_FAILED)
account.refresh_from_db()
return contracts.ExternalAccountUpdateResult(account=_to_external_account(account))
def set_external_account_custom_properties(
team_id: int,
external_id: str,
*,
properties: dict[str, Any],
created_by_id: int | None = None,
workflow_id: str | None = None,
) -> contracts.ExternalAccountCustomPropertiesResult:
"""Set or clear custom property values on an account by definition id, for the external API.
Resolves the account by external id, then applies every ``{definition_id: value}`` pair
transactionally. A null value clears an active value. A bad value or unknown definition rolls
the whole batch back. Returns a result the view maps to the exact HTTP status/body: account not
found, unknown definition, invalid value, a concurrent-write conflict, a generic write failure,
or success carrying only the set values.
"""
account = _get_external_account_by_external_id(team_id, external_id)
if account is None:
return contracts.ExternalAccountCustomPropertiesResult(
error=contracts.ExternalAccountCustomPropertiesError.ACCOUNT_NOT_FOUND
)
source_backed = _source_backed_definition_ids(team_id, list(properties.keys()))
if source_backed:
return contracts.ExternalAccountCustomPropertiesResult(
error=contracts.ExternalAccountCustomPropertiesError.SOURCE_MANAGED,
error_field=str(next(iter(source_backed))),
)
try:
with transaction.atomic():
rows = _custom_property_values_logic.set_account_custom_properties_by_id(
team_id=team_id,
account_id=account.id,
properties=properties,
created_by_id=created_by_id,
workflow_id=workflow_id,
)
except _custom_property_values_logic.CustomPropertyDefinitionNotFound as exc:
return contracts.ExternalAccountCustomPropertiesResult(
error=contracts.ExternalAccountCustomPropertiesError.DEFINITION_NOT_FOUND,
error_field=str(exc.identifier),
)
except _custom_property_values_logic.InvalidCustomPropertyValue as exc:
return contracts.ExternalAccountCustomPropertiesResult(
error=contracts.ExternalAccountCustomPropertiesError.INVALID_VALUE,
error_field=exc.field,
)
except _custom_property_values_logic.CustomPropertyValueConflict:
return contracts.ExternalAccountCustomPropertiesResult(
error=contracts.ExternalAccountCustomPropertiesError.CONFLICT
)
except Exception as e:
capture_exception(e, {"team_id": team_id, "external_id": external_id})
return contracts.ExternalAccountCustomPropertiesResult(
error=contracts.ExternalAccountCustomPropertiesError.UPDATE_FAILED
)
return contracts.ExternalAccountCustomPropertiesResult(values=[_to_custom_property_value(row) for row in rows])
# ---------------------------------------------------------------------------
# Presentation wave: account / customer-journey / profile-config CRUD.
#
# The four DRF viewsets that back the Accounts UI reach their models exclusively
# through the functions below. Everything HTTP — request validation, status
# codes, pagination wiring, permission-mixin gating — stays in the view; the data
# access, transactions, conflict handling, pydantic-error formatting, and the
# activity logging that used to live in ``presentation/views/utils.py`` and the
# ViewSets' ``perform_*`` hooks all live here.
# ---------------------------------------------------------------------------
class AccountConflictError(Exception):
"""Raised when an account write violates the per-team unique external_id constraint."""
class AccountPropertiesValidationError(Exception):
"""Raised when account properties fail the pydantic schema. ``messages`` mirrors the
field-error list the old serializer produced from ``PydanticValidationError``."""
def __init__(self, messages: list[str]) -> None:
super().__init__("; ".join(messages))
self.messages = messages
class CustomerJourneyConflictError(Exception):
"""Raised when a customer journey already exists for the given insight (per team)."""
class CustomPropertyDefinitionConflictError(Exception):
"""Raised when a custom property definition violates the per-team unique name constraint."""
class CanonicalCustomPropertyReadOnlyError(Exception):
"""Canonical names and types identify the properties that PostHog records.
Manual API writes must preserve those identifiers and their system-managed values.
"""
class ResourceForbiddenError(Exception):
"""Raised when the caller passes resource/object access checks at the team level but
lacks the object-level access required for the action — the view maps this to 403,
matching the ``AccessControlPermission.has_object_permission`` path it replaces."""
class GoogleAccountBackfillUnavailable(Exception):
pass
class WarehouseSyncPausedError(Exception):
"""Raised when a person-property "sync now" is triggered while the team's warehouse
syncing is paused (monthly limit reached). The view maps this to 400 with the same
message the canonical warehouse schema reload/resync endpoints return."""
class ViewNotSyncableError(Exception):
"""Raised when a person-property "sync now" targets a materialized view that can't be
materialized on demand — it was deleted, or its DAG still runs on the older data-modeling
schedule, whose workflow never stages person-property rows. The view maps this to 400."""
# Re-export the "not found" exceptions so the view can branch to 404 without importing the
# models. They are model ``DoesNotExist`` subclasses raised by the team-scoped detail fetches.
Account_DoesNotExist = Account.DoesNotExist
CustomerJourney_DoesNotExist = CustomerJourney.DoesNotExist
def _format_pydantic_errors(exc: PydanticValidationError) -> list[str]:
messages = []
for err in exc.errors():
loc = ".".join(str(part) for part in err["loc"])
messages.append(f"{loc}: {err['msg']}" if loc else err["msg"])
return messages
def _set_tags(
tags: list[str] | None, account: Account, actor: "User | None" = None, workflow_id: str | None = None
) -> None:
"""Replace the account's tags, creating/deleting ``TaggedItem`` rows individually so
each change emits its own activity-log entry (the account activity stream depends on
this).
Mirrors ``posthog.api.tagged_item.set_tags_on_object`` + ``cleanup_orphan_tags`` but
stays on pure-model imports so the facade keeps DRF off its import path. ``None`` means
"tags not supplied" — leave them untouched (matches the serializer mixin).
Sets ``account.prefetched_tags`` to the resulting rows so a freshly-written account
renders its new tags without re-reading a stale prefetch (the mixin did the same)."""
if tags is None:
return
deduped_tags = list({tagify(t) for t in tags})
tagged_item_objects = []
added_tags: list[Tag] = []
for tag in deduped_tags:
tag_instance, _ = Tag.objects.get_or_create(name=tag, team_id=account.team_id)
tagged_item_instance, created = account.tagged_items.get_or_create(tag_id=tag_instance.id)
tagged_item_instance.tag = tag_instance
tagged_item_objects.append(tagged_item_instance)
if created:
added_tags.append(tag_instance)
removed_tags: list[Tag] = []
# Activity logging reads each deleted item's tag, its team and the tagged object.
removed_items = (
account.tagged_items.exclude(tag__name__in=deduped_tags)
.select_related("tag__team")
.prefetch_related("uuid_object")
)
for tagged_item in removed_items:
removed_tags.append(tagged_item.tag)
tagged_item.delete()
if removed_tags:
Tag.objects.filter(
Q(team_id=account.team_id) & Q(id__in=[tag.id for tag in removed_tags]) & Q(tagged_items__isnull=True)
).delete()
account.prefetched_tags = tagged_item_objects # type: ignore[attr-defined]
_schedule_account_tags_added(account, added_tags, actor, workflow_id=workflow_id)
_schedule_account_tags_removed(account, removed_tags, actor, workflow_id=workflow_id)
def _schedule_account_tags_added(
account: Account, tags: list[Tag], actor: "User | None", workflow_id: str | None = None
) -> None:
"""Emit $account_tag_added after commit for newly created rows only.
A workflow that adds its trigger tag again must not emit another event.
"""
if not tags:
return
def emit() -> None:
try:
emit_account_tags_added(account, tags, actor, workflow_id=workflow_id)
except Exception as e:
capture_exception(e)
transaction.on_commit(emit)
def _schedule_account_tags_removed(
account: Account, tags: list[Tag], actor: "User | None", workflow_id: str | None = None
) -> None:
"""Emit $account_tag_removed after commit for deleted rows only."""
if not tags:
return
def emit() -> None:
try:
emit_account_tags_removed(account, tags, actor, workflow_id=workflow_id)
except Exception as e:
capture_exception(e)
transaction.on_commit(emit)
def _log_activity_swallowing(
*,
instance,
scope: str,
activity: str,
name: str,
organization_id,
team_id: int,
user: "User | None",
was_impersonated: bool,
previous=None,
trigger: Trigger | None = None,
) -> None:
"""Replicates ``posthog.api.utils.log_activity_from_viewset`` — including its blanket
``except: pass`` — for the account / customer-journey write paths."""
try:
detail_kwargs: dict[str, Any] = {"name": name}
if trigger is not None:
detail_kwargs["trigger"] = trigger
if previous is not None:
detail_kwargs["changes"] = changes_between(cast(AuditableScope, scope), previous=previous, current=instance)
log_activity(
organization_id=organization_id,
team_id=team_id,
user=user,
was_impersonated=was_impersonated,
item_id=str(instance.id),
scope=scope,
activity=activity,
detail=Detail(**detail_kwargs),
)
except Exception:
pass
# --- CustomerProfileConfig ---
def _to_customer_profile_config_view(config: CustomerProfileConfig) -> contracts.CustomerProfileConfigView:
return contracts.CustomerProfileConfigView(
id=config.id,
scope=config.scope,
content=config.content,
sidebar=config.sidebar,
created_at=config.created_at,
updated_at=config.updated_at,
)
def _log_customer_profile_config_activity(
*,
instance: CustomerProfileConfig,
activity: str,
organization_id,
team_id: int,
user: "User",
was_impersonated: bool,
previous: Optional[CustomerProfileConfig] = None,
) -> None:
"""Folds in ``presentation/views/utils.log_customer_profile_config_activity`` verbatim
(note: unlike the account/journey path, this one does NOT swallow exceptions)."""
name = f"{instance.scope} profile"
changes = changes_between("CustomerProfileConfig", previous=previous, current=instance)
log_activity(
organization_id=organization_id,
team_id=team_id,
user=user,
was_impersonated=was_impersonated,
item_id=str(instance.id),
scope="CustomerProfileConfig",
activity=activity,
detail=Detail(name=name, changes=changes),
)
def list_customer_profile_configs(team_id: int, *, page: PageRequest) -> Page[contracts.CustomerProfileConfigView]:
"""One page of the team's profile configs."""
queryset = CustomerProfileConfig.objects.filter(team_id=team_id)
return select_page(queryset, page).map(_to_customer_profile_config_view)
def get_customer_profile_config(team_id: int, config_id: str) -> contracts.CustomerProfileConfigView | None:
config = _get_team_scoped(CustomerProfileConfig, team_id, config_id)
return _to_customer_profile_config_view(config) if config is not None else None
def create_customer_profile_config(
*,
team_id: int,
scope: str,
content: Any,
sidebar: Any,
organization_id,
user: "User",
was_impersonated: bool,
) -> contracts.CustomerProfileConfigView:
config = CustomerProfileConfig.objects.create(
team_id=team_id, created_by=user, scope=scope, content=content, sidebar=sidebar
)
_log_customer_profile_config_activity(
instance=config,
activity="created",
organization_id=organization_id,
team_id=team_id,
user=user,
was_impersonated=was_impersonated,
)
return _to_customer_profile_config_view(config)
def update_customer_profile_config(
*,
team_id: int,
config_id: str,
fields: dict[str, Any],
organization_id,
user: "User",
was_impersonated: bool,
) -> contracts.CustomerProfileConfigView | None:
"""Apply ``fields`` (only the keys the caller sent) to a team-scoped config. Returns the
updated view, or None when no config matches the id for this team (→ 404 in the view)."""
config = _get_team_scoped(CustomerProfileConfig, team_id, config_id)
if config is None:
return None
previous = CustomerProfileConfig.objects.get(pk=config.pk)
for attr, value in fields.items():
setattr(config, attr, value)
config.save()
_log_customer_profile_config_activity(
instance=config,
activity="updated",
organization_id=organization_id,
team_id=team_id,
user=user,
was_impersonated=was_impersonated,
previous=previous,
)
return _to_customer_profile_config_view(config)
def delete_customer_profile_config(
*,
team_id: int,
config_id: str,
organization_id,
user: "User",
was_impersonated: bool,
) -> bool:
"""Delete a team-scoped config. Returns False when none matched (→ 404)."""
config = _get_team_scoped(CustomerProfileConfig, team_id, config_id)
if config is None:
return False
instance_id = config.id
instance_scope = config.scope
config.delete()
# Mirror the old viewset: log against a transient instance carrying the deleted id/scope.
_log_customer_profile_config_activity(
instance=CustomerProfileConfig(id=instance_id, scope=instance_scope),
activity="deleted",
organization_id=organization_id,
team_id=team_id,
user=user,
was_impersonated=was_impersonated,
)
return True
# --- AccountView ---
InvalidAccountViewContent = _account_views_logic.InvalidAccountViewContent
AccountViewVersionConflict = _account_views_logic.AccountViewVersionConflict
AccountViewPermissionDenied = _account_views_logic.AccountViewPermissionDenied
def _to_account_view(
view: AccountViewModel,
*,
actor_user_id: int,
can_edit_team_views: bool,
is_project_admin: bool,
) -> contracts.AccountView:
is_creator = view.created_by_id == actor_user_id
return contracts.AccountView(
id=view.id,
name=view.name,
visibility=cast(Literal["private", "team"], view.visibility),
content=view.content,
text_content=view.text_content,
version=view.version,
created_by=view.created_by_id,
last_modified_by=view.last_modified_by_id,
created_at=view.created_at,
updated_at=view.updated_at,
can_edit=(view.visibility == AccountViewVisibility.PRIVATE and is_creator)
or (view.visibility == AccountViewVisibility.TEAM and can_edit_team_views),
can_delete=is_creator or is_project_admin,
can_change_visibility=is_creator or is_project_admin,
)
def list_account_views(
*, team_id: int, user_id: int, can_edit_team_views: bool, is_project_admin: bool
) -> list[contracts.AccountView]:
return [
_to_account_view(
view,
actor_user_id=user_id,
can_edit_team_views=can_edit_team_views,
is_project_admin=is_project_admin,
)
for view in _account_views_logic.list_account_views(team_id=team_id, user_id=user_id)
]
def get_account_view(
*,
team_id: int,
user_id: int,
view_id: UUID,
can_edit_team_views: bool,
is_project_admin: bool,
) -> contracts.AccountView | None:
view = _account_views_logic.get_account_view(team_id=team_id, user_id=user_id, view_id=view_id)
return (
_to_account_view(
view,
actor_user_id=user_id,
can_edit_team_views=can_edit_team_views,
is_project_admin=is_project_admin,
)
if view is not None
else None
)
def create_account_view(
*, team_id: int, user_id: int, name: str, content: dict[str, Any], is_project_admin: bool
) -> contracts.AccountView:
view = _account_views_logic.create_account_view(team_id=team_id, user_id=user_id, name=name, content=content)
return _to_account_view(view, actor_user_id=user_id, can_edit_team_views=True, is_project_admin=is_project_admin)
def update_account_view(
*,
team_id: int,
user_id: int,
view_id: UUID,
expected_version: int,
can_edit_team_views: bool,
is_project_admin: bool,
name: str | None = None,
content: dict[str, Any] | None = None,
visibility: str | None = None,
) -> contracts.AccountView | None:
view = _account_views_logic.update_account_view(
team_id=team_id,
user_id=user_id,
view_id=view_id,
expected_version=expected_version,
can_edit_team_views=can_edit_team_views,
is_project_admin=is_project_admin,
name=name,
content=content,
visibility=visibility,
)
return (
_to_account_view(
view,
actor_user_id=user_id,
can_edit_team_views=can_edit_team_views,
is_project_admin=is_project_admin,
)
if view is not None
else None
)
def delete_account_view(
*, team_id: int, user_id: int, view_id: UUID, expected_version: int, is_project_admin: bool
) -> bool:
return _account_views_logic.delete_account_view(
team_id=team_id,
user_id=user_id,
view_id=view_id,
expected_version=expected_version,
is_project_admin=is_project_admin,
)
# --- UserCustomerAnalyticsConfig ---
InvalidPinnedAccountProperties = contracts.InvalidPinnedAccountProperties
def _to_user_customer_analytics_config(
config: UserCustomerAnalyticsConfigModel,
) -> contracts.UserCustomerAnalyticsConfig:
raw_references = _user_customer_analytics_config_logic.read_pinned_properties(config)
return contracts.UserCustomerAnalyticsConfig(
pinned_properties=[
contracts.PinnedAccountProperty(
kind=cast(contracts.PinnedAccountPropertyKind, reference["kind"]),
id=str(reference["id"]),
)
for reference in raw_references
],
task_digest=_user_customer_analytics_config_logic.read_task_digest(config),
account_detail_tabs=_user_customer_analytics_config_logic.read_account_detail_tabs(config),
)
def get_user_customer_analytics_config(*, team_id: int, user_id: int) -> contracts.UserCustomerAnalyticsConfig:
config = _user_customer_analytics_config_logic.get_or_create_config(team_id=team_id, user_id=user_id)
return _to_user_customer_analytics_config(config)
def update_user_customer_analytics_config(
*, team_id: int, user_id: int, pinned_properties: list[contracts.PinnedAccountProperty]
) -> contracts.UserCustomerAnalyticsConfig:
config = _user_customer_analytics_config_logic.update_pinned_properties(
team_id=team_id,
user_id=user_id,
references=[(AccountPropertyPinKind(reference.kind), reference.id) for reference in pinned_properties],
)
return _to_user_customer_analytics_config(config)
def update_user_account_detail_tabs(
*,
team_id: int,
user_id: int,
ordered_tab_ids: list[str],
hidden_tab_ids: list[str],
default_tab_id: str | None,
) -> contracts.UserCustomerAnalyticsConfig:
config = _user_customer_analytics_config_logic.update_account_detail_tabs(
team_id=team_id,
user_id=user_id,
ordered_tab_ids=ordered_tab_ids,
hidden_tab_ids=hidden_tab_ids,
default_tab_id=default_tab_id,
)
return _to_user_customer_analytics_config(config)
def update_user_task_digest_preferences(
*,
team_id: int,
user_id: int,
enabled: bool | None = None,
send_time: time | None = None,
cadence: str | None = None,
) -> contracts.UserCustomerAnalyticsConfig:
config = _user_customer_analytics_config_logic.update_task_digest(
team_id=team_id,
user_id=user_id,
enabled=enabled,
send_time=send_time,
cadence=TaskDigestCadence(cadence) if cadence is not None else None,
)
return _to_user_customer_analytics_config(config)
# --- CustomPropertyDefinition ---
def _to_custom_property_definition_view(
definition: CustomPropertyDefinition,
references: list[contracts.CustomPropertyReference] | None = None,
has_workflow_reference: bool = False,
user_access_control: "UserAccessControl | None" = None,
enrichment_by_source_id: "dict[Any, tuple[Any, CustomPropertySyncRun | None]] | None" = None,
) -> contracts.CustomPropertyDefinitionView:
return contracts.CustomPropertyDefinitionView(
id=definition.id,
name=definition.name,
description=definition.description,
display_type=definition.display_type,
target_type=definition.target_type,
group_type_index=definition.group_type_index,
is_big_number=definition.is_big_number,
is_canonical=definition.name in CANONICAL_DISPLAY_TYPE_BY_NAME,
created_at=definition.created_at,
created_by=definition.created_by_id,
updated_at=definition.updated_at,
references=references or [],
has_workflow_reference=has_workflow_reference,
source=_definition_source_view(definition, user_access_control, enrichment_by_source_id),
options=_to_custom_property_options(definition.options),
)
def _to_custom_property_options(
options: list[dict[str, Any]] | None,
) -> list[contracts.CustomPropertyOption] | None:
if options is None:
return None
return [contracts.CustomPropertyOption(**option) for option in options]
def _custom_property_references_by_definition_id(
team_id: int, definition_id: str | None = None
) -> dict[str, list[HogFlowReference]]:
"""Map each referenced definition id to the workflows that set it via the "Update account
property" action. One scan of the team's workflows, matched by definition id. Pass
``definition_id`` to scan for just that one definition (the single-definition lookup)."""
usage = get_hog_flows_referencing_template_input_keys(
team_id,
_ACCOUNT_PROPERTY_TEMPLATE_ID,
_ACCOUNT_PROPERTY_INPUT_KEY,
only_value_key=definition_id,
)
return usage
def _to_custom_property_references(
workflow_references: list[HogFlowReference],
) -> list[contracts.CustomPropertyReference]:
return [
contracts.CustomPropertyReference(
id=reference.id, name=reference.name, status=reference.status, type="workflow"
)
for reference in workflow_references
]
def _definition_source_view(
definition: CustomPropertyDefinition,
user_access_control: "UserAccessControl | None" = None,
enrichment_by_source_id: "dict[Any, tuple[Any, CustomPropertySyncRun | None]] | None" = None,
) -> contracts.CustomPropertySourceView | None:
"""The source bound to this definition (reverse one-to-one ``source``), or None. List reads
``select_related("source")`` so this stays a cache hit; detail reads pay one extra query. Warehouse
schedule/run enrichment is gated on the caller's warehouse-source viewer access, and batched by the
list path via ``enrichment_by_source_id`` to avoid per-row queries."""
try:
source = definition.source
except CustomPropertySource.DoesNotExist:
return None
enrichment = (
enrichment_by_source_id.get(source.id, _RESOLVE_ENRICHMENT_INLINE)
if enrichment_by_source_id is not None
else _RESOLVE_ENRICHMENT_INLINE
)
return _to_custom_property_source_view(source, user_access_control, enrichment)
def _custom_property_definitions_queryset(
team_id: int, exclude_group_targets: bool, target_type: str | None
) -> QuerySet[CustomPropertyDefinition]:
queryset = CustomPropertyDefinition.objects.for_team(team_id).select_related("source").order_by("name", "pk")
if exclude_group_targets:
queryset = queryset.exclude(target_type=TargetType.GROUP.value)
if target_type is not None:
queryset = queryset.filter(target_type=target_type)
return queryset
def _to_custom_property_definition_views(
team_id: int, page: list[CustomPropertyDefinition], user_access_control: "UserAccessControl"
) -> list[contracts.CustomPropertyDefinitionView]:
workflow_references = _custom_property_references_by_definition_id(team_id)
references = filter_hog_flow_references_by_access_level(team_id, workflow_references, user_access_control)
sources: list[CustomPropertySource] = []
for d in page:
try:
sources.append(d.source)
except CustomPropertySource.DoesNotExist:
pass
enrichment = _batch_source_enrichment(team_id, sources, user_access_control)
return [
_to_custom_property_definition_view(
d,
_to_custom_property_references(references.get(str(d.id), [])),
has_workflow_reference=bool(workflow_references.get(str(d.id))),
user_access_control=user_access_control,
enrichment_by_source_id=enrichment,
)
for d in page
]
def list_custom_property_definitions(
team_id: int,
*,
page: PageRequest,
user_access_control: "UserAccessControl",
exclude_group_targets: bool = False,
target_type: str | None = None,
) -> Page[contracts.CustomPropertyDefinitionView]:
"""One page of the team's custom property definitions, ordered by name.
``has_workflow_reference`` is included for every caller. ``references`` carries only workflow
metadata the caller can read. ``exclude_group_targets`` hides group-target definitions from callers
without ``group`` read authorization. ``target_type`` narrows the scan to one target, so a caller
that wants a single target doesn't page over every definition to find it."""
queryset = _custom_property_definitions_queryset(team_id, exclude_group_targets, target_type)
selected = select_page(queryset, page)
views = _to_custom_property_definition_views(team_id, selected.results, user_access_control)
return Page(results=views, count=selected.count)
def list_all_custom_property_definitions(
team_id: int,
*,
user_access_control: "UserAccessControl",
exclude_group_targets: bool = False,
) -> list[contracts.CustomPropertyDefinitionView]:
"""All of the team's custom property definitions, ordered by name, for a caller that needs the whole list."""
queryset = _custom_property_definitions_queryset(team_id, exclude_group_targets, None)
return _to_custom_property_definition_views(team_id, list(queryset), user_access_control)
def get_custom_property_definition_target_type(team_id: int, definition_id: str) -> str | None:
definition = _get_custom_property_definition(team_id, definition_id)
return definition.target_type if definition is not None else None
def get_custom_property_definition(
team_id: int, definition_id: str, *, user_access_control: "UserAccessControl"
) -> contracts.CustomPropertyDefinitionView | None:
definition = _get_custom_property_definition(team_id, definition_id)
if definition is None:
return None
workflow_references_by_definition_id = _custom_property_references_by_definition_id(
team_id, definition_id=str(definition.id)
)
workflow_references = workflow_references_by_definition_id.get(str(definition.id), [])
references = filter_hog_flow_references_by_access_level(
team_id, workflow_references_by_definition_id, user_access_control
).get(str(definition.id), [])
return _to_custom_property_definition_view(
definition,
_to_custom_property_references(references),
has_workflow_reference=bool(workflow_references),
user_access_control=user_access_control,
)
def list_custom_property_value_suggestions(team_id: int, definition_id: str, search: str | None) -> list[str]:
"""Suggested filter values for a custom property — see the logic function for the per-type
behavior. Empty for unknown definitions."""
return _custom_property_values_logic.list_custom_property_value_suggestions(
team_id=team_id, definition_id=definition_id, search=search
)
def create_custom_property_definition(
*,
team_id: int,
name: str,
description: str | None,
display_type: str,
is_big_number: bool,
options: list[dict[str, Any]] | None = None,
target_type: str = TargetType.ACCOUNT.value,
group_type_index: int | None = None,
organization_id,
user: "User",
was_impersonated: bool,
) -> contracts.CustomPropertyDefinitionView:
try:
definition = CustomPropertyDefinition.objects.for_team(team_id).create(
team_id=team_id,
created_by=user,
name=name,
description=description,
display_type=display_type,
target_type=target_type,
# Only group targets carry an index; force it null otherwise to satisfy the check constraint.
group_type_index=group_type_index if target_type == TargetType.GROUP.value else None,
is_big_number=coerce_is_big_number(display_type, is_big_number),
options=normalize_options(DisplayType(display_type), options),
)
except IntegrityError:
raise CustomPropertyDefinitionConflictError("A custom property with this name already exists for this team.")
_log_activity_swallowing(
instance=definition,
scope="CustomPropertyDefinition",
activity="created",
name=definition.name,
organization_id=organization_id,
team_id=team_id,
user=user,
was_impersonated=was_impersonated,
)
return _to_custom_property_definition_view(definition)
def _assert_canonical_fields_unchanged(definition: CustomPropertyDefinition, fields: dict[str, Any]) -> None:
"""Refuse a rename or a type change on a canonical property — PostHog owns both.
Everything else on the definition (description, position in a view) stays editable. Deleting
it is allowed: the next recorded value recreates it.
"""
if definition.name not in CANONICAL_DISPLAY_TYPE_BY_NAME:
return
for attr in ("name", "display_type"):
if attr in fields and fields[attr] != getattr(definition, attr):
raise CanonicalCustomPropertyReadOnlyError(
f"'{definition.name}' is set by PostHog, so its {attr.replace('_', ' ')} can't be changed."
)
def update_custom_property_definition(
*,
team_id: int,
definition_id: str,
fields: dict[str, Any],
organization_id,
user: "User",
was_impersonated: bool,
user_access_control: "UserAccessControl | None" = None,
) -> contracts.CustomPropertyDefinitionView | None:
"""Apply ``fields`` (only the keys the caller sent) to a team-scoped definition. Returns the
updated view, or None when no definition matches the id for this team (→ 404)."""
definition = _get_custom_property_definition(team_id, definition_id)
if definition is None:
return None
_assert_canonical_fields_unchanged(definition, fields)
previous = CustomPropertyDefinition.objects.for_team(team_id).get(pk=definition.pk)
for attr, value in fields.items():
setattr(definition, attr, value)
# Re-coerce against the effective display type: a PATCH that only flips the type to a
# non-numeric one must clear a previously-set is_big_number (the partial-update case).
definition.is_big_number = coerce_is_big_number(definition.display_type, definition.is_big_number)
definition.options = normalize_options(
DisplayType(definition.display_type),
definition.options,
existing_ids=frozenset(option["id"] for option in previous.options or []),
)
try:
with transaction.atomic():
definition.save()
if DisplayType(definition.display_type) == DisplayType.SELECT:
apply_option_side_effects(
team_id=team_id,
definition_id=definition.id,
previous_options=previous.options,
new_options=definition.options,
)
except IntegrityError:
raise CustomPropertyDefinitionConflictError("A custom property with this name already exists for this team.")
_log_activity_swallowing(
instance=definition,
scope="CustomPropertyDefinition",
activity="updated",
name=definition.name,
organization_id=organization_id,
team_id=team_id,
user=user,
was_impersonated=was_impersonated,
previous=previous,
)
workflow_references_by_definition_id = _custom_property_references_by_definition_id(
team_id, definition_id=str(definition.id)
)
workflow_references = workflow_references_by_definition_id.get(str(definition.id), [])
references = (
filter_hog_flow_references_by_access_level(
team_id, workflow_references_by_definition_id, user_access_control
).get(str(definition.id), [])
if user_access_control is not None
else []
)
return _to_custom_property_definition_view(
definition,
_to_custom_property_references(references),
has_workflow_reference=bool(workflow_references),
user_access_control=user_access_control,
)
def delete_custom_property_definition(
*,
team_id: int,
definition_id: str,
organization_id,
user: "User",
was_impersonated: bool,
) -> bool:
"""Delete a team-scoped definition. Returns False when none matched (→ 404)."""
definition = _get_custom_property_definition(team_id, definition_id)
if definition is None:
return False
_log_activity_swallowing(
instance=definition,
scope="CustomPropertyDefinition",
activity="deleted",
name=definition.name,
organization_id=organization_id,
team_id=team_id,
user=user,
was_impersonated=was_impersonated,
)
definition.delete()
return True
# --- CustomPropertySource ---
class CustomPropertySourceValidationError(Exception):
"""Raised when a source's saved_query isn't a usable view for the team, or the definition is
already source-backed (→ 400)."""
def _temporal_run_url(run: "CustomPropertySyncRun") -> str | None:
if not run.workflow_id or not run.workflow_run_id:
return None
base = settings.TEMPORAL_UI_HOST
namespace = settings.TEMPORAL_NAMESPACE
if not base or not namespace:
return None
return f"{base.rstrip('/')}/namespaces/{namespace}/workflows/{run.workflow_id}/{run.workflow_run_id}"
def _to_sync_run_view(
run: "CustomPropertySyncRun", *, include_temporal_url: bool = False
) -> contracts.CustomPropertySyncRunView:
return contracts.CustomPropertySyncRunView(
id=run.id,
job_id=run.job_id,
account_segment=run.segment,
sync_phase=run.phase,
attempt=run.attempt,
workflow_id=run.workflow_id if include_temporal_url else None,
workflow_run_id=run.workflow_run_id if include_temporal_url else None,
temporal_url=_temporal_run_url(run) if include_temporal_url else None,
trigger=run.trigger,
status=run.status,
started_at=run.started_at,
finished_at=run.finished_at,
rows_read=run.rows_read,
changed=run.changed,
existing=run.existing,
produced=run.produced,
skipped_missing_person=run.skipped_missing_person,
error=run.error,
created_at=run.created_at,
)
@frozen
class _ProfileWarehouseMeta:
"""Display metadata a profile source derives from the warehouse object it reads.
Resolved for both binding kinds so the view builder doesn't branch on kind. ``external_data_source``
is set only for a schema binding (a view has no import source), ``saved_query_name`` only for a view.
"""
table_name: str
sync_frequency_interval_seconds: float | None = None
next_sync_at: datetime | None = None
external_data_source: UUID | None = None
saved_query_name: str | None = None
def _profile_binding(source: CustomPropertySource) -> "WarehouseBinding | None":
"""The warehouse object a person/group-target source reads, or None for an account source.
Reads ``definition.target_type`` rather than inferring from which column is set: an account source
is also bound to a saved query, so the binding column alone no longer tells the two apart. Callers
pass a source with its definition selected.
"""
if source.definition.target_type not in _WAREHOUSE_PROFILE_TARGETS:
return None
if source.saved_query_id is not None:
return saved_query_binding(source.saved_query_id)
if source.external_data_schema_id is not None:
return schema_binding(source.external_data_schema_id)
return None
def _resolve_schema(team_id: int, schema_id: Any, user_access_control: "UserAccessControl | None") -> Any:
"""The ``ExternalDataSchema`` (with ``.source`` loaded) for a schema-bound source, or None when it
no longer exists or the caller lacks object-level ``external_data_source`` viewer access.
``user_access_control`` None (service auth) skips the object check, matching ``_enforce_object_access``.
``apps.get_model`` keeps this off a warehouse_sources internal import."""
schema_model = apps.get_model("warehouse_sources", "ExternalDataSchema")
schema = schema_model.objects.filter(id=schema_id, team_id=team_id).select_related("source", "table").first()
if schema is None:
return None
if user_access_control is not None and not user_access_control.check_access_level_for_object(
schema.source, required_level="viewer"
):
return None
return schema
def _resolve_saved_query(team_id: int, saved_query_id: Any, user_access_control: "UserAccessControl | None") -> Any:
"""The ``DataWarehouseSavedQuery`` for a view-bound source, or None when it no longer resolves or
the caller lacks object-level ``warehouse_view`` viewer access — the same gate the warehouse view
endpoints and HogQL resolution apply."""
saved_query_model = apps.get_model("data_modeling", "DataWarehouseSavedQuery")
saved_query = saved_query_model.objects.filter(id=saved_query_id, team_id=team_id).exclude(deleted=True).first()
if saved_query is None:
return None
if user_access_control is not None and not user_access_control.check_access_level_for_object(
saved_query, required_level="viewer"
):
return None
return saved_query
def _saved_query_meta(saved_query: Any) -> _ProfileWarehouseMeta:
"""Display metadata for a view-bound source. A view's name is already its HogQL name, so it needs
no table-name resolution. A view's frequency lives on its DAG node, which leaves the next run
unknown rather than guessable — so both schedule fields stay None."""
return _ProfileWarehouseMeta(table_name=saved_query.name, saved_query_name=saved_query.name)
def _resolve_profile_warehouse_meta(
source: CustomPropertySource, user_access_control: "UserAccessControl | None"
) -> _ProfileWarehouseMeta | None:
"""Warehouse-derived display metadata for a profile source, or None for an account source, a
warehouse object that no longer exists, or a caller without viewer access to it."""
binding = _profile_binding(source)
if binding is None:
return None
if binding.is_saved_query:
saved_query = _resolve_saved_query(source.team_id, binding.id, user_access_control)
return _saved_query_meta(saved_query) if saved_query is not None else None
schema = _resolve_schema(source.team_id, binding.id, user_access_control)
return _schema_meta(schema) if schema is not None else None
def _schema_table_name(schema: Any) -> str:
"""The bound table as it is named in HogQL, so the UI shows the name the table picker offered.
Falls back to the schema name when the first sync hasn't created the table yet. The HogQL import
is deferred to keep the heavy database module off this module's import path."""
from posthog.hogql.database.database import (
get_data_warehouse_table_name, # noqa: PLC0415 — keeps HogQL off the import path
)
if schema.table_id is None:
return schema.name
return get_data_warehouse_table_name(schema.source, schema.table.name)
def _schema_meta(schema: Any) -> _ProfileWarehouseMeta:
"""Display metadata for a schema-bound source. Both schedule fields stay None when the schema has
no sync frequency configured."""
interval = schema.sync_frequency_interval
next_sync_at = (
schema.last_synced_at + interval if interval is not None and schema.last_synced_at is not None else None
)
return _ProfileWarehouseMeta(
table_name=_schema_table_name(schema),
sync_frequency_interval_seconds=interval.total_seconds() if interval is not None else None,
next_sync_at=next_sync_at,
external_data_source=schema.source_id,
)
# Sentinel so a caller can pass a prefetched (schema, latest_run) pair — including ``(None, None)``
# for a person source the caller can't see — distinct from "resolve inline" (the detail path).
class _ResolveEnrichmentInline:
pass
_RESOLVE_ENRICHMENT_INLINE = _ResolveEnrichmentInline()
def _to_custom_property_source_view(
source: CustomPropertySource,
user_access_control: "UserAccessControl | None" = None,
enrichment: "tuple[_ProfileWarehouseMeta | None, CustomPropertySyncRun | None] | _ResolveEnrichmentInline" = _RESOLVE_ENRICHMENT_INLINE,
) -> contracts.CustomPropertySourceView:
# Schedule + latest-run enrichment applies only to person/group sources; account sources leave it
# None. The enrichment exposes the underlying warehouse object's schedule and run metadata, so it's
# gated on the caller's viewer access to that object — a caller without it sees the source but not
# its warehouse-derived metadata. ``enrichment`` lets list endpoints prefetch the metadata + latest
# run in one batched query each (see ``_batch_source_enrichment``) instead of two per row.
latest_run: contracts.CustomPropertySyncRunView | None = None
if isinstance(enrichment, _ResolveEnrichmentInline):
meta = _resolve_profile_warehouse_meta(source, user_access_control)
latest = source.sync_runs.order_by("-created_at").first() if meta is not None else None
_expire_stale_running_runs(source.team_id, [latest])
else:
meta, latest = enrichment
if meta is not None:
latest_run = _to_sync_run_view(latest) if latest is not None else None
# A profile source's sync status (raw error text, failure streak, last-synced time) is produced by
# the underlying warehouse object, so it's warehouse-derived metadata gated the same way as the
# schedule/latest-run above — a caller without viewer access on that object sees the mapping but not
# its status. Column descriptions are likewise warehouse-derived (populated from the object's
# ``information_schema.columns`` or set by a warehouse editor), so they're gated the same way.
# Account sources are not warehouse-gated; their status and descriptions stay visible.
warehouse_status_visible = _profile_binding(source) is None or meta is not None
return contracts.CustomPropertySourceView(
id=source.id,
definition=source.definition_id,
saved_query=source.saved_query_id,
external_data_schema=source.external_data_schema_id,
source_column=source.source_column,
key_column=source.key_column,
column_property_map=source.column_property_map,
column_descriptions=source.column_descriptions if warehouse_status_visible else {},
is_enabled=source.is_enabled,
consecutive_failures=source.consecutive_failures if warehouse_status_visible else 0,
last_synced_at=source.last_synced_at if warehouse_status_visible else None,
last_sync_error=source.last_sync_error if warehouse_status_visible else None,
created_at=source.created_at,
created_by=source.created_by_id,
updated_at=source.updated_at,
sync_frequency_interval_seconds=meta.sync_frequency_interval_seconds if meta else None,
next_sync_at=meta.next_sync_at if meta else None,
latest_run=latest_run,
external_data_source=meta.external_data_source if meta else None,
table_name=meta.table_name if meta else None,
saved_query_name=meta.saved_query_name if meta else None,
)
def _batch_source_enrichment(
team_id: int, sources: list[CustomPropertySource], user_access_control: "UserAccessControl | None"
) -> dict[Any, "tuple[_ProfileWarehouseMeta | None, CustomPropertySyncRun | None]"]:
"""Resolve the warehouse metadata (with viewer access applied) and latest run for a page of profile
sources in one query per warehouse kind, so a list endpoint doesn't issue two per-row queries (see
the per-row path in ``_to_custom_property_source_view``). Returns
``{source_id: (meta_or_None, latest_run)}``; account sources are absent, so they resolve inline to no
enrichment."""
bindings = {s.id: _profile_binding(s) for s in sources}
profile_sources = [s for s in sources if bindings[s.id] is not None]
if not profile_sources:
return {}
schema_ids = {b.id for b in bindings.values() if b is not None and not b.is_saved_query}
saved_query_ids = {b.id for b in bindings.values() if b is not None and b.is_saved_query}
schemas_by_id: dict[str, Any] = {}
if schema_ids:
schema_model = apps.get_model("warehouse_sources", "ExternalDataSchema")
schemas_by_id = {
str(schema.id): schema
for schema in schema_model.objects.filter(id__in=schema_ids, team_id=team_id).select_related(
"source", "table"
)
}
saved_queries_by_id: dict[str, Any] = {}
if saved_query_ids:
saved_query_model = apps.get_model("data_modeling", "DataWarehouseSavedQuery")
saved_queries_by_id = {
str(saved_query.id): saved_query
for saved_query in saved_query_model.objects.filter(id__in=saved_query_ids, team_id=team_id).exclude(
deleted=True
)
}
# Latest run per source in one query: DISTINCT ON (source_id) keeps the newest row per source.
latest_run_by_source_id: dict[Any, CustomPropertySyncRun] = {
run.source_id: run
for run in CustomPropertySyncRun.objects.for_team(team_id)
.filter(source_id__in=[s.id for s in profile_sources])
.order_by("source_id", "-created_at")
.distinct("source_id")
}
enrichment: dict[Any, tuple[_ProfileWarehouseMeta | None, CustomPropertySyncRun | None]] = {}
authorized_runs: list[CustomPropertySyncRun | None] = []
for source in profile_sources:
binding = bindings[source.id]
assert binding is not None # profile_sources is filtered on exactly this
meta = _batched_meta(binding, schemas_by_id, saved_queries_by_id, user_access_control)
latest = latest_run_by_source_id.get(source.id) if meta is not None else None
# Only mutate runs the caller can view; expiring runs for hidden warehouse objects would let a
# denied viewer flip their status through the source-list endpoint.
if latest is not None:
authorized_runs.append(latest)
enrichment[source.id] = (meta, latest)
_expire_stale_running_runs(team_id, authorized_runs)
return enrichment
def _batched_meta(
binding: "WarehouseBinding",
schemas_by_id: dict[str, Any],
saved_queries_by_id: dict[str, Any],
user_access_control: "UserAccessControl | None",
) -> _ProfileWarehouseMeta | None:
"""One binding's metadata from the prefetched maps, or None when it is missing or access-denied.
The access check mirrors the per-row resolvers: the import source for a schema, the view itself for
a saved query."""
if binding.is_saved_query:
saved_query = saved_queries_by_id.get(binding.id)
if saved_query is None:
return None
if user_access_control is not None and not user_access_control.check_access_level_for_object(
saved_query, required_level="viewer"
):
return None
return _saved_query_meta(saved_query)
schema = schemas_by_id.get(binding.id)
if schema is None:
return None
if user_access_control is not None and not user_access_control.check_access_level_for_object(
schema.source, required_level="viewer"
):
return None
return _schema_meta(schema)
def _saved_query_belongs_to_team(team_id: int, saved_query_id) -> bool:
"""Whether the saved query exists for this team and isn't soft-deleted. Uses ``apps.get_model`` so
customer_analytics never imports data_modeling (which isn't a dependency)."""
saved_query_model = apps.get_model("data_modeling", "DataWarehouseSavedQuery")
return saved_query_model.objects.filter(id=saved_query_id, team_id=team_id).exclude(deleted=True).exists()
def _materialized_saved_query_belongs_to_team(team_id: int, saved_query_id) -> bool:
"""Whether the saved query resolves for this team *and* is materialized. A profile source reads the
view's Delta table directly, which only a materialized view has."""
saved_query_model = apps.get_model("data_modeling", "DataWarehouseSavedQuery")
return (
saved_query_model.objects.filter(id=saved_query_id, team_id=team_id, is_materialized=True)
.exclude(deleted=True)
.exists()
)
def _external_data_schema_belongs_to_team(team_id: int, schema_id) -> bool:
"""Whether the warehouse schema (raw synced table) exists for this team. ``apps.get_model`` keeps
customer_analytics from importing warehouse_sources internals (isolation)."""
schema_model = apps.get_model("warehouse_sources", "ExternalDataSchema")
return schema_model.objects.filter(id=schema_id, team_id=team_id).exists()
def _validate_column_property_map(column_property_map: Any) -> dict[str, str]:
"""A person-source's column->property map must be a non-empty {str: non-empty str} object."""
if not isinstance(column_property_map, dict) or not column_property_map:
raise CustomPropertySourceValidationError("column_property_map must be a non-empty object.")
for column, property_name in column_property_map.items():
if not isinstance(column, str) or not column:
raise CustomPropertySourceValidationError("column_property_map keys must be non-empty column names.")
if not isinstance(property_name, str) or not property_name:
raise CustomPropertySourceValidationError("column_property_map values must be non-empty property names.")
return column_property_map
def _validate_column_descriptions(column_descriptions: Any, mapped_columns: set[str]) -> dict[str, str]:
"""Optional {warehouse_column: description} for a person source. Descriptions are keyed by the
same warehouse columns the source maps; unknown columns and blank descriptions are dropped."""
if column_descriptions is None:
return {}
if not isinstance(column_descriptions, dict):
raise CustomPropertySourceValidationError("column_descriptions must be an object.")
cleaned: dict[str, str] = {}
for column, description in column_descriptions.items():
if column not in mapped_columns:
continue
if description is None or (isinstance(description, str) and not description.strip()):
continue
if not isinstance(description, str):
raise CustomPropertySourceValidationError("column_descriptions values must be strings.")
cleaned[column] = description.strip()
return cleaned
def _send_initial_account_property_sync(team_id: int, saved_query_id: str) -> None:
try:
current_app.send_task(
"customer_analytics.process_custom_property_sync",
kwargs={"team_id": team_id, "saved_query_id": saved_query_id},
)
except Exception as error:
capture_exception(error)
def _enqueue_initial_account_property_sync(source: CustomPropertySource) -> None:
if (
not source.is_enabled
or source.saved_query_id is None
or source.definition.target_type != TargetType.ACCOUNT.value
):
return
team_id, saved_query_id = source.team_id, str(source.saved_query_id)
transaction.on_commit(lambda: _send_initial_account_property_sync(team_id, saved_query_id))
# Targets fed by the warehouse staging/sync pipeline (person + group), as opposed to the account
# materialized-view path. These share the sync-now / backfill / run-history machinery.
_WAREHOUSE_PROFILE_TARGETS = (TargetType.PERSON.value, TargetType.GROUP.value)
_ONE_PROFILE_BINDING_ERROR = "A person/group property source needs exactly one of external_data_schema and saved_query."
# A run row only reaches a terminal state when its activity records one. Account segment workflows can
# retry for a full day, while profile sync activities time out after six hours.
STALE_RUNNING_RUN_AFTER = timedelta(hours=6)
STALE_ACCOUNT_RUNNING_RUN_AFTER = timedelta(hours=25)
STALE_RUNNING_RUN_ERROR = (
"This run stopped reporting progress. Run the warehouse source again. If it keeps failing, contact support."
)
def _expire_stale_running_runs(team_id: int, runs: "Iterable[CustomPropertySyncRun | None]") -> None:
"""Fail abandoned 'running' rows, both in the database and in the passed-in objects so the caller
serializes what it just wrote. Runs on the read paths the UI polls, so a stuck row self-heals."""
now = timezone.now()
stale = [
run
for run in runs
if run is not None
and run.status == SyncStatus.RUNNING.value
and (run.started_at or run.created_at)
< now - (STALE_ACCOUNT_RUNNING_RUN_AFTER if run.segment is not None else STALE_RUNNING_RUN_AFTER)
]
if not stale:
return
finished_at = timezone.now()
CustomPropertySyncRun.objects.for_team(team_id).filter(id__in=[run.id for run in stale]).update(
status=SyncStatus.FAILED.value, finished_at=finished_at, error=STALE_RUNNING_RUN_ERROR
)
for run in stale:
run.status = SyncStatus.FAILED.value
run.finished_at = finished_at
run.error = STALE_RUNNING_RUN_ERROR
def _create_running_runs(team_id: int, binding: "WarehouseBinding", trigger: str) -> list[Any]:
"""Insert a 'running' run for each enabled person/group source on the binding that isn't already
running. The UI shows these as in-progress and disables the trigger while they exist; the sync and
backfill activities reconcile them to their terminal state (see record_sync_run). An existing row
suppresses only a duplicate placeholder; the binding workflow still receives a signal and opens a
new row when its follow-up starts. Returns the source ids a placeholder was created for, so the
caller can reconcile them to FAILED if the workflow start never happens (see ``_fail_created_runs``)."""
# A source and a run name the same binding through different columns: a source's schema binding is
# the `external_data_schema` FK, a run's is the plain `schema_id`.
source_field = "saved_query_id" if binding.is_saved_query else "external_data_schema_id"
run_field = "saved_query_id" if binding.is_saved_query else "schema_id"
with transaction.atomic():
# Lock the candidate sources so a concurrent trigger for the same binding can't pass the
# "already running" check and insert a duplicate RUNNING row before this one commits.
sources = list(
CustomPropertySource.objects.for_team(team_id)
.filter(
is_enabled=True,
definition__target_type__in=_WAREHOUSE_PROFILE_TARGETS,
**{source_field: binding.id},
)
.select_for_update()
)
if not sources:
return []
running = list(
CustomPropertySyncRun.objects.for_team(team_id).filter(source__in=sources, status=SyncStatus.RUNNING.value)
)
# An abandoned row must not coalesce away a fresh trigger.
_expire_stale_running_runs(team_id, running)
already_running = {run.source_id for run in running if run.status == SyncStatus.RUNNING.value}
to_create = [source for source in sources if source.id not in already_running]
now = timezone.now()
CustomPropertySyncRun.objects.bulk_create(
[
CustomPropertySyncRun(
team_id=team_id,
source=source,
trigger=trigger,
status=SyncStatus.RUNNING.value,
started_at=now,
**{run_field: binding.id},
)
for source in to_create
]
)
return [source.id for source in to_create]
def _fail_created_runs(team_id: int, source_ids: list[Any], error: str) -> None:
"""Reconcile the RUNNING placeholders just created for these sources to FAILED. Called when the
workflow start never happened (Temporal unreachable), so the rows don't sit 'running' forever with
the UI trigger disabled, and the next attempt isn't coalesced against a dead placeholder."""
if not source_ids:
return
CustomPropertySyncRun.objects.for_team(team_id).filter(
source_id__in=source_ids, status=SyncStatus.RUNNING.value
).update(status=SyncStatus.FAILED.value, finished_at=timezone.now(), error=error)
def _start_backfill(team_id: int, binding: "WarehouseBinding", trigger: str) -> None:
"""Start the person-property backfill workflow. Failure must not fail the originating write."""
created_source_ids: list[Any] = []
# The temporal client is heavy; keep it off the CA facade import (django.setup) path. Imported
# before the try so the except clause below can name WarehouseBindingMissingError even when an
# earlier line raises.
from products.warehouse_sources.backend.facade.temporal import ( # noqa: PLC0415
WarehouseBindingMissingError,
start_person_property_backfill,
)
try:
# Placeholder rows before starting, so the activity always finds a running row to reconcile.
created_source_ids = _create_running_runs(team_id, binding, trigger)
start_person_property_backfill(team_id=team_id, binding=binding, trigger=trigger)
except WarehouseBindingMissingError:
# The warehouse object was deleted between saving the source and this deferred start. There is
# nothing to back-fill, so reconcile the placeholders without capturing it as an error.
_fail_created_runs(team_id, created_source_ids, "The warehouse table or view for this source no longer exists.")
except Exception as e:
# The workflow never started, so nothing will reconcile the placeholders — fail them here.
_fail_created_runs(team_id, created_source_ids, "Failed to start backfill")
capture_exception(e)
def _start_person_backfill_if_enabled(source: CustomPropertySource) -> None:
"""Auto-start a backfill after a person/group source is created/enabled so historical rows populate
immediately rather than waiting for the next warehouse run. Profile sources only (an account source
has its own Celery sync); serialized per table by the workflow id."""
binding = _profile_binding(source)
if not source.is_enabled or binding is None:
return
team_id = source.team_id
transaction.on_commit(lambda: _start_backfill(team_id, binding, "backfill"))
def _stamp_profile_source_provenance(source: CustomPropertySource, binding: "WarehouseBinding") -> None:
"""Apply the source's current mapping metadata without waiting for a value-hash change."""
from products.warehouse_sources.backend.facade.person_property_provenance import ( # noqa: PLC0415
stamp_person_property_provenance,
)
column_property_map = source.column_property_map or {}
column_descriptions = source.column_descriptions or {}
property_descriptions = {
column_property_map[column]: description
for column, description in column_descriptions.items()
if column in column_property_map and description
}
# Property definitions are keyed by effective project, not team.
project_id = Team.objects.filter(pk=source.team_id).values_list("project_id", flat=True).first()
if project_id is None:
return
stamp_person_property_provenance(
team_id=source.team_id,
project_id=project_id,
binding=binding,
source_id=str(source.id),
definition_id=str(source.definition_id),
target=source.definition.target_type,
group_type_index=source.definition.group_type_index,
property_names=column_property_map.values(),
property_descriptions=property_descriptions,
)
def _triggerable_profile_binding(team_id: int, source_id: str) -> "WarehouseBinding | None":
"""The warehouse object to act on for a person/group-property trigger, or None when the source isn't
a valid, flag-enabled warehouse-profile source (→ the view returns 400)."""
source = CustomPropertySource.objects.for_team(team_id).filter(id=source_id).select_related("definition").first()
if source is None:
return None
# A disabled source (e.g. auto-disabled after repeated failures) can't be re-triggered until it's
# re-enabled — otherwise the "sync now"/backfill actions would keep launching billable warehouse
# runs for a mapping the system already turned off.
if not source.is_enabled:
return None
if not person_properties_flag_enabled(team_id):
return None
return _profile_binding(source)
def _assert_warehouse_access(
team_id: int,
binding: "WarehouseBinding | None",
user_access_control: "UserAccessControl | None",
level: str,
) -> None:
"""A profile source drives a real warehouse run, so acting on it or reading its warehouse metadata
requires the caller's object-level access to what it reads at ``level``, not account-scope access
alone: the ``external_data_source`` for a schema, the ``warehouse_view`` for a materialized view.
Mirrors the canonical warehouse endpoints, which gate through ``get_object``. ``None`` (service auth,
which the permission layer skips object checks for) is a no-op, matching ``_enforce_object_access``.
Raises ``ResourceForbiddenError`` (→ 403) when the caller is denied. A warehouse object that no
longer resolves is a no-op: there is nothing left to protect, and the caller's own write will fail
its validation. ``apps.get_model`` keeps this off a warehouse_sources/data_modeling internal import."""
if user_access_control is None or binding is None:
return
if binding.is_saved_query:
saved_query_model = apps.get_model("data_modeling", "DataWarehouseSavedQuery")
saved_query = saved_query_model.objects.filter(id=binding.id, team_id=team_id).exclude(deleted=True).first()
if saved_query is None:
return
_enforce_object_access(saved_query, user_access_control, level)
return
schema_model = apps.get_model("warehouse_sources", "ExternalDataSchema")
schema = schema_model.objects.filter(id=binding.id, team_id=team_id).select_related("source").first()
if schema is None:
return
_enforce_object_access(schema.source, user_access_control, level)
def _assert_warehouse_editor(
team_id: int, binding: "WarehouseBinding | None", user_access_control: "UserAccessControl | None"
) -> None:
"""Editor gate for acting on a profile source — a manual sync/backfill, or creating/enabling the
mapping (which auto-triggers one)."""
_assert_warehouse_access(team_id, binding, user_access_control, "editor")
def _assert_warehouse_viewer(
team_id: int, binding: "WarehouseBinding | None", user_access_control: "UserAccessControl | None"
) -> None:
"""Viewer gate for reading a profile source's warehouse run metadata (row counts, schedule, sync
errors), which exposes the warehouse object it reads."""
_assert_warehouse_access(team_id, binding, user_access_control, "viewer")
def trigger_person_property_sync(
*, team_id: int, source_id: str, user_access_control: "UserAccessControl | None" = None
) -> bool:
""" "Sync now" for a profile source: start a fresh warehouse run of whatever it reads — an import for
a schema (billable), a materialization for a view. The person-property child runs off that run.
Returns False for an invalid source (→ 400). Requires editor access to the warehouse object (→ 403),
honors the team's warehouse sync pause (→ ``WarehouseSyncPausedError``), and rejects a view still on
the older data-modeling schedule (→ ``ViewNotSyncableError``)."""
binding = _triggerable_profile_binding(team_id, source_id)
if binding is None:
return False
_assert_warehouse_editor(team_id, binding, user_access_control)
from products.warehouse_sources.backend.facade.temporal import ( # noqa: PLC0415
ExternalDataSchemaSyncPausedError,
SavedQueryNotFoundError,
SavedQueryNotOnV2ScheduleError,
trigger_saved_query_materialization,
trigger_schema_sync,
)
# Open the run rows before the warehouse run starts, so the history shows it in progress right away
# and the trigger buttons stay disabled until it settles. The person-property activity reconciles
# them when the run reaches it (see record_sync_run).
created_source_ids = _create_running_runs(team_id, binding, SyncTrigger.SYNC.value)
try:
if binding.is_saved_query:
trigger_saved_query_materialization(team_id=team_id, saved_query_id=binding.id)
else:
trigger_schema_sync(team_id=team_id, schema_id=binding.id)
except ExternalDataSchemaSyncPausedError as e:
_fail_created_runs(team_id, created_source_ids, "Warehouse syncs are paused for this project")
raise WarehouseSyncPausedError(str(e)) from e
except (SavedQueryNotOnV2ScheduleError, SavedQueryNotFoundError) as e:
_fail_created_runs(team_id, created_source_ids, str(e))
raise ViewNotSyncableError(str(e)) from e
except Exception:
_fail_created_runs(team_id, created_source_ids, "Failed to start sync")
raise
return True
def trigger_person_property_backfill(
*, team_id: int, source_id: str, trigger: str = "manual", user_access_control: "UserAccessControl | None" = None
) -> bool | None:
"""Request a backfill for a profile source's table. Returns True when a new visible run starts,
False when an existing run receives a guaranteed latest-state follow-up, or None for an invalid
source (→ 400). Requires editor access to the warehouse object (→ 403)."""
binding = _triggerable_profile_binding(team_id, source_id)
if binding is None:
return None
_assert_warehouse_editor(team_id, binding, user_access_control)
# Placeholder rows before starting, so the activity always finds a running row to reconcile.
created_source_ids = _create_running_runs(team_id, binding, trigger)
# `created_source_ids` covers every enabled source on the binding, not just the one requested —
# a sibling source can pick up a fresh placeholder while this source's own run was already in
# flight and merely coalesced. Report 'started' only when the requested source is among them.
started_new_run = str(source_id) in {str(created_id) for created_id in created_source_ids}
from products.warehouse_sources.backend.facade.temporal import ( # noqa: PLC0415
WarehouseBindingMissingError,
start_person_property_backfill,
)
try:
start_person_property_backfill(team_id=team_id, binding=binding, trigger=trigger)
return started_new_run
except WarehouseBindingMissingError:
# The warehouse table or view was deleted after the placeholders were created; reconcile them
# so the source isn't stuck 'running', and report an invalid source (→ 400) rather than a
# coalesced run for a table that is gone.
_fail_created_runs(team_id, created_source_ids, "The warehouse table or view for this source no longer exists.")
return None
except Exception:
# The workflow never started; reconcile the placeholders so the source isn't stuck 'running'
# with its trigger disabled, then surface the error to the caller.
_fail_created_runs(team_id, created_source_ids, "Failed to start backfill")
raise
def list_custom_property_sources(
team_id: int,
*,
page: PageRequest,
user_access_control: "UserAccessControl | None" = None,
exclude_group_targets: bool = False,
) -> Page[contracts.CustomPropertySourceView]:
"""One page of the team's custom-property sources, newest first. Warehouse
schedule/run enrichment per source is gated on the caller's warehouse-source viewer access.
``exclude_group_targets`` hides sources feeding a group-target definition from callers without
``group`` read authorization."""
queryset = CustomPropertySource.objects.for_team(team_id).select_related("definition").order_by("-created_at")
if exclude_group_targets:
queryset = queryset.exclude(definition__target_type=TargetType.GROUP.value)
selected = select_page(queryset, page)
enrichment = _batch_source_enrichment(team_id, selected.results, user_access_control)
return selected.map(
lambda s: _to_custom_property_source_view(
s, user_access_control, enrichment.get(s.id, _RESOLVE_ENRICHMENT_INLINE)
)
)
def get_custom_property_source(
team_id: int, source_id: str, user_access_control: "UserAccessControl | None" = None
) -> contracts.CustomPropertySourceView | None:
source = CustomPropertySource.objects.for_team(team_id).select_related("definition").filter(id=source_id).first()
return _to_custom_property_source_view(source, user_access_control) if source is not None else None
def get_custom_property_source_binding_id(team_id: int, source_id: str) -> str | None:
"""The id of the warehouse object a source reads — its saved query for a view binding, its external
data schema for a table binding — or None when the source doesn't resolve or reads neither. Kept to
two id columns (no definition join, no view building) because the sync throttle calls it per request
to key its limit on the warehouse object rather than the mapping."""
try:
row = (
CustomPropertySource.objects.for_team(team_id)
.filter(id=source_id)
.values_list("saved_query_id", "external_data_schema_id")
.first()
)
except (ValidationError, ValueError): # a non-UUID id from the URL is simply unknown
return None
if row is None:
return None
saved_query_id, schema_id = row
binding_id = saved_query_id or schema_id
return str(binding_id) if binding_id is not None else None
def create_custom_property_source(
*,
team_id: int,
definition_id: str | UUID,
key_column: str,
is_enabled: bool,
user: "User",
saved_query_id: str | UUID | None = None,
source_column: str | None = None,
external_data_schema_id: str | UUID | None = None,
column_property_map: dict | None = None,
column_descriptions: dict | None = None,
user_access_control: "UserAccessControl | None" = None,
) -> contracts.CustomPropertySourceView:
definition = _get_custom_property_definition(team_id, definition_id)
if definition is None:
raise CustomPropertySourceValidationError("Custom property definition not found for this team.")
# The definition's target decides which binding is valid: an account source reads one saved-query
# column; a person/group source maps columns from either an imported schema's table or a
# materialized view onto profile properties.
create_kwargs: dict[str, Any] = {
"team_id": team_id,
"created_by": user,
"definition_id": definition_id,
"key_column": key_column,
"is_enabled": is_enabled,
}
if definition.target_type in _WAREHOUSE_PROFILE_TARGETS:
if saved_query_id is not None and external_data_schema_id is not None:
raise CustomPropertySourceValidationError(_ONE_PROFILE_BINDING_ERROR)
if source_column:
raise CustomPropertySourceValidationError(
"A person/group property source maps columns with column_property_map, not source_column."
)
# Validate the map shape in memory before the DB lookups below.
validated_map = _validate_column_property_map(column_property_map)
create_kwargs["column_property_map"] = validated_map
create_kwargs["column_descriptions"] = _validate_column_descriptions(
column_descriptions, set(validated_map.keys())
)
if saved_query_id is not None:
# An unmaterialized view has no table to read, so the source could never sync — reject it
# here rather than creating a mapping that stays silently empty.
if not _materialized_saved_query_belongs_to_team(team_id, saved_query_id):
raise CustomPropertySourceValidationError("Materialized view not found for this team.")
binding = saved_query_binding(saved_query_id)
create_kwargs["saved_query_id"] = saved_query_id
elif external_data_schema_id is not None:
if not _external_data_schema_belongs_to_team(team_id, external_data_schema_id):
raise CustomPropertySourceValidationError("Warehouse schema not found for this team.")
binding = schema_binding(external_data_schema_id)
create_kwargs["external_data_schema_id"] = external_data_schema_id
else:
raise CustomPropertySourceValidationError(_ONE_PROFILE_BINDING_ERROR)
# Mapping (and enabling) a warehouse table into profile properties drives real warehouse runs,
# so require the caller's editor access on what it reads, not account-scope editor alone.
_assert_warehouse_editor(team_id, binding, user_access_control)
else:
if saved_query_id is None or not source_column:
raise CustomPropertySourceValidationError(
"An account property source needs a saved_query and source_column."
)
if external_data_schema_id is not None or column_property_map is not None:
raise CustomPropertySourceValidationError(
"An account property source uses saved_query + source_column, not external_data_schema."
)
if not _saved_query_belongs_to_team(team_id, saved_query_id):
raise CustomPropertySourceValidationError("Saved query not found for this team.")
create_kwargs["saved_query_id"] = saved_query_id
create_kwargs["source_column"] = source_column
try:
source = CustomPropertySource.objects.for_team(team_id).create(**create_kwargs)
except IntegrityError as exc:
# Both FKs are team-validated above, so the only expected violation is the definition's
# one-to-one uniqueness; re-raise anything else instead of mislabeling it as a duplicate.
if "unique" not in str(exc).lower() and "duplicate" not in str(exc).lower():
raise
raise CustomPropertySourceValidationError("This custom property already has a source.")
_enqueue_initial_account_property_sync(source)
_start_person_backfill_if_enabled(source)
return _to_custom_property_source_view(source, user_access_control)
@transaction.atomic
def update_custom_property_source(
*, team_id: int, source_id: str, fields: dict[str, Any], user_access_control: "UserAccessControl | None" = None
) -> contracts.CustomPropertySourceView | None:
"""Apply writable fields to a team-scoped source. Re-enabling (is_enabled False→True) resets the
failure streak and clears the last error. Returns None (→ 404) when no source matches."""
source = (
CustomPropertySource.objects.for_team(team_id)
.select_for_update(of=("self",))
.select_related("definition")
.filter(id=source_id)
.first()
)
if source is None:
return None
fields = dict(fields)
profile_mapping_fields = {"column_property_map", "column_descriptions"}.intersection(fields)
if profile_mapping_fields:
if source.definition.target_type not in _WAREHOUSE_PROFILE_TARGETS:
if any(fields[field] is not None for field in profile_mapping_fields):
raise CustomPropertySourceValidationError(
"An account property source uses saved_query + source_column, not external_data_schema."
)
# Account GET responses include these profile-only fields as null. Treating those nulls as
# absent keeps the writable representation compatible with a GET/PATCH round trip.
for field in profile_mapping_fields:
fields.pop(field)
profile_mapping_fields.clear()
else:
validated_map = _validate_column_property_map(fields.get("column_property_map", source.column_property_map))
if "column_property_map" in fields:
fields["column_property_map"] = validated_map
if "column_descriptions" in fields:
fields["column_descriptions"] = _validate_column_descriptions(
fields["column_descriptions"], set(validated_map)
)
elif "column_property_map" in fields:
fields["column_descriptions"] = _validate_column_descriptions(
source.column_descriptions, set(validated_map)
)
reenabling = fields.get("is_enabled") is True and not source.is_enabled
mapping_changed = "column_property_map" in fields and fields["column_property_map"] != source.column_property_map
descriptions_changed = (
"column_descriptions" in fields and fields["column_descriptions"] != source.column_descriptions
)
columns_changed = any(
attr in fields and fields[attr] != getattr(source, attr) for attr in ("source_column", "key_column")
)
columns_changed = columns_changed or mapping_changed
# Profile mapping fields always require editor access to the bound warehouse object, including while
# disabled. Existing re-enable/column changes require it when they will trigger a backfill.
will_be_enabled = fields.get("is_enabled", source.is_enabled) is True
binding = _profile_binding(source)
if binding is not None and (profile_mapping_fields or (will_be_enabled and (reenabling or columns_changed))):
_assert_warehouse_editor(team_id, binding, user_access_control)
for attr, value in fields.items():
setattr(source, attr, value)
if reenabling:
source.consecutive_failures = 0
source.last_sync_error = None
source.save()
# Provenance names the source that writes a property, so only a source that will write claims it.
# Re-enabling runs a backfill, and that stamps the mapping the source has by then.
if binding is not None and will_be_enabled and (mapping_changed or descriptions_changed):
_stamp_profile_source_provenance(source, binding)
# Only re-sync on a change that affects what gets written — not on every (possibly no-op) PATCH.
if reenabling or columns_changed:
_enqueue_initial_account_property_sync(source)
if will_be_enabled:
_start_person_backfill_if_enabled(source)
return _to_custom_property_source_view(source, user_access_control)
def delete_custom_property_source(
*, team_id: int, source_id: str, user_access_control: "UserAccessControl | None" = None
) -> bool:
"""Delete a team-scoped source. Returns False when none matched (→ 404). Deleting a profile source
permanently stops its warehouse-driven updates, so it requires the caller's editor access on the
warehouse object (→ 403 via ``ResourceForbiddenError``), matching create/update/sync/backfill."""
source = CustomPropertySource.objects.for_team(team_id).select_related("definition").filter(id=source_id).first()
if source is None:
return False
_assert_warehouse_editor(team_id, _profile_binding(source), user_access_control)
deleted, _ = source.delete()
return deleted > 0
def list_custom_property_sync_runs(
team_id: int,
source_id: str,
*,
page: PageRequest,
user_access_control: "UserAccessControl | None" = None,
include_temporal_urls: bool = False,
search: str | None = None,
) -> Page[contracts.CustomPropertySyncRunView]:
"""One page of the warehouse-backed custom property sync runs of a source, newest first.
Scoped by team and source, so another team's or source's runs are never returned. Profile-source
histories require viewer access to their warehouse object; account-source histories are visible to
the same callers who can view the source."""
source = CustomPropertySource.objects.for_team(team_id).select_related("definition").filter(id=source_id).first()
if source is not None:
_assert_warehouse_viewer(team_id, _profile_binding(source), user_access_control)
queryset: QuerySet[CustomPropertySyncRun] = CustomPropertySyncRun.objects.for_team(team_id).filter(
source_id=source_id
)
if search:
queryset = cast(
"QuerySet[CustomPropertySyncRun]",
queryset.annotate(workflow_run_id_text=Cast("workflow_run_id", output_field=CharField())).filter(
Q(job_id__icontains=search)
| Q(workflow_id__icontains=search)
| Q(workflow_run_id_text__icontains=search)
| Q(status__icontains=search)
| Q(segment__icontains=search)
| Q(trigger__icontains=search)
| Q(error__icontains=search)
),
)
queryset = queryset.order_by("-created_at")
selected = select_page(queryset, page)
_expire_stale_running_runs(team_id, selected.results)
return selected.map(lambda run: _to_sync_run_view(run, include_temporal_url=include_temporal_urls))
FeatureRequestValidationError = _feature_requests_logic.FeatureRequestValidationError
FeatureRequestProductAreaConflictError = _feature_requests_logic.FeatureRequestProductAreaConflictError
FeatureRequestConflictError = _feature_requests_logic.FeatureRequestConflictError
GitHubLinkUnavailableError = _feature_request_github_logic.GitHubLinkUnavailableError
def list_feature_request_product_areas(
team_id: int, *, include_inactive: bool = False
) -> list[contracts.FeatureRequestProductAreaView]:
return _feature_requests_logic.list_product_areas(team_id, include_inactive=include_inactive)
def create_feature_request_product_area(
*, team_id: int, name: str, display_order: int, actor_id: int
) -> contracts.FeatureRequestProductAreaView:
return _feature_requests_logic.create_product_area(
team_id=team_id,
name=name,
display_order=display_order,
actor_id=actor_id,
)
def update_feature_request_product_area(
*,
team_id: int,
product_area_id: UUID,
name: str | None,
display_order: int | None,
is_active: bool | None,
actor_id: int,
) -> contracts.FeatureRequestProductAreaView | None:
return _feature_requests_logic.update_product_area(
team_id=team_id,
product_area_id=product_area_id,
name=name,
display_order=display_order,
is_active=is_active,
actor_id=actor_id,
)
def list_feature_requests(
*,
team_id: int,
user_access_control: "UserAccessControl",
filters: contracts.FeatureRequestListFilters,
page: PageRequest,
) -> Page[contracts.FeatureRequestView]:
return _feature_requests_logic.list_feature_requests(
team_id=team_id,
user_access_control=user_access_control,
filters=filters,
page=page,
)
def get_feature_request(
*, team_id: int, feature_request_id: UUID, user_access_control: "UserAccessControl"
) -> contracts.FeatureRequestView | None:
return _feature_requests_logic.get_feature_request(
team_id=team_id,
feature_request_id=feature_request_id,
user_access_control=user_access_control,
)
def create_feature_request(
*,
team_id: int,
input: contracts.CreateFeatureRequestInput,
actor_id: int,
user_access_control: "UserAccessControl",
) -> contracts.FeatureRequestCreateOutcome:
return _feature_requests_logic.create_feature_request(
team_id=team_id,
input=input,
actor_id=actor_id,
user_access_control=user_access_control,
)
def update_feature_request(
*,
team_id: int,
feature_request_id: UUID,
input: contracts.UpdateFeatureRequestInput,
actor_id: int,
user_access_control: "UserAccessControl",
) -> contracts.FeatureRequestView | None:
return _feature_requests_logic.update_feature_request(
team_id=team_id,
feature_request_id=feature_request_id,
input=input,
actor_id=actor_id,
user_access_control=user_access_control,
)
def link_feature_request_github(
*,
team_id: int,
feature_request_id: UUID,
input: contracts.LinkFeatureRequestGitHubInput,
actor_id: int,
user_access_control: "UserAccessControl",
) -> contracts.FeatureRequestView | None:
return _feature_request_github_logic.link_feature_request_github(
team_id=team_id,
feature_request_id=feature_request_id,
input=input,
actor_id=actor_id,
user_access_control=user_access_control,
)
def set_feature_request_github_sync(
*,
team_id: int,
feature_request_id: UUID,
expected_version: int,
enabled: bool,
actor_id: int,
user_access_control: "UserAccessControl",
) -> contracts.FeatureRequestView | None:
return _feature_request_github_logic.set_feature_request_github_sync(
team_id=team_id,
feature_request_id=feature_request_id,
expected_version=expected_version,
enabled=enabled,
actor_id=actor_id,
user_access_control=user_access_control,
)
def unlink_feature_request_github(
*,
team_id: int,
feature_request_id: UUID,
expected_version: int,
actor_id: int,
user_access_control: "UserAccessControl",
) -> contracts.FeatureRequestView | None:
return _feature_request_github_logic.unlink_feature_request_github(
team_id=team_id,
feature_request_id=feature_request_id,
expected_version=expected_version,
actor_id=actor_id,
user_access_control=user_access_control,
)
def process_feature_request_github_delivery(
*,
installation_id: str,
repository: str,
issue_number: int,
issue_title: str,
issue_state: str,
issue_state_reason: str,
github_updated_at: datetime,
github_delivery_id: str | None = None,
github_received_at: str | None = None,
) -> str:
from products.customer_analytics.backend.tasks.tasks import (
process_feature_request_github_issue, # noqa: PLC0415 — Celery task registration must stay off the facade import path
)
task = process_feature_request_github_issue.delay(
installation_id=installation_id,
repository=repository,
issue_number=issue_number,
issue_title=issue_title,
issue_state=issue_state,
issue_state_reason=issue_state_reason,
github_updated_at=github_updated_at.isoformat(),
github_delivery_id=github_delivery_id,
github_received_at=github_received_at,
)
return task.id
def add_feature_request_account(
*,
team_id: int,
feature_request_id: UUID,
input: contracts.AddFeatureRequestAccountInput,
actor_id: int,
user_access_control: "UserAccessControl",
) -> contracts.FeatureRequestView | None:
return _feature_requests_logic.add_feature_request_account(
team_id=team_id,
feature_request_id=feature_request_id,
input=input,
actor_id=actor_id,
user_access_control=user_access_control,
)
def create_feature_request_evidence(
*,
team_id: int,
feature_request_id: UUID,
input: contracts.CreateFeatureRequestEvidenceInput,
actor_id: int,
user_access_control: "UserAccessControl",
) -> contracts.FeatureRequestView | None:
return _feature_requests_logic.create_feature_request_evidence(
team_id=team_id,
feature_request_id=feature_request_id,
input=input,
actor_id=actor_id,
user_access_control=user_access_control,
)
def update_feature_request_evidence(
*,
team_id: int,
feature_request_id: UUID,
input: contracts.UpdateFeatureRequestEvidenceInput,
actor_id: int,
user_access_control: "UserAccessControl",
) -> contracts.FeatureRequestView | None:
return _feature_requests_logic.update_feature_request_evidence(
team_id=team_id,
feature_request_id=feature_request_id,
input=input,
actor_id=actor_id,
user_access_control=user_access_control,
)
def delete_feature_request_evidence(
*,
team_id: int,
feature_request_id: UUID,
input: contracts.DeleteFeatureRequestEvidenceInput,
actor_id: int,
user_access_control: "UserAccessControl",
) -> contracts.FeatureRequestView | None:
return _feature_requests_logic.delete_feature_request_evidence(
team_id=team_id,
feature_request_id=feature_request_id,
input=input,
actor_id=actor_id,
user_access_control=user_access_control,
)
def set_feature_request_archived(
*,
team_id: int,
feature_request_id: UUID,
expected_version: int,
archived: bool,
actor_id: int,
user_access_control: "UserAccessControl",
) -> contracts.FeatureRequestView | None:
return _feature_requests_logic.set_feature_request_archived(
team_id=team_id,
feature_request_id=feature_request_id,
expected_version=expected_version,
archived=archived,
actor_id=actor_id,
user_access_control=user_access_control,
)
def list_feature_request_history(
*, team_id: int, feature_request_id: UUID, user_access_control: "UserAccessControl"
) -> list[contracts.FeatureRequestHistoryView] | None:
return _feature_requests_logic.list_feature_request_history(
team_id=team_id,
feature_request_id=feature_request_id,
user_access_control=user_access_control,
)
def list_feature_request_status_history(
*, team_id: int, feature_request_id: UUID, user_access_control: "UserAccessControl"
) -> list[contracts.FeatureRequestStatusHistoryView] | None:
return _feature_requests_logic.list_feature_request_status_history(
team_id=team_id,
feature_request_id=feature_request_id,
user_access_control=user_access_control,
)
# --- CustomerJourney ---
def _to_customer_journey_view(journey: CustomerJourney) -> contracts.CustomerJourneyView:
return contracts.CustomerJourneyView(
id=journey.id,
insight=journey.insight_id,
name=journey.name,
description=journey.description,
created_at=journey.created_at,
created_by=journey.created_by_id,
updated_at=journey.updated_at,
)
def _customer_journeys_queryset(team_id: int):
"""Team-scoped customer journeys, ordered by creation. Object-level access filtering is
applied by the caller (list applies it; detail relies on the per-object check)."""
return CustomerJourney.objects.order_by("created_at").filter(team_id=team_id)
def insight_belongs_to_team(team_id: int, insight_id: int) -> bool:
"""Whether the given insight is in the team — backs the journey serializer's
``validate_insight`` (kept as a cheap existence probe so the model stays hidden)."""
from products.product_analytics.backend.facade.models import Insight
return Insight.objects.filter(pk=insight_id, team_id=team_id).exists()
def list_customer_journeys(
team_id: int, *, page: PageRequest, user_access_control: "UserAccessControl"
) -> Page[contracts.CustomerJourneyView]:
queryset = user_access_control.filter_queryset_by_access_level(_customer_journeys_queryset(team_id))
return select_page(queryset, page).map(_to_customer_journey_view)
def get_customer_journey(
team_id: int, journey_id: str, user_access_control: "UserAccessControl", required_level: str | None
) -> contracts.CustomerJourneyView:
"""Fetch one team-scoped journey, enforcing object-level access. Raises
``CustomerJourney.DoesNotExist`` (→ 404) when absent and ``ResourceForbiddenError``
(→ 403) when the caller lacks object access — mirroring the old viewset."""
journey = _get_object_or_raise(_customer_journeys_queryset(team_id), journey_id, CustomerJourney)
_enforce_object_access(journey, user_access_control, required_level)
return _to_customer_journey_view(journey)
def create_customer_journey(
*,
team_id: int,
insight_id: int,
name: str,
description: str | None,
organization_id,
user: "User",
was_impersonated: bool,
) -> contracts.CustomerJourneyView:
try:
journey = CustomerJourney.objects.create(
team_id=team_id, created_by=user, insight_id=insight_id, name=name, description=description
)
except IntegrityError:
raise CustomerJourneyConflictError("A customer journey already exists for this insight.")
_log_activity_swallowing(
instance=journey,
scope="CustomerJourney",
activity="created",
name=journey.name,
organization_id=organization_id,
team_id=team_id,
user=user,
was_impersonated=was_impersonated,
)
return _to_customer_journey_view(journey)
def update_customer_journey(
*,
team_id: int,
journey_id: str,
fields: dict[str, Any],
user_access_control: "UserAccessControl",
required_level: str | None,
organization_id,
user: "User",
was_impersonated: bool,
) -> contracts.CustomerJourneyView:
journey = _get_object_or_raise(_customer_journeys_queryset(team_id), journey_id, CustomerJourney)
_enforce_object_access(journey, user_access_control, required_level)
previous = CustomerJourney.objects.get(pk=journey.pk)
for attr, value in fields.items():
setattr(journey, attr, value)
journey.save()
_log_activity_swallowing(
instance=journey,
scope="CustomerJourney",
activity="updated",
name=journey.name,
organization_id=organization_id,
team_id=team_id,
user=user,
was_impersonated=was_impersonated,
previous=previous,
)
return _to_customer_journey_view(journey)
def delete_customer_journey(
*,
team_id: int,
journey_id: str,
user_access_control: "UserAccessControl",
required_level: str | None,
organization_id,
user: "User",
was_impersonated: bool,
) -> None:
journey = _get_object_or_raise(_customer_journeys_queryset(team_id), journey_id, CustomerJourney)
_enforce_object_access(journey, user_access_control, required_level)
_log_activity_swallowing(
instance=journey,
scope="CustomerJourney",
activity="deleted",
name=journey.name,
organization_id=organization_id,
team_id=team_id,
user=user,
was_impersonated=was_impersonated,
)
journey.delete()
# --- Account (full CRUD view) ---
def _account_view_tags(account: Account) -> list[str]:
"""Tags for an account, preferring the prefetched list when present (list path) so
the query budget stays flat — matching the old ``TaggedItemSerializerMixin``."""
if hasattr(account, "prefetched_tags"):
return [p.tag.name for p in account.prefetched_tags]
return list(account.tagged_items.values_list("tag__name", flat=True)) if account.pk else []
def _account_view_notebooks(account: Account) -> list[str]:
return [link.notebook.short_id for link in account.notebooks.all()]
def _to_account_details(account: Account) -> contracts.AccountDetails:
return contracts.AccountDetails(
id=account.id,
name=account.name,
external_id=account.external_id,
# Raw stored JSON (already ``exclude_unset`` from the manager), so an account with
# no assignments serializes ``properties`` as ``{}`` exactly as before. Retired role
# keys are dropped: rows not yet backfilled must not leak them into responses, or the
# frontend's read-modify-write of ``properties`` sends them back and gets a 400.
properties={k: v for k, v in (account._properties or {}).items() if k not in RETIRED_ROLE_KEYS},
# Unsorted, matching the old ``TaggedItemSerializerMixin.to_representation`` output.
tags=_account_view_tags(account),
notebooks=_account_view_notebooks(account),
slack_summary_cadence=account.slack_summary_cadence,
churned_at=account.churned_at,
ignored_at=account.ignored_at,
created_at=account.created_at,
created_by=account.created_by_id,
updated_at=account.updated_at,
)
class InvalidAccountTableColumn(ValueError):
pass
ACCOUNT_TABLE_MAX_HISTORY_POINTS = 50_000
def _account_table_field_values(
account: Account, fields: frozenset[contracts.AccountTableField]
) -> dict[contracts.AccountTableField, str | None]:
properties = account.properties
values: dict[contracts.AccountTableField, str | None] = {}
for field in sorted(fields, key=lambda account_field: account_field.value):
match field:
case contracts.AccountTableField.NAME:
values[field] = account.name
case contracts.AccountTableField.EXTERNAL_ID:
values[field] = account.external_id
case contracts.AccountTableField.CREATED_AT:
values[field] = account.created_at.isoformat() if account.created_at else None
case contracts.AccountTableField.UPDATED_AT:
values[field] = account.updated_at.isoformat() if account.updated_at else None
case contracts.AccountTableField.CHURNED_AT:
values[field] = account.churned_at.isoformat() if account.churned_at else None
case contracts.AccountTableField.IGNORED_AT:
values[field] = account.ignored_at.isoformat() if account.ignored_at else None
case contracts.AccountTableField.STRIPE_CUSTOMER_ID:
values[field] = properties.stripe_customer_id
case contracts.AccountTableField.HUBSPOT_DEAL_ID:
values[field] = properties.hubspot_deal_id
case contracts.AccountTableField.BILLING_ID:
values[field] = properties.billing_id
case contracts.AccountTableField.SFDC_ID:
values[field] = properties.sfdc_id
case contracts.AccountTableField.ZENDESK_ID:
values[field] = properties.zendesk_id
case _:
raise ValueError(f"Unsupported account table field: {field}")
return values
@frozen
class _AccountTableDefinitions:
selection: contracts.AccountTableColumnSelection
sort: contracts.AccountTableSort | None
relationships: dict[UUID, AccountRelationshipDefinition]
custom_properties: dict[UUID, CustomPropertyDefinition]
def filter_supported_filters(
self,
filters: tuple[contracts.AccountTableFilter, ...],
*,
ignore_invalid_custom_property_filters: bool,
) -> tuple[contracts.AccountTableFilter, ...]:
known_filters = tuple(
filter_
for filter_ in filters
if (
not isinstance(
filter_, contracts.AccountTableRelationshipFilter | contracts.AccountTableCustomPropertyFilter
)
or (
isinstance(filter_, contracts.AccountTableRelationshipFilter)
and filter_.definition_id in self.relationships
)
or (
isinstance(filter_, contracts.AccountTableCustomPropertyFilter)
and filter_.definition_id in self.custom_properties
)
)
)
if ignore_invalid_custom_property_filters:
return filter_valid_account_filters(known_filters, custom_property_display_types=self.display_types)
return known_filters
@property
def display_types(self) -> dict[UUID, DisplayType]:
return {id_: DisplayType(definition.display_type) for id_, definition in self.custom_properties.items()}
def _validate_account_table_definitions(
*,
team_id: int,
selection: contracts.AccountTableColumnSelection,
filters: tuple[contracts.AccountTableFilter, ...],
sort: contracts.AccountTableSort | None,
ignore_missing_definitions: bool = False,
) -> _AccountTableDefinitions:
relationship_ids = set(selection.relationship_definition_ids)
relationship_ids.update(
filter_.definition_id for filter_ in filters if isinstance(filter_, contracts.AccountTableRelationshipFilter)
)
if sort and sort.kind == contracts.AccountTableSortKind.RELATIONSHIP:
if sort.definition_id is None:
raise InvalidAccountTableColumn("Relationship sorting requires a definition.")
if sort.definition_id:
relationship_ids.add(sort.definition_id)
relationships = AccountRelationshipDefinition.objects.for_team(team_id).order_by("name", "id")
if not selection.use_default_columns:
relationships = relationships.filter(id__in=relationship_ids)
relationship_definitions = {definition.id: definition for definition in relationships}
invalid_relationship_ids = relationship_ids - relationship_definitions.keys()
if invalid_relationship_ids and not ignore_missing_definitions:
invalid_ids = ", ".join(sorted(str(definition_id) for definition_id in invalid_relationship_ids))
raise InvalidAccountTableColumn(f"Unknown relationship definitions: {invalid_ids}")
selected_relationship_ids = set(selection.relationship_definition_ids) & relationship_definitions.keys()
if selection.use_default_columns:
selected_relationship_ids.update(relationship_definitions)
selection = replace(
selection,
relationship_definition_ids=frozenset(selected_relationship_ids),
account_fields=frozenset({contracts.AccountTableField.NAME})
if selection.use_default_columns
else selection.account_fields,
include_tags=selection.use_default_columns or selection.include_tags,
include_note_count=selection.use_default_columns or selection.include_note_count,
)
custom_property_ids = set(selection.custom_property_definition_ids) | set(selection.custom_property_history_windows)
custom_property_ids.update(
filter_.definition_id for filter_ in filters if isinstance(filter_, contracts.AccountTableCustomPropertyFilter)
)
if sort and sort.kind == contracts.AccountTableSortKind.CUSTOM_PROPERTY:
if sort.definition_id is None:
raise InvalidAccountTableColumn("Custom property sorting requires a definition.")
custom_property_ids.add(sort.definition_id)
custom_properties = {
definition.id: definition
for definition in CustomPropertyDefinition.objects.for_team(team_id)
.filter(id__in=custom_property_ids, target_type=TargetType.ACCOUNT)
.select_related("source")
}
custom_property_display_types = {
id_: DisplayType(definition.display_type) for id_, definition in custom_properties.items()
}
invalid_custom_property_ids = custom_property_ids - set(custom_property_display_types)
if invalid_custom_property_ids and not ignore_missing_definitions:
invalid_ids = ", ".join(sorted(str(definition_id) for definition_id in invalid_custom_property_ids))
raise InvalidAccountTableColumn(f"Unknown account custom property definitions: {invalid_ids}")
selection = replace(
selection,
custom_property_definition_ids=frozenset(selection.custom_property_definition_ids & custom_properties.keys()),
custom_property_history_windows={
id_: days for id_, days in selection.custom_property_history_windows.items() if id_ in custom_properties
},
)
if sort and sort.definition_id is not None:
if (
sort.kind == contracts.AccountTableSortKind.RELATIONSHIP
and sort.definition_id not in relationship_definitions
) or (
sort.kind == contracts.AccountTableSortKind.CUSTOM_PROPERTY and sort.definition_id not in custom_properties
):
sort = None
definitions = _AccountTableDefinitions(
selection=selection, sort=sort, relationships=relationship_definitions, custom_properties=custom_properties
)
non_numeric_history_ids = {
definition_id
for definition_id in selection.custom_property_history_windows
if custom_property_display_types[definition_id].value not in NUMERIC_DISPLAY_TYPES
}
if non_numeric_history_ids:
invalid_ids = ", ".join(sorted(str(definition_id) for definition_id in non_numeric_history_ids))
raise InvalidAccountTableColumn(f"Custom property history requires numeric definitions: {invalid_ids}")
return definitions
LIFECYCLE_ACCOUNT_TABLE_FIELDS = frozenset(
{contracts.AccountTableField.CHURNED_AT, contracts.AccountTableField.IGNORED_AT}
)
def _selects_lifecycle_accounts(filters: tuple[contracts.AccountTableFilter, ...]) -> bool:
return any(
isinstance(filter_, contracts.AccountTableFieldFilter)
and filter_.field in LIFECYCLE_ACCOUNT_TABLE_FIELDS
and filter_.operator != contracts.AccountTableFieldOperator.IS_NOT_SET
for filter_ in filters
)
def _filter_out_hidden_lifecycle_accounts(
queryset: QuerySet[Account],
filters: tuple[contracts.AccountTableFilter, ...],
*,
include_churned: bool,
include_ignored: bool,
) -> QuerySet[Account]:
# Track Rules skip churned accounts, so a churned account keeps its ignored_at. Hiding either
# state here would drop accounts that a churned or ignored filter asks for.
if _selects_lifecycle_accounts(filters):
return queryset
if not include_churned:
queryset = queryset.filter(churned_at__isnull=True)
if not include_ignored:
queryset = queryset.filter(ignored_at__isnull=True)
return queryset
def _apply_account_table_filters(
queryset: QuerySet[Account],
*,
team_id: int,
user_access_control: "UserAccessControl",
filters: tuple[contracts.AccountTableFilter, ...],
filter_groups: tuple[tuple[contracts.AccountTableFilter, ...], ...],
custom_property_display_types: dict[UUID, DisplayType],
include_churned: bool,
include_ignored: bool,
) -> QuerySet[Account]:
member_external_ids_by_query: dict[str, tuple[str, ...]] = {}
for filter_ in filters:
if isinstance(filter_, contracts.AccountTableSearchFilter):
query = filter_.query.strip()
if parse_email_search(query) is not None:
member_external_ids_by_query[query] = _list_account_search_member_external_ids(
team_id, query, user_access_control
)
break
try:
queryset = apply_account_filters(
queryset,
team_id=team_id,
filters=filters,
custom_property_display_types=custom_property_display_types,
member_external_ids_by_query=member_external_ids_by_query,
)
if filter_groups:
matching_groups = Q()
for group in filter_groups:
group_query = _filter_out_hidden_lifecycle_accounts(
queryset,
filters + group,
include_churned=include_churned,
include_ignored=include_ignored,
)
group_query = apply_account_filters(
group_query,
team_id=team_id,
filters=group,
custom_property_display_types=custom_property_display_types,
)
matching_groups |= Q(pk__in=group_query.order_by().values("pk"))
queryset = queryset.filter(matching_groups)
return queryset
except InvalidAccountFilter as error:
raise InvalidAccountTableColumn(str(error)) from error
def _apply_account_table_sort(
queryset: QuerySet[Account],
*,
team_id: int,
sort: contracts.AccountTableSort | None,
) -> QuerySet[Account]:
if sort is None:
return queryset.order_by("-created_at", "-id")
if sort.kind == contracts.AccountTableSortKind.ACCOUNT_FIELD:
if sort.account_field is None:
raise InvalidAccountTableColumn("Account field sorting requires a field.")
direct_fields = {
contracts.AccountTableField.NAME: "name",
contracts.AccountTableField.EXTERNAL_ID: "external_id",
contracts.AccountTableField.CREATED_AT: "created_at",
contracts.AccountTableField.UPDATED_AT: "updated_at",
contracts.AccountTableField.CHURNED_AT: "churned_at",
contracts.AccountTableField.IGNORED_AT: "ignored_at",
}
if direct_field := direct_fields.get(sort.account_field):
queryset = queryset.annotate(_account_table_sort=F(direct_field))
else:
queryset = queryset.annotate(_account_table_sort=KeyTextTransform(sort.account_field.value, "_properties"))
elif sort.kind == contracts.AccountTableSortKind.TAGS:
tag_values = (
TaggedItem.objects.matching_outer(Account)
.filter(tag__team_id=team_id)
.values("object_uuid")
.annotate(value=ArrayAgg("tag__name", order_by="tag__name"))
.values("value")
)
queryset = queryset.annotate(_account_table_sort=Subquery(tag_values, output_field=ArrayField(CharField())))
elif sort.kind == contracts.AccountTableSortKind.NOTE_COUNT:
note_counts = (
ResourceNotebook.objects.filter(account_id=OuterRef("pk"))
.values("account_id")
.annotate(value=Count("id"))
.values("value")
)
queryset = queryset.annotate(
_account_table_sort=Coalesce(Subquery(note_counts, output_field=IntegerField()), Value(0))
)
elif sort.kind == contracts.AccountTableSortKind.RELATIONSHIP:
if sort.definition_id is None:
raise InvalidAccountTableColumn("Relationship sorting requires a definition.")
relationship_values = (
AccountRelationship.objects.for_team(team_id)
.filter(
account_id=OuterRef("pk"),
definition_id=sort.definition_id,
ended_at__isnull=True,
user_id__isnull=False,
)
.values("account_id")
.annotate(value=ArrayAgg("user_id", order_by="user_id"))
.values("value")
)
queryset = queryset.annotate(
_account_table_sort=Subquery(relationship_values, output_field=ArrayField(IntegerField()))
)
order = F("_account_table_sort")
primary_order = (
order.asc(nulls_last=True)
if sort.direction == contracts.AccountTableSortDirection.ASCENDING
else order.desc(nulls_last=True)
)
return queryset.order_by(primary_order, "id")
def _list_accounts_sorted_by_custom_property(
queryset: QuerySet[Account],
*,
team_id: int,
sort: contracts.AccountTableSort,
custom_property_display_types: dict[UUID, DisplayType],
offset: int,
limit: int,
) -> list[Account]:
if sort.definition_id is None:
raise InvalidAccountTableColumn("Custom property sorting requires a definition.")
value_field = {
DataType.STRING: "value_str",
DataType.NUMERIC: "value_num",
DataType.BOOLEAN: "value_bool",
DataType.DATETIME: "value_datetime",
}[DATA_TYPE_BY_DISPLAY_TYPE[custom_property_display_types[sort.definition_id]]]
sort_value = F(f"custom_property_values__{value_field}")
with_value = queryset.filter(
custom_property_values__team_id=team_id,
custom_property_values__definition_id=sort.definition_id,
custom_property_values__is_deleted=False,
**{f"custom_property_values__{value_field}__isnull": False},
).annotate(
_account_table_sort=(
Left(sort_value, SORT_VALUE_STR_PREFIX_LENGTH) if value_field == "value_str" else sort_value
),
)
sort_keys = [F("_account_table_sort"), *([sort_value] if value_field == "value_str" else [])]
if sort.direction == contracts.AccountTableSortDirection.ASCENDING:
with_value = with_value.order_by(*(key.asc() for key in sort_keys), "id")
else:
with_value = with_value.order_by(*(key.desc() for key in sort_keys), "-id")
accounts: list[Account] = list(with_value[offset : offset + limit])
if len(accounts) == limit:
return accounts
with_value_count = offset + len(accounts) if accounts or offset == 0 else with_value.count()
without_value = queryset.exclude(
Exists(
CustomPropertyValue.objects.for_team(team_id).filter(
account_id=OuterRef("pk"),
definition_id=sort.definition_id,
is_deleted=False,
**{f"{value_field}__isnull": False},
)
)
).order_by("id")
without_value_offset = max(offset - with_value_count, 0)
return accounts + list(without_value[without_value_offset : without_value_offset + limit - len(accounts)])
class _PercentileCont(Aggregate):
function = "PERCENTILE_CONT"
template = "%(function)s(0.5) WITHIN GROUP (ORDER BY %(expressions)s)%(filter)s"
output_field = FloatField()
def query_accounts_metrics(
*,
team_id: int,
user_access_control: "UserAccessControl",
filters: tuple[contracts.AccountTableFilter, ...],
metrics: tuple[contracts.AccountTableMetric, ...],
filter_groups: tuple[tuple[contracts.AccountTableFilter, ...], ...] = (),
include_churned: bool = False,
include_ignored: bool = False,
ignore_missing_definitions: bool = False,
) -> list[float | int | None]:
definition_ids = frozenset(
metric.definition_id
for metric in metrics
if isinstance(metric, contracts.AccountTableAggregateMetric | contracts.AccountTableCountThresholdMetric)
)
definitions = _validate_account_table_definitions(
team_id=team_id,
selection=contracts.AccountTableColumnSelection(custom_property_definition_ids=definition_ids),
filters=filters + tuple(filter_ for group in filter_groups for filter_ in group),
sort=None,
ignore_missing_definitions=ignore_missing_definitions,
)
filters = definitions.filter_supported_filters(
filters, ignore_invalid_custom_property_filters=ignore_missing_definitions
)
filter_groups = tuple(
known
for group in filter_groups
if (
known := definitions.filter_supported_filters(
group, ignore_invalid_custom_property_filters=ignore_missing_definitions
)
)
)
custom_property_display_types = definitions.display_types
non_numeric_definition_ids = {
definition_id
for definition_id in definition_ids
if definition_id in custom_property_display_types
and DATA_TYPE_BY_DISPLAY_TYPE[custom_property_display_types[definition_id]] != DataType.NUMERIC
}
if non_numeric_definition_ids and not ignore_missing_definitions:
raise InvalidAccountTableColumn("Account table metrics require numeric custom properties.")
accounts = _accounts_queryset(team_id, user_access_control)
if not filter_groups:
accounts = _filter_out_hidden_lifecycle_accounts(
accounts, filters, include_churned=include_churned, include_ignored=include_ignored
)
accounts = _apply_account_table_filters(
accounts,
team_id=team_id,
user_access_control=user_access_control,
filters=filters,
filter_groups=filter_groups,
custom_property_display_types=custom_property_display_types,
include_churned=include_churned,
include_ignored=include_ignored,
)
results: list[float | int | None] = [None] * len(metrics)
for index, metric in enumerate(metrics):
if isinstance(metric, contracts.AccountTableCountMetric):
results[index] = accounts.count()
aggregate_expressions: dict[str, Aggregate] = {}
for index, metric in enumerate(metrics):
alias = f"metric_{index}"
if isinstance(metric, contracts.AccountTableAggregateMetric | contracts.AccountTableCountThresholdMetric) and (
metric.definition_id not in custom_property_display_types
or metric.definition_id in non_numeric_definition_ids
):
continue
if isinstance(metric, contracts.AccountTableAggregateMetric):
aggregate_type = {
contracts.AccountTableAggregation.SUM: Sum,
contracts.AccountTableAggregation.AVERAGE: Avg,
contracts.AccountTableAggregation.MINIMUM: Min,
contracts.AccountTableAggregation.MAXIMUM: Max,
contracts.AccountTableAggregation.MEDIAN: _PercentileCont,
}[metric.aggregation]
aggregate_expressions[alias] = aggregate_type(
"value_num",
filter=Q(definition_id=metric.definition_id),
)
elif isinstance(metric, contracts.AccountTableCountThresholdMetric):
comparison = {
contracts.AccountTableThresholdOperator.GREATER_THAN: Q(value_num__gt=metric.value),
contracts.AccountTableThresholdOperator.GREATER_THAN_OR_EQUAL: Q(value_num__gte=metric.value),
contracts.AccountTableThresholdOperator.LESS_THAN: Q(value_num__lt=metric.value),
contracts.AccountTableThresholdOperator.LESS_THAN_OR_EQUAL: Q(value_num__lte=metric.value),
contracts.AccountTableThresholdOperator.EQUAL: Q(value_num=metric.value),
contracts.AccountTableThresholdOperator.NOT_EQUAL: ~Q(value_num=metric.value),
}[metric.operator]
aggregate_expressions[alias] = Count(
"account_id",
filter=Q(definition_id=metric.definition_id) & comparison,
)
if aggregate_expressions:
values = CustomPropertyValue.objects.for_team(team_id).filter(
account_id__in=accounts.order_by().values("id"),
is_deleted=False,
value_num__isnull=False,
)
aggregated = values.aggregate(**aggregate_expressions)
for index, metric in enumerate(metrics):
if f"metric_{index}" not in aggregated:
continue
value = aggregated.get(f"metric_{index}")
if isinstance(metric, contracts.AccountTableAggregateMetric) and value is not None:
results[index] = float(value) * (metric.scale if metric.scale is not None else 1)
elif isinstance(metric, contracts.AccountTableCountThresholdMetric):
results[index] = int(value or 0)
return results
def _resolve_account_logo_domain(account: Account) -> str | None:
properties = account.properties
return resolve_logo_domain(
website_domain=properties.website_domain,
email_domains=properties.email_domains,
)
def query_accounts_table(
*,
team_id: int,
user_access_control: "UserAccessControl",
selection: contracts.AccountTableColumnSelection,
filters: tuple[contracts.AccountTableFilter, ...],
sort: contracts.AccountTableSort | None,
offset: int,
limit: int,
filter_groups: tuple[tuple[contracts.AccountTableFilter, ...], ...] = (),
include_churned: bool = False,
include_ignored: bool = False,
ignore_missing_definitions: bool = False,
) -> contracts.AccountTablePage:
definitions = _validate_account_table_definitions(
team_id=team_id,
selection=selection,
filters=filters + tuple(filter_ for group in filter_groups for filter_ in group),
sort=sort,
ignore_missing_definitions=ignore_missing_definitions,
)
filters = definitions.filter_supported_filters(
filters, ignore_invalid_custom_property_filters=ignore_missing_definitions
)
filter_groups = tuple(
known
for group in filter_groups
if (
known := definitions.filter_supported_filters(
group, ignore_invalid_custom_property_filters=ignore_missing_definitions
)
)
)
custom_property_display_types = definitions.display_types
selection = definitions.selection
sort = definitions.sort
queryset = _accounts_queryset(team_id, user_access_control)
if not filter_groups:
queryset = _filter_out_hidden_lifecycle_accounts(
queryset, filters, include_churned=include_churned, include_ignored=include_ignored
)
queryset = _apply_account_table_filters(
queryset,
team_id=team_id,
user_access_control=user_access_control,
filters=filters,
filter_groups=filter_groups,
custom_property_display_types=custom_property_display_types,
include_churned=include_churned,
include_ignored=include_ignored,
)
if sort is not None and sort.kind == contracts.AccountTableSortKind.CUSTOM_PROPERTY:
fetched_accounts = _list_accounts_sorted_by_custom_property(
queryset,
team_id=team_id,
sort=sort,
custom_property_display_types=custom_property_display_types,
offset=offset,
limit=limit + 1,
)
else:
queryset = _apply_account_table_sort(queryset, team_id=team_id, sort=sort)
fetched_accounts = list(queryset[offset : offset + limit + 1])
has_more = len(fetched_accounts) > limit
accounts = fetched_accounts[:limit]
account_ids = [account.id for account in accounts]
tags_by_account: dict[UUID, list[str]] = {account_id: [] for account_id in account_ids}
if selection.include_tags:
for account_id, tag_name in (
TaggedItem.objects.for_objects(Account, account_ids)
.order_by("tag__name")
.values_list("object_uuid", "tag__name")
):
tags_by_account[account_id].append(tag_name)
note_counts_by_account: dict[UUID, int] = dict.fromkeys(account_ids, 0)
if selection.include_note_count:
for result in (
ResourceNotebook.objects.filter(account_id__in=account_ids).values("account_id").annotate(count=Count("id"))
):
note_counts_by_account[result["account_id"]] = result["count"]
relationship_ids = selection.relationship_definition_ids
sorted_relationship_ids = sorted(relationship_ids, key=lambda definition_id: definition_id.hex)
relationships_by_account: dict[UUID, dict[UUID, list[int]]] = {
account_id: {definition_id: [] for definition_id in sorted_relationship_ids} for account_id in account_ids
}
if relationship_ids:
for account_id, definition_id, user_id in (
AccountRelationship.objects.for_team(team_id)
.filter(
account_id__in=account_ids,
definition_id__in=relationship_ids,
ended_at__isnull=True,
user_id__isnull=False,
)
.order_by("user_id")
.values_list("account_id", "definition_id", "user_id")
):
relationships_by_account[account_id][definition_id].append(user_id)
custom_property_ids = selection.custom_property_definition_ids
sorted_custom_property_ids = sorted(custom_property_ids, key=lambda definition_id: definition_id.hex)
custom_properties_by_account: dict[UUID, dict[UUID, float | bool | str | None]] = {
account_id: dict.fromkeys(sorted_custom_property_ids) for account_id in account_ids
}
if custom_property_ids:
for value in CustomPropertyValue.objects.for_team(team_id).filter(
account_id__in=account_ids,
definition_id__in=custom_property_ids,
is_deleted=False,
):
custom_properties_by_account[value.account_id][value.definition_id] = _scalar_value_for_display_type(
value, custom_property_display_types[value.definition_id]
)
history_windows = selection.custom_property_history_windows
custom_property_history_by_account: dict[
UUID, dict[UUID, list[contracts.AccountTableCustomPropertyHistoryPoint]]
] = {account_id: {definition_id: [] for definition_id in history_windows} for account_id in account_ids}
if history_windows:
now = timezone.now()
history_filter = Q()
for definition_id, window_days in history_windows.items():
history_filter |= Q(definition_id=definition_id, created_at__gte=now - timedelta(days=window_days))
history_filter |= Q(definition_id=definition_id, is_deleted=False)
active_values = CustomPropertyValue.objects.for_team(team_id).filter(
account_id=OuterRef("account_id"),
definition_id=OuterRef("definition_id"),
is_deleted=False,
)
history_point_count = 0
history_values = (
CustomPropertyValue.objects.for_team(team_id)
.filter(history_filter, Exists(active_values), account_id__in=account_ids, value_num__isnull=False)
.order_by("created_at", "id")
.iterator(chunk_size=2_000)
)
for value in history_values:
history_point_count += 1
if history_point_count > ACCOUNT_TABLE_MAX_HISTORY_POINTS:
raise InvalidAccountTableColumn(
f"Account table queries support up to {ACCOUNT_TABLE_MAX_HISTORY_POINTS} history points."
)
assert value.value_num is not None
custom_property_history_by_account[value.account_id][value.definition_id].append(
contracts.AccountTableCustomPropertyHistoryPoint(
timestamp=value.created_at,
value=value.value_num,
)
)
rows = [
contracts.AccountTableRow(
id=account.id,
name=account.name,
external_id=account.external_id,
logo_domain=_resolve_account_logo_domain(account),
account_fields=_account_table_field_values(account, selection.account_fields),
tags=tags_by_account[account.id] if selection.include_tags else None,
note_count=note_counts_by_account[account.id] if selection.include_note_count else None,
relationships=relationships_by_account[account.id],
custom_properties=custom_properties_by_account[account.id],
custom_property_history=custom_property_history_by_account[account.id],
)
for account in accounts
]
workflow_reference_ids: frozenset[str] = (
frozenset(
cast(
list[str],
cache.get_or_set(
f"customer_analytics:account_table_workflow_references:{team_id}",
lambda: list(_custom_property_references_by_definition_id(team_id)),
timeout=60,
),
)
)
if definitions.custom_properties
else frozenset()
)
property_definitions = []
for definition in definitions.custom_properties.values():
try:
source_id = definition.source.id
except CustomPropertySource.DoesNotExist:
source_id = None
property_definitions.append(
contracts.AccountTableCustomPropertyDefinition(
id=definition.id,
name=definition.name,
description=definition.description,
display_type=definition.display_type,
is_big_number=definition.is_big_number,
is_canonical=definition.name in CANONICAL_DISPLAY_TYPE_BY_NAME,
has_workflow_reference=str(definition.id) in workflow_reference_ids,
source_id=source_id,
options=definition.options,
)
)
return contracts.AccountTablePage(
rows=rows,
has_more=has_more,
limit=limit,
offset=offset,
relationship_definitions=[
_to_account_relationship_definition(definition) for definition in definitions.relationships.values()
],
custom_property_definitions=property_definitions,
)
def list_accounts_for_view(
*,
team_id: int,
user_access_control: "UserAccessControl",
page: PageRequest,
search: str | None = None,
tags: list[str] | None = None,
all_roles_unassigned: bool = False,
include_churned: bool = False,
include_ignored: bool = False,
ordering: str | None = None,
inactive_last: bool = False,
) -> Page[contracts.AccountDetails]:
"""The accounts list endpoint, behind the facade: team + object-level access filtering,
the search / tags / unassigned / ordering query filters, notebook + tag prefetching, and
pagination. ``tags``/``ordering`` are pre-validated by
the view; an empty ``tags`` list is treated as "no tag filter" (matches old behavior)."""
queryset = _accounts_queryset(team_id, user_access_control).prefetch_related(
Prefetch("notebooks", queryset=ResourceNotebook.objects.select_related("notebook")),
Prefetch("tagged_items", queryset=TaggedItem.objects.select_related("tag"), to_attr="prefetched_tags"),
)
if not include_churned:
queryset = queryset.filter(churned_at__isnull=True)
if not include_ignored:
queryset = queryset.filter(ignored_at__isnull=True)
if search:
queryset = queryset.filter(_get_account_search_q(team_id, search, user_access_control))
if tags:
queryset = queryset.filter(tagged_items__tag__name__in=tags).distinct()
# "Unassigned" means nobody actively holds any relationship on the account, matching the
# accounts list HogQL runner's allRolesUnassigned.
if all_roles_unassigned:
queryset = queryset.exclude(
id__in=AccountRelationship.objects.for_team(team_id)
.filter(ended_at__isnull=True, user__isnull=False)
.values("account_id")
)
order_fields = [ordering or "-created_at"]
if inactive_last:
queryset = queryset.annotate(
is_inactive=ExpressionWrapper(
Q(churned_at__isnull=False) | Q(ignored_at__isnull=False), output_field=BooleanField()
)
)
order_fields.insert(0, "is_inactive")
queryset = queryset.order_by(*order_fields)
return select_page(queryset, page).map(_to_account_details)
def get_account_for_view(
*, team_id: int, account_id: str, user_access_control: "UserAccessControl", required_level: str | None
) -> contracts.AccountDetails:
"""Fetch one team-scoped account with tags + notebooks, enforcing object-level access.
Raises ``Account.DoesNotExist`` (→ 404) / ``ResourceForbiddenError`` (→ 403)."""
account = _get_account_for_detail(team_id, account_id)
_enforce_object_access(account, user_access_control, required_level)
return _to_account_details(account)
def get_account_for_view_by_external_id(
*, team_id: int, external_id: str, user_access_control: "UserAccessControl", required_level: str | None
) -> contracts.AccountDetails:
account = _account_detail_queryset(team_id).get(external_id=external_id)
_enforce_object_access(account, user_access_control, required_level)
return _to_account_details(account)
class _Unset(Enum):
UNSET = "unset"
_UNSET = _Unset.UNSET
def _cap_to_field_length(field_name: str, value: str) -> str:
max_length = cast(CharField, Account._meta.get_field(field_name)).max_length
return value[:max_length]
def _enqueue_meeting_rematch(team_id: int, account_id: str) -> None:
try:
current_app.send_task(
"customer_analytics.rematch_account_meetings",
kwargs={"team_id": team_id, "account_id": account_id},
)
except Exception as error:
capture_exception(error)
def update_account(
account: Account,
*,
name: str | _Unset = _UNSET,
external_id: str | None | _Unset = _UNSET,
properties: "dict | _ModelAccountProperties | _Unset" = _UNSET,
slack_summary_cadence: "str | None | _Unset" = _UNSET,
churned_at: "datetime | None | _Unset" = _UNSET,
ignored_at: "datetime | None | _Unset" = _UNSET,
allow_matching_updates: bool = False,
) -> Account:
"""Field-write primitive shared by every account update path. Only the fields passed are
written; ``properties`` replaces the stored JSON wholesale. Product-internal — takes and
returns the model, so it must not be called across the product boundary."""
update_fields: list[str] = []
matching_expanded = False
matching_changed = False
external_id_changed = False
previous_known_emails: list[str] = []
previous_email_domains: list[str] = []
if not isinstance(name, _Unset):
account.name = _cap_to_field_length("name", name)
update_fields.append("name")
if not isinstance(external_id, _Unset):
next_external_id = _cap_to_field_length("external_id", external_id) if external_id is not None else None
external_id_changed = next_external_id != account.external_id
account.external_id = next_external_id
update_fields.append("external_id")
if not isinstance(properties, _Unset):
previous_properties = account.properties
previous_known_emails = previous_properties.known_emails
previous_email_domains = previous_properties.email_domains
validated_properties = _ModelAccountProperties.from_input(properties)
known_emails_added = set(validated_properties.known_emails) - set(previous_properties.known_emails)
email_domains_added = set(validated_properties.email_domains) - set(previous_properties.email_domains)
matching_changed = set(validated_properties.known_emails) != set(previous_properties.known_emails) or set(
validated_properties.email_domains
) != set(previous_properties.email_domains)
if matching_changed and not allow_matching_updates:
raise ResourceForbiddenError
matching_expanded = bool(known_emails_added or email_domains_added)
account._properties = validated_properties.model_dump(mode="json", exclude_unset=True)
update_fields.append("_properties")
if not isinstance(slack_summary_cadence, _Unset):
account.slack_summary_cadence = slack_summary_cadence
update_fields.append("slack_summary_cadence")
if not isinstance(churned_at, _Unset):
account.churned_at = churned_at
update_fields.append("churned_at")
if not isinstance(ignored_at, _Unset):
account.ignored_at = ignored_at
update_fields.append("ignored_at")
if update_fields:
account.save(update_fields=update_fields)
if matching_expanded:
transaction.on_commit(lambda: _enqueue_meeting_rematch(account.team_id, str(account.id)))
if external_id_changed:
schedule_email_thread_link_recalculation(account.team_id)
elif matching_changed:
schedule_email_thread_link_recalculation_for_account_properties(
account.team_id,
str(account.id),
previous_known_emails=previous_known_emails,
previous_email_domains=previous_email_domains,
)
return account
def create_account(
*,
team: Team,
name: str,
created_by: "User | None" = None,
external_id: str | None = None,
properties: "dict | _ModelAccountProperties | None" = None,
tags: list[str] | None = None,
slack_summary_cadence: str | None = None,
churned_at: datetime | None = None,
ignored_at: datetime | None = None,
was_impersonated: bool = False,
trigger: Trigger | None = None,
) -> Account:
"""The single account-creation write path: validates properties, sets tags, and logs
activity. Product-internal — it returns the model, so it must not be called across the
product boundary.
Raises ``AccountPropertiesValidationError`` / ``AccountConflictError``."""
try:
with transaction.atomic():
validated = _ModelAccountProperties.from_input(properties or {})
account = Account.objects.unscoped().create(
team=team,
created_by=created_by,
name=_cap_to_field_length("name", name),
external_id=_cap_to_field_length("external_id", external_id) if external_id is not None else None,
_properties=validated.model_dump(mode="json", exclude_unset=True),
slack_summary_cadence=slack_summary_cadence,
churned_at=churned_at,
ignored_at=ignored_at,
)
_set_tags(tags, account, actor=created_by)
except PydanticValidationError as exc:
raise AccountPropertiesValidationError(_format_pydantic_errors(exc))
except IntegrityError:
raise AccountConflictError("An account with this external_id already exists for this team.")
_log_activity_swallowing(
instance=account,
scope="Account",
activity="created",
name=account.name,
organization_id=team.organization_id,
team_id=team.pk,
user=created_by,
was_impersonated=was_impersonated,
trigger=trigger,
)
return account
def create_account_for_view(
*,
team: Team,
input: contracts.CreateAccountInput,
user: "User",
was_impersonated: bool,
) -> contracts.AccountDetails:
account = create_account(
team=team,
created_by=user,
name=input.name,
external_id=input.external_id,
properties=input.properties,
tags=input.tags,
slack_summary_cadence=input.slack_summary_cadence,
churned_at=input.churned_at,
ignored_at=input.ignored_at,
was_impersonated=was_impersonated,
)
return _to_account_details(account)
def update_account_for_view(
*,
team_id: int,
account_id: str,
input: contracts.UpdateAccountInput,
user_access_control: "UserAccessControl",
required_level: str | None,
organization_id,
user: "User",
was_impersonated: bool,
allow_matching_updates: bool = False,
) -> contracts.AccountDetails:
account = _get_account_for_detail(team_id, account_id)
_enforce_object_access(account, user_access_control, required_level)
previous = Account.objects.unscoped().get(pk=account.pk)
update_kwargs: dict[str, Any] = {}
if input.name is not None:
update_kwargs["name"] = input.name
if input.external_id_provided:
update_kwargs["external_id"] = input.external_id
if input.properties_provided:
update_kwargs["properties"] = input.properties if input.properties is not None else {}
if input.slack_summary_cadence_provided:
update_kwargs["slack_summary_cadence"] = input.slack_summary_cadence
if input.churned_at_provided:
update_kwargs["churned_at"] = input.churned_at
if input.ignored_at_provided:
update_kwargs["ignored_at"] = input.ignored_at
update_kwargs["allow_matching_updates"] = allow_matching_updates
try:
with transaction.atomic():
account = update_account(account, **update_kwargs)
_set_tags(input.tags, account, actor=user)
if input.external_id_provided and account.external_id != previous.external_id:
# The external_id is the account's group key — every stream filtering on
# the old key must be rebuilt or it keeps streaming the stale key's events.
for stream in _event_streams_containing_account(account):
sync_event_stream_destination(stream, team=account.team, user=user)
except PydanticValidationError as exc:
raise AccountPropertiesValidationError(_format_pydantic_errors(exc))
except IntegrityError:
raise AccountConflictError("An account with this external_id already exists for this team.")
_log_activity_swallowing(
instance=account,
scope="Account",
activity="updated",
name=account.name,
organization_id=organization_id,
team_id=team_id,
user=user,
was_impersonated=was_impersonated,
previous=previous,
)
# Off-to-on only: the coordinator picks a mid-flight cadence change up within the hour,
# and one backfill per switch is LLM spend nobody asked for.
if not previous.slack_summary_cadence and account.slack_summary_cadence:
_dispatch_initial_channel_summary(account)
return _to_account_details(account)
# Roughly 70 accounts opting into a daily cadence in one day, far above real use.
CHANNEL_SUMMARY_BACKFILL_DAILY_CAP = 500
def _reserve_backfill_budget(team_id: int, requested: int) -> int:
"""How many of ``requested`` backfill dispatches this team may still start today.
The coordinator throttles itself with per-run caps, but these dispatches are driven by
an API call, so one caller opting in many channel-bound accounts could otherwise start
unbounded LLM work in a burst. ``cache.incr`` is atomic, so parallel requests cannot all
slip under the ceiling. Whatever this refuses, the coordinator still summarizes on
schedule.
"""
window = int(datetime.now(UTC).timestamp()) // 86400
key = f"ca_channel_summary_backfills:{team_id}:{window}"
cache.add(key, 0, timeout=86400)
try:
used = cache.incr(key, requested)
except ValueError:
# The key expired between add and incr; this request is the window's first.
used = requested
allowed = requested - max(0, used - CHANNEL_SUMMARY_BACKFILL_DAILY_CAP)
return max(0, allowed)
def _dispatch_initial_channel_summary(account: Account) -> None:
cadence = account.slack_summary_cadence
slack_channel_id = (account._properties or {}).get("slack_channel_id")
if not cadence or not slack_channel_id:
return
periods = _channel_summaries_logic.get_initial_summary_periods(cadence, timezone.now(), account.team.timezone_info)
allowed = _reserve_backfill_budget(account.team_id, len(periods))
if allowed < len(periods):
logger.warning(
"channel_summary_backfill_throttled",
team_id=account.team_id,
requested=len(periods),
allowed=allowed,
)
# Newest first, so a partly-throttled backfill keeps the periods a user looks at first.
for period in sorted(periods, key=lambda p: p.start, reverse=True)[:allowed]:
try:
trigger_immediate_channel_summary(
team_id=account.team_id,
account_id=str(account.id),
account_name=account.name,
slack_channel_id=slack_channel_id,
cadence=cadence,
period_start=period.start,
period_end=period.end,
)
except Exception as e:
# Per period, so one bad dispatch doesn't drop the rest.
capture_exception(
e,
{
"team_id": account.team_id,
"account_id": str(account.id),
"period_start": period.start.isoformat(),
},
)
def delete_account_for_view(
*,
team_id: int,
account_id: str,
user_access_control: "UserAccessControl",
required_level: str | None,
organization_id,
user: "User",
was_impersonated: bool,
) -> None:
account = _get_account_for_detail(team_id, account_id)
_enforce_object_access(account, user_access_control, required_level)
with transaction.atomic():
# Authority is checked under the same account lock enrollment and claims take, so an account
# that became managed a moment ago cannot be deleted on a stale read. The definitions its rows
# sit under are locked too, so none can become controlled before the cascade runs.
locked, definitions = _relationships_logic.lock_account_and_its_definitions(team_id, account.id)
if locked is None:
raise Account.DoesNotExist
is_managed = AccountRelationshipControl.objects.for_team(team_id).filter(account=locked).exists()
# The cascade would take relationship rows with it, so rows under a controlled definition
# refuse the account's deletion the way they refuse their own.
has_controlled_history = any(definition.is_controlled for definition in definitions)
if is_managed or has_controlled_history:
raise AccountOwnershipManagedError(account_id)
_log_activity_swallowing(
instance=account,
scope="Account",
activity="deleted",
name=account.name,
organization_id=organization_id,
team_id=team_id,
user=user,
was_impersonated=was_impersonated,
)
# Streams referencing this account must be captured before the delete cascades
# their membership rows away, then resynced so the account's group key doesn't
# linger in a Slack destination filter.
streams = _event_streams_containing_account(account)
team = account.team
_customer_tasks_logic.remove_customer_task_assignee_access_for_account(team=team, account_id=account.id)
account.delete()
schedule_email_thread_link_recalculation(team_id)
for stream in streams:
sync_event_stream_destination(stream, team=team, user=user)
def _account_detail_queryset(team_id: int) -> QuerySet[Account]:
return Account.objects.for_team(team_id).prefetch_related(
Prefetch("notebooks", queryset=ResourceNotebook.objects.select_related("notebook")),
Prefetch("tagged_items", queryset=TaggedItem.objects.select_related("tag"), to_attr="prefetched_tags"),
)
def _get_account_for_detail(team_id: int, account_id: str) -> Account:
"""Team-scoped account fetch for detail/write paths (object-level access is enforced
separately). Prefetches notebooks + tags so the returned view renders without extra
queries, matching the old viewset's ``safely_get_queryset`` + tag-mixin prefetch.
Raises ``Account.DoesNotExist`` when not found in the team."""
return _get_object_or_raise(_account_detail_queryset(team_id), account_id, Account)
# --- AccountNotebook (nested under an account) ---
def _to_user_basic_info(user: "User | None") -> contracts.UserBasicInfo | None:
# None when the notebook has no creator/modifier — the old nested
# ``UserBasicSerializer`` rendered ``null`` for a null FK, so preserve that.
if user is None:
return None
return contracts.UserBasicInfo(
id=user.id,
uuid=user.uuid,
distinct_id=user.distinct_id,
first_name=user.first_name,
last_name=user.last_name,
email=user.email,
is_email_verified=user.is_email_verified,
hedgehog_config=user.hedgehog_config,
role_at_organization=user.role_at_organization,
)
def _notebook_user_to_basic_info(
user: "notebook_contracts.NotebookUserInfo | None",
) -> contracts.UserBasicInfo | None:
if user is None:
return None
return contracts.UserBasicInfo(
id=user.id,
uuid=user.uuid,
distinct_id=user.distinct_id,
first_name=user.first_name,
last_name=user.last_name,
email=user.email,
is_email_verified=user.is_email_verified,
hedgehog_config=user.hedgehog_config,
role_at_organization=user.role_at_organization,
)
def _to_account_notebook_view(notebook: "notebook_contracts.AccountNotebook") -> contracts.AccountNotebookView:
return contracts.AccountNotebookView(
id=notebook.id,
short_id=notebook.short_id,
title=notebook.title,
content=notebook.content,
text_content=notebook.text_content,
created_at=notebook.created_at,
created_by=_notebook_user_to_basic_info(notebook.created_by),
last_modified_at=notebook.last_modified_at,
last_modified_by=_notebook_user_to_basic_info(notebook.last_modified_by),
)
def get_accessible_account_id(team_id: int, account_id: str, user_access_control: "UserAccessControl") -> str | None:
"""The account_id when the caller has object-level access to that team-scoped account,
else None — backs the notebook viewset's parent-account gate (object denial → 404,
via filtering rather than a permission check)."""
queryset = user_access_control.filter_queryset_by_access_level(Account.objects.unscoped().filter(team_id=team_id))
try:
account = queryset.filter(id=account_id).first()
except (ValidationError, ValueError):
return None
return str(account.id) if account is not None else None
def list_account_presence_viewers(
team_id: int,
account_id: str,
user_access_control: "UserAccessControl",
user: "User",
) -> list[contracts.AccountPresenceViewer] | None:
accessible_account_id = get_accessible_account_id(team_id, account_id, user_access_control)
if accessible_account_id is None:
return None
display_name = user.get_full_name().strip() or user.first_name.strip() or "A teammate"
return _account_presence_logic.heartbeat_account_presence(
team_id=team_id,
account_id=accessible_account_id,
viewer=contracts.AccountPresenceViewer(user_id=user.id, display_name=display_name),
)
def list_accounts_presence(
team_id: int,
account_ids: list[str],
user_access_control: "UserAccessControl",
*,
viewer_user_id: int | None,
) -> list[contracts.AccountPresence]:
accessible_account_ids = list(
user_access_control.filter_queryset_by_access_level(
Account.objects.unscoped().filter(team_id=team_id, id__in=account_ids)
).values_list("id", flat=True)
)
viewers_by_account_id = _account_presence_logic.list_account_presence(
team_id=team_id, account_ids=[str(account_id) for account_id in accessible_account_ids]
)
return [
contracts.AccountPresence(
account_id=account_id,
viewers=[
viewer for viewer in viewers_by_account_id.get(str(account_id), []) if viewer.user_id != viewer_user_id
],
)
for account_id in accessible_account_ids
]
def get_editable_account_id(team_id: int, account_id: str, user_access_control: "UserAccessControl") -> str | None:
"""The account_id when the caller can edit that account, else None."""
account = _resolve_accessible_account(team_id, user_access_control, account_id=account_id)
if account is None or not user_access_control.check_access_level_for_object(account, required_level="editor"):
return None
return str(account.id)
def list_account_channel_summaries(
team_id: int,
account_id: str,
user_access_control: "UserAccessControl",
*,
page: PageRequest,
) -> Page[contracts.AccountChannelSummaryView] | None:
"""One page of the stored Slack channel summaries of an accessible account, newest period first.
None when the parent account isn't accessible (→ 404)."""
if get_accessible_account_id(team_id, account_id, user_access_control) is None:
return None
queryset = (
AccountChannelSummary.objects.for_team(team_id)
.filter(account_id=account_id)
.order_by("-period_start", "-generated_at")
)
return select_page(queryset, page).map(_to_channel_summary_view)
def _to_channel_summary_view(summary: AccountChannelSummary) -> contracts.AccountChannelSummaryView:
return contracts.AccountChannelSummaryView(
id=summary.id,
slack_channel_id=summary.slack_channel_id,
cadence=summary.cadence,
period_start=summary.period_start,
period_end=summary.period_end,
content=summary.content,
message_count=summary.message_count,
messages=summary.messages,
generated_at=summary.generated_at,
)
def list_accounts_due_for_slack_summary(now: datetime | None = None) -> list[contracts.AccountDueForSlackSummary]:
"""Accounts opted into periodic Slack channel summaries whose last closed period has no
stored summary yet. Cross-team — backs the conversations summary coordinator.
Due means: a cadence is set, a Slack channel is bound, and no summary row exists for
``(account, cadence, period_start)`` where the period is the last closed calendar window
in the account team's timezone. A cadence change mid-period only ever looks at the
current cadence's own last closed window — no retro-generation.
"""
now = now or timezone.now()
candidates: list[contracts.AccountDueForSlackSummary] = []
for account in (
Account.objects.unscoped().filter(slack_summary_cadence__isnull=False).select_related("team").iterator()
):
# Raw dict read: one account with stored properties that no longer validate must not
# take the whole coordinator scan down.
slack_channel_id = (account._properties or {}).get("slack_channel_id")
cadence = account.slack_summary_cadence
if not slack_channel_id or not cadence:
continue
period = _channel_summaries_logic.get_last_closed_period(cadence, now, account.team.timezone_info)
candidates.append(
contracts.AccountDueForSlackSummary(
team_id=account.team_id,
account_id=str(account.id),
account_name=account.name,
slack_channel_id=slack_channel_id,
cadence=cadence,
period_start=period.start,
period_end=period.end,
)
)
if not candidates:
return []
existing = set(
AccountChannelSummary.objects.unscoped()
.filter(
account_id__in=[c.account_id for c in candidates],
period_start__in={c.period_start for c in candidates},
)
.values_list("account_id", "cadence", "period_start")
)
return [c for c in candidates if (UUID(c.account_id), c.cadence, c.period_start) not in existing]
def get_account_slack_summary_binding(team_id: int, account_id: str) -> contracts.AccountSlackSummaryBinding | None:
"""The account's current summary cadence and channel binding, or None when the
account is gone or no longer opted in. Backs the summary activity's recheck just
before messages are fetched and sent to the LLM: consent or binding changes after
coordinator dispatch must cancel the queued summary."""
account = Account.objects.for_team(team_id).filter(id=account_id).first()
if account is None or not account.slack_summary_cadence:
return None
slack_channel_id = (account._properties or {}).get("slack_channel_id")
if not slack_channel_id:
return None
return contracts.AccountSlackSummaryBinding(
cadence=account.slack_summary_cadence, slack_channel_id=slack_channel_id
)
def record_channel_summary(
*,
team_id: int,
account_id: str,
slack_channel_id: str,
cadence: str,
period_start: datetime,
period_end: datetime,
content: str,
message_count: int,
messages: list[dict] | None = None,
model_name: str = "",
) -> str | None:
"""Store a finished channel summary pushed in by the conversations pipeline.
``messages`` is the per-message audit metadata ([{author, sent_at, permalink}]),
never message text.
Idempotent on ``(team, account, cadence, period_start)``: a retry or overlapping run
resolves to the existing row's id instead of double-writing. Returns None when the
account no longer exists (deleted mid-flight) — the period's summary is simply dropped.
"""
if not Account.objects.for_team(team_id).filter(id=account_id).exists():
return None
try:
# atomic() so the duplicate-key error rolls back to a savepoint and the
# existing-row lookup below still has a usable connection.
with transaction.atomic():
summary = AccountChannelSummary.objects.for_team(team_id).create(
team_id=team_id,
account_id=account_id,
slack_channel_id=slack_channel_id,
cadence=cadence,
period_start=period_start,
period_end=period_end,
content=content,
message_count=message_count,
messages=messages or [],
model_name=model_name,
)
except IntegrityError:
existing = (
AccountChannelSummary.objects.for_team(team_id)
.filter(account_id=account_id, cadence=cadence, period_start=period_start)
.first()
)
return str(existing.id) if existing is not None else None
return str(summary.id)
def get_account_support_tickets(
team_id: int,
account_id: str,
user_access_control: "UserAccessControl",
*,
limit: int = 50,
) -> list[TicketSummary] | None:
"""Support tickets (from the conversations product) for an accessible account, newest activity
first. None when the parent account isn't accessible (→ 404); an empty list when the account
has no linked customer org key, or has one but no matching tickets.
Raises :class:`ResourceForbiddenError` (→ 403) when the caller can read the account but not
tickets — this endpoint is authorized as ``account`` while the payload is ticket content, so
the ``ticket`` resource has to be gated separately or this path bypasses its RBAC."""
if get_accessible_account_id(team_id, account_id, user_access_control) is None:
return None
if not user_access_control.check_access_level_for_resource("ticket", "viewer"):
raise ResourceForbiddenError()
account = _resolve_account(team_id, account_id=account_id)
if account is None or not account.external_id:
return []
return list_account_tickets(team_id, account.external_id, user_access_control, limit=limit)
def get_account_support_ticket_messages(
team_id: int,
account_id: str,
ticket_id: str,
user_access_control: "UserAccessControl",
*,
page: PageRequest,
) -> Page[SupportTicketMessage] | None:
if get_accessible_account_id(team_id, account_id, user_access_control) is None:
return None
if not user_access_control.check_access_level_for_resource("ticket", "viewer"):
raise ResourceForbiddenError()
account = _resolve_account(team_id, account_id=account_id)
if account is None or not account.external_id:
return None
result = list_account_ticket_messages(
team_id,
account.external_id,
ticket_id,
user_access_control,
offset=page.offset,
limit=page.limit,
)
if result is None:
return None
messages, count = result
return Page(results=messages, count=count)
def get_account_email_threads(
team_id: int,
account_id: str,
user_access_control: "UserAccessControl",
*,
page: PageRequest,
) -> Page[AccountEmailThreadSummary] | None:
if get_accessible_account_id(team_id, account_id, user_access_control) is None:
return None
if not user_access_control.check_access_level_for_resource("ticket", "viewer"):
raise ResourceForbiddenError()
threads, count = list_account_email_threads(team_id, account_id, offset=page.offset, limit=page.limit)
return Page(results=threads, count=count)
def get_account_email_thread_messages(
team_id: int,
account_id: str,
thread_id: str,
user_access_control: "UserAccessControl",
*,
page: PageRequest,
) -> Page[AccountEmailThreadMessage] | None:
if get_accessible_account_id(team_id, account_id, user_access_control) is None:
return None
if not user_access_control.check_access_level_for_resource("ticket", "viewer"):
raise ResourceForbiddenError()
result = list_account_email_thread_messages(team_id, account_id, thread_id, offset=page.offset, limit=page.limit)
if result is None:
return None
messages, count = result
return Page(results=messages, count=count)
AccountTrackRuleValidationError = _account_track_rules_logic.AccountTrackRuleValidationError
AccountTrackRuleVersionConflict = _account_track_rules_logic.AccountTrackRuleVersionConflict
AccountTrackRuleRunError = _account_track_rules_logic.AccountTrackRuleRunError
class AccountTrackRuleRunAlreadyActive(ValueError):
pass
def get_account_track_rules(team_id: int) -> contracts.AccountTrackRulesConfig:
return _account_track_rules_logic.get_account_track_rules(team_id)
def update_account_track_rules(
*,
team_id: int,
raw_config: dict[str, Any],
user: "User",
organization_id: UUID,
was_impersonated: bool,
) -> contracts.AccountTrackRulesConfig:
return _account_track_rules_logic.update_account_track_rules(
team_id=team_id,
raw_config=raw_config,
user=user,
organization_id=organization_id,
was_impersonated=was_impersonated,
)
def preview_account_track_rules(
team_id: int, raw_config: dict[str, Any] | None = None
) -> contracts.AccountTrackRulePreview:
return _account_track_rules_logic.preview_account_track_rules(team_id, raw_config)
def list_account_track_rule_runs(team_id: int, *, page: PageRequest) -> Page[contracts.AccountTrackRuleRunView]:
return _account_track_rules_logic.list_account_track_rule_runs(team_id, page=page)
def trigger_account_track_rule_run(
*,
team_id: int,
idempotency_key: UUID,
user_id: int,
) -> tuple[contracts.AccountTrackRuleRunView, bool]:
run, created = _account_track_rules_logic.create_account_track_rule_run(
team_id=team_id,
idempotency_key=idempotency_key,
user_id=user_id,
)
if not created:
return _account_track_rules_logic.to_run_view(run), False
from posthog.temporal.common.client import sync_connect # noqa: PLC0415
from products.customer_analytics.backend.temporal.account_track_rules import ( # noqa: PLC0415
AccountTrackRuleEvaluationInput,
AccountTrackRuleEvaluationWorkflow,
account_track_rule_workflow_id,
)
try:
client = sync_connect()
asyncio.run(
client.start_workflow(
AccountTrackRuleEvaluationWorkflow.run,
AccountTrackRuleEvaluationInput(
team_id=team_id,
run_id=str(run.id),
config_version=run.config_version,
),
id=account_track_rule_workflow_id(team_id),
task_queue=settings.VIDEO_EXPORT_TASK_QUEUE,
id_reuse_policy=WorkflowIDReusePolicy.ALLOW_DUPLICATE,
retry_policy=RetryPolicy(maximum_attempts=1),
)
)
except WorkflowAlreadyStartedError as error:
_account_track_rules_logic.fail_account_track_rule_run(team_id, run.id)
raise AccountTrackRuleRunAlreadyActive("Another Track Rules run is already in progress.") from error
except Exception:
_account_track_rules_logic.fail_account_track_rule_run(team_id, run.id)
raise
return _account_track_rules_logic.to_run_view(run), True
def list_calendar_sync_statuses(team_id: int) -> list[contracts.CalendarSyncStatus]:
"""Sync state of every connected calendar for the team: last completed sync and
whether a run is currently in flight (started but not finished, within the sync
activity's timeout — a run past it is considered dead, not running)."""
from products.customer_analytics.backend.logic.calendar_sync import ( # noqa: PLC0415 — keeps requests/HogQL layers off the import path
LAST_SYNCED_AT_CONFIG_KEY,
SYNC_RETRY_AT_CONFIG_KEY,
SYNC_STALE_AFTER,
SYNC_STARTED_AT_CONFIG_KEY,
get_calendar_sync_interval,
)
statuses = []
for integration in sorted(IntegrationManager.google_calendar.oauth.list(team_id), key=lambda row: row.id):
config = integration.config or {}
last_synced_at = _parse_datetime(config.get(LAST_SYNCED_AT_CONFIG_KEY))
started_at = _parse_datetime(config.get(SYNC_STARTED_AT_CONFIG_KEY))
retry_at = _parse_datetime(config.get(SYNC_RETRY_AT_CONFIG_KEY))
now = timezone.now()
is_syncing = bool(
(retry_at and retry_at > now)
or (
started_at
and (last_synced_at is None or started_at > last_synced_at)
and started_at > now - SYNC_STALE_AFTER
)
)
statuses.append(
contracts.CalendarSyncStatus(
integration_id=integration.id,
last_synced_at=last_synced_at,
is_syncing=is_syncing,
sync_interval_minutes=get_calendar_sync_interval(config),
)
)
return statuses
def update_calendar_sync_interval(team_id: int, integration_id: int, interval_minutes: int) -> bool:
from products.customer_analytics.backend.logic.calendar_sync import ( # noqa: PLC0415
SYNC_INTERVAL_CONFIG_KEY,
update_calendar_sync_config,
)
try:
update_calendar_sync_config(integration_id, team_id, {SYNC_INTERVAL_CONFIG_KEY: interval_minutes})
except IntegrationNotFound:
return False
return True
def _parse_datetime(value: str | None) -> datetime | None:
if not value:
return None
try:
return datetime.fromisoformat(value)
except ValueError:
return None
def trigger_calendar_sync(
team_id: int,
integration_id: int,
*,
user_id: int | None,
has_management_access: bool,
) -> str | None:
"""Start the calendar-sync workflow for one connected calendar, outside the hourly
schedule. Returns 'started', 'already_running' (a sync for this calendar is in
flight; the workflow id is deterministic per integration), or None when the
integration doesn't exist for this team (→ 404)."""
try:
integration = IntegrationManager.google_calendar.oauth.get(team_id, integration_id)
except IntegrationNotFound:
return None
if not has_management_access and not integration.can_be_managed_by_creator(user_id):
raise ResourceForbiddenError
from posthog.temporal.common.client import sync_connect # noqa: PLC0415 — keeps temporal off the import path
from products.customer_analytics.backend.temporal.calendar_sync import ( # noqa: PLC0415 — same
CalendarSyncInput,
CalendarSyncWorkflow,
)
client = sync_connect()
try:
asyncio.run(
client.start_workflow(
CalendarSyncWorkflow.run,
CalendarSyncInput(integration_id=integration_id, team_id=team_id),
id=f"google-calendar-sync-{integration_id}",
task_queue=settings.VIDEO_EXPORT_TASK_QUEUE,
id_reuse_policy=WorkflowIDReusePolicy.ALLOW_DUPLICATE,
retry_policy=RetryPolicy(maximum_attempts=1),
)
)
except WorkflowAlreadyStartedError:
return "already_running"
return "started"
def trigger_google_account_backfill(
team_id: int,
integration_id: int,
*,
start_date: date,
end_date: date,
has_management_access: bool,
) -> str | None:
try:
IntegrationManager.google_calendar.oauth.get(team_id, integration_id)
except IntegrationNotFound:
return None
if not has_management_access:
raise ResourceForbiddenError
if not can_sync_google_account_email(integration_id, team_id):
raise GoogleAccountBackfillUnavailable
from posthog.temporal.common.client import sync_connect # noqa: PLC0415 — keeps temporal off the import path
from products.customer_analytics.backend.temporal.calendar_sync import ( # noqa: PLC0415 — same
GoogleAccountBackfillInput,
GoogleAccountBackfillWorkflow,
)
client = sync_connect()
try:
asyncio.run(
client.start_workflow(
GoogleAccountBackfillWorkflow.run,
GoogleAccountBackfillInput(
integration_id=integration_id,
team_id=team_id,
start_at=datetime.combine(start_date, time.min, tzinfo=UTC).isoformat(),
end_at=datetime.combine(end_date + timedelta(days=1), time.min, tzinfo=UTC).isoformat(),
),
id=f"google-calendar-sync-{integration_id}",
task_queue=settings.VIDEO_EXPORT_TASK_QUEUE,
id_reuse_policy=WorkflowIDReusePolicy.ALLOW_DUPLICATE,
retry_policy=RetryPolicy(maximum_attempts=1),
)
)
except WorkflowAlreadyStartedError:
return "already_running"
return "started"
def list_account_meetings(
team_id: int,
account_id: str,
user_access_control: "UserAccessControl",
*,
page: PageRequest,
search: str | None = None,
) -> Page[contracts.MeetingView] | None:
"""Synced calendar meetings for an accessible account, newest first, optionally
filtered by ``search`` (title or attendee email/name). A recurring series shows each
past occurrence but only its next upcoming one. None when the account isn't
accessible (→ 404)."""
if get_accessible_account_id(team_id, account_id, user_access_control) is None:
return None
now = timezone.now()
next_occurrence_id = (
Meeting.objects.for_team(team_id)
.filter(account_id=account_id, ical_uid=OuterRef("ical_uid"), start_time__gte=now)
.exclude(recurrence_instance_id="")
.exclude(status=MeetingStatus.CANCELLED)
.order_by("start_time")
.values("id")[:1]
)
queryset = Meeting.objects.for_team(team_id).filter(
Q(recurrence_instance_id="") | Q(start_time__lt=now) | Q(id=Subquery(next_occurrence_id)),
account_id=account_id,
)
if search:
queryset = queryset.filter(
Q(title__icontains=search)
| Q(participants__email__icontains=search)
| Q(participants__display_name__icontains=search)
).distinct()
selected = select_page(queryset.order_by("-start_time").prefetch_related("participants"), page)
meetings = selected.results
from products.customer_analytics.backend.logic.gong import ( # noqa: PLC0415 — keeps HogQL off the facade import path
get_gong_urls_by_meeting_id,
)
team = user_access_control.team
if team is None or team.id != team_id:
team = Team.objects.get(id=team_id)
gong_urls_by_meeting_id = get_gong_urls_by_meeting_id(team=team, user=user_access_control.user, meetings=meetings)
views = [
contracts.MeetingView(
id=meeting.id,
title=meeting.title,
is_recurring=bool(meeting.recurrence_instance_id),
gong_url=gong_urls_by_meeting_id.get(meeting.id),
start_time=meeting.start_time,
end_time=meeting.end_time,
organizer_email=meeting.organizer_email,
status=meeting.status,
participants=[
contracts.MeetingParticipantView(
email=participant.email,
display_name=participant.display_name,
response_status=participant.response_status,
is_organizer=participant.is_organizer,
person_id=participant.person_id,
)
for participant in meeting.participants.all()
],
)
for meeting in meetings
]
return Page(results=views, count=selected.count)
def list_account_notebooks(
team_id: int,
account_id: str,
user_access_control: "UserAccessControl",
*,
search: str | None = None,
order: str | None = None,
) -> list[contracts.AccountNotebookView] | None:
"""Internal notebooks linked to an accessible account. Optionally full-text filtered by
``search`` (title + content) and sorted by ``order`` (creation date or author); defaults to
newest first. None when the parent account isn't accessible (→ 404)."""
if get_accessible_account_id(team_id, account_id, user_access_control) is None:
return None
return [
_to_account_notebook_view(n) for n in notebooks.list_account_notebooks(account_id, search=search, order=order)
]
def list_account_notes_for_view(
*,
team_id: int,
user_access_control: "UserAccessControl",
page: PageRequest,
search: str | None = None,
account_id: UUID | str | None = None,
created_by_ids: list[int] | None = None,
assigned_to_ids: list[int] | None = None,
) -> Page[contracts.AccountNoteView]:
"""Team-wide account notes (internal notebooks linked to accounts), newest-modified first,
restricted to accounts the caller can read. ``search`` matches note title/content (full-text)
and account name (substring). ``account_id`` narrows to one account, ``created_by_ids`` to
notes authored by the given users, ``assigned_to_ids`` to notes on accounts where one of the
given users actively holds a relationship."""
accounts = _accounts_queryset(team_id, user_access_control)
if assigned_to_ids:
# "Assigned to" means any active relationship, matching the accounts list HogQL
# runner's assignedToUserIds.
accounts = accounts.filter(
id__in=AccountRelationship.objects.for_team(team_id)
.filter(ended_at__isnull=True, user_id__in=assigned_to_ids)
.values("account_id")
)
accessible_account_ids = accounts.values_list("id", flat=True)
notes, count = notebooks.list_team_account_notes(
team_id,
account_ids=accessible_account_ids,
account_id=account_id,
created_by_ids=created_by_ids,
search=search,
offset=page.offset,
limit=page.limit,
)
views = [
contracts.AccountNoteView(
short_id=note.short_id,
title=note.title,
created_at=note.created_at,
last_modified_at=note.last_modified_at,
account_id=note.account_id,
account_name=note.account_name,
created_by=_notebook_user_to_basic_info(note.created_by),
)
for note in notes
]
return Page(results=views, count=count)
def get_account_notebook(
team_id: int, account_id: str, short_id: str, user_access_control: "UserAccessControl"
) -> contracts.AccountNotebookView | None:
"""One internal notebook linked to an accessible account. None when the account isn't
accessible or no such linked notebook exists (→ 404)."""
if get_accessible_account_id(team_id, account_id, user_access_control) is None:
return None
notebook = notebooks.get_account_notebook(account_id, short_id)
return _to_account_notebook_view(notebook) if notebook is not None else None
def create_account_notebook(
*,
team_id: int,
team,
account_id: str,
input: contracts.CreateAccountNotebookInput,
user: "User",
user_access_control: "UserAccessControl",
) -> contracts.AccountNotebookView | None:
"""Create an internal notebook and link it to an accessible account. None when the
parent account isn't accessible (→ 404). The view supplies ``synthesized_content``
(markdown→tiptap) so the ``ee.hogai`` helper stays off the facade import path."""
if get_accessible_account_id(team_id, account_id, user_access_control) is None:
return None
content = input.synthesized_content if input.synthesized_content is not None else input.content
created = notebooks.create_account_notebook(
team_id,
account_id,
title=input.title,
content=content,
text_content=input.text_content,
created_by_id=user.id,
last_modified_by_id=user.id,
)
# The creator is also the (only) modifier of a just-created notebook, so the user the
# caller already holds is both `created_by` and `last_modified_by` — no extra fetch.
author = _to_user_basic_info(user)
return contracts.AccountNotebookView(
id=created.id,
short_id=created.short_id,
title=created.title,
content=created.content,
text_content=created.text_content,
created_at=created.created_at,
created_by=author,
last_modified_at=created.last_modified_at,
last_modified_by=author,
)
def delete_account_notebook(
*, team_id: int, account_id: str, short_id: str, user_access_control: "UserAccessControl"
) -> bool:
"""Delete an internal notebook linked to an accessible account. False when the account
isn't accessible or no such notebook exists (→ 404)."""
if get_accessible_account_id(team_id, account_id, user_access_control) is None:
return False
return notebooks.delete_account_notebook(account_id, short_id)
# --- shared resolution / access helpers for the CRUD paths ---
def _get_team_scoped(model, team_id: int, pk: str | UUID):
"""Fetch a team-scoped row by pk, or None (malformed/absent). Used by the
profile-config path, whose old viewset returned 404 for both."""
try:
return model.objects.filter(team_id=team_id).get(pk=pk)
except (model.DoesNotExist, ValidationError, ValueError):
return None
def _get_custom_property_definition(team_id: int, definition_id: str | UUID) -> CustomPropertyDefinition | None:
try:
return CustomPropertyDefinition.objects.for_team(team_id).get(pk=definition_id)
except (CustomPropertyDefinition.DoesNotExist, ValidationError, ValueError):
return None
def _get_object_or_raise(queryset, pk: str, model):
"""Fetch by pk from an already-scoped queryset, raising ``model.DoesNotExist`` for
absent/malformed ids (the view maps that to 404)."""
try:
obj = queryset.filter(pk=pk).first()
except (ValidationError, ValueError):
raise model.DoesNotExist()
if obj is None:
raise model.DoesNotExist()
return obj
def _enforce_object_access(obj, user_access_control: "UserAccessControl", required_level: str | None) -> None:
"""Object-level access gate matching ``AccessControlPermission.has_object_permission``:
raise ``ResourceForbiddenError`` (→ 403) when the caller lacks ``required_level`` on the
object. The view computes ``required_level`` from the HTTP method (viewer / editor), and
passes ``None`` when the permission layer would skip the object check (service auth) — in
which case the gate is a no-op, exactly like ``has_object_permission`` returning early."""
if required_level is None:
return
if not user_access_control.check_access_level_for_object(obj, required_level=required_level): # type: ignore[arg-type]
raise ResourceForbiddenError()
# --- Custom property values ---
# Re-exported from logic so the presentation layer can catch them — the import-linter forbids
# presentation importing logic directly, so these errors are part of the facade's surface.
CustomPropertyDefinitionNotFound = _custom_property_values_logic.CustomPropertyDefinitionNotFound
CustomPropertyValueConflict = _custom_property_values_logic.CustomPropertyValueConflict
InvalidCustomPropertyValue = _custom_property_values_logic.InvalidCustomPropertyValue
def _source_backed_definition_ids(team_id: int, definition_ids: Iterable[str | UUID]) -> set[UUID]:
"""Definition ids from ``definition_ids`` that are backed by a view sync. Manual writes to these
are closed at the API layer (the sync writes them through the logic directly), so callers can't
fight the sync over the value."""
return set(
CustomPropertySource.objects.for_team(team_id)
.filter(definition_id__in=definition_ids)
.values_list("definition_id", flat=True)
)
class CustomPropertyValueSourceManaged(Exception):
"""Raised when a manual write targets a source-backed definition. The view sync writes such
definitions through the logic layer directly; the manual API path is closed so the two can't
fight over the value (→ 400)."""
def _to_custom_property_value(row: "CustomPropertyValue") -> contracts.CustomPropertyValue:
return contracts.CustomPropertyValue(
id=row.id,
account_id=row.account_id,
definition_id=row.definition_id,
value=_custom_property_values_logic.value_of(row),
created_at=row.created_at,
created_by_id=row.created_by_id,
)
def set_custom_property_value(
team_id: int,
account_id: str | UUID,
definition_id: str | UUID,
value: Any,
*,
actor: "User | None" = None,
) -> contracts.CustomPropertyValue:
definition = _get_custom_property_definition(team_id, definition_id)
if definition is not None and definition.name in CANONICAL_DISPLAY_TYPE_BY_NAME:
raise CanonicalCustomPropertyReadOnlyError(
"This custom property is managed by PostHog and can't be edited manually."
)
if _source_backed_definition_ids(team_id, [definition_id]):
raise CustomPropertyValueSourceManaged(
"This custom property is managed by a data warehouse source and can't be set manually."
)
row = _custom_property_values_logic.set_custom_property_value(
team_id=team_id,
account_id=account_id,
definition_id=definition_id,
value=value,
created_by_id=actor.id if actor else None,
actor=actor,
)
return _to_custom_property_value(row)
def clear_custom_property_value(
team_id: int,
account_id: str | UUID,
definition_id: str | UUID,
*,
actor: "User | None" = None,
) -> None:
definition = _get_custom_property_definition(team_id, definition_id)
if definition is not None and definition.name in CANONICAL_DISPLAY_TYPE_BY_NAME:
raise CanonicalCustomPropertyReadOnlyError(
"This custom property is managed by PostHog and can't be edited manually."
)
if _source_backed_definition_ids(team_id, [definition_id]):
raise CustomPropertyValueSourceManaged(
"This custom property is managed by a data warehouse source and can't be cleared manually."
)
_custom_property_values_logic.set_account_custom_properties_by_id(
team_id=team_id, account_id=account_id, properties={str(definition_id): None}, actor=actor
)
def record_last_slack_message_at(*, team_id: int, account_id: str | UUID, timestamp: datetime) -> bool:
"""Record when a customer last messaged in the Slack channel bound to `account_id`.
For conversations, which sees the messages. Throttled and self-creating — see the logic
function. Returns whether the stored value moved.
"""
return _custom_property_values_logic.record_last_slack_message_at(
team_id=team_id, account_id=account_id, timestamp=timestamp
)
def list_active_custom_property_values(team_id: int, account_id: str | UUID) -> list[contracts.CustomPropertyValue]:
"""The account's current (non-deleted) custom property values as contracts, newest first."""
rows = _custom_property_values_logic.list_active_custom_property_values(team_id=team_id, account_id=account_id)
return [_to_custom_property_value(row) for row in rows]
# --- Account relationships ---
class AccountRelationshipDefinitionConflictError(Exception):
"""Raised when a relationship definition violates the per-team unique name constraint."""
class AccountRelationshipDefinitionControlledError(Exception):
"""The definition is controlled, so it can be neither deleted nor made multi-holder until control
ends."""
class AccountRelationshipProtectedError(Exception):
"""The relationship row belongs to a controlled definition's history and cannot be hard-deleted."""
class AccountOwnershipManagedError(Exception):
"""The account manages a controlled relationship or carries relationship rows under a controlled
definition, so it cannot be deleted."""
class AccountRelationshipRoleManagedError(Exception):
"""An agent acting for a person reached a controlled relationship the account manages; only the
person may change it."""
def _project_api_actor(user: "User | None", via_agent: bool) -> _relationships_logic.Actor:
"""A person's own request, or an agent acting for them through the MCP server. An agent counts
as an autonomous writer, like the in-app AI tool, so it cannot transfer or clear a managed
relationship."""
source = AccountRelationshipSource.AI if via_agent else AccountRelationshipSource.HUMAN
return _relationships_logic.Actor(source=source, user=user)
def _to_account_relationship_definition(
definition: AccountRelationshipDefinition,
) -> contracts.AccountRelationshipDefinition:
return contracts.AccountRelationshipDefinition(
id=definition.id,
name=definition.name,
description=definition.description,
is_single_holder=definition.is_single_holder,
is_controlled=definition.is_controlled,
)
def _to_account_relationship(relationship: AccountRelationship) -> contracts.AccountRelationship:
user = relationship.user
return contracts.AccountRelationship(
id=relationship.id,
definition=_to_account_relationship_definition(relationship.definition),
user=contracts.AccountAssignment(id=user.id, email=user.email) if user is not None else None,
started_at=relationship.started_at,
ended_at=relationship.ended_at,
source=cast(contracts.RelationshipSourceValue | None, relationship.source),
)
def list_account_relationship_definitions(
team_id: int, *, page: PageRequest
) -> Page[contracts.AccountRelationshipDefinition]:
queryset = AccountRelationshipDefinition.objects.for_team(team_id).order_by("name")
return select_page(queryset, page).map(_to_account_relationship_definition)
def list_all_account_relationship_definitions(team_id: int) -> list[contracts.AccountRelationshipDefinition]:
queryset = AccountRelationshipDefinition.objects.for_team(team_id).order_by("name", "pk")
return [_to_account_relationship_definition(definition) for definition in queryset]
def create_account_relationship_definition(
*,
team_id: int,
name: str,
description: str | None = None,
is_single_holder: bool = True,
created_by: "User",
) -> contracts.AccountRelationshipDefinition:
try:
definition = AccountRelationshipDefinition.objects.for_team(team_id).create(
team_id=team_id,
name=name,
description=description,
is_single_holder=is_single_holder,
created_by=created_by,
)
except IntegrityError:
raise AccountRelationshipDefinitionConflictError(
"A relationship definition with this name already exists for this team."
)
return _to_account_relationship_definition(definition)
def get_account_relationship_definition(
team_id: int, definition_id: str | UUID
) -> contracts.AccountRelationshipDefinition | None:
definition = AccountRelationshipDefinition.objects.for_team(team_id).filter(id=definition_id).first()
if definition is None:
return None
return _to_account_relationship_definition(definition)
_DEFINITION_EDITABLE_FIELDS = frozenset({"name", "description", "is_single_holder"})
def update_account_relationship_definition(
*, team_id: int, definition_id: str | UUID, fields: dict[str, Any]
) -> contracts.AccountRelationshipDefinition | None:
"""Rename or describe a definition, or change its cardinality. Whether it is controlled is not an
edit: it changes only through ``ownership.set_controlled``, which holds the guards."""
unexpected = set(fields) - _DEFINITION_EDITABLE_FIELDS
if unexpected:
raise ValueError(f"Fields cannot be edited here: {', '.join(sorted(unexpected))}")
with transaction.atomic():
# The definition lock keeps control from starting between this check and the save.
definition = _ownership.lock_definition(team_id, definition_id)
if definition is None:
return None
if fields.get("is_single_holder") is False and definition.is_controlled:
raise AccountRelationshipDefinitionControlledError(str(definition_id))
for attr, value in fields.items():
setattr(definition, attr, value)
try:
definition.save(update_fields=[*fields, "updated_at"])
except IntegrityError:
raise AccountRelationshipDefinitionConflictError(
"A relationship definition with this name already exists for this team."
)
return _to_account_relationship_definition(definition)
def delete_account_relationship_definition(*, team_id: int, definition_id: str | UUID) -> bool:
"""Hard-deletes the definition and (by cascade) its assignment history. Returns False when
no definition matches the id for this team (→ 404). A controlled definition raises instead."""
with transaction.atomic():
# Locked, so control cannot start between the check and the delete.
definition = _ownership.lock_definition(team_id, definition_id)
if definition is None:
return False
if definition.is_controlled:
raise AccountRelationshipDefinitionControlledError(str(definition_id))
definition.delete()
return True
def list_account_relationships(
*, team_id: int, account_id: str | UUID, include_history: bool = False
) -> list[contracts.AccountRelationship]:
"""The account's active relationships, or its full assignment timeline with ``include_history``."""
queryset = (
AccountRelationship.objects.for_team(team_id)
.filter(account_id=account_id)
.select_related("definition", "user")
.order_by("definition__name", "-started_at")
)
if not include_history:
queryset = queryset.filter(ended_at__isnull=True)
return [_to_account_relationship(relationship) for relationship in queryset]
class AccountRelationshipDefinitionNotFound(Exception):
pass
class AccountRelationshipAssigneeNotInOrganization(Exception):
pass
def assign_account_relationship(
*,
team_id: int,
account_id: str | UUID,
definition_id: str | UUID,
user_id: int,
created_by: "User",
via_agent: bool = False,
) -> contracts.AccountRelationship:
"""Assign a user to an account relationship. Single-holder definitions hand off — the
previous active assignment is ended in the same transaction. Idempotent when the user
already actively holds the relationship.
Raises ``Account_DoesNotExist`` (→ 404), ``AccountRelationshipDefinitionNotFound`` and
``AccountRelationshipAssigneeNotInOrganization`` (→ 400), and ``AccountRelationshipRoleManagedError``
(→ 409) when an agent acting for the user reaches a controlled relationship the account manages.
"""
account = Account.objects.for_team(team_id).select_related("team").get(id=account_id)
definition = AccountRelationshipDefinition.objects.for_team(team_id).filter(id=definition_id).first()
if definition is None:
raise AccountRelationshipDefinitionNotFound(str(definition_id))
membership = (
OrganizationMembership.objects.select_related("user")
.filter(organization_id=account.team.organization_id, user_id=user_id)
.first()
)
if membership is None:
raise AccountRelationshipAssigneeNotInOrganization(str(user_id))
try:
relationship = _relationships_logic.assign(
team_id=team_id,
account=account,
definition=definition,
user=membership.user,
actor=_project_api_actor(created_by, via_agent),
)
except _relationships_logic.ManagedRolePolicyError:
raise AccountRelationshipRoleManagedError(str(definition_id))
return _to_account_relationship(relationship)
def end_account_relationship(
*,
team_id: int,
account_id: str | UUID,
relationship_id: str | UUID,
actor: "User | None" = None,
via_agent: bool = False,
) -> contracts.AccountRelationship | None:
"""End an active assignment. Returns None when no active assignment matches this account
(missing, another account's, or already ended) — mapped to 404."""
try:
relationship = _relationships_logic.end_relationship(
team_id=team_id,
account_id=account_id,
relationship_id=str(relationship_id),
actor=_project_api_actor(actor, via_agent),
)
except _relationships_logic.AccountRelationshipNotFound:
return None
except _relationships_logic.ManagedRolePolicyError:
raise AccountRelationshipRoleManagedError(str(relationship_id))
return _to_account_relationship(relationship)
def delete_account_relationship(
*,
team_id: int,
account_id: str | UUID,
relationship_id: str | UUID,
actor: "User | None" = None,
via_agent: bool = False,
) -> bool:
try:
_relationships_logic.delete_relationship(
team_id=team_id,
account_id=account_id,
relationship_id=str(relationship_id),
actor=_project_api_actor(actor, via_agent),
)
except _relationships_logic.AccountRelationshipNotFound:
return False
except _relationships_logic.ProtectedRelationshipHistoryError:
raise AccountRelationshipProtectedError(str(relationship_id))
return True
def _to_customer_task_user_view(user: "User | None") -> contracts.CustomerTaskUserView | None:
if user is None:
return None
return contracts.CustomerTaskUserView(
id=user.id,
email=user.email,
first_name=user.first_name,
last_name=user.last_name,
)
def _to_customer_task_view(task: CustomerTask, user_access_control: "UserAccessControl") -> contracts.CustomerTaskView:
account = (
contracts.CustomerTaskAccountView(id=task.account.id, name=task.account.name)
if task.account is not None
else None
)
return contracts.CustomerTaskView(
id=task.id,
account=account,
name=task.name,
description=task.description,
status=task.status,
assigned_to=_to_customer_task_user_view(task.assigned_to),
due_at=task.due_at,
completed_at=task.completed_at,
completed_by=_to_customer_task_user_view(task.completed_by),
created_by=_to_customer_task_user_view(task.created_by),
archived_at=task.archived_at,
created_at=task.created_at,
updated_at=task.updated_at,
can_edit=_customer_tasks_logic.can_edit_customer_task(task, user_access_control),
can_restore=_customer_tasks_logic.can_restore_customer_task(task, user_access_control),
)
def _to_customer_task_change_value(
*,
field: str,
value: object | None,
account_context_present: bool,
account_context_id: object | None,
visible_account_ids: frozenset[str],
) -> object | None:
if field == "account":
if value is None:
return None
if isinstance(value, dict):
account_id = value.get("id")
account_name = value.get("name")
if isinstance(account_id, str) and isinstance(account_name, str):
try:
normalized_account_id = str(UUID(account_id))
except ValueError:
pass
else:
if normalized_account_id in visible_account_ids:
return {"id": account_id, "name": account_name}
return {"id": None, "name": "Restricted account"}
if not account_context_present:
return None
if account_context_id is None:
return value
if isinstance(account_context_id, str):
try:
normalized_account_id = str(UUID(account_context_id))
except ValueError:
return None
if normalized_account_id in visible_account_ids:
return value
return None
def _to_customer_task_activity_view(
activity: CustomerTaskActivity, visible_account_ids: frozenset[str]
) -> contracts.CustomerTaskActivityView:
changes = []
for change in activity.changes:
if not isinstance(change, dict):
continue
field = str(change.get("field", ""))
changes.append(
contracts.CustomerTaskChange(
field=field,
before=_to_customer_task_change_value(
field=field,
value=change.get("before"),
account_context_present="before_account_id" in change,
account_context_id=change.get("before_account_id"),
visible_account_ids=visible_account_ids,
),
after=_to_customer_task_change_value(
field=field,
value=change.get("after"),
account_context_present="after_account_id" in change,
account_context_id=change.get("after_account_id"),
visible_account_ids=visible_account_ids,
),
)
)
return contracts.CustomerTaskActivityView(
id=activity.id,
activity_type=activity.activity_type,
changes=changes,
actor=_to_customer_task_user_view(activity.actor),
created_at=activity.created_at,
)
CUSTOMER_TASK_ACTIVITY_TYPE_CHOICES = CustomerTaskActivityType.choices
CUSTOMER_TASK_STATUS_CHOICES = CustomerTaskStatus.choices
def list_customer_tasks(
*,
team_id: int,
user_access_control: "UserAccessControl",
filters: contracts.CustomerTaskListFilters,
page: PageRequest,
) -> Page[contracts.CustomerTaskView]:
tasks = _customer_tasks_logic.list_customer_tasks(
team_id=team_id,
user_access_control=user_access_control,
filters=filters,
page=page,
)
return tasks.map(lambda task: _to_customer_task_view(task, user_access_control))
def get_customer_task(
*, team_id: int, task_id: UUID | str, user_access_control: "UserAccessControl"
) -> contracts.CustomerTaskView | None:
task = _customer_tasks_logic.get_customer_task(
team_id=team_id,
task_id=task_id,
user_access_control=user_access_control,
)
return _to_customer_task_view(task, user_access_control) if task is not None else None
def create_customer_task(
*,
team: Team,
input: contracts.CreateCustomerTaskInput,
actor: "User | None",
user_access_control: "UserAccessControl",
) -> contracts.CustomerTaskView:
task = _customer_tasks_logic.create_customer_task(
team=team,
input=input,
actor=actor,
user_access_control=user_access_control,
)
return _to_customer_task_view(task, user_access_control)
def update_customer_task(
*,
team: Team,
task_id: UUID | str,
input: contracts.UpdateCustomerTaskInput,
actor: "User | None",
user_access_control: "UserAccessControl",
) -> contracts.CustomerTaskView | None:
task = _customer_tasks_logic.update_customer_task(
team=team,
task_id=task_id,
input=input,
actor=actor,
user_access_control=user_access_control,
)
if task is None:
return None
fresh_user_access_control = UserAccessControl(user=user_access_control.user, team=team)
return _to_customer_task_view(task, fresh_user_access_control)
def bulk_update_customer_tasks(
*,
team: Team,
task_ids: list[UUID],
input: contracts.UpdateCustomerTaskInput,
archived: bool | None,
actor: "User | None",
user_access_control: "UserAccessControl",
) -> int | None:
return _customer_tasks_logic.bulk_update_customer_tasks(
team=team,
task_ids=task_ids,
input=input,
archived=archived,
actor=actor,
user_access_control=user_access_control,
)
def archive_customer_task(
*,
team_id: int,
task_id: UUID | str,
actor: "User | None",
user_access_control: "UserAccessControl",
) -> contracts.CustomerTaskView | None:
task = _customer_tasks_logic.archive_customer_task(
team_id=team_id,
task_id=task_id,
actor=actor,
user_access_control=user_access_control,
)
return _to_customer_task_view(task, user_access_control) if task is not None else None
def restore_customer_task(
*,
team_id: int,
task_id: UUID | str,
actor: "User | None",
user_access_control: "UserAccessControl",
) -> contracts.CustomerTaskView | None:
task = _customer_tasks_logic.restore_customer_task(
team_id=team_id,
task_id=task_id,
actor=actor,
user_access_control=user_access_control,
)
return _to_customer_task_view(task, user_access_control) if task is not None else None
def list_customer_task_activities(
*,
team_id: int,
task_id: UUID | str,
user_access_control: "UserAccessControl",
page: PageRequest,
) -> Page[contracts.CustomerTaskActivityView] | None:
result = _customer_tasks_logic.list_customer_task_activities(
team_id=team_id,
task_id=task_id,
user_access_control=user_access_control,
page=page,
)
if result is None:
return None
visible_account_ids = result.visible_account_ids
return result.activities.map(lambda activity: _to_customer_task_activity_view(activity, visible_account_ids))
# --- EventStream ---
class EventStreamValidationError(Exception):
"""Raised when an event-stream write references a Slack integration that isn't the
team's (→ 400)."""
class EventStreamConflictError(Exception):
"""Raised when a user creates a second event stream in a team (→ 409)."""
def _own_streams(team_id: int, user: "User"):
"""Streams are per-user: every read and write is scoped to the caller's own stream."""
return EventStream.objects.for_team(team_id).filter(created_by=user)
def _to_event_stream_view(stream: EventStream) -> contracts.EventStreamView:
account_ids = list(stream.members.order_by("created_at").values_list("account_id", flat=True))
return contracts.EventStreamView(
id=stream.id,
enabled=stream.enabled,
event_names=list(stream.event_names or []),
slack_integration=stream.slack_integration_id,
slack_channel_id=stream.slack_channel_id,
slack_channel_name=stream.slack_channel_name,
account_ids=account_ids,
created_at=stream.created_at,
created_by=stream.created_by_id,
updated_at=stream.updated_at,
)
def _validate_slack_integration(team_id: int, integration_id: int | None) -> None:
if integration_id is None:
return
try:
IntegrationManager.slack.oauth.get(team_id, integration_id)
except IntegrationNotFound:
raise EventStreamValidationError("Slack integration not found for this team.") from None
def _normalize_event_names(event_names: Iterable[str]) -> list[str]:
"""Deduplicated, order-preserving event names with blanks dropped."""
return [name for name in dict.fromkeys(event_names) if name and name.strip()]
def list_event_streams(team_id: int, *, user: "User") -> list[contracts.EventStreamView]:
"""The caller's event streams — at most one exists per user (unique per team+owner)."""
return [_to_event_stream_view(s) for s in _own_streams(team_id, user).order_by("created_at")]
def create_event_stream(
*,
team_id: int,
enabled: bool,
event_names: list[str],
slack_integration_id: int | None,
slack_channel_id: str,
slack_channel_name: str,
user: "User",
) -> contracts.EventStreamView:
"""Create the caller's event stream. Raises :class:`EventStreamConflictError` when they
already have one and :class:`EventStreamValidationError` for a foreign Slack integration."""
_validate_slack_integration(team_id, slack_integration_id)
try:
stream = EventStream.objects.for_team(team_id).create(
team_id=team_id,
created_by=user,
enabled=enabled,
event_names=_normalize_event_names(event_names),
slack_integration_id=slack_integration_id,
slack_channel_id=slack_channel_id,
slack_channel_name=slack_channel_name,
)
except IntegrityError as exc:
if "unique" not in str(exc).lower() and "duplicate" not in str(exc).lower():
raise
raise EventStreamConflictError("You already have an event stream in this project.")
return _to_event_stream_view(stream)
def update_event_stream(
*, team_id: int, stream_id: str | UUID, fields: dict[str, Any], user: "User"
) -> contracts.EventStreamView | None:
"""Apply ``fields`` (enabled / event_names / slack_integration_id / slack_channel_id /
slack_channel_name) to the caller's stream. Returns None (→ 404) when no stream matches."""
stream = _own_streams(team_id, user).filter(id=stream_id).first()
if stream is None:
return None
if "slack_integration_id" in fields:
_validate_slack_integration(team_id, fields["slack_integration_id"])
if "event_names" in fields:
fields = {**fields, "event_names": _normalize_event_names(fields["event_names"])}
for attr, value in fields.items():
setattr(stream, attr, value)
stream.save()
return _to_event_stream_view(stream)
def delete_event_stream(*, team_id: int, stream_id: str | UUID, user: "User") -> bool:
"""Delete the caller's stream (memberships cascade) and archive its managed Slack
destination so it can't keep delivering. Returns False when none matched (→ 404)."""
stream = _own_streams(team_id, user).filter(id=stream_id).first()
if stream is None:
return False
with transaction.atomic():
archive_event_stream_destination(stream)
stream.delete()
return True
def delete_event_streams_for_user(*, user_id: int, organization_id: UUID | str) -> int:
"""Archive and delete every event stream the user owns across the organization's teams.
Called by core when the user's organization membership is removed — a departed member's
stream must stop delivering customer events to their Slack channel. Returns the number
of streams deleted."""
streams = list(EventStream.objects.unscoped().filter(created_by_id=user_id, team__organization_id=organization_id))
for stream in streams:
with transaction.atomic():
archive_event_stream_destination(stream)
stream.delete()
return len(streams)
def _event_streams_containing_account(account: Account) -> list[EventStream]:
return list(EventStream.objects.for_team(account.team_id).filter(members__account=account))
def set_event_stream_member(
*,
team_id: int,
stream_id: str | UUID,
account_id: str | UUID,
included: bool,
user: "User",
user_access_control: "UserAccessControl",
) -> contracts.EventStreamView | None:
"""Add or remove an account from the caller's stream. Idempotent in both directions.
Returns None (→ 404) when no stream matches; raises ``Account_DoesNotExist`` for a
foreign, unknown, or (when adding) object-level-denied account."""
stream = _own_streams(team_id, user).filter(id=stream_id).first()
if stream is None:
return None
account = Account.objects.for_team(team_id).filter(id=account_id).first()
if account is None:
raise Account_DoesNotExist()
if included:
# Adding an account pipes its events into Slack, so a denied account must behave
# like an unknown one. Removal stays team-scoped: members must be droppable even
# after access to them is revoked.
if get_accessible_account_id(team_id, str(account.id), user_access_control) is None:
raise Account_DoesNotExist()
# for_team() filters don't propagate into creation — team_id must be in defaults.
EventStreamMember.objects.for_team(team_id).get_or_create(
stream=stream,
account=account,
defaults={"team_id": team_id, "created_by": user},
)
else:
EventStreamMember.objects.for_team(team_id).filter(stream=stream, account=account).delete()
return _to_event_stream_view(stream)
# --- Announcements ---
def _to_announcement_delivery_view(delivery) -> contracts.AnnouncementDeliveryView:
return contracts.AnnouncementDeliveryView(
id=delivery.id,
slack_channel_id=delivery.slack_channel_id,
slack_channel_name=delivery.slack_channel_name,
status=delivery.status,
error=delivery.error,
slack_message_ts=delivery.slack_message_ts,
sent_at=delivery.sent_at,
)
def _to_announcement_view(announcement) -> contracts.AnnouncementView:
return contracts.AnnouncementView(
id=announcement.id,
short_id=announcement.short_id,
message=announcement.message,
status=announcement.status,
send_as=announcement.send_as,
sender_display_name=announcement.sender_display_name,
total_channels=announcement.total_channels,
sent_count=announcement.sent_count,
failed_count=announcement.failed_count,
sent_at=announcement.sent_at,
created_at=announcement.created_at,
created_by=_to_user_basic_info(announcement.created_by),
deliveries=[_to_announcement_delivery_view(d) for d in announcement.deliveries.all()],
)
def _announcements_queryset(team_id: int):
return (
Announcement.objects.for_team(team_id)
.select_related("created_by")
.prefetch_related("deliveries")
.order_by("-created_at")
)
def list_announcements(team_id: int, *, page: PageRequest) -> Page[contracts.AnnouncementView]:
return select_page(_announcements_queryset(team_id), page).map(_to_announcement_view)
def get_announcement(team_id: int, short_id: str) -> contracts.AnnouncementView | None:
announcement = _announcements_queryset(team_id).filter(short_id=short_id).first()
return _to_announcement_view(announcement) if announcement is not None else None
def create_announcement(
*, team_id: int, user: "User", message: str, channels: list[str], send_as: str = "bot"
) -> contracts.AnnouncementView:
team = Team.objects.get(id=team_id)
announcement = _announcements_logic.create_announcement(team, user, message, channels, send_as)
# Dispatch only after the delivery rows commit; a rollback must not leave a phantom task.
transaction.on_commit(lambda: send_announcement.delay(str(announcement.id), team_id))
return _to_announcement_view(announcement)
def list_announcement_channels(team_id: int) -> list[contracts.AnnouncementChannelView]:
try:
return _announcements_logic.list_channels(team_id)
except SupportSlackNotConfigured:
return []
except SupportSlackChannelsUnavailable:
logger.warning("announcement_channels_unavailable", team_id=team_id)
return []
def get_key_metrics(*, team: Team, user: "User") -> list[contracts.KeyMetric] | None:
"""The key metrics, or None while a background calculation is still running."""
return _key_metrics_logic.key_metrics(team, user)
def get_key_metric_names(*, team: Team) -> dict[str, str]:
return _key_metrics_logic.key_metric_names(team)