Skip to content

Last reviewed: 2026-07-17 Approved by: HKWhitten Approved date: 2026-07-17 Audience: accounting, developer Governing truth: - Accounts - Account Contract - Account Role Contract - ADR 0023: BooksPlus Starter Chart and Dolibarr Account Crosswalk

Dolibarr Account Crosswalk Contract

This contract is canonical.

Ownership

BooksPlus owns the authoritative crosswalk, target-account validation, and canonical account-role assignments.

bp3-doli owns Dolibarr source-account identity, observed source attributes, projection convergence, and a synchronized operational mapping read model.

Neither system may infer the other system's identity from a visible code.

Canonical objects

DolibarrSourceAccountIdentity

Required fields:

  • dolibarr_source_account_id
  • source_system_instance_id
  • logical_account_key
  • entity
  • pcg_version
  • observed_stored_code
  • observed_label
  • observed_pcg_type
  • source_status
  • projection_version
  • created_by_actor_id
  • created_at
  • last_changed_by_actor_id
  • last_changed_at
  • reason
  • audit_reference
  • correlation_id
  • version

Allowed source statuses:

  • active
  • inactive
  • retired
  • conflict

Rules:

  • dolibarr_source_account_id is an opaque UUID assigned once and never recomputed from mutable attributes.
  • Source identity is the pair source_system_instance_id + dolibarr_source_account_id.
  • logical_account_key is stable across rename and renumber operations.
  • entity + pcg_version + observed_stored_code is a discovery locator and observed uniqueness boundary, not identity.
  • Codes are strings and preserve leading zeros.
  • Dolibarr row ids, labels, displayed or padded codes, pcg_type, and hashes of mutable fields are prohibited as source identity.
  • A pcg_version migration preserves source identity only when an approved migration explicitly declares logical continuity.
  • A missing or conflicting registry identity remains reviewable; it must not be replaced silently.

DolibarrAccountCrosswalkMapping

Required fields:

  • mapping_id
  • company_id
  • source_system_instance_id
  • dolibarr_source_account_id
  • booksplus_account_id
  • mapping_version
  • effective_from
  • effective_to
  • mapping_status
  • observed_dolibarr_stored_code
  • observed_booksplus_code
  • created_by_actor_id
  • created_at
  • last_changed_by_actor_id
  • last_changed_at
  • reason
  • audit_reference
  • correlation_id
  • version

Allowed mapping statuses:

  • pending_review
  • active
  • superseded
  • retired
  • conflict

Rules:

  • booksplus_account_id is immutable BooksPlus account identity.
  • Observed codes are review snapshots and must not be used as either system's identity.
  • Effective boundaries are dates and are inclusive.
  • effective_to, when present, must be on or after effective_from.
  • effective_to is a present nullable field; null means no approved end date.
  • Audit and correlation fields are present and may be null only when no such reference exists. A protected change still requires a reason.
  • Within one selected mapping version, active effective intervals must not overlap for the same company, source-system instance, and source-account id.
  • A source account resolves to at most one BooksPlus account for an activity date and selected mapping version.
  • The target BooksPlus account must belong to the company and satisfy active, posting, direct-posting, and workflow eligibility required by the operation.
  • Rename and renumber operations create history or new effective observations; they do not replace either immutable id.
  • Superseded and retired mappings remain available for historical activity-date resolution and audit.

The governed natural key is:

company_id
+ source_system_instance_id
+ dolibarr_source_account_id
+ mapping_version
+ effective_from

DolibarrRoleProjection

Required fields:

  • role_projection_id
  • company_id
  • source_system_instance_id
  • canonical_role_key
  • dolibarr_source_account_id
  • booksplus_account_id
  • mapping_version
  • effective_from
  • effective_to
  • mapping_status
  • creation and last-change attribution, reason, audit, correlation, and version fields matching the crosswalk mapping

Rules:

  • canonical_role_key must exist in the Account Role Contract.
  • The BooksPlus role assignment must resolve the canonical role to the same booksplus_account_id carried by the active account crosswalk.
  • A role projection is an operational mapping; it does not create or replace a BooksPlus AccountRoleAssignment.
  • Singleton roles resolve to at most one Dolibarr source account for the same company, source system, selected mapping version, and activity date.
  • All six ADR 0023 InvAcct roles must resolve before Inventory Summary export is ready.
  • A product or supplier-invoice account code may be reconciled to a role projection only through exact stored-code evidence and recorded Dolibarr formatting context.

