---
id: CON-PFM-MTD-005
name: Custom Record
feature: FEAT-PFM-MTD-05
product_area: platform
module: metadata
revision: 1
status: draft
product_intent: confirmed
implementation_evidence: observed
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
definition: >-
  A custom record holds one instance of a custom object’s information, with derived identity, validated
  properties, relationships, lifecycle and retained change history.
owned_by: MOD-PFM-MTD
synonyms:
  - record of a custom object
  - 'boat, licence, inspection (the object''s own name)'
not_to_be_confused_with:
  - The object defines shared properties for all its records.
  - CRM retains values for contact-specific additional fields.
facets:
  - name: Property values
    meaning: Typed values governed by the object’s properties and applicable write rules.
    used_for: Keeping the organization’s information validated and queryable.
  - name: Number and name
    meaning: A sequence number and configured components that produce the display identity.
    used_for: Recognizing records consistently.
  - name: Version
    meaning: A concurrency token preventing stale replacement of committed work.
    used_for: Preventing stale saves from overwriting committed work.
  - name: Publication state
    meaning: Optional review and publication states with publication time.
    used_for: Determining publication availability for public consumers.
  - name: Archive and deletion
    meaning: 'Retained retirement or removal after version, lock and relationship checks.'
    used_for: Retiring and removing records under deliberate authority.
  - name: History
    meaning: Inspectable revisions with change context and prior values.
    used_for: Inspecting previous changes after lifecycle operations.
  - name: Business event
    meaning: Ledger announcements for supported committed operations and asynchronous delivery.
    used_for: Allowing subscribers to react to supported changes.
  - name: External id and loads
    meaning: A caller-supplied identity used for repeatable loads within an object.
    used_for: Running repeatable migrations and feeds.
relationships:
  - to: CON-PFM-MTD-004
    statement: A record belongs to its object and ordinarily requires that object to be active for mutation.
    provenance: test
    source: >-
      services-platform:modules/custom-objects/tests/integration/services/persistence/custom-object-records.integration.spec.js#refuses
      a record of a draft object, and writes nothing
  - to: CON-PFM-MTD-002
    statement: Property values use the object’s field definitions and applicable rules.
    provenance: test
    source: >-
      services-platform:modules/custom-objects/tests/integration/services/persistence/custom-object-records.integration.spec.js#requires
      the sail area of a sloop
  - to: CON-PFM-MTD-006
    statement: Connections to native and custom records determine the consequences of deletion.
    provenance: test
    source: >-
      services-platform:modules/custom-objects/tests/integration/services/persistence/custom-object-records.integration.spec.js#refuses
      to delete a record an open restricting association names, and removes nothing
lifecycle:
  - state: live
    meaning: Ordinary browsing and authorized writes are available.
    how_it_changes: Archival retains it; permitted deletion removes it.
  - state: archived
    meaning: Ordinary browsing excludes retained data and edits are blocked.
    how_it_changes: Restoration returns it to browsing; permitted direct deletion can remove it.
  - state: deleted
    meaning: The record is removed while revisions remain available under their contract.
    how_it_changes: There is no record restoration operation.
acted_on_by:
  - CAP-PFM-MTD-012
  - CAP-PFM-MTD-013
  - CAP-PFM-MTD-014
  - CAP-PFM-MTD-015
  - CAP-PFM-MTD-016
visible_to:
  - ACT-PFM-008
  - ACT-PFM-009
  - ACT-PFM-010
  - ACT-PFM-012
evidence:
  - >-
    services-platform at ad3f6a6582843008ed0f5a17b131878d15829af1: docs/custom-objects.md §12 to §24, Events,
    Import, export and reset; docs/business-events.md; docs/record-history.md;
    modules/custom-objects/db/custom-object-records.table.ts, custom-object-record-values.table.ts,
    custom-object-unique-values.table.ts, record-revisions.table.ts, business-events.table.ts,
    business-event-queue.table.ts, managed-assets.table.ts; services/persistence/custom-object-records.ts;
    record-rules.ts.
  - >-
    react-console at baf6dae382d6f41dce976c7f848667ccc37e076f: app/(console)/console/[tenantId]/objects/**,
    components/console/custom-objects/**; Playwright PLAT-M5-S03 to S07.
supersedes: []
---

# Custom Record

## What It Is

A custom record is one item in an organization-defined register. A Boat object defines the shared structure; the record for Miss Belle holds that boat’s particular information. Rhythm derives a recognizable name and number and keeps typed property values under the object’s definitions.

Records can also carry relationships, external identities and optional publication states. Archival and deletion are separate choices. History and business events provide different accounts of change: revisions support inspection of prior information, while events let subscribers react to supported committed operations.

## Why It Matters

Staff need to enter trustworthy information without bypassing the definition they share. Service validation protects type, required values, conditional rules, references and uniqueness. Version checks let two people work on the same item without silently replacing each other’s changes.

Retained history helps people understand corrections and lifecycle actions. External identities help integrations recognize an existing record on a later load. Relationship policies prevent a deletion from disregarding another record’s dependence on the item being removed.

## How It Works

A caller with suitable object reach creates or changes records while the object is active. The service validates the resulting values and reports property-specific problems without echoing rejected content. Creation can fill compatible defaults, and references must resolve to suitable existing records.

Patch retains omitted properties; replacement clears omitted live properties. Derived names combine configured components or fall back to the prefixed number. Numeric values use scaled storage within the supported safe range, and normalized unique reservations protect equivalent text values.

Visibility checks reject changed hidden values rather than automatically clearing untouched hidden information. A driver-only change can therefore retain a previously stored value. This is an examined implementation distinction that needs a product decision rather than a broader promise that every save removes hidden content.

## What It Contains

Property values, derived name and number, version, publication, archival, history, business events and external identity are the record’s main facets. Image and file values add managed attachments prepared before the record mutation. Failed preparation identifies the property without disclosing the supplied address.

Publication time follows the published state. Archival retains information and removes the record from ordinary browsing; it blocks ordinary edits and publication changes. Direct deletion remains possible for an unlocked archived record while its object is active, subject to the usual relationship and version checks.

## What It Is Related To

The custom object supplies the definition and operating settings. Custom fields and their rules govern property values. Links connect the record to contacts, organizations and other custom records, and endpoint policies determine whether deletion detaches, cascades or refuses.

History retains revisions even after deletion under its own access contract. The business-event ledger and delivery work support asynchronous consumers. Loads reuse the ordinary write contract, while their source identity and validated impact support repeatable integration work.

## What Needs Deciding

The product should settle the intended treatment of untouched hidden values and deletion of archived records. Event retention and dependency ordering also need focused proof beyond broad lifecycle tests. Design should keep record history, business announcements and audit separate, because their payloads, consumers and no-op behavior do not establish an identical account of every write.