Core Concepts
Six ideas explain almost everything surprising about this module. Learn them once here and the two applet pages stop being a list of screens.
1. The claim line is the unit of everything
A claim has a header — a title, a claimant, a cost-centre branch — and one or more claim lines. The header is a folder. Everything that actually happens happens on the line:
- the status is on the line (the header’s is recomputed from its lines);
- the approval route is on the line, chosen by the line’s claim item;
- the entitlement deduction is on the line;
- the claim cycle collects lines, not claims;
- every report row is a line.
So two lines on one claim can go to different approvers, land in different months and be paid in different ways. A claim is “approved” only when every line on it is.
A line’s own path, from draft to paid:
flowchart TD
D["DRAFT<br/>claimant writes the line"] -->|Submit| P["PENDING_APPROVAL"]
D -->|"Submit, line ticked<br/>Non-Reimbursable"| A2["APPROVED<br/>never routed"]
P -->|"supervisor rejects"| REJ["REJECTED<br/>claimant may clone it"]
P -->|"last approval level approves"| SPLIT{"claim item's<br/>Payment Processing Option"}
SPLIT -->|SALARY_PAYMENT| A1["APPROVED<br/>hand to payroll"]
SPLIT -->|FINANCE_PAYMENT| R["PENDING_DOC_REVIEW<br/>waiting for a claim cycle"]
R -->|"swept into the month's cycle"| INBOX["Checking Reports → Inbox"]
INBOX -->|"reviewer accepts"| REV["REVIEWED<br/>then APPROVED at the final level"]
INBOX -->|"reviewer puts on hold"| HOLD["ON_HOLD<br/>claimant e-mailed"]
HOLD -->|"claimant resubmits"| RES["RESUBMITTED"] --> INBOX
REV --> PAY["Bank Report / PV Details Report<br/>→ paid by hand"]
A1 --> PAY2["Payroll Payment report<br/>→ paid through payroll"]
Both applets store their data in the claims records. AAT, the family’s internal name, is audit, assurance and tax, the practice area the module was originally built for. That is why the professional-body, engagement and sampling features exist, and why they read as more audit-firm than retail.
2. The claim item decides everything about a line
Pick the claim item and you have picked the approval route, the required fields, the cap and the payment method. These are the four settings on a claim item that change a line’s behaviour most:
| Setting on the claim item | What it decides |
|---|---|
| Approval Workflow | Which route in §3 the line takes. The claimant picks a workflow on the line first and is offered only the items that carry it; the line then keeps its own copy, and that copy is what the approval run reads at submission. So changing an item’s workflow re-routes no line already saved — only one whose item is picked again on the edit screen |
| Payment Processing Option | FINANCE_PAYMENT — the line goes to a claim cycle for finance review. SALARY_PAYMENT — the line is APPROVED the moment the last supervisor approves, and paid through payroll. The two never mix |
| Claim Account | Required when the workflow is HR benefit; this is the pool the entitlement balance comes from |
| Claimable Period (Days) / Threshold / UOM | The only caps that exist besides the entitlement balance: how far back the cost dates may span, and the rate per kilometre or per day |
The required-field flags (receipt number, vendor, attachment, OCR attachment, internal employees, professional body, travel location, mileage) are also on the item, which is why the same claim form looks different for two different expense types.
3. Three approval workflows on the screen, and this engine is real
Every other approval in BigLedger is optional. Claims is the exception. It has its own approval engine — approval settings with levels, quorums and types, and a per-line approval sequence built when the line is submitted — and a line cannot pass without it. This is not the generic document-approval engine (which covers only Purchase Order, Purchase Requisition and Stock Requisition), and it is not Workflow Design, which nothing in claims reads.
The Approval Workflow drop-down on a claim item has three entries:
| What the drop-down says | When you would use it | How it finds approvers | Stored as |
|---|---|---|---|
| Non-Chargeable | Ordinary staff expenses — travel, mileage, meals | Employees holding the required approval designation in the claimant’s branch. Set under Settings → Branches → Approval Designation | EMPLOYEE_ORG_CHART |
| Non-Chargeable – Entitlement | Medical, dental, professional subscriptions — anything drawn from an allowance | The HR Claim Approval levels on the claim account | CLAIM_ACCOUNT |
| Chargeable | Re-billing a client job | The roles on the engagement the line names | ENGAGEMENT_PIC |
The stored value is worth knowing because it is not the one you would guess. EMPLOYEE_ORG_CHART
is what “Non-Chargeable” writes today — it is not a retired value — and the approval processor
routes it and EMPLOYEE_AD_HOC to the same ad-hoc logic, so the two names mean one route.
Two further values exist in the backend and are not on the screen. PROJECT_PIC (approvers from
a project’s person-in-charge roles) works if a claim item is written through the API. EVENT does
not: the processor has no branch for it, so the line gets no approval sequence, no error and no
approver, and stays at PENDING_APPROVAL indefinitely.
Each level has an approval type (any one approver, or all of them) and a quorum (how many approvers are needed). A default approver catches the case where the claimant is at the top and has nobody above them. A delegation period substitutes a stand-in for a named approver between two dates, and the sequence records that the approval was delegated.
Two behaviours worth knowing before you meet them:
- A line ticked Non-Reimbursable skips approval entirely. It is
APPROVEDon submit with the approval date set to now. It is for money the company has already paid and only wants on record. - An incomplete approval setting fails the submission, it does not park it. The message names the missing piece — level and quorum, your designation on the branch, an approver for that designation, too few approvers for the levels, or the HR approvers and levels on a claim account.
- A missing default approver is the one gap submission does not catch. The check for it is switched off in the code, so the line is accepted; then, if nobody holds the approval designation, building the approval sequence fails and the line never reaches an approver. What you see is a line that stays pending approval with nobody to approve it; its processing status shows a failure or, depending on which write landed last, still inserted to queue. Nothing re-runs it — the support-side retry reaches only lines that could not be queued at all — so once the default approver is set the claimant withdraws the line and raises it again.
4. The entitlement balance — and the checkbox that switches it on
A claim account is a pool of money (medical, professional subscription, training). An entitlement is the top-up rule on that pool: how much, how often, over what validity period, prorated for new joiners or not. Employees are linked to an entitlement individually, by an auto top-up run, or by an upload.
When an HR-benefit line is submitted, BigLedger adds up what is already approved and pending against
that account and refuses the line if the new amount will not fit, with
CLAIM_DOC_LINES_INSUFFICIENT_BALANCE. If the account is convertible, it draws on the convertible
account before failing.
And the check applies to HR-benefit lines only. Ad-hoc, engagement, project and event lines have no entitlement, no balance and no cap beyond the claim item’s claimable period and threshold.
The balance is spent at final supervisor approval, not at submission and not at payment: a
UTILIZE line (negative) is posted against the claimant’s account then, with a CONVERSION line
against the convertible account if needed. That too happens only when Display Entitlement
Balance is ticked — with it off the balance is neither checked nor drawn down. And if the main
balance is short and there is no convertible account to draw on, the final approval itself stops with
ERROR_UTILIZE_LOGIC on the approval queue. Withdrawing or rejecting a line before approval completes
leaves the balance alone; a line that was approved and then put on hold has already spent it.
5. A claim cycle is one company, one month
Finance does not review claims one at a time. Lines that finished supervisor approval sit at
PENDING_DOC_REVIEW until a claim cycle collects them.
flowchart LR
CUT["Claim Cut-Off Logic<br/>one row per company"] -->|"scheduled job"| CYC["Claim cycle<br/>company + month<br/>status OPEN"]
APPR["Lines at PENDING_DOC_REVIEW"] -->|"final approval date<br/>≤ approval cut-off end date"| CYC
CYC --> INBOX["Checking Reports → Inbox"]
INBOX -->|"reviewer level 1 … n accepts"| RDY["APPROVED<br/>ready to pay"]
INBOX -->|"On Hold"| BACK["back to the claimant"]
RDY --> REP["Bank Report · PV Details · Cross-Billing<br/>Pivot · Prof Subscription"]
CYC -->|"final-level reviewer closes it"| CLOSED["CLOSED"]
CLOSED -->|"everything not ready to pay"| NEXT["next month's cycle"]
Four dates shape a cycle, all computed from the company’s Claim Cut-Off Logic: the finance cut-off, the supervisor approval cut-off, the extension end date, and the finance last-review date. Where a date is set as a number of days before or after the finance cut-off, the days are working days and skip the holidays on the calendar; where it is set as a specific day of the month, it is that calendar day.
Three consequences:
- No cut-off row means no cycle, and therefore no finance review ever happens. Approved lines
pile up at
PENDING_DOC_REVIEWand nobody sees them. This is the most common “claims are stuck” cause. - A line approved after the approval cut-off end date waits for next month. That is the cut-off doing its job, not a bug.
- Closing a cycle is not a deadline that discards anything. Whatever is not ready to pay is moved into next month’s cycle, keeping a link back to where it came from.
A line can reach its cycle without waiting for the periodic job. At final approval it is attached straight away to its company’s cycle for the month it was approved in, if that cycle already exists and the approval is inside the approval cut-off. And the cut-off form’s Immediate Ingest panel has a toggle, Auto-add approved claims to active cycle: with it on, a line that found no cycle that way is attached to the current month’s open cycle (created if there is none), past the cut-off.
6. Finance review is by level, and it is not the same as supervisor approval
Supervisor approval and finance review are two different engines with two different configurations, and people conflate them constantly.
| Supervisor approval | Finance review | |
|---|---|---|
| Configured in | Claim Applet → Claim Approval Settings | Claim Cycle Applet → Reviewer Setting |
| Who is listed | Approvers by designation, engagement role or HR level | Named employees, per company, each with a level |
| What it produces | PENDING_DOC_REVIEW (or APPROVED for salary-payment items) | REVIEWED, then APPROVED with ready to pay at the highest level |
| Who may close the month | — | Only a reviewer with Is Final Approval Level ticked |
A reviewer can act only on lines whose latest reviewed level is below their own. Two reviewers acting on the same line at once means the second one is told the line was already reviewed — refresh and it is done, not lost.
7. Nothing posts, and that is by design
There is no journal, no stock movement and no payment voucher anywhere in this module. Claims is not a generic financial document — it has no amount signum, no quantity signum, no journal handler and no VOID. The GL codes carried on a line exist so that the PV Details Report can tell a human what to code the payment to.
The claim header does carry posting-status fields for a payment voucher and a purchase invoice. Nothing in the claim module ever sets them.
Payment happens in one of three ways, all of them manual or external:
- Bank Report → upload to the bank portal, one payment per employee.
- PV Details Report → raise a Payment Voucher by hand; the cycle has a column to record the voucher reference, but nothing fills it in for you.
- Salary-payment CSV → hand to payroll, for claim items set to
SALARY_PAYMENT.
A closed cycle is also marked ready to sync, so an external ETL integration can pick it up. Nothing in BigLedger polls it.