Model records, revisions, and commands
Preserve the business meaning of a record across system boundaries.
Map identity before mapping fields
An entity definition describes a type. A record represents a particular item under that type. A revision identifies an applicable version of its content, and an execution records work against a governing source. Keep those identities separate in your integration.
External keys and labels can change or collide. Establish matching rules, namespaces, and correction behavior before importing records. A hash verifies the bytes or representation being hashed; it does not prove the physical identity of a material.
Carry meaning across the boundary
| Information | Why it matters |
|---|---|
| Record and source-system identifiers | Match the correct thing without relying on its display name. |
| Type and revision | Interpret fields and operating content in their applicable context. |
| Units and precision | Avoid a numerically valid but operationally incorrect result. |
| State and evidence | Distinguish received, reviewed, approved, held, and released. |
| Time and provenance | Separate when something occurred from when it was imported. |
Use governed operations for consequential changes
Treat release, review, activation, issue, and reversal as operations with prerequisites and outcomes. Directly setting a display status can omit the checks or evidence that make the state meaningful.
When designing the handoff, specify the intended operation, actor, expected record revision, evidence, and reconciliation reference. Use the actual request schema for your deployment; these are modeling considerations, not field names.
Preserve a correction trail
A correction should remain related to the original import or action. Distinguish changing an interpretation from changing source evidence. If a downstream effect has already occurred, plan the authorized reversal or compensating action explicitly.