Advanced GL Mapping implementation manual

This chapter teaches an accountant or implementation consultant how to configure Administration → GL Mapping at /settings/gl-mapping. It is not enough to make the Trial Balance balance: the mapping must send the right business event to the right account, for the right company, branch, tax regime, book, and date.

Before opening the screen

Complete this order in a demonstration company first:

1. Create the company, base currency, branches, tax registrations, and open financial periods.
2. Build the chart: account groups first, then posting ledgers (cash, bank, receivables, revenue, inventory, COGS, tax, payables, rounding, FX).
3. Create cost centres, profit centres, segments, and projects that will receive line dimensions.
4. Decide the sales and purchase stage flow and which stages are allowed to post.
5. Obtain the accountant’s policy for domestic, inter-state/export, exempt, service, stock, returns, credit notes, payments, and FX.
6. Give the implementer gl:manage; give reviewers gl:read. Every change is audited.

Screen navigation and safe setup

The window has Posting Rules and Test a Document tabs. The other tabs are under Advanced. Configure in this sequence: Books → Account Roles → Templates → Stage Matrix → Account Mapping → Validations → Dimensions → Periods → What-If → Versions.

Never press Seed Defaults on a trading company without a dry run and snapshot. It replaces stage postings and mapping rules. Use Versions → Create before every material change. Restore replaces configuration but never rewrites journals already posted.

Tab 1 — Posting Rules

This is the health view: “when this event occurs, which journal will be created?”

Field / control	What to fill	Impact
Flow filter	Sales, Purchase, or All	Narrows review; does not change rules
Search	Event, stage, or account name	Finds every event using a role/ledger
Event row	Flow, stage, subtype, journal summary	Confirms the winning rule
Auto-post chip	On/off state	Off resolves but does not create a journal
Missing-account chip	Unresolved roles	The affected document cannot post safely
Account picker	Ledger for the displayed semantic role	Repoints every event using that role
Amount basis	Total, net, tax, or per-line basis	Changes the journal amount; edit the template, not the row

Example invoice (10,000 net + 1,800 tax):

Dr Sundry Debtors 11,800
  Cr Domestic Sales 10,000
  Cr Output CGST 900
  Cr Output SGST 900

For an inter-state/export scenario the tax lines must instead resolve to Output IGST or the configured export treatment. If both simulations produce the same tax journal, stop and fix the tax regime/rules before go-live.

Tab 2 — Test a Document

This tab writes nothing. Use it for a domestic sale, inter-state sale, service purchase, stocked purchase, payment, return, and credit note.

Field	Example	Why it matters
Process type	SALES	Selects the correct backbone
Document subtype	RETAIL, EXPORT, or blank	Selects a specific rule before the generic fallback
Stage	INVOICE	Selects the event being resolved
Place of supply	Intra-state / inter-state	Selects CGST+SGST versus IGST
Amounts	net=10000, tax=1800, total=11800	Tests amount basis and rounding
Currency/rate	USD, rate 3.6725	Tests conversion to company base currency
Context	bp.group=EXPORT	Proves conditional rules match
Result	Resolved lines, unmapped roles, balanced flag	Read unmapped roles first

Advanced tab — Books

Books are parallel reporting bases, not branches. Fill Code, Name, Principle (IFRS, LOCAL, TAX, or MGMT), Currency where required, and Is leading for exactly one book. A stage rule pointing to a book protects it from deletion. The leading book is the default for reports and cannot be deleted until another is made leading.

Advanced tab — Account Roles

Roles are semantic slots used by templates; they are not ledgers. Create stable codes such as AR, REVENUE, OUTPUT_CGST, OUTPUT_SGST, OUTPUT_IGST, INVENTORY, COGS, AP, INPUT_TAX, BANK, CASH, ROUNDING, and FX_GAIN_LOSS.

Field	What to fill	Impact
Code	Permanent machine key, e.g. REVENUE	Used by templates and integrations; do not rename casually
Name	Accountant-readable label	Appears in the Posting Rules grid
Module	Sales, purchase, inventory, finance, etc.	Organises the role catalogue
Normal side	Debit or credit expectation	Documentation guard; template line decides actual side
Active	On while in use	Inactive roles remain traceable; do not delete roles in use

Advanced tab — Templates

A template is the journal recipe. Fill Code, Name, Flow, stage purpose, active, and complete lines. Each line requires Role, Dr/Cr, amount basis (TOTAL, NET, TAX, or another supported basis), and scope (DOCUMENT or LINE). The complete replacement payload must contain at least one debit and one credit; zero-value lines are omitted.