The governed natural key is:

company_id
+ source_system_instance_id
+ canonical_role_key
+ mapping_version
+ effective_from

DolibarrMappingSetSelection

Required fields:

  • selection_id
  • company_id
  • source_system_instance_id
  • mapping_version
  • effective_from
  • effective_to
  • selection_status
  • creation and last-change attribution, reason, audit, correlation, and version fields

Allowed selection statuses:

  • pending_review
  • active
  • superseded
  • retired
  • conflict

Rules:

  • A resolver receives or obtains one explicit selected mapping version.
  • Active selection intervals must not overlap for the same company and source system.
  • More than one applicable active selection is ambiguous and fails resolution.
  • A resolver must not select the newest mapping row or version silently.

Resolution

Required request context:

  • company id;
  • source-system instance id;
  • activity date;
  • selected mapping version, or an unambiguous effective mapping-set selection; and
  • either stable source-account id or canonical role key.

Successful account resolution returns:

  • stable Dolibarr source-account id;
  • immutable BooksPlus account id;
  • canonical role key when role resolution was requested;
  • mapping version and effective interval;
  • exact observed Dolibarr stored code;
  • observed BooksPlus code;
  • source and target eligibility state; and
  • mapping/audit reference.

Allowed resolution outcomes:

  • resolved
  • missing
  • ambiguous
  • stale
  • inactive_source
  • ineligible_target
  • wrong_scope
  • conflict

Only resolved permits the governed operation to continue. Zero applicable rows is missing. More than one applicable row or selection is ambiguous.

Validation and conflict handling

Validation must reject or hold for review:

  • overlapping active effective intervals;
  • multiple active mapping-set selections;
  • duplicate singleton role targets;
  • wrong-company or wrong-source-system references;
  • unknown or conflicting source-account identity;
  • an inactive source needed by the operation;
  • an inactive, retired, non-posting, wrong-company, or otherwise ineligible BooksPlus target;
  • a role projection inconsistent with the BooksPlus AccountRoleAssignment;
  • a stale observed code after rename or renumber;
  • a stored/displayed-code mismatch that cannot be explained by captured Dolibarr formatting controls; and
  • incompatible identity reuse during pcg_version migration or rebuild.

No resolver, migration, provisioning pass, or reconciliation process may repair these conditions silently.

Synchronization recommendation

BooksPlus should publish a company/source-scoped versioned crosswalk snapshot or equivalent API representation containing mapping-set selection, account mappings, role projections, version, generated time, and content checksum.

bp3-doli should validate and retain that snapshot as an operational read model. It should reject a checksum conflict, unsupported contract version, missing mapping version, or stale snapshot when the consuming operation requires a newer approved version. Transport details remain outside this contract.

Persistence recommendation

BooksPlus PostgreSQL persistence should enforce immutable ids and natural-key uniqueness in the database and should combine service validation with a database-level non-overlap constraint for active effective intervals and mapping-set selections. A write should lock or otherwise serialize the affected company/source/version scope so concurrent approvals cannot create an ambiguity that each request failed to observe.

bp3-doli should import a complete approved snapshot transactionally, validate its checksum, contract version, mapping version, effective intervals, source identities, and six required InvAcct roles, then make the new read model active as one cutover. A partial snapshot must never become the active resolver state.

Security and audit

Source-account adoption, crosswalk change, role projection, mapping-set selection, and retirement are protected accounting-configuration actions. They require actor and company context, authorization, reason, append-only audit evidence, and correlation context when part of a multi-step change.

Customer-identifying configuration and credentials must not appear in public projection artifacts or logs.

Required verification

  • UUID and logical-key stability across rename and renumber;
  • reproducible provisioning restores the same standard/profile UUIDs;
  • reviewed adoption assigns one UUID and is idempotent on replay;
  • mapping resolution before, on, and after both inclusive effective boundaries;
  • rejection of overlapping intervals and multiple selected versions;
  • rejection of missing, ambiguous, stale, inactive, wrong-scope, and ineligible mappings;
  • all six InvAcct role projections are mandatory for export readiness;
  • exact stored-code comparison remains distinct from displayed padding;
  • customer overlays may change compatible stored codes but not protected roles or source identity; and
  • normalized export, drift comparison, configuration history, and reconciliation contain source identity and mapping evidence.