Data case / 03 · Activation contract, removals & reconciliation

Operationalizing analytical signals back into CRM

Computing a metric or a segment is the easy part. Making it arrive safely where people act—and stop driving action when it is no longer true—is the design.

The case in brief

Current reality

Performance and segments are computed in the analytical layer, but people act in the CRM—and without an activation contract, values arrive stale, editable, duplicated or long after they stopped being true.

What must become true

The CRM receives only the governed signals needed for operational action—each with its subject, value or state, as-of date, version, definition, provenance and current or removed status—so updates, removals and reruns are safe and the published state is reconciled against the expected analytical state.

Design question

What should be written back into the operational system, at what grain—and how does a changed or removed signal stop driving action safely?

01The reality · current state

What the data does today.

Account performance, pipeline coverage and a monthly performance segment—On Track, Underperforming, At Risk or No Sale—are computed in the data platform. Sellers and managers work in the CRM and should act there. The first attempt copied every KPI detail into CRM fields that users could overwrite, with no date and no link to the definition; segments were added but never removed, and a rerun after a failure wrote some accounts twice.

  • Sellers overwrite derived values they disagree with
  • Nobody can tell whether a value is from today or from last month
  • Some accounts carry two segments after a rerun; others carry none
  • Accounts that left the population keep their last segment for months
  • A partially failed writeback goes unnoticed for weeks
  • Teams recompute the metric in CRM reports because they do not trust the copy

02The semantic problem

Which meanings are mixed today.

Without an activation contract, every team picks one of the same bad options.

  • Recompute in the CRMA second definition of the metric, drifting from the first.
  • Query live on every screenValues that cannot drive lists, assignment or automation—and fail when analytics is down.
  • Copy the detailAnalytical history in operational fields, without provenance or a freshness promise.
  • Add, never removeOld segments keep driving action after the condition changed.

03Key dimension · Activation contract, removals & reconciliation

A signal has a lifecycle—and an explicit exit

What lands in the CRM is small, read-only and self-describing. Every state of the signal carries its version, freshness and provenance, and the lifecycle only closes when what was expected is what the CRM holds.

Lifecycle of a signal
  1. 01ComputedDerived from the governed modelCarries Definition version
  2. 02PublishedReleased as the full expected state for the periodCarries Run version · as-of date
  3. 03AppliedUpserted in the CRM by key—safe to repeatCarries Delivery state
  4. 04CurrentRead-only on the account, available for actionCarries Freshness · provenance link
  5. 05Changed or removedA new value, a new segment or “not eligible”—never a silent blankCarries New version
  6. 06ReconciledExpected compared with actual; differences have ownersCarries Reconciliation result

The activation contract

Activation contract: each field, the question it answers and its rule
FieldAnswersRule
SubjectWhich account does it apply to?The governed business key—never a name
SignalWhich value or commercial state?Exactly one current state per eligible account
GrainAt which operational level does it make sense?Account × signal × period
As ofWhen was it true?Shown beside the value; stale after its promise
VersionWhich definition and run produced it?A recalculation publishes a new version; the CRM keeps the latest
ProvenanceWhere can the evidence be traced?Links to the definition, owner and sources
ActionabilityWhich downstream process may react?Declared per signal; the reaction belongs to the automation case
ExitWhat happens when it is no longer true?An explicit removal or “not eligible”, applied like any other change

Expected state against actual state

Eligible accounts for the period, as published

ExpectedIn the CRMCompared byAccount identityCurrent segmentPeriodRun versionEligibility
Show
Expected compared with In the CRM, one row per key
KeyExpectedIn the CRMOutcome
ACC-A12On TrackOn TrackMatchBoth sides agree.
ACC-B07At RiskUnderperformingDifferenceWrong state: a rerun applied an older version after the newer one.
ACC-C33Underperforming—MissingThe writeback batch stopped half-way.
ACC-D19Not eligibleNo SaleUnexpectedThe account left the population; its removal was never written.
ACC-E02At Risk · v7At Risk · v6DifferenceStale version: the value is right, but it was produced by an older definition.
ACC-F58No SaleNo SaleMatchBoth sides agree.
  1. Match

    Same account, same state, same version.

    Owner
    Nobody
    Action
    Record the check.
  2. Difference

    Wrong state or stale version.

    Owner
    Data platform team
    Action
    Re-apply the current version; the upsert by key is idempotent.
  3. Missing

    Published, not present in the CRM.

    Owner
    Integration operations
    Action
    Replay the missing keys from the run.
  4. Unexpected

    Present in the CRM, not in the published population.

    Owner
    Data platform team
    Action
    Write the removal so it stops driving action.

An analytical signal in the CRM is a governed projection—not a second source of analytical truth. Removal is a first-class state change, and reconciliation is part of activation, not cleanup.

04Grain & contracts

What one row or message means.

Meaning, grain, key, freshness and owner—written down before anything is mapped.

Contract

Account signal

The published value or state of one signal for one account and period.

Grain
Account × signal × period
Key
Analytical customer key + signal + period + version
Freshness
Daily; stale after its promise
Owner
Sales operations (definition) · data team (computation)
Contract

Segment membership

The current segment of one eligible account for one period.

Grain
Account × period
Key
Account + period + run version
Freshness
Monthly, rerunnable
Owner
Sales operations
Contract

Membership change

An entry, change or removal to apply downstream.