Example sales invoice template:

Side	Role	Basis	Scope
Dr	AR	TOTAL	DOCUMENT
Cr	REVENUE	NET	LINE
Cr	OUTPUT_CGST	TAX	DOCUMENT
Cr	OUTPUT_SGST	TAX	DOCUMENT

Do not create a new template for every customer. Keep the journal shape here and use Account Mapping conditions to choose a different destination ledger.

Advanced tab — Stage Matrix

The matrix answers “when does this template run?”

Field	Example	Impact
Flow	SALES	Sales and purchase backbones are separate
Document subtype	EXPORT	Optional narrowing key
Stage	INVOICE	Must be a valid stage for the flow
Book	LEADING	Selects the reporting book
Auto-JE	On	Allows the journal to post automatically
Posting template	SALES_INVOICE	Blank means the stage advances without a journal
Priority	50 specific, 100 fallback	Lower number wins

The identity is Flow + subtype + stage + book. These values lock after creation. A generic row at priority 100 and an export row at priority 50 is the safe pattern; equal priorities make the winning rule ambiguous.

Advanced tab — Account Mapping

This tab maps each role to a real ledger.

Field	Example	Impact
Account role	REVENUE	Semantic slot from the template
Ledger	Export Sales	Actual posting destination
Priority	50	Specific rule before fallback
Conditions	bp.group equals EXPORT	Context that must match
Effective from/to	2026-01-01 to blank	Time-boxes the policy
Status	Active	Inactive rule never matches
Description	“Saudi export revenue”	Explains intent to the next consultant

Worked rules:

Priority	Role	Ledger	Condition
50	REVENUE	Export Sales	bp.group = EXPORT
100	REVENUE	Domestic Sales	none (fallback)

Advanced tab — Validations

Create pre-posting checks with Name, severity (WARN or BLOCK), flow, stage, conditions, and an instruction-style message. Start as WARN, observe real data, then promote to BLOCK. Example: “Set customer tax registration before export invoice.” A validation prevents the wrong journal before it reaches the ledger.

Advanced tab — Periods and Dimensions

Periods require a calendar, start/end dates, and status (OPEN, CLOSED, LOCKED). Only OPEN accepts posting. Dimensions define cost centre, profit centre, segment, and project values. Assign them before transactions; changing dimensions after posting requires controlled reversal and reposting.

Advanced tab — Diagnostics and recovery

• Suggest mappings uses ledger-name keywords; review every suggestion.
• Unmapped roles finds template roles with no destination; apply only additive repairs.
• Missing journals identifies documents that advanced through a posting stage without a journal; repair explicit document IDs, never “repair all”.
• Rounding readiness checks the rounding role and ledger before enabling round-off.
• GST upgrade previews the old single-tax mapping and the six-role replacement.
• What-If replays recent documents against proposed rules without saving them.
• Versions creates, compares, and restores snapshots. Posted journals remain unchanged.

Go-live test pack

Run and retain the result for: domestic stock sale, export sale, service sale, purchase with input tax, payment by bank, payment by cheque (with instrument number/date), partial delivery, return, credit note, foreign-currency invoice, round-off, and a locked-period attempt. For each, compare the expected debit/credit, tax component, warehouse movement, currency conversion, dimensions, and report result.

Always-on demonstration: Demo Retail Group LLC

Use one repeatable company while learning so that every field has a consequence. Demo Retail Group LLC is a UAE legal entity with Dubai and Abu Dhabi branches, a Dubai distribution centre, AED as base currency, SAR and USD customer transactions, VAT registration, perpetual inventory, and a leading IFRS book. It sells 100 oak chairs to a Saudi customer for AED 125 each, gives a 5% discount, delivers from Dubai, invoices in SAR at the dated exchange rate, and receives payment by bank transfer. The same company also buys chairs from an overseas supplier and returns five damaged units.

Before entering the mapping screen, write the expected journals on paper:

Event	Debit	Credit	Operational proof
Sales order	None	None	Reservation and open quantity
Delivery	Inventory issue / COGS if configured	Inventory	Delivery note, warehouse, batch
Export invoice	Customer AR for total	Export revenue + output tax treatment	Invoice, tax regime, currency/rate
Receipt	Bank AED equivalent	Customer AR	Bank reference and allocation
Supplier invoice	Inventory/expense + input tax	Supplier AP	Supplier invoice no/date
Return	Returned inventory	COGS/revenue reversal as configured	Return reason and inspection

