Configuration
Almost nothing in this module is configured by ticking a box in an Application Settings screen. The behaviour lives in master data — claim items, claim accounts, approval settings, cut-off logic, reviewer settings — and a missing piece announces itself as a refused submission with a named error, usually in front of an employee who is trying to get their money back.
This page lists what must exist, where it is set, and what the failure looks like, so you can recognise a gap from its message. The order is a dependency order, not a rule the product enforces; out of sequence simply means you hit the failures later.
1. People, before anything else
| What | Where | If it is missing |
|---|---|---|
| Every claimant, approver and finance reviewer exists as an employee whose primary login e-mail matches the employee record | Employee Maintenance | The claim screens refuse to load: Cannot find your email … from Employee Applet |
| Employees have designations on their branch | Employee Maintenance, then Claim Applet → Settings → Branches → Approval Designation | Ad-hoc submissions fail: Your designation … is yet to be configured for branch … and Approver for designation … under branch … is yet to be configured |
| Employees who will be reimbursed by bank transfer have a payment method with bank code and account number | Employee Maintenance | The Bank Report generates, but those rows have no bank code and no account number — and nobody notices until the payment file is rejected |
The e-mail link is the whole identity model here. A claimant is resolved from the login’s primary
e-mail to an employee record, every time. Change someone’s e-mail without changing their employee
record and they lose access to their own claims.
2. Company structure
| What | Where | Why it matters |
|---|---|---|
| Companies and branches | Organization | A claim’s cost-centre branch drives approver lookup; a claim cycle is per company |
| Company holiday events on the calendar | Organization | Cut-off dates set as a number of days before or after the finance cut-off are counted in working days and skip these. Without them those cut-offs land on public holidays |
| Fiscal year and period rows for the cycle month | Chart of Account | The cycle processor creates them if they are missing, so this rarely bites — but it is the only place claims touches the fiscal calendar |
The Claim Applet has its own Settings → Branches screen. It is a view of the same branches with claim-specific tabs added: Employees, Employee Ranking (used to order approvals by rank) and Approval Designation. Branches are not created here.
3. Expense GL codes
| What | Where | Note |
|---|---|---|
| Expense GL codes, and billing GL codes if you re-bill clients | Chart of Account | Selected on each claim item and carried onto the line for reporting only |
There is no company default GL mapping to set for claims, because claims posts no journal. A missing
GL code produces an empty column in the PV Details Report, not a posting failure. It is still worth
getting right — that report is what the person raising the payment voucher codes from.
4. Claim items — the piece that does the most work
Claim Applet → Settings → Claim Item Category, then Claim Items. A claim item is unique on code plus expense company.
For each expense type you want people to claim, decide:
- Approval Workflow — the drop-down offers three: Non-Chargeable (ordinary staff expenses), Non-Chargeable – Entitlement (drawn from an allowance) and Chargeable (re-billed to an engagement). This is the biggest decision on the form; see Core concepts §3.
- Approval Setting — which set of levels and quorums applies.
- Payment Processing Option — finance cycle, or payroll.
- Claim Account — mandatory for HR-benefit items.
- Required fields — attachment, OCR attachment, vendor and receipt number, follow-up programme and guests, professional body, subscription type, travel allowance, mileage, location tracking, internal employees.
- Claimable Period (Days), Threshold and UOM (
KMorDAYS) — for example RM 0.80 per kilometre. The claimable period is only checked on lines that carry an OCR receipt document and a receipt date (and never on a non-reimbursable line, a resubmission, or a clone of a rejected one). If the item does not require Supporting Document Using OCR Attachment, the period is recorded and not enforced. - Expense and billing GL codes and companies, and the markup ratio if you re-bill.
| Failure | Message |
|---|---|
| Receipt is older than the claimable period, on a line that carries an OCR receipt | Maximum claimable period of claim item … is N days. But total claim period days is M |
| Item requires internal employees and none are listed | Internal Employees information are not provided for Claim Lines … |
| Professional claim whose receipt date is outside the membership validity | Receipt date … is not within validity date range … |
5. Approval settings
Claim Applet → Settings → Claim Approval Settings. One per workflow type you use. Each carries a name, a code, the workflow type, a default approver, a branch or engagement role, and a list of levels — each level with an approval type (any one, or all) and a quorum.
| Failure | Message | Fix |
|---|---|---|
| No levels configured | Approval level & quorum are yet to be configured … | Add the levels |
| Nobody holds the approval designation and the setting has no default approver | No message. Submission accepts the line; building its approval sequence then fails. What you see is a line that stays pending approval with nobody to approve it; its processing status shows a failure, or still inserted to queue | Set the default approver; then the claimant withdraws the line and raises it again. The support-side retry skips a line that is still pending approval, and Resubmit reaches only lines finance put on hold |
| Not enough approvers hold the designation | Total N approver required … Currently M approver | Link more approvers under Branches → Approval Designation |
| No HR approver, or too few HR levels, on the claim account | HR person to approve your claim is yet to be configured / HR/TIM are not fully configured. Total required approval levels is N, but only M … | Claim Accounts → HR Claim Approval |
Optionally add Claim Approval Delegation Periods — a main employee, a stand-in, and the dates between which the stand-in acts. The approval sequence records that the approval was delegated.
6. Claim accounts and entitlements, if you run allowances
Claim Applet → Settings → Claim Accounts, then Claim Entitlements.
- Create the claim account (code, name, currency).
- Tick Display Entitlement Balance — see the warning below.
- Add the HR Claim Approval levels on the account.
- Create the entitlement: top-up amount, recurring rule, calculation by amount or by quantity, validity period, whether it is prorated for new joiners, whether it has no limit.
- Link employees — on the Employees tab, through an Auto Top-up template → event → run, or with Upload Employee Entitlement.
- Optionally set up account conversion, so a main account can draw on a convertible one when it is short.
If you do not tick Display Entitlement Balance, the entitlement is not enforced. The balance
check at submission runs only for claim accounts with that flag on. Untick it and employees can claim
past their allowance with no error and no warning — the allowance becomes a number nobody sees and
nothing checks.
| Failure | Message |
|---|---|
| Employee not linked to the entitlement, or the balance will not cover the line | Claimant is not entitled to claim … / CLAIM_DOC_LINES_INSUFFICIENT_BALANCE |
| HR set a validity end date that has passed | Your Professional Study Scheme claim was forfeited on … |
7. Claim cut-off logic — one row per company, or nothing ever reaches finance
Claim Applet → Settings → Claim Cut-Off Logic. This is the single most commonly missed piece of the whole module.
| Date | How it is expressed |
|---|---|
| Finance cut-off | Last day of the month, or a specific day |
| Supervisor approval cut-off | A number of days before the finance cut-off, or a specific day |
| Extension window | A number of days after the finance cut-off, or a specific day |
| Finance last-review date | A number of days after the finance cut-off, or a specific day |
| Immediate Ingest — Auto-add approved claims to active cycle | A toggle. On: a line at final approval that has no cycle yet joins the current month’s open cycle, created if need be, even past the approval cut-off. Off: it joins its approval month’s cycle at approval only if that cycle exists and the approval is inside the cut-off; otherwise it waits for the cycle job |
With no cut-off row for a company, no claim cycle is ever created for it. Supervisors approve,
lines reach
PENDING_DOC_REVIEW, and there they stay — invisible to finance, with no error anywhere.
If the complaint is “approved claims never reach us”, check this before anything else.8. Reviewer settings — who may review, and who may close the month
Claim Cycle Applet → Settings → Reviewer Setting. One row per employee per company: name, e-mail, approval level, and Is Final Approval Level.
| Failure | Message |
|---|---|
| You are not a reviewer for that company | User is yet to be configured to review claim lines under company: … |
| You try to close a cycle without final level | You are not a finance reviewer in Reviewer Setting / You are not final review level … not allowed to close claim cycle |
| Your level is not above the line’s latest reviewed level | Approve silently does nothing for those lines and the error names the level |
Exactly one level should carry Is Final Approval Level, and it should be the highest. A line becomes ready to pay when the highest configured level accepts it.
9. The rest — useful, not blocking
| What | Where | Why |
|---|---|---|
| Travel Allowance rates | Claim Applet → Settings → Travel Allowance | Per-diem by destination, with breakfast / lunch / dinner / inconvenience components a line can deduct |
| Professional Body, Subscriptions and Memberships | Claim Applet → Settings | Lookup lists for professional subscription and study-scheme claims |
| Email Template | Claim Applet → Settings → Email Template | The approval-pending notification, the daily reminder to approvers, and the review notification the claimant gets when a line is put on hold. Writing a template does not switch the e-mails on — see the warning below |
| Forex data source | Forex | Needed only for foreign-currency lines, and only when Show Forex Data source is on |
| Printable Format Settings | Claim Applet → Settings | The formats available to the Export action |
The claim e-mails are off until somebody schedules them, and nothing schedules them for you.
The approval notification is sent by a daily clock with the code
CLAIM_EMAIL_NOTIFICATION_FOR_APPROVAL_PROCESSOR, and that clock has to be created by hand in the
Scheduler Applet, with the code and the name both set and
the cron 0 9 * * * for 09:00 daily. The scheduled claim cut-off job, which creates
the monthly cycles, tries to create it on every run and fails every time, because it sets a name but no code, and a
schedule row without a code is refused. Nothing reports the failure. No row with that code means no
approval e-mail: the approval template you write here is saved and never sent. Nothing on this screen tells you
the row is missing, so confirm it in the Scheduler Applet before you promise an approver a reminder.What success looks like
Ten minutes, one test claim, five checks:
- Open My Claim as an ordinary employee. It loads — so the e-mail-to-employee link works.
- Create a claim with one line on an ad-hoc item and Submit. It is accepted — so the approval setting is complete.
- Open the line’s Approval Sequence tab. It names a real approver at each level — so the designation links resolve.
- Have that approver Approve it from Pending Approvals. The line moves to
PENDING_DOC_REVIEW. - Open the Claim Cycle Applet. A cycle exists for the company and month, and the line is in its Checking Reports → Inbox — so the cut-off row and the reviewer setting are both right.
If step 5 fails and steps 1–4 passed, it is the cut-off row.
Common mistakes
| Mistake | Symptom |
|---|---|
| No Claim Cut-Off Logic row for a company | Approved lines never reach finance, with no error anywhere |
| Display Entitlement Balance left unticked | Entitlements are silently unenforced; employees over-claim |
| No reviewer flagged Is Final Approval Level | Lines still become ready to pay when a reviewer at the highest configured level reviews them, but the cycle cannot be closed: closing needs a reviewer flagged Is Final Approval Level for that company |
| Employee payment method missing bank details | Bank Report rows with empty bank code and account number |
| Approval setting edited after submission | Queued lines fail with an approval-sequence processor error and never reach an approver; fix the setting, then withdraw them and raise them again — the support-side retry does not reach a line that is still pending approval |
| Assuming claims post to the ledger | The month closes with no journal, because there never was one — see Core concepts §7 |