Skip to content

Source truth: - Accounts - Account Contract - Account Role Contract - Chart Import Contract - Starter Chart Installation Contract - Setup Readiness Contract - ADR 0017: Chart Maintenance Surrounds the Accounting Kernel - ADR 0023: BooksPlus Starter Chart and Dolibarr Account Crosswalk

Chart of Accounts

The chart of accounts classifies the company's accounting activity. The current desktop presents one Guided Setup area for choosing and reviewing the BooksPlus starter chart, the active chart already present, or a staged CSV chart import. It also supports starter-chart collision review and exact chart acknowledgement.

Current desktop boundary

Account-role assignment or repair still exists behind application services but has no supported desktop entry point. Do not change roles through service-level instructions or direct database repair. The current desktop can display and acknowledge valid assignments but cannot repair a retained or imported chart's missing roles.

Choose the visible chart path

Use the starter chart when the company can use BooksPlus's compact launch chart and does not need to preserve a different chart structure. Choose Install starter chart from Guided Setup.

If the company already has an active chart, choose Review Current Chart. Retaining the chart does not give its accounts starter identity and does not assign missing BooksPlus account roles. Keep Existing Chart remains the equivalent choice when a starter-chart collision review is already pending.

Choose Staged CSV chart import only for account master data that has been reviewed outside BooksPlus and can use the supported columns described below.

Install and review the starter chart

  1. In Guided Setup, choose Install starter chart.
  2. If no collisions are found, inspect the displayed chart result. Confirm the account code, name, type, status, posting eligibility, source, and starter identity shown for the accounts.
  3. Choose Acknowledge displayed chart only after reviewing that exact result.
  4. On the next Guided Setup item, inspect every required account role and its assigned account before choosing Acknowledge displayed account roles.

Running starter installation again does not create duplicate starter accounts. Account codes are text and may contain leading zeros. Account identity remains stable even if an account code changes later.

Review an existing chart

  1. In Choose one chart path, confirm that the active accounts displayed in Guided Setup are the intended company chart.
  2. Review each account's code, name, type, normal balance, status, posting eligibility, source, and stable identity.
  3. Choose Review Current Chart to acknowledge that exact displayed result.

This action does not install starter accounts, infer meaning from account numbers, or create role assignments. If required roles are missing, setup moves to account-role review and remains blocked there until the later supported role-resolution surface is available.

Stage and commit a CSV chart

Prepare a UTF-8 CSV with this header row:

code,name,type,normal_balance,status,description,external_id

code, name, type, and normal_balance are required. Supported types are asset, liability, equity, income (or revenue), and expense (or cost_of_sales). Normal balance is debit or credit. Status may be blank or active; an initial import cannot create inactive or retired accounts. Account codes are text, so leading zeros are preserved. Do not include opening balances.

  1. Enter a durable source name and paste the CSV content.
  2. Choose Stage CSV Preview. BooksPlus stores the source fingerprint, normalized rows, actor, time, and every warning or blocking error.
  3. Review every displayed row and issue. An existing same-company code produces a warning and that row will be skipped; invalid or duplicate import rows are blocking errors.
  4. If errors are present, correct the source and stage it with a new source name. Do not commit or acknowledge the blocked preview.
  5. When Commit Displayed Import is enabled, choose it once. BooksPlus creates only the reviewable active accounts through governed account maintenance and records the result.
  6. Inspect the resulting active chart, including source and posting eligibility, then choose Acknowledge displayed chart.

BooksPlus rejects silently staging the identical CSV source twice. A staged preview survives reload. A chart acknowledgement is unavailable while the latest selected preview remains staged, even when it contains no errors; commit the displayed preview first.

Resolve starter-chart collisions

BooksPlus preflights the complete starter chart before changing accounts. If an existing account uses a starter code, Starter-chart collisions require review appears and all collisions are listed together.

Review the existing and starter account details, compatibility result, and any issues. Then choose one available action:

  • Adopt Compatible — available only when every listed account is compatible. Adoption keeps the existing account identity, source, code, name, activity, and history, and adds the reviewed standard identity and canonical role assignments.
  • Keep Existing Chart — retain the current chart without starter identity or starter role assignments. Required role readiness may remain blocked.
  • Cancel Review — make no account or role changes. Correct the chart later through an authorized account-maintenance path and retry.

An account is not compatible merely because its number, name, or source looks similar. Incompatible collisions cannot be adopted. Do not resolve collisions by deleting accounts, silently renumbering them, rewriting their source, or resetting the database.

Review account roles

Account roles connect business meaning to stable account identity; they do not derive meaning from account numbers. Guided Setup displays each required launch role, its cardinality, assigned account code and name, immutable account reference, and eligibility.

Required launch-readiness roles are:

Role shown in setup Business meaning
receivable.trade Trade accounts receivable
payable.trade Trade accounts payable
tax.sales_tax_payable Sales-tax liability
equity.retained_earnings Retained earnings and equity continuity
revenue.product Product revenue
expense.cost_of_goods_sold Cost of goods sold
expense.inventory_adjustment Inventory-adjustment expense
expense.purchase_price_variance Purchase-price variance
clearing.inventory_fallback Review clearing for unresolved inventory movement meaning

A role is blocked when its assignment is missing, duplicates a singleton, points to another company, or resolves to an inactive, retired, non-posting, or otherwise ineligible account. The account-role acknowledgement remains disabled until every required role shown is valid.

To resolve a required role:

  1. In Resolve required launch account roles, review every role's key, required-singleton cardinality, current account, eligibility, and blocker.
  2. Under Assign or replace one required role, select the required role.
  3. Select an eligible account. The list contains only active same-company posting accounts with direct posting allowed; the account's code, name, and type are shown for recognition.
  4. Enter the business reason for the assignment or replacement.
  5. Choose Assign Selected Role and inspect the updated exact role subject.
  6. Repeat until every required role has one eligible assignment, then choose Acknowledge displayed account roles.

Assignment uses stable account identity and does not change the account's code, name, type, normal balance, source, or posting configuration. BooksPlus does not infer a role from account numbers or names. Replacing a singleton preserves the prior account and role history and records the governed chart-change audit. Selecting a new eligible account is also the supported recovery for a duplicate required-singleton conflict.

Unavailable chart paths

Optional future workflow roles and production security roles are not managed by this chart setup surface. Production users, security roles, and permissions remain separate from accounting account roles.

Opening balances are not chart master data and must never be added to a chart import. QBO replacement is also unavailable in the desktop and must not be substituted for ordinary startup setup.

After review

Continue Guided Setup with permission review and the opening-balance disposition. If the chart, a material account review field, a collision result, or a required role assignment later changes, BooksPlus makes the earlier acknowledgement stale and requires review of the new displayed subject.