Now map the screen fields to this story. Company and branch determine which chart, tax registration, period, and warehouse are legal; selecting Abu Dhabi while using Dubai’s tax registration produces a plausible but wrong invoice. Currency and exchange rate determine the base-currency journal; never overwrite the rate just to make a report total match. Customer group is the context key for the export revenue rule. Warehouse identifies physical ownership; it does not select the revenue account. Project/cost centre explains management margin and must be set before posting. Posting date chooses the open period; document date describes the commercial evidence; due date drives ageing. These dates must never be collapsed into one “date” field in training material.

Field length and type discipline

The UI Atlas records an explicit maximum only where the control declares one. A blank maximum means “not declared on this control”, not unlimited storage. Treat codes as stable identifiers, names as labels, dates as ISO YYYY-MM-DD, percentages as decimal rates, and money as decimal values with company precision. Do not place JSON, secrets, tax certificates, or long explanations into a short code or remarks field. If a business needs a longer reference, store it in the supporting document or attachment and link the evidence.

What a consultant must hand over

The implementation pack should include a role-to-ledger matrix, every template’s complete debit/credit recipe, stage matrix with priority, conditions and effective dates, validation catalogue, period calendar, dimension list, ten simulation outputs, one version snapshot ID, and the name of the approver. Include screenshots or exported results for both the expected and refused cases. A future consultant should be able to reproduce the Demo Retail Group LLC invoice without asking what “tax” or “sales” means in your chart.

If a result is different from the expected journal, classify it before changing anything: data issue (wrong party, date, tax, currency, or warehouse), configuration issue (wrong priority, role, template, or ledger), permission issue (user cannot submit or approve), period issue (closed/locked date), or product limitation (the required event is not implemented). This classification prevents a dangerous habit: changing the chart to hide a data error.

For the underlying endpoint calls, see the API Library and its complete endpoint inventory. For screen-level labels and declared input limits, use OSERP Atlas.

Field-by-field implementation worksheet

Use this worksheet during a configuration workshop. The implementer fills the proposed value, the accountant confirms the accounting meaning, and the tester records the simulation ID. Never accept a mapping because the screen saved; acceptance requires the expected journal and refusal cases.

Tab	Field	What to enter	Example for Demo Retail Group LLC	Verify
Books	Code	Stable short identifier	IFRS-AED	Appears on reports and stage rows
Books	Principle	Reporting basis	IFRS	Confirm policy owner
Books	Leading	One book only	Yes	Trial balance defaults correctly
Roles	Code	Semantic machine key	EXPORT_REVENUE	No duplicate or renamed key
Roles	Normal side	Expected balance side	Credit	Documentation guard only
Templates	Code	Journal recipe key	SALES_EXPORT_INV	API and stage reference
Templates	Amount basis	Total/net/tax/line	NET	Recalculate with a tax example
Templates	Scope	Document or line	LINE	Multi-line invoice produces lines
Stage Matrix	Priority	Lower number wins	50	Specific rule beats fallback
Stage Matrix	Auto-JE	Whether to post	On	Locked-period test still refuses
Mapping	Condition field	Context key	bp.group	Use an actual document value
Mapping	Operator	equals/in/contains	equals	Case and whitespace are tested
Mapping	Effective from	Policy start	2026-01-01	Backdated document test
Mapping	Effective to	Policy end or blank	blank	Future version does not overlap
Validation	Severity	WARN or BLOCK	BLOCK	Refusal message is actionable
Validation	Message	User instruction	“Set export tax code”	Message names the field
Dimensions	Required	Whether line is mandatory	Yes for project sales	Missing value is blocked
Periods	Status	OPEN/CLOSED/LOCKED	OPEN	Closed and locked tests differ
Versions	Snapshot name	Human-readable checkpoint	before-saudi-export	Restore ID is recorded

How a winning rule is determined

OSERP evaluates active rules that match flow, stage, book, effective dates, and context. It then selects the lowest priority number. If two rules have the same priority and both match, treat the result as ambiguous even if a current response happens to pick one. The safe pattern is a narrow rule at priority 50 and a generic fallback at 100. Do not use customer name as the first condition when a stable customer group, tax registration, branch, or country code exists.

For a Saudi export invoice, the matching path should be visible in the test response:

flow=SALES
stage=INVOICE
book=IFRS-AED
context.bp.group=EXPORT
stageRule=SALES_INVOICE_EXPORT (priority 50)
role.REVENUE -> Export Sales (mapping priority 50)
role.OUTPUT_TAX -> Export VAT / zero-rated treatment

