spec: Content Analytics Mode (persist/read-only) for issue #37521

specs/37521-content-analytics-mode/spec.md

@@ -0,0 +1,231 @@
+# Feature Specification: Content Analytics Mode (Persist / Read Only)
+
+**Feature Branch**: `37521-content-analytics-mode`
+
+**Created**: 2026-09-14
+
+**Status**: Draft
+
+**Type**: New Feature
+
+**Input**: User description: "Specification work for ticket: https://github.com/dotCMS/core/issues/37521"
+
+## Clarifications
+
+### Session 2026-09-14
+
+- Q: Should changing Analytics Mode be recorded in an audit/activity log? → A: No special audit trail — matches existing Content Analytics app config save behavior (no App config field in dotCMS currently gets a dedicated audit-log entry on save).
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Stop an instance from persisting analytics events (Priority: P1)
+
+A customer runs a non-production dotCMS instance (e.g. UAT) that currently sends analytics
+events into the same shared analytics dataset as their Production instance. They want to stop
+that instance from writing data — without creating dedicated users or roles in Production, and
+without anyone else's data being affected.
+
+**Why this priority**: This is the entire reason the feature exists — it replaces a much more
+complex cross-environment access model (epic #37349) with a single per-instance switch. Without
+this story there is no feature.
+
+**Independent Test**: On an instance already configured for Content Analytics, set Analytics
+Mode to "Read Only", perform a tracked action (e.g. view a page), and confirm no new event
+reaches the Content Analytics infrastructure while existing dashboard data for that
+tenant/project is still visible.
+
+**Acceptance Scenarios**:
+
+1. **Given** an instance configured for Content Analytics with Analytics Mode set to "Read &
+   Write", **When** an admin changes Analytics Mode to "Read Only" and saves, **Then** the
+   instance stops sending analytics events from that point forward.
+2. **Given** an instance with Analytics Mode set to "Read Only", **When** a site visitor
+   triggers a trackable action, **Then** no analytics event for that action is sent to the
+   Content Analytics infrastructure.
+3. **Given** an instance with Analytics Mode set to "Read Only", **When** an admin changes
+   Analytics Mode back to "Read & Write" and saves, **Then** the instance resumes sending
+   analytics events without requiring a restart.
+4. **Given** an instance with Analytics Mode set to "Read Only" whose content is consumed by a
+   headless/SPA application through the Content Analytics SDK (not a server-rendered page),
+   **When** that application triggers a tracked event, **Then** no event reaches the Content
+   Analytics infrastructure — the same guarantee holds for SDK-driven traffic as for
+   server-rendered page tracking.
+
+---
+
+### User Story 2 - Existing customers keep working unchanged after upgrade (Priority: P2)
+
+A customer already has Content Analytics configured and events flowing today. After upgrading
+to the version that introduces Analytics Mode, nothing should change for them unless they
+deliberately act.
+
+**Why this priority**: A silent behavior change on upgrade (events stopping without anyone
+choosing that) would be a regression and a support incident. This must hold before the feature
+can ship.
+
+**Independent Test**: Take an instance with Content Analytics already configured and events
+flowing, upgrade it, and confirm events continue flowing with no configuration change required.
+
+**Acceptance Scenarios**:
+
+1. **Given** an instance that had Content Analytics configured before this feature existed,
+   **When** the instance is upgraded, **Then** its Analytics Mode is "Read & Write" and it
+   continues sending events exactly as before.
+
+---
+
+### User Story 3 - Dashboards keep working regardless of mode (Priority: P3)
+
+An admin on a "Read Only" instance still wants to view that tenant/project's analytics
+dashboards and reports.
+
+**Why this priority**: Read Only must mean "no ingest," not "no access" — otherwise the feature
+removes value (viewing analytics) instead of just removing risk (unwanted writes).
+
+**Independent Test**: On an instance set to "Read Only", open the Content Analytics dashboard
+and confirm existing data for the tenant/project renders normally.
+
+**Acceptance Scenarios**:
+
+1. **Given** an instance with Analytics Mode set to "Read Only", **When** an admin opens the
+   Content Analytics dashboard, **Then** existing analytics data for that tenant/project
+   displays exactly as it would on a "Read & Write" instance.
+
+---
+
+### Edge Cases
+
+- Switching Analytics Mode from "Read & Write" to "Read Only" does not delete, hide, or alter
+  any analytics events already persisted — it only stops new events going forward.
+- "From that point forward" means no analytics event generated after the mode switch is saved
+  is submitted to the Content Analytics infrastructure — any event already queued or in flight
+  at the moment of the switch is not retroactively recalled once submission has started, but no
+  event generated after the switch is queued or sent.
+- An instance that has never had the Content Analytics app configured shows no Analytics Mode
+  input and is unaffected by this feature.
+- Analytics data for a tenant + project is never split or labeled by which environment produced
+  it — a "Read Only" instance and a "Read & Write" instance for the same tenant/project
+  contribute to (or read) the exact same dataset, with no environment distinction anywhere.
+- An instance that the Platform Team has not enabled for Content Analytics access at all has no
+  Analytics Mode to set — that enablement gate is a precondition of this feature, not part of it.
+- An instance running an active Experiment (A/B test) that is switched to "Read Only" stops
+  collecting new experiment result data for that instance, for the same reason it stops
+  collecting any other analytics data — this is expected, not a defect.
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: System MUST provide an "Analytics Mode" input in the Content Analytics app
+  configuration with exactly two selectable values: "Read & Write" and "Read Only".
+- **FR-002**: System MUST default Analytics Mode to "Read & Write" for every instance that had
+  Content Analytics already configured before this feature existed, so no customer's event flow
+  changes as a side effect of upgrading.
+- **FR-002a**: System MUST also default Analytics Mode to "Read & Write" when an admin
+  configures the Content Analytics app for the first time on an instance that never had it
+  configured before — new setups behave the same as upgraded ones; there is no scenario where
+  an instance ends up "Read Only" without an admin deliberately choosing it.
+- **FR-003**: When Analytics Mode is "Read & Write", system MUST continue sending analytics
+  events to the Content Analytics infrastructure exactly as it does today.
+- **FR-004**: When Analytics Mode is "Read Only", system MUST NOT forward any event to the
+  Content Analytics infrastructure's ingest endpoint. Every collection method — dotCMS's
+  built-in page/impression/click tracking on server-rendered pages, and the headless/SPA SDK
+  used by external applications — always submits events through this same dotCMS instance
+  first, never directly from the browser or an external app to the Content Analytics
+  infrastructure; gating that one instance-side ingest hand-off is therefore sufficient to cover
+  every collection method, with no separate client-side path left ungated. This is scoped
+  strictly to Content Analytics ingest traffic — it does not affect any other, unrelated
+  telemetry, health-check, or usage-reporting signal the instance emits.
+- **FR-005**: System MUST apply an Analytics Mode change without requiring the dotCMS instance
+  to be restarted. On a clustered instance, the change MUST propagate to every node using the
+  same cluster-wide cache-invalidation mechanism every other Content Analytics app configuration
+  field already relies on — no new propagation mechanism, and no special same-node-only
+  guarantee, is introduced for this field. A brief window where a sibling node has not yet
+  received the change (matching that existing mechanism's normal propagation delay) is expected
+  and acceptable; nodes are not expected to diverge beyond it.
+- **FR-006**: System MUST allow users to view existing analytics dashboards and reports
+  regardless of the instance's current Analytics Mode.
+- **FR-007**: System MUST NOT classify, distinguish, or filter analytics data by originating
+  environment anywhere in the pipeline — all events for a given tenant and project are combined
+  with no environment dimension, superseding the environment-selector approach previously
+  proposed in epic #37349.
+- **FR-008**: System MUST accept analytics events without requiring an environment identifier —
+  omitting it MUST NOT cause the event to be rejected, reversing the required-environment
+  validation introduced under #37407.
+- **FR-009**: System MUST NOT require a dedicated audit/activity log entry for Analytics Mode
+  changes — it is saved like any other Content Analytics app configuration field, with no new
+  audit trail introduced by this feature.
+
+### Key Entities
+
+- **Instance Analytics Configuration**: A per-dotCMS-instance setting living in the Content
+  Analytics app configuration. Holds the Analytics Mode value ("Read & Write" or "Read Only").
+  Only meaningful on an instance the Platform Team has already enabled for Content Analytics
+  access.
+- **Analytics Event**: A tracked user/content interaction submitted to the Content Analytics
+  infrastructure. Identified by tenant and project; carries no environment identity.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: An admin can change an instance's analytics-persistence behavior end-to-end
+  (open configuration, change mode, save) in under one minute, with no deployment or restart.
+- **SC-002**: 100% of instances that were sending analytics data before this change continue
+  doing so immediately after upgrading, with zero customer action required — measured by
+  comparing each instance's analytics event count for a fixed window immediately before and
+  after upgrade and confirming neither drops to zero nor decreases unexpectedly.
+- **SC-003**: An instance set to "Read Only" produces zero new analytics events in the shared
+  analytics dataset while retaining full, unchanged access to its existing dashboards and
+  reports — measured, on the instance side (since the shared dataset does not distinguish which
+  instance contributed a given event, per FR-007), by confirming no outbound event submission
+  occurs for any tracked action performed while Read Only is active, and that the same dashboard
+  queries return unchanged data before and after the switch.
+- **SC-004**: Customers can control per-instance analytics persistence without creating or
+  managing any additional users or roles for cross-instance access — eliminating the operational
+  burden the original epic (#37349) set out to avoid.
+
+## Legacy Considerations *(dotCMS-specific — mandatory)*
+
+- **Existing behavior touched**: The Content Analytics app configuration (a dotCMS Cloud
+  feature) and the analytics event submission path from a dotCMS instance to the Content
+  Analytics infrastructure. This is modern, actively-developed functionality — not legacy
+  `com.dotmarketing.*` surface — though the underlying Apps/Integrations configuration framework
+  it builds on predates it. Experiments (A/B testing) is a downstream consumer of the same
+  dataset (it queries the same analytics data to compute results) and is affected as a
+  consequence, though it is not itself modified by this feature.
+- **Backward-compatibility expectations**: Every instance with Content Analytics already
+  configured must keep working exactly as before immediately after upgrade (default "Read &
+  Write"). The only contract change is relaxing the recently-introduced required `environment`
+  parameter on event submission back to optional — no other existing behavior changes.
+- **Known related decisions**: Reverses the required, non-blank `environment` parameter decision
+  from epic #37349's 2026-09-09 amendment (formalized in the `dot-ca-event-manager`
+  constitution v1.2.0, Principle II, and specced under #37407). The `environment` column already
+  added to the ClickHouse schema is left in place, unused, with no migration performed. The plan
+  phase will formally consult `dotCMS/platform-adrs` (e.g. ADR-0022) for anything governing the
+  Content Analytics app configuration or event-submission contract.
+
+## Assumptions
+
+- The Platform Team's existing mechanism for enabling which instances may access the Content
+  Analytics infrastructure at all is unchanged by this feature; Analytics Mode only governs
+  persist-vs-read-only behavior on top of that existing gate.
+- "Content Analytics app" refers to the existing per-instance App/Integration configuration
+  screen for Content Analytics — this feature adds a field to it, not a new settings page.
+- Read Only is enforced entirely on the dotCMS instance side, at the single point through which
+  every event — regardless of collection method — already passes on its way to the Content
+  Analytics infrastructure; the infrastructure itself requires no new rejection logic of its
+  own for this feature. **This is the assumption the whole feature depends on** — if any
+  collection method (present or future) were found to submit events directly to the Content
+  Analytics infrastructure instead of through the instance, Read Only would silently leak for
+  that path. `/speckit-plan` MUST re-trace the actual ingest path for every current collection
+  method (server-rendered tracking and the headless/SPA SDK) against the code at plan time,
+  rather than carrying this forward as an unverified assumption, and Acceptance Scenario 4 above
+  MUST be covered by a real test, not just server-rendered tracking.
+- Experiments (A/B testing) results are computed from the same Content Analytics dataset this
+  feature gates. Setting an instance to Read Only is expected to also stop new experiment
+  result data from that instance — this is accepted, not treated as a gap to work around, since
+  an instance an admin has deliberately chosen not to persist analytics from cannot
+  simultaneously produce live experiment measurements.
+- Users who can already edit the Content Analytics app configuration today are the same users
+  authorized to change Analytics Mode — no new permission model is introduced.