Journals and journal lines
A journal document is the controlled accounting record that groups balanced debit and credit lines for one economic event or authorised manual adjustment. A line is one account-side classification inside that document. Neither is a substitute for the original invoice, Payment, refund, expenditure, approval, or bank evidence.
Audience: accountants, finance managers, approvers, auditors, implementers, and support analysts
Learning time: 50 minutes
Navigation: Finance → Accounting → Journals (finance/general-ledger/journal-entries)
Availability: current product supports journal listing, detail, manual document posting, source lineage, integrity review, and linked reversals.
Learning outcomes
You will be able to:
- distinguish a journal header, line, legacy projected entry, source record, and reversal;
- interpret draft, pending, posted, and reversed document states without mixing them with legacy entry states;
- prepare balanced multi-line manual journals;
- verify transaction and functional amounts and dimensions;
- apply exact create, list, read, and reverse permissions;
- use reversal rather than destructive editing of posted history;
- investigate duplicate, unbalanced, mis-scoped, or source-less journal evidence.
Definitions and record model
The current journal-header contract records an entry number, entry date, description, optional source type and source ID, transaction currency, functional currency, exchange rate, status, idempotency key, line count, totals, actor evidence, reversal links, metadata, and ordered lines.
Each line records line number, account ID, side (debit or credit), transaction amount, functional amount, currencies, exchange rate, optional description, and dimensions such as department, cost centre, project, fund, and revenue stream.
The older journal-entry representation pairs one debit account and one credit account. Multi-line documents can be projected into legacy rows for listing; Makronexus groups those rows by journal-header identity in the UI. Do not count each projection as a separate economic journal.
Prerequisites
| Requirement | Evidence |
|---|---|
| Selected school and tenant | journal school scope and active context |
| Active non-header accounts | account IDs, codes, types, and status |
| Open eligible period | entry date covered by allowed period |
| Approved manual-journal policy | allowManualJournalPosting, amount threshold, approval rule |
| Balanced business explanation | source or adjustment memorandum |
| Currency evidence | transaction/functional currencies and rate |
| Dimensions | approved cost centre/project/fund/revenue-stream values where required |
| Idempotency key | stable identity for the posting request |
| Separation | maker must not self-approve where policy enforces segregation |
Roles and exact permissions
| Action | Exact API ability | Current UI compatibility checks | Safe rule |
|---|---|---|---|
| List journals | gl_journal_entry:list | may also recognise gl_journal_entries:list, financial_gl_journal_entry:list, or broad Finance fallbacks | configure the exact API ability |
| Read a journal | gl_journal_entry:read | UI can open grouped header or legacy detail | retain source and line evidence |
| Create manual journal | gl_journal_entry:create | may also recognise plural/financial aliases or broad create fallbacks | do not treat fallback visibility as backend authority |
| Reverse journal | gl_journal_entry:reverse | may also recognise plural/financial aliases | reason and linked offsetting entry required |
| List accounts | gl_account:list | account selector | only active non-header accounts |
| Read account | gl_account:read | detail/drill-down | confirm scope and normal balance |
Permission aliases are an implementation compatibility issue, not proof that all names are interchangeable. Support investigations must record the exact ability sent by the backend and the exact UI gate that rendered the action.
State model
Journal headers support draft, pending, posted, and reversed. The legacy entry model exposes draft, posted, and reversed.
Do not assume every manual journal passes through pending. Effective policy determines whether direct posting, change request, or approval is required. Posted and reversed records are historical evidence; correction uses a new linked document.
Prepare a manual journal
Before opening the form, write the accounting explanation in plain language. Identify why a normal source workflow cannot produce the required entry. Manual journals should not be used to hide missing source configuration, duplicate a delayed automatic posting, force a bank reconciliation, or correct a source record without preserving its business meaning.
A valid multi-line document must:
- use sequential line numbers;
- include at least one debit and one credit line;
- use active non-header accounts;
- balance transaction debit and credit totals;
- balance functional debit and credit totals;
- carry consistent currencies and exchange-rate evidence;
- retain an idempotency key;
- contain sufficient description and dimensions for review.
Guided procedure
- Open Finance → Accounting → Journals and select Entries rather than Integrity.
- Confirm the selected school, date range, status, source type, and account filters.
- Search for the proposed source or adjustment first. This prevents a duplicate manual journal for an existing automatic posting.
- Select New Journal only with
gl_journal_entry:create. - Enter document date and description. The description must explain the economic event, not merely say “adjustment.”
- Select transaction and functional currencies. Enter the approved exchange rate and retain its source when they differ.
- Add ordered lines. For each line select the account, debit/credit side, transaction amount, functional amount, description, and required dimensions.
- Verify account scope, active status, non-header status, and normal balance. A normal-balance mismatch may be valid, but it requires explanation.
- Compare total debits and credits in both currency layers.
- Submit through the permitted direct-post or maker-checker path with a stable idempotency key.
- Open the returned document. Verify header, all lines, actor, timestamps, totals, source, and any legacy projection IDs.
- Drill into account activity and the relevant statement.
- Attach or cross-reference the approval memorandum and supporting evidence.
Reversal procedure
A reversal is append-only. It creates an offsetting journal and links it to the original.
- Confirm the original is the incorrect document and has not already been reversed.
- Record the reason, expected correction date, supporting reference, and approval.
- Use Reverse with
gl_journal_entry:reverse. - Verify that debit and credit sides are offset, the original links to the reversal, the reversal links back, and actor/timestamp evidence exists.
- Post the correct replacement separately if required. Do not edit the reversal into the desired entry.
Accounting impact
Journal lines are the accounting impact. Account type determines normal balance: assets and expenses normally carry debit balances; liabilities, equity, and revenue normally carry credit balances. Normal balance does not prohibit the opposite side; it helps reviewers interpret whether the movement is expected.
| Review question | Evidence |
|---|---|
| Is the document balanced? | transaction and functional totals |
| Is the account appropriate? | effective mapping or approved manual rationale |
| Is the date valid? | open period and source date policy |
| Is the currency reproducible? | rate, source, timestamp, reference |
| Is the source traceable? | source type, source ID, reference, detail |
| Is correction append-only? | reversal header IDs and reason |
| Is duplicate prevention visible? | idempotency key and existing-document response |
Worked scenario: Mupfure Learning Academy
An approved insurance prepayment must be reclassified monthly from prepaid expense to insurance expense. The accountant confirms that the current product has no verified recurring-journal scheduler, so each authorised monthly adjustment is a separate manual journal or an external controlled process. The August journal debits insurance expense and credits prepaid expense for the approved amount. It carries the period, memorandum, account IDs, functional currency, dimensions, and idempotency key.
A later review finds the amount wrong. The accountant reverses the August document and posts a corrected replacement. The original is never deleted.
Failure modes
| Symptom | Likely cause | Evidence to inspect | Safe action | Escalate when |
|---|---|---|---|---|
| create button visible but request is 403 | UI fallback ability differs from API permission | session abilities and API response | request gl_journal_entry:create | exact ability exists and backend still denies |
| lines do not balance | amount, side, currency, or rate error | all line totals | correct draft before posting | posted unbalanced document exists |
| grouped row amount looks duplicated | multi-line projections grouped incorrectly | journal header ID and projected entry IDs | read header detail | projections cannot be tied to one header |
| account unavailable | inactive, header, wrong school, or missing permission | account record and scope | select approved posting account | valid account omitted from API |
| duplicate journal after timeout | retry used a different idempotency key | request IDs and keys | identify existing journal before new request | backend created two for same key |
| reversal action unavailable | record is projection, already reversed, or permission absent | header/detail and abilities | open header and use governed reversal | posted unreversed header cannot be reversed |
| no recurring option | recurring journals are not verified in current product | route and API evidence | use approved manual/process schedule | business requires automation not implemented |
Verification checklist
- Header and every line belong to the selected school.
- Source or manual rationale is explicit.
- Entry date is eligible.
- Accounts are active and non-header.
- Transaction debits equal transaction credits.
- Functional debits equal functional credits.
- Currency and exchange-rate evidence is retained.
- Dimensions are complete.
- Idempotency key is stable.
- Poster and timestamps are visible.
- Reversal links are bidirectional where applicable.
- Account activity and statements reflect the expected net movement.
Practice and knowledge check
Guided practice: create a balanced four-line journal in a test school, then read its grouped and line-level representations.
Independent scenario: the browser timed out after submit. Explain how to decide whether to retry and which identifier must remain unchanged.
- What is the difference between a journal header and a line?
- Why can grouped legacy projections mislead counts?
- Which two currency-layer equalities must hold?
- What is the preferred exact create ability?
- Why is a reversal not an edit?
- When is a manual journal unsafe?
- Does Makronexus currently prove a recurring-journal scheduler?
Answer guide: the header owns document identity and totals; lines classify accounts; projections can show one document as multiple pairs; both transaction and functional totals balance; use gl_journal_entry:create; reversal preserves history; manual journals must not conceal source/configuration defects; recurring scheduling is not verified.
Next lesson
Continue to Subledger and General Ledger.