If the response instead selects SALES_INVOICE_DEFAULT, inspect the document subtype, customer group, tax registration, and effective date before changing any ledger. If the stage rule is correct but revenue is domestic, inspect Account Mapping priority. If revenue is correct but tax is wrong, inspect tax configuration and not the revenue account.

Conditional mapping patterns

Use one pattern consistently across companies. Group-based mapping is appropriate when all export customers share a policy. Branch-based mapping is appropriate when a branch has a legally separate registration or chart. Item-group mapping is appropriate when goods and services use different revenue or COGS accounts. Project-based mapping is appropriate when a contract requires a dedicated WIP or revenue stream. Date-based mapping is appropriate for a statutory change. Each condition needs an owner, effective date, test document, and fallback behavior.

Avoid condition sprawl. Ten overlapping customer-specific rules are harder to audit than three customer-group rules and a documented exception. An exception should have an expiry date and an approval, otherwise it becomes an undocumented permanent chart.

Posting-impact walkthroughs

Run these simulations in sequence and save the output. The amounts are deliberately small enough to calculate by hand.

1. Domestic stock sale: one chair, net AED 1,000 and VAT AED 50. Expected result: Dr AR AED 1,050; Cr domestic revenue AED 1,000; Cr output VAT AED 50. If perpetual inventory is enabled, delivery separately relieves inventory and debits COGS.
2. Saudi export sale: one chair, SAR 1,000 translated at AED 0.98, with the configured export tax treatment. Expected result: AR in document currency and base currency, export revenue, and either zero-rated or exempt tax treatment according to the tax policy. Do not assume “export” means zero tax without verifying the tax code and evidence.
3. Purchase with recoverable input tax: net AED 2,000 and tax AED 100. Expected result: Dr inventory or expense AED 2,000; Dr input tax AED 100; Cr AP AED 2,100. The input-tax account must not be used for non-recoverable expense.
4. Receipt with bank fee: customer pays AED 1,050 and bank fee is AED 5. Expected result: Dr bank AED 1,045; Dr bank-fee expense AED 5; Cr AR AED 1,050. The receipt allocation and bank statement must reconcile to the same external reference.
5. Return after delivery: one damaged chair returns. Expected result: stock receipt or quarantine movement, COGS reversal or return account according to policy, and a credit note referencing the original invoice. Never delete the original delivery.

For every test, record document ID, company, branch, book, posting date, exchange-rate source, tax code, warehouse, dimensions, resulting lines, balance status, and audit event. The tester signs only after an independent reviewer repeats at least one simulation.

Refusal tests consultants must demonstrate

Correct configuration includes controlled refusal. Attempt an export invoice without tax registration evidence; an invoice in a closed period; a journal with an inactive role; a stock delivery from an unavailable warehouse; a duplicate external reference; a line without a required dimension; and a template with only credit lines. Each attempt should stop with a clear instruction, no partial journal, and an audit event. If a refusal creates a journal anyway, classify it as a product defect and preserve the evidence.

Change-control record

Every production change should include the business reason, affected company/book, before snapshot ID, after snapshot ID, roles and ledgers changed, priority/effective-date analysis, simulation IDs, refusal-test IDs, approver, deployment time, rollback owner, and communication plan. A mapping change can alter future postings without changing historical journals; reports must therefore show the rule version or effective policy used. After deployment, monitor unmapped roles, unexpected account volume, tax variance, and suspense balances for at least one close cycle.

Advanced workshop: Demo Retail Group LLC across three companies

Use this scenario to prove that a consultant understands mapping as a controlled decision tree. Demo Retail Group LLC operates UAE stores, a Saudi subsidiary, and an India sourcing company. The group sells an AED 1,000 appliance domestically, exports a SAR 1,000 appliance to Saudi, buys inventory from India in INR, transfers stock between UAE branches, and receives a card settlement net of a gateway fee.

Step 1 — Identify the posting context

Before opening the mapping screen, write the context as data. Record company, branch, document type, stage, book, document date, tax date, customer or supplier group, country, tax registration, item group, warehouse, project, currency, and source event. A consultant who starts by searching for an account usually fixes the symptom instead of the context.

Context key	UAE domestic sale	Saudi export sale	India purchase
Company	DRC UAE LLC	DRC Saudi LLC	DRC Sourcing India Pvt Ltd
Stage	Invoice	Invoice	Supplier invoice
Book	IFRS-AED	IFRS-SAR	IFRS-INR
Party group	DOMESTIC	EXPORT	STRATEGIC-SUPPLIER
Country	AE	SA	IN
Item group	APPLIANCE	APPLIANCE	APPLIANCE
Warehouse	DXB-MAIN	RUH-DC	BOM-PORT
Currency	AED	SAR	INR

