Rhythm 2.0 Specifications

Appearance

CAP-CRM-REG-010Identify placements that need recalculation

Markdown

CAP-CRM-REG-010

Identify placements that need recalculation

Markdown
  • DocumentDraft
  • Product intentProposed
  • ImplementationObserved

Planning

Feature
FEAT-CRM-REG-04
Key concepts
CON-CRM-REG-002, CON-CRM-REG-004
Actors
ACT-CRM-003, ACT-CRM-002
Journeys
JNY-CRM-REG-002
Depends on
CAP-CRM-REG-003
Related
CAP-CRM-REG-002, CAP-CRM-REG-003, CAP-CRM-REG-004, CAP-CRM-REG-005, CAP-CRM-REG-011
Proved by
ATS-CRM-REG-010
Exercised by
JNY-CRM-REG-001, JNY-CRM-REG-004

KindCapabilityProduct areaCRMModuleRegionsRevision2

Read atservices-crm a8d1364freact-console baf6dae3

Identify placements that need recalculation ​

Purpose ​

Staff distinguish records placed under earlier settings from records brought into line with the current policy.

How It Works ​

Saving a policy records a change without moving existing records. The settings read compares its policy generation with successful recalculations. The console uses the resulting signal to show a banner on the Assignment Rules tab. A successful run clears that signal only if its recorded generation covers the current policy. A rule changed during processing leaves the signal set after completion. Counting generations recognizes changes that share a timestamp with the start of a run. An unchanged settings save still raises the count and can request unnecessary recalculation. Disabled assignment suppresses the request. Staff use the explicit recalculation action to bring older placements into line.

Relationships ​

  • Configure automatic placement and its address sources establishes participation and address-source choices for placement.
  • Retire regions while preserving their references handles retirement and reference-sensitive removal of regional definitions.
  • Build the geographic assignment policy maintains the geographic policy that other regional workflows evaluate.
  • Maintain individual rules alongside the shared policy provides individual-rule API maintenance alongside whole-policy editing.
  • Apply the current policy across existing records applies policy changes to existing records.

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Outcomes
Policy changes leave existing placement intact until recalculation.Staff receive a signal when the current policy generation lacks a successful run.
Surfaces
consoleapi
Intent sources
services-crm:docs/migrations/crm-regions/README.md#2026-10-08 — Final acceptance (decision 2026-10-08, Andrew: saving rules changes no record; staff press Recalculate)services-crm:docs/migrations/crm-regions/README.md#2026-10-12 — Final acceptance (second pass), decision 2026-10-11: rule or setting changes move no record; manual Recalculate with a recalculation-needed bannerservices-crm:docs/migrations/crm-regions/README.md#2026-10-15 — Final acceptance (console follow-ups) (Andrew approved 2026-10-15: two tabs, Test an Address dialog, drawers, a read-only Assignment Rules tab with its own editor screen and the banner)

Controls

16 controls apply, from the corpus control catalogue.

TC-AZ-001 TC-AZ-002 TC-AZ-003 TC-AZ-004 TC-AZ-006 TC-DAT-001 TC-DAT-002 TC-DAT-003 TC-LOG-004 TC-LOG-005 TC-PI-001 TC-PRV-001 TC-PRV-002 TC-TEN-001 TC-TEN-002 TC-TEN-003

Permissions

KeyChecked atScope
crm.regions.readapitenant

Business Rules

10 rules, 7 to be proved before approval. A rule's product intent is derived from its origin: 0 confirmed by a product decision, the rest inheriting this capability's proposed.

