Appearance
Opening Balance Journals
| Backlog field | Value |
|---|---|
| Story ID | AP-ACC-008 |
| Epic | Accounting |
| Story type | Report |
| Review status | Draft - business analyst and business owner review required |
| Source evidence | AppsPortal.Apis controller, application command/query handlers, validators, domain entities, and matching MFE workflow where available |
| Last source review | 2026-07-10 |
User story
As implementation accountants, I want to load and post starting account balances so that the ledger begins from an approved baseline.
Posting reference: AppsPortal Posting Ledger explains debit/credit construction. Delegation and Interaction Contracts explains module ownership, delegated commands, linked records, commit boundaries, and reversal propagation.
Acceptance criteria
- Only authorized users can view or execute the feature's actions.
- Required business data, active dependencies, tenant/branch scope, and current document state are validated.
- Invalid requests return actionable validation errors without applying a partial change.
- Search, list, view, print, and export operations use the same authorized business scope.
- Material create, edit, status, approval, posting, reversal, and integration actions are auditable where applicable.
- Financial or stock effects are applied atomically and no more than once.
Posting details
- Validate Draft state, opening date/period, active posting accounts, currencies, account nature, and balanced local debits/credits.
- Accounting posts the opening journal directly; no stock or payment delegate is called.
- The journal establishes opening GL balances and supplies linked lines used by Customer and Vendor Opening Balance validation.
- Unpost is allowed only in an open period and when later posted dependent journals/subledger activity do not exist.
- No opening effect is partially removed: status and ledger availability change together.
General ledger posting
| Component | Debit | Credit | Rule |
|---|---|---|---|
| Opening lines | Selected opening debit accounts | Selected opening credit accounts | Local debits must equal local credits; accounts active/postable. |
Other module and document effects
| Area | Effect | Conditional/no effect |
|---|---|---|
| Customer/Vendor openings | Supplies linkable GL lines used to validate their subledger opening amounts/nature. | Does not automatically create customer/vendor opening documents. |
| Inventory/Finance | No stock quantity or bank/treasury movement. | Inventory opening is separate. |
| Accounting reports | Establishes opening GL balances. | Draft lines have no ledger effect. |
Core acceptance scenarios
- Given a balanced Draft opening journal in the permitted opening period, when an authorized accountant posts it, then the opening ledger baseline becomes effective and linked customer/vendor opening balances can validate against its lines.
- Given later posted dependent activity exists, when the operation is attempted, then Unpost is rejected and the baseline remains effective.
- Given the same Post request is retried after success, when the source is no longer Draft, then no duplicate journal, stock, balance, payment, or lifecycle effect is created.
Business rules
Opening-balance journals require an opening period/date, valid accounts/currencies, debit/credit nature and amounts, and a balanced journal. Post makes the baseline effective in the ledger. Unpost requires an open period and is blocked when later posted journals depend on the opening baseline. Unpost removes the opening effect without deleting its audit identity.
Customer and Vendor Opening Balances are linked to opening journal lines. Their total and net account nature must match the linked journal amount before their own Post can succeed.
Frontend page coverage
The following UI coverage is sourced from the pulled MFE route configuration. A Module-level supporting artifact mapping is evidence of a reachable screen, but requires BA confirmation that it belongs to this story rather than a more specific feature story.
| Route/page | Component | Mode | Route permission/guard | Mapping confidence | Source |
|---|---|---|---|---|---|
| (module default) | JournalEntryOpeningBalanceListComponent | List/navigation | Permission: AppAccountingPermissions.OpeningBalanceJournalEntries_Add; Guards: PolicyAuthGuard | Explicit frontend feature rule | apps/accounting/src/app/remote-entry/journal-entry/journal-entry.module.ts:151 |
| add | AddJournalEntryOpeningBalanceComponent | Add | Permission: AppAccountingPermissions.OpeningBalanceJournalEntries_Add; Guards: PolicyAuthGuard | Explicit frontend feature rule | apps/accounting/src/app/remote-entry/journal-entry/journal-entry.module.ts:158 |
| edit/:id | EditJournalEntryOpeningBalanceComponent | Edit | Permission: AppAccountingPermissions.OpeningBalanceJournalEntries_Edit; Guards: PolicyAuthGuard, preventPostedGuard | Explicit frontend feature rule | apps/accounting/src/app/remote-entry/journal-entry/journal-entry.module.ts:168 |
| journal-entry-opening-balance | MainOpeningBalanceComponent | List/navigation | Permission: AppAccountingPermissions.OpeningBalanceJournalEntries_List; Guards: PolicyAuthGuard | Explicit frontend feature rule | apps/accounting/src/app/remote-entry/journal-entry/journal-entry.module.ts:141 |
| view/:id | ViewJournalEntryOpeningBalanceComponent | View/detail | Permission: AppAccountingPermissions.OpeningBalanceJournalEntries_View; Guards: PolicyAuthGuard | Explicit frontend feature rule | apps/accounting/src/app/remote-entry/journal-entry/journal-entry.module.ts:179 |
Observed frontend fields and validation
| Component | Control | Observed frontend rule | Component source |
|---|---|---|---|
| AddJournalEntryOpeningBalanceComponent | account | Visible control; optional or API-dependent | apps/accounting/src/app/remote-entry/journal-entry/pages/journal-entry-opening-balance/add-journal-entry-opening-balance/add-journal-entry-opening-balance.component.ts |
| AddJournalEntryOpeningBalanceComponent | creditAmount | Visible control; optional or API-dependent | apps/accounting/src/app/remote-entry/journal-entry/pages/journal-entry-opening-balance/add-journal-entry-opening-balance/add-journal-entry-opening-balance.component.ts |
| AddJournalEntryOpeningBalanceComponent | currency | Visible control; optional or API-dependent | apps/accounting/src/app/remote-entry/journal-entry/pages/journal-entry-opening-balance/add-journal-entry-opening-balance/add-journal-entry-opening-balance.component.ts |
| AddJournalEntryOpeningBalanceComponent | currencyRate | Visible control; optional or API-dependent | apps/accounting/src/app/remote-entry/journal-entry/pages/journal-entry-opening-balance/add-journal-entry-opening-balance/add-journal-entry-opening-balance.component.ts |
| AddJournalEntryOpeningBalanceComponent | debitAmount | Visible control; optional or API-dependent | apps/accounting/src/app/remote-entry/journal-entry/pages/journal-entry-opening-balance/add-journal-entry-opening-balance/add-journal-entry-opening-balance.component.ts |
| AddJournalEntryOpeningBalanceComponent | description | Required in component validator | apps/accounting/src/app/remote-entry/journal-entry/pages/journal-entry-opening-balance/add-journal-entry-opening-balance/add-journal-entry-opening-balance.component.ts |
| AddJournalEntryOpeningBalanceComponent | journalDate | Required in component validator | apps/accounting/src/app/remote-entry/journal-entry/pages/journal-entry-opening-balance/add-journal-entry-opening-balance/add-journal-entry-opening-balance.component.ts |
| AddJournalEntryOpeningBalanceComponent | lineDescription | Visible control; optional or API-dependent | apps/accounting/src/app/remote-entry/journal-entry/pages/journal-entry-opening-balance/add-journal-entry-opening-balance/add-journal-entry-opening-balance.component.ts |
| AddJournalEntryOpeningBalanceComponent | refrenceNumber | Required in component validator | apps/accounting/src/app/remote-entry/journal-entry/pages/journal-entry-opening-balance/add-journal-entry-opening-balance/add-journal-entry-opening-balance.component.ts |
| EditJournalEntryOpeningBalanceComponent | accountId | Required in component validator | apps/accounting/src/app/remote-entry/journal-entry/pages/journal-entry-opening-balance/edit-journal-entry-opening-balance/edit-journal-entry-opening-balance.component.ts |
| EditJournalEntryOpeningBalanceComponent | creditAmount | Required in component validator | apps/accounting/src/app/remote-entry/journal-entry/pages/journal-entry-opening-balance/edit-journal-entry-opening-balance/edit-journal-entry-opening-balance.component.ts |
| EditJournalEntryOpeningBalanceComponent | currencyRate | Required in component validator | apps/accounting/src/app/remote-entry/journal-entry/pages/journal-entry-opening-balance/edit-journal-entry-opening-balance/edit-journal-entry-opening-balance.component.ts |
| EditJournalEntryOpeningBalanceComponent | debitAmount | Required in component validator | apps/accounting/src/app/remote-entry/journal-entry/pages/journal-entry-opening-balance/edit-journal-entry-opening-balance/edit-journal-entry-opening-balance.component.ts |
| EditJournalEntryOpeningBalanceComponent | description | Required in component validator | apps/accounting/src/app/remote-entry/journal-entry/pages/journal-entry-opening-balance/edit-journal-entry-opening-balance/edit-journal-entry-opening-balance.component.ts |
| EditJournalEntryOpeningBalanceComponent | journalDate | Required in component validator | apps/accounting/src/app/remote-entry/journal-entry/pages/journal-entry-opening-balance/edit-journal-entry-opening-balance/edit-journal-entry-opening-balance.component.ts |
| EditJournalEntryOpeningBalanceComponent | lineDescription | Required in component validator | apps/accounting/src/app/remote-entry/journal-entry/pages/journal-entry-opening-balance/edit-journal-entry-opening-balance/edit-journal-entry-opening-balance.component.ts |
| EditJournalEntryOpeningBalanceComponent | referenceNumber | Required in component validator | apps/accounting/src/app/remote-entry/journal-entry/pages/journal-entry-opening-balance/edit-journal-entry-opening-balance/edit-journal-entry-opening-balance.component.ts |
Observed frontend actions
| Component | Click action/handler | Business review requirement | Component source |
|---|---|---|---|
| AddJournalEntryOpeningBalanceComponent | addThing | Document the enabled state, permission, input context, resulting API or navigation effect, success refresh, and concrete failure behavior for this handler. | apps/accounting/src/app/remote-entry/journal-entry/pages/journal-entry-opening-balance/add-journal-entry-opening-balance/add-journal-entry-opening-balance.component.ts |
| AddJournalEntryOpeningBalanceComponent | deleteLine | Available only in deletable states with Delete permission; identify the record in confirmation, call delete once, remove/refresh the list row on success, and retain the row with the API reason on failure. | apps/accounting/src/app/remote-entry/journal-entry/pages/journal-entry-opening-balance/add-journal-entry-opening-balance/add-journal-entry-opening-balance.component.ts |
| AddJournalEntryOpeningBalanceComponent | openCostPopup | Document the enabled state, permission, input context, resulting API or navigation effect, success refresh, and concrete failure behavior for this handler. | apps/accounting/src/app/remote-entry/journal-entry/pages/journal-entry-opening-balance/add-journal-entry-opening-balance/add-journal-entry-opening-balance.component.ts |
| AddJournalEntryOpeningBalanceComponent | openDialog | Open the item/lookup/tracking dialog with the current warehouse, item, UOM, and remaining quantity context; accepted values must return to the correct line and cancel must not mutate it. | apps/accounting/src/app/remote-entry/journal-entry/pages/journal-entry-opening-balance/add-journal-entry-opening-balance/add-journal-entry-opening-balance.component.ts |
| AddJournalEntryOpeningBalanceComponent | routeToJournal | Navigate only when a linked journal ID exists and the user can view Accounting; otherwise the action is absent/disabled and no transaction data changes. | apps/accounting/src/app/remote-entry/journal-entry/pages/journal-entry-opening-balance/add-journal-entry-opening-balance/add-journal-entry-opening-balance.component.ts |
| AddJournalEntryOpeningBalanceComponent | save | Validate the concrete form and line collection, prevent duplicate submission, persist once, show API field/business errors in context, and navigate/refresh only after success. | apps/accounting/src/app/remote-entry/journal-entry/pages/journal-entry-opening-balance/add-journal-entry-opening-balance/add-journal-entry-opening-balance.component.ts |
| EditJournalEntryOpeningBalanceComponent | addNewRow | Add one initialized detail row without changing existing rows; apply defaults and line validators, preserve stable row identity, and exclude incomplete rows from Save/Post. | apps/accounting/src/app/remote-entry/journal-entry/pages/journal-entry-opening-balance/edit-journal-entry-opening-balance/edit-journal-entry-opening-balance.component.ts |
| EditJournalEntryOpeningBalanceComponent | deleteJournalEntryLine | Available only in deletable states with Delete permission; identify the record in confirmation, call delete once, remove/refresh the list row on success, and retain the row with the API reason on failure. | apps/accounting/src/app/remote-entry/journal-entry/pages/journal-entry-opening-balance/edit-journal-entry-opening-balance/edit-journal-entry-opening-balance.component.ts |
| EditJournalEntryOpeningBalanceComponent | openCostPopup | Document the enabled state, permission, input context, resulting API or navigation effect, success refresh, and concrete failure behavior for this handler. | apps/accounting/src/app/remote-entry/journal-entry/pages/journal-entry-opening-balance/edit-journal-entry-opening-balance/edit-journal-entry-opening-balance.component.ts |
| EditJournalEntryOpeningBalanceComponent | openDialog | Open the item/lookup/tracking dialog with the current warehouse, item, UOM, and remaining quantity context; accepted values must return to the correct line and cancel must not mutate it. | apps/accounting/src/app/remote-entry/journal-entry/pages/journal-entry-opening-balance/edit-journal-entry-opening-balance/edit-journal-entry-opening-balance.component.ts |
| JournalEntryOpeningBalanceListComponent | onEdit | Open the identified editable record only with Edit permission; posted/locked records remain blocked by route or action state and list context must be recoverable on return. | apps/accounting/src/app/remote-entry/journal-entry/pages/journal-entry-opening-balance/journal-entry-opening-balance-list/journal-entry-opening-balance-list.component.ts |
| JournalEntryOpeningBalanceListComponent | onPost | Available only for a postable Draft and Post permission; confirm the document, prevent a second submission, call the posting API, and refresh status, journal/stock links, and row actions. Failure must keep the pre-post state. | apps/accounting/src/app/remote-entry/journal-entry/pages/journal-entry-opening-balance/journal-entry-opening-balance-list/journal-entry-opening-balance-list.component.ts |
| JournalEntryOpeningBalanceListComponent | onUnPost | Available only for a postable Draft and Post permission; confirm the document, prevent a second submission, call the posting API, and refresh status, journal/stock links, and row actions. Failure must keep the pre-post state. | apps/accounting/src/app/remote-entry/journal-entry/pages/journal-entry-opening-balance/journal-entry-opening-balance-list/journal-entry-opening-balance-list.component.ts |
| JournalEntryOpeningBalanceListComponent | onView | Open the authorized record in view mode with its status, totals, lines, source and generated-document links; handle deleted, forbidden, and missing records without exposing stale data. | apps/accounting/src/app/remote-entry/journal-entry/pages/journal-entry-opening-balance/journal-entry-opening-balance-list/journal-entry-opening-balance-list.component.ts |
| JournalEntryOpeningBalanceListComponent | printout | Generate the printout for the selected record and authorized branch/tenant; use posted/current values and surface print, template, ZATCA/ETA, or popup failures without changing transaction state. | apps/accounting/src/app/remote-entry/journal-entry/pages/journal-entry-opening-balance/journal-entry-opening-balance-list/journal-entry-opening-balance-list.component.ts |
| ViewJournalEntryOpeningBalanceComponent | openCostPopup | Document the enabled state, permission, input context, resulting API or navigation effect, success refresh, and concrete failure behavior for this handler. | apps/accounting/src/app/remote-entry/journal-entry/pages/journal-entry-opening-balance/view-journal-entry-opening-balance/view-journal-entry-opening-balance.component.ts |
Page-specific frontend acceptance criteria
- (module default) - List/navigation: Load an authorized paged/searchable list or navigation page; preserve filters/sort/paging and expose only permitted row and bulk actions. Security observed: Permission: AppAccountingPermissions.OpeningBalanceJournalEntries_Add; Guards: PolicyAuthGuard
- add - Add: Render permitted fields, required indicators, defaults, dependent lookups, validation, Save/Cancel, loading, success, and API-error states. Security observed: Permission: AppAccountingPermissions.OpeningBalanceJournalEntries_Add; Guards: PolicyAuthGuard
- edit/:id - Edit: Load the identified record, enforce state/permission field locks, preserve concurrency identity, validate changes, and return without losing filters. Security observed: Permission: AppAccountingPermissions.OpeningBalanceJournalEntries_Edit; Guards: PolicyAuthGuard, preventPostedGuard
- journal-entry-opening-balance - List/navigation: Load an authorized paged/searchable list or navigation page; preserve filters/sort/paging and expose only permitted row and bulk actions. Security observed: Permission: AppAccountingPermissions.OpeningBalanceJournalEntries_List; Guards: PolicyAuthGuard
- view/:id - View/detail: Load an authorized immutable/detail representation with status-aware actions, linked records, print/export where exposed, and not-found/forbidden handling. Security observed: Permission: AppAccountingPermissions.OpeningBalanceJournalEntries_View; Guards: PolicyAuthGuard