Grain
Account × change
Key
Account + period + change type
Freshness
Within a day of the run
Owner
Data platform team
Why this grain
Chosen grain
Account × signal × period: the level at which a seller or manager can act.
Too fine
Transaction or line detail in the CRM is analytical history, not a signal—and it goes stale.
Too coarse
Region or team values cannot drive an account’s list view, assignment or follow-up.

05Identity & authority

Who may create, change, read or derive each concept.

Highlight
Data authority by business concept: which system may create, update, read or derive each concept
Business conceptData platformIntegration layerCRM
Eligible populationDefined once in the data platform; the CRM does not decide who is in scope.DeriveNo authorityRead
Signal value & segmentDerived in the data platform; read-only in the CRM. A dispute goes to the definition owner, not into the field.DeriveNo authorityRead
As-of date, version & provenanceStamped at computation; travels with every value.CreateReadRead
Writeback delivery stateOwned by the layer that writes; reconciled against what was published.ReadCreateUpdateNo authority
Signal historyKept by period in the data platform—never in CRM fields.CreateNo authorityNo authority
Seller comment on the signalThe seller’s context—kept beside the value, never replacing it.ReadNo authorityCreateUpdate

No system owns a whole record here. Authority sits with each concept—and sometimes changes hands when the lifecycle does.

06Population, version & freshness

Publish the full expected state—not only the additions.

Treating only new entries as events makes removals, reclassification and recovery invisible. Publishing the complete expected state for the period makes every one of them explicit.

Population and version rules for published signals: the rule and why it exists
RuleWhy
The eligible population is explicitAn account with no segment and an account out of scope are different facts
Exactly one current state per eligible accountTwo memberships—or none—are detectable failures, not edge cases
Every run publishes the full expected stateRemovals and recoveries are visible as changes, not as absences
Changes are applied by run versionA rerun is idempotent; an older version never overwrites a newer one
Every value carries its as-of date and freshness promiseA stale value is visibly stale, and new actions are suppressed

07Candidate architectures

Credible options, judged against these premises.

Situational

Query live from the CRM

Users who only look at the number

Cost: Cannot drive list views, assignment or automation; depends on analytics being up
Rejected

Copy every KPI detail and add segments as they appear

Small, stable populations that never shrink

Cost: Volume, staleness, duplicates and removals nobody sees
Selected

Governed signals at account grain, full expected state, idempotent apply, reconcile

Signals that should change an operational action

Cost: Needs an activation contract, run versions and a reconciliation step

Design decision

Publish a small set of governed, read-only analytical signals at an operationally meaningful grain; treat changes and removals as explicit state transitions; apply them idempotently; and reconcile the complete expected state against what the operational system actually holds.

08Resulting architecture

Where the data comes from, where it goes—and how.

Every hand-over is named with its mode. The mode follows the business tolerance for waiting, inconsistency and loss.

Systems and partiesData platformIntegration layerCRM

  1. 01 · Data platformGoverned model

    Performance at account × month—see the performance data model.

    Hands over by Batch
  2. 02 · Data platformSignal computation

    Metric values and exactly one segment per eligible account.

    Hands over by Batch
  3. 03 · Data platformExpected state

    The full population for the period, with explicit removals.

    Hands over by API
  4. 04 · Integration → CRMCRM writeback

    Upsert by account, signal and version; read-only fields.

    Hands over by Event
  5. 05 · CRMAvailable for action

    Current signals on the account—what happens next belongs to the automation case.

09Failure & quality

Design the failure path before the happy path.

  • Writeback partially succeedsReconciliation: missingReplay the missing keys; upsert makes it safeIntegration operations
  • A rerun after a failureSame period, new run versionApply by version; older versions are ignoredData platform team
  • An account leaves the populationReconciliation: unexpectedWrite the removal explicitly; downstream reactions close through the automation caseData platform team
  • An eligible account gets no segmentPopulation count against segmented countFail the run before publishingSales operations
  • Values are older than their promiseAs-of date past the freshness promiseShow “stale” in the CRM and suppress new actionsData platform team

Data quality is a property of the contract

Signal quality: dimension, owner, how it is detected and what happens when it fails
DimensionOwnerDetected byWhen it fails
CompletenessData platform teamPopulation count against segmented countThe run is not published
IdentityMaster dataSignals whose subject has no current accountHeld back and routed to master data
FreshnessData platform teamAs-of date against the promiseShown as stale; no new actions
ReconciliationIntegration operationsExpected against actual after every runDifferences routed to their owners

10Governance

Who keeps the meaning stable over time.

Governance of activation: what is governed, by whom, how often and on what evidence
WhatOwnerCadenceEvidence
Which signals reach the CRMSales operationsWith every new signal requestSignals published and the actions they drive
Freshness promise per signalData platform ownerReviewed quarterlyStale signals by period
Reconciliation differencesIntegration operationsAfter every runOpen differences and their age

11The second layer

Questions that change the design.

What lands

  1. Should the value be copied or queried live?
  2. What is the writeback grain—and what does the user need beside the number?
  3. Which downstream process may react to it?

Change & removal

  1. What happens when the metric is recalculated?
  2. How is “no longer eligible” represented?
  3. How is a rerun made safe?

Ownership

  1. Who owns a failed writeback?
  2. Can the CRM change the analytical value?
  3. Who owns each class of reconciliation difference?

12Decisions & outputs

What the work produces.

  1. 01Activation contract
  2. 02Signal lifecycle
  3. 03Eligibility & exactly-one-state rules
  4. 04Removal semantics
  5. 05Run versioning & rerun rule
  6. 06Expected-vs-actual reconciliation
  7. 07Lineage link