IdRuleKindEnforced atProvenance
01must prove
Proposed
Saving assignment settings or rules leaves contact and organization placements unchanged until staff run recalculation.
origin: services-crm:docs/migrations/crm-regions/README.md#2026-10-08 — Final acceptance (decision 2026-10-08, Andrew: saving rules changes no record; staff press Recalculate)
no proof recorded yet
policyservicetest
services-crm:modules/regions/tests/integration/services/region-assignment/region-assignment.integration.spec.js#rule changes and the recalculation › changes no record when the rules are saved
02must prove
Proposed
With assignment enabled, recalculation is needed after policy changes beyond the generation of a successful run or when no run has succeeded.
origin: services-crm:docs/migrations/crm-regions/README.md#2026-10-12 — Final acceptance (second pass), decision 2026-10-11: rule or setting changes move no record; manual Recalculate with a recalculation-needed banner
no proof recorded yet
calculationservicetest
services-crm:modules/regions/tests/integration/services/region-assignment/region-assignment-rules.integration.spec.js#whether a recalculation is needed › says a recalculation is needed once the rules have been saved and nothing has recalculated
03must prove
Proposed
Settings saves, individual-rule writes and deactivation of targets referenced by enabled rules increment the policy change count.
no proof recorded yet
calculationservicetest
services-crm:modules/regions/tests/integration/services/region-assignment/region-assignment-rules.integration.spec.js#whether a recalculation is needed › says one is needed again as soon as a rule is added
04must prove
Proposed
A policy change committed during a run leaves recalculation needed after that run completes.
origin: services-crm:docs/migrations/crm-regions/README.md#2026-10-12 — Final acceptance (second pass), decision 2026-10-11: rule or setting changes move no record; manual Recalculate with a recalculation-needed banner
no proof recorded yet
calculationservicetest
services-crm:modules/regions/tests/integration/services/region-assignment/region-assignment-rules.integration.spec.js#whether a recalculation is needed › a rule saved while a recalculation is under way › says one is still needed, because the run was recorded under the rules as they were before
05must prove
Proposed
Recalculation need compares generation counts rather than timestamps, recognizing changes even at the same instant as a run starts.
no proof recorded yet
calculationservicetest
services-crm:modules/regions/tests/integration/services/region-assignment/region-assignment-rules.integration.spec.js#whether a recalculation is needed › a rule change stamped at the very instant the last run started › says one is needed after a rule is added at the very instant the run started
06must prove
Proposed
Disabled assignment and workspaces without saved settings do not request recalculation.
no proof recorded yet
calculationservicetest
services-crm:modules/regions/tests/integration/services/persistence/region-assignment-settings.queries.integration.spec.js#a tenant that has saved no settings › says no recalculation is needed, because a tenant with no settings assigns nothing to recalculate
07
Proposed
Settings reads include the time of the most recent recorded policy change.
policyservicetest
services-crm:modules/regions/tests/integration/services/persistence/region-assignment-settings.queries.integration.spec.js#the settings of a tenant that saved them › answers the moment the rules last changed, which is the save that wrote them
08must prove
Proposed
An unchanged settings replacement still increments the policy change count.
no proof recorded yet
calculationserviceobserved
services-crm:modules/regions/services/persistence/region-assignment-settings.ts:saveRegionAssignmentSettings
09
Proposed
The Assignment Rules tab displays a recalculation-needed banner with its own action when required and omits it otherwise.
origin: services-crm:docs/migrations/crm-regions/README.md#2026-10-15 — Final acceptance (console follow-ups) (Andrew approved 2026-10-15: two tabs, Test an Address dialog, drawers, a read-only Assignment Rules tab with its own editor screen and the banner)
policyconsoletest
react-console:components/regions/__tests__/recalculation.test.tsx#the banner › asks for a recalculation and carries the button to run it
10
Proposed
With automatic assignment disabled, the console neither requests nor offers recalculation.
policyconsoletest
react-console:components/regions/__tests__/rules-tab.test.tsx#the Assignment Rules tab while assignment is off › does not ask for a recalculation of records nothing is assigning

Scenarios

IdGivenWhenThenProvenance
01The current policy has a successful recalculation.An administrator adds and saves another rule.Existing placements remain and recalculation becomes needed.test
react-console:e2e/dev/regions.dev.spec.ts#asks for a recalculation after a rule changes, and stops asking once it has run

Edge Cases

IdGivenWhenThenProvenance
02A recalculation is processing existing records.An administrator changes the policy before completion.The completed run does not clear the need for another recalculation.test
services-crm:modules/regions/tests/integration/services/region-assignment/region-assignment-rules.integration.spec.js#whether a recalculation is needed › a rule saved while a recalculation is under way › says one is still needed, because the run was recorded under the rules as they were before

The Markdown files under specs/ in rhythmsoftware/rhythm-v2-docs are the canonical source of truth. This reader is a generated, read-only projection of them.

Rhythm Software