Rhythm 2.0 Specifications

Appearance

CAP-PFM-DJE-008Restore a bulk update while preserving later changes

Markdown

CAP-PFM-DJE-008

Restore a bulk update while preserving later changes

Markdown
  • DocumentDraft
  • Product intentConfirmed
  • ImplementationObserved

Planning

Feature
FEAT-PFM-DJE-02
Exercised by
FAS-PFM-DJE-02-01, FAS-PFM-DJE-02-02, FAS-PFM-DJE-02-03, FAS-PFM-DJE-02-04, FAS-PFM-DJE-02-05
Key concepts
CON-PFM-DJE-001
Actors
ACT-PFM-035
Journeys
JNY-PFM-DJE-002
Related
CAP-PFM-DJE-004, CAP-PFM-DJE-006, CAP-PFM-DJE-007
Proved by
ATS-PFM-DJE-008

Implementation

Executable suites
TST-PFM-DJE-012, TST-PFM-DJE-032, TST-PFM-DJE-080, TST-PFM-DJE-119

KindCapabilityProduct areaPlatformModuleData Job EngineRevision1

Read atmacroservice-libraries 54536a44services-crm a8d1364freact-console baf6dae3

Restore a bulk update while preserving later changes ​

Purpose ​

Administrators plan restoration of reversible record changes and review anything that must remain as it is.

How It Works ​

An administrator requests rollback from a completed update. Rhythm compares its receipts and recorded history with the current records. It identifies records that can be restored and explains exclusions. A later change to an affected field prevents restoration of that record. Input containing a custom field or collection is also outside the supported restoration scope. The plan becomes a separate validated job that the administrator reviews and applies. Version checks preserve edits made after planning. A plan with no eligible records is already finished with rejections. The backend supports organization updates as well as contact updates, although the console exposes only contact restoration. The product should explain that surface difference and the records excluded from restoration.

Relationships ​

  • Job controls prevent retry after an applied rollback.
  • Intervening-edit protection supplies related concurrency safeguards.
  • Hard deletion is outside restoration scope.

The Formal Contract

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

Outcomes
Restoration has its own reviewed job.Later field changes remain protected and explain exclusions.Unsupported restoration is reported explicitly.
Surfaces
consoleapi
Intent sources
services-platform:docs/milestones/plans/PLAT-M19-plan.md#A3services-crm:docs/milestones/CRM-M7-data-operations.md#D-39services-platform:docs/milestones/plans/PLAT-M19-plan.md#S09

Controls

27 controls apply, from the corpus control catalogue.

TC-AVL-004 TC-AZ-001 TC-AZ-002 TC-AZ-003 TC-AZ-004 TC-DAT-001 TC-DAT-002 TC-DAT-003 TC-DAT-004 TC-LOG-002 TC-LOG-003 TC-LOG-004 TC-LOG-005 TC-MON-001 TC-PI-001 TC-PI-002 TC-PI-003 TC-PI-004 TC-PI-005 TC-PRV-001 TC-PRV-002 TC-TEN-001 TC-TEN-002 TC-TEN-003 TC-VEN-001 TC-VEN-002 TC-VEN-003

Permissions

KeyChecked atScope
crm.contacts.bulkapitenant
crm.contacts.updateapitenant
crm.organizations.bulkapitenant
crm.organizations.updateapitenant
data.jobs.rollbackconsoletenant

Business Rules

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

IdRuleKindEnforced atProvenance
01must prove
Confirmed
Rollback planning creates a separate validated job linked to the original, requiring its own impact fingerprint for application.
origin: services-platform:docs/milestones/plans/PLAT-M19-plan.md#A3
proved by ATS-PFM-DJE-004-09, ATS-PFM-DJE-005-10, ATS-PFM-DJE-008-01, ATS-PFM-DJE-008-07, ATS-PFM-DJE-008-08, TST-PFM-DJE-119
lifecycleservicetest
services-crm:modules/data-jobs/tests/integration/services/jobs/contact-update-rollback.integration.spec.js#plans it already validated, because planning a rollback IS validating it
02must prove
Confirmed
A record is reversible only when the affected fields still hold the job’s values and have no later changes; exclusions identify the field, editor and time, or report deletion, without quoting values.
origin: services-platform:docs/milestones/plans/PLAT-M19-plan.md#A3
proved by ATS-PFM-DJE-005-10, ATS-PFM-DJE-006-09, ATS-PFM-DJE-008-02, ATS-PFM-DJE-008-08, ATS-PFM-DJE-008-09, TST-PFM-DJE-080, TST-PFM-DJE-119
calculationservicetest
services-crm:modules/data-jobs/tests/integration/services/jobs/contact-update-rollback.integration.spec.js#says which field changed since the job and when, without saying what it was changed to
03must prove
Confirmed
Rollback input must carry each record’s current version; missing versions refuse the plan without creating work, and edits after planning conflict at application.
origin: services-crm:docs/milestones/CRM-M7-data-operations.md#D-39
proved by ATS-PFM-DJE-006-09, ATS-PFM-DJE-008-03, ATS-PFM-DJE-008-09, TST-PFM-DJE-032
policyservicetest
macroservice-libraries:packages/data-jobs/src/tests/integration/rollback-and-retry.integration.spec.ts#refuses a rollback plan with an unversioned item, and writes no rollback job
04must prove
Confirmed
Rollback refuses hard deletes, unfinished jobs, absent receipts, unsupported operations and jobs whose rollback has already been applied.
origin: services-crm:docs/milestones/CRM-M7-data-operations.md#D-39
proved by ATS-PFM-DJE-007-10, ATS-PFM-DJE-008-04, ATS-PFM-DJE-008-10, TST-PFM-DJE-012
validationservicetest
macroservice-libraries:packages/data-jobs/src/data-job-actions.spec.ts#does not offer Rollback once a rollback has been applied, by the code the route answers, and still does while one is only planned
05must prove
Confirmed
Rollback supports ordinary record fields; changing a collection or custom field makes that record non-reversible as a whole.
origin: services-platform:docs/milestones/plans/PLAT-M19-plan.md#A3
proved by ATS-PFM-DJE-008-05
policyservicedocumented
services-crm:docs/data-jobs.md#Putting a bulk change back
06must prove
Confirmed
Rollback requires bulk and update permission, with update authority rechecked for the submitter during processing.
origin: services-crm:docs/milestones/CRM-M7-data-operations.md#D-39
proved by ATS-PFM-DJE-008-06
permissionapi, servicedocumented
macroservice-libraries:packages/data-jobs/README.md#What a rollback promises, and what Retry does beside it
07
Confirmed
Contact and organization update operations support rollback; imports, configuration changes and activity jobs do not declare it.
policyservicedocumented
services-crm:docs/data-jobs.md#What is not built
08
Confirmed
A rollback with no reversible records is created in completed-with-rejections state.
lifecycleservicedocumented
macroservice-libraries:packages/data-jobs/README.md#Rolling a job back
09
Confirmed
A rollback job may itself be rolled back; merely planning rollback does not prevent another plan or retry of the original job.
proved by ATS-PFM-DJE-004-09, ATS-PFM-DJE-008-07
policyservicedocumented
macroservice-libraries:packages/data-jobs/README.md#Rolling a job back

Scenarios

IdGivenWhenThenProvenance
01A colleague edits two contacts after a ten-contact bulk update.An administrator prepares and applies restoration.The plan restores eight untouched contacts and preserves the two later edits as explained exclusions.test
services-crm:modules/data-jobs/tests/integration/services/jobs/contact-update-rollback.integration.spec.js#plans a rollback of the eight nobody touched, and refuses the two somebody did

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