The document context is the evidence for a matching rule. If a field is missing, decide whether the correct response is a validation block, a fallback mapping, or an explicit suspense account. Do not infer country from a display name or currency from a bank account.

Step 2 — Configure roles before accounts

Create semantic roles first: AR_CONTROL, REVENUE_DOMESTIC, REVENUE_EXPORT, OUTPUT_TAX, INVENTORY, COGS, AP_CONTROL, INPUT_TAX, GATEWAY_CLEARING, BANK, FX_REALIZED, and INTERCOMPANY_STOCK. Roles describe why a line exists; accounts are the company-specific destination.

Role	UAE account	Saudi account	India account	Normal side
AR_CONTROL	110010	210010	310010	Debit
REVENUE_DOMESTIC	410100	510100	610100	Credit
REVENUE_EXPORT	410200	510200	610200	Credit
OUTPUT_TAX	220100	320100	420100	Credit
INVENTORY	130100	230100	330100	Debit
COGS	510100	610100	710100	Debit
GATEWAY_CLEARING	110900	210900	310900	Debit

The role table is reusable across companies; the account table is scoped to a company and book. If a Saudi subsidiary uses a different account for export revenue, do not create a new role called SAUDI_EXPORT_REVENUE unless its accounting meaning is genuinely different. Prefer the same role with a Saudi account mapping.

Step 3 — Create templates with explicit amount bases

The domestic invoice template has AR_CONTROL = gross, REVENUE_DOMESTIC = net, and OUTPUT_TAX = tax. A gateway receipt template has BANK = net settlement, GATEWAY_CLEARING = gross, and GATEWAY_FEE_EXPENSE = fee. An inventory delivery template has COGS = cost and INVENTORY = cost. The amount basis must state whether it is total, net, tax, fee, quantity times cost, or a derived allocation.

For the AED 1,000 domestic invoice with AED 50 VAT, the template produces Dr AR 1,050, Cr domestic revenue 1,000, and Cr output tax 50. A template with AR_CONTROL = net would still save, but it would leave AED 50 unexplained. The simulation must catch this before production.

Step 4 — Order rules from narrow to general

Configure the Saudi export rule at priority 50 for company=DRC Saudi LLC, stage=INVOICE, party.group=EXPORT, and item.group=APPLIANCE. Configure the domestic fallback at priority 100 for stage=INVOICE and item.group=APPLIANCE. Configure an unmapped-role block at priority 900. The rule report should show why a document matched, not only which account was selected.

If a customer belongs to both EXPORT and WHOLESALE, the rule must use a deterministic precedence or reject the ambiguity. Do not depend on record insertion order. If two active rules share priority and match the same context, block posting and create a configuration task.

Step 5 — Prove company and branch isolation

Post the same item in the UAE and Saudi companies and compare the generated lines. The account numbers may differ, but the role and document meaning should remain consistent. Attempt to post a Saudi document using the UAE company’s account mapping; the API should refuse a cross-company account or resolve only from the Saudi book. Attempt a branch transfer without source and destination dimensions; the required-dimension validation should stop it before a journal is created.

Step 6 — Reconcile settlement and FX

When the card gateway settles AED 1,045 after a AED 5 fee, the receipt first clears the gross AR through gateway clearing. The bank line is AED 1,045, the fee expense is AED 5, and the external gateway reference links all three lines. For a SAR invoice settled in AED, the receipt stores document currency, base currency, applied rate, rate source, value date, and realised FX. The mapping must not post the entire difference to a generic suspense account.

Step 7 — Diagnose a wrong account using evidence

Suppose a Saudi export invoice posted to domestic revenue. Capture the document ID, context payload, selected stage rule, rule priority, role, account, effective dates, user, and book. Then inspect in order: party group, tax registration, item group, company scope, stage, effective date, and fallback priority. Re-run the same document in simulation mode after one change. A screenshot of the final account is not enough; the consultant must preserve the winning rule path and the refusal or correction evidence.

Consultant sign-off criteria

The mapping is ready only when the implementation pack contains the role catalogue, account catalogue per company, template amount bases, stage priorities, field lengths and data types, effective-date matrix, required dimensions, tax policy references, ten positive simulations, seven refusal simulations, snapshot IDs, rollback procedure, and approver. The sign-off statement should answer: “If a new consultant joins tomorrow, can they reproduce the journal and explain every field without asking the original implementer?”