--- product_area: platform module: data-job-engine revision: 1 status: draft owned_by: MOD-PFM-DJE synonyms: - producer key - external key - ID crosswalk entry supersedes: [] id: CON-PFM-DJE-004 name: Source Key feature: FEAT-PFM-DJE-04 product_intent: confirmed implementation_evidence: observed source_sha: macroservice-libraries: 54536a441935c6e09fdb7f96f0bec71c52ba4e03 services-crm: a8d1364f1dd44b723bb5f9acba12f983e9ec8d69 services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 definition: >- A source key identifies a producer’s record within its source system and record kind; a workspace mapping connects that identity to its Rhythm record and delivery evidence. not_to_be_confused_with: - >- Destination identifiers and display numbers identify Rhythm records rather than their producer mappings. - Duplicate-detection identity concerns whether different records represent the same person. facets: - name: Producer identity meaning: The source-system name namespaces keys supplied by different producers. used_for: Separating independent feeds. - name: Delivery revision meaning: Producer revision tokens contribute to operation-specific stale and duplicate decisions. used_for: Ordering and reconciling repeat input. - name: Replacement policy meaning: >- Reject protects later staff edits; overwrite permits producer replacement subject to explicit expected versions. used_for: Choosing authority for recurring updates. - name: Producer-written version meaning: The mapping records the destination version last written by that producer. used_for: Detecting intervening destination edits. - name: Keyed references meaning: Input can identify dependencies through their producer keys. used_for: Loading related records without destination identifiers. relationships: - to: CON-PFM-DJE-001 statement: Successful keyed record writes retain their mappings in the same transaction. provenance: documented source: 'macroservice-libraries:packages/data-jobs/README.md#Keyed writes and the ID crosswalk' - to: CON-PFM-DJE-005 statement: Workspace reset removes loaded mappings with records so later input starts a new load. provenance: documented source: 'services-platform:docs/data-jobs/tenant-reset.md#2. What goes and what stays' acted_on_by: - CAP-PFM-DJE-006 - CAP-PFM-DJE-012 - CAP-PFM-DJE-015 - CAP-PFM-DJE-017 visible_to: - ACT-PFM-035 - ACT-PFM-036 - ACT-PFM-037 evidence: - >- Reviewed evidence: macroservice-libraries (54536a44): packages/data-jobs/README.md (Keyed writes and the ID crosswalk); src/keyed-item-decision.ts, apply-keyed-item.ts, data-id-mapping-columns.ts. - >- Reviewed evidence: services-crm (a8d1364f): docs/data-jobs.md (The crosswalk; Reading a load back by source key); modules/data-jobs/export/import-crosswalk.dataset.ts. - 'Reviewed evidence: services-platform (ad3f6a65): docs/data-jobs/platform-data-operations.md.' --- # Source Key ## What It Is A source key is how a producing system identifies a record it sends to Rhythm. The producer might know a membership number or an identifier from the customer’s previous system, while Rhythm has a different destination identity. The mapping between them allows later work to ask which destination record belongs to the producer’s input rather than guessing from a name or address. That mapping is scoped to the workspace, producer and record kind. It retains the destination record and evidence about the producer’s applied delivery. Repeated input can therefore be interpreted according to the requested operation and revision. The same visible key from another producer does not automatically identify the same record. This concept is broader than a column on an import form. It supports recurring delivery, dependency resolution, correction and reconciliation across several jobs. Staff do not normally maintain the mapping as a catalogue; they encounter it through those tasks. ## What It Is Not A producer key is not a Rhythm display number, and it is not inherently the record’s stored external identifier. Imports can default that external identifier from the key, but the mapping and record value remain distinct. Nor is a mapping a duplicate-detection judgment. A different key can identify a new destination record even when Product would consider it another representation of the same person. ## How It Is Used Integrations provide keys in their input and use supported lookups to inspect the resulting records. Implementation staff use keyed references when datasets depend on records loaded elsewhere in a package. Administrators encounter the same identity model in file-based insert, upsert and update work. Good use establishes a stable producer namespace and revision convention before recurring delivery begins. Insert, whole-record replacement and patching have different repeat-input behavior. Treating them as identical can hide an intended update or replace information unexpectedly. Staff also need to decide whether the producer may overwrite local corrections rather than allowing the delivery tool to make that authority choice implicitly. ## Its Facets **Producer identity.** The source-system namespace distinguishes independent feeds and keeps similar keys from accidentally sharing a mapping. **Delivery revision.** Revision tokens help determine whether input is old or repeated. Their ordering must match the producer’s intended sequence; opaque text does not necessarily sort like numbered versions. **Replacement policy.** This records whether recurring input should protect a later staff correction or permit the producer to replace it. Explicit expected versions can provide a sharper condition for a particular write. **Producer-written version.** The mapping remembers the destination version associated with the producer’s write, providing context for later concurrency checks. **Keyed references.** Records can describe parents, organizations and other dependencies using identities the producer already knows. Missing references explain blocked input rather than requiring fabricated destination identifiers. ## How It Relates Data jobs use mappings during keyed processing. Successful creation retains the mapping with its record, while rejected creation leaves the producer identity available for correction. Reconciliation reads the current destination record rather than reconstructing an immutable import snapshot. Reset clears loaded mappings; deletion and supported merge behavior affect their destinations. ## What It Could Become Product still needs to decide how new-key imports participate in duplicate detection. Membership also needs executable mapping infrastructure before its declared operations can load structure. Clearer revision and overwrite-policy guidance would help integrations reconcile deliveries without relying on assumptions about identity or ordering.