Resolve a blocking validation issue

Who does this: Payroll Executive · Payroll Lead When: A submitted cycle has at least one open BLOCKING issue and is sitting in ACTION_REQUIREDResult: The blocking issue is resolved (artifact uploaded or condition no longer applies). Validation re-runs cleanly and the cycle moves on toward READY_FOR_EXPORT.

When a client submits, the platform runs the validation rules against the submission. Anything that fails as BLOCKING lands in the cycle's Issues tab and stops the cycle from advancing. You can't generate the export while a blocking issue is open.

This runbook walks the standard resolution path: figure out what's missing, get it (either from the client or from your own files), and re-run validation. For the rarer case where the rule genuinely shouldn't apply to this cycle, see Override a blocking issue — that's a Payroll Lead action that needs a justification on the audit trail.

Before you start

• [ ] The cycle is in ACTION_REQUIRED status. (If it's still in INTAKE_IN_PROGRESS, the client hasn't submitted yet — you can't resolve issues that haven't been raised.)
• [ ] You've opened the cycle's Issues tab and read what's actually flagged. Each issue card shows the rule that fired, a plain-language reason, and which employee or change the issue is linked to.

Understanding what blocked

The Issues tab shows one card per open issue. The card's headline tells you which rule triggered:

Issue code	What it means	Typical fix
ATTENDANCE_REQUIRED	The client submitted no attendance data for the month	Ask the client for attendance, or if the client has an attendance system that auto-extracts, confirm OCR ran
DOCUMENT_REQUIREMENTS_MET	One change (named on the issue) has no document of its own and nobody has approved it yet	Attach its document, or approve the change as a confirmed manual entry, then Re-check
FOREIGN_LEAVER_IR21	A foreign employee leaver was declared but no IR21 task is recorded	Confirm IR21 was filed with IRAS; upload the acknowledgement
NS_DOCUMENTATION	A National Service claim was declared but no NS documentation attached	Ask the client for the NS pay claim form
DUPLICATE_RECEIPTS	A claim line repeats a receipt (same supplier, bill date, amount) this month or one already paid, or two files are identical	Confirm with the client; reject the repeat, or a Lead overrides that one line
SALARY_DELTA_THRESHOLD	An employee's salary changed by more than 20% vs the prior cycle	Confirm the change is intentional with the client; if so, this needs a Lead override
PAYROLL_VARIANCE_THRESHOLD	Aggregate payroll changed by more than 10% vs the prior cycle	Sanity-check with the client; large headcount swings or bonus months are common causes
OCR_LOW_CONFIDENCE	A document a change still awaiting approval rests on has fields read with a low score	Open the file, check the value on its card and approve or correct it, then Re-check; if only the client can tell, Ask client on the check
CPF_AW_CEILING	An employee is at risk of breaching the CPF Additional Wage ceiling. Shown as not checked while no year-to-date wages are on file (the usual case today)	Check the ceiling in Infotech in a bonus or AWS month

The full reference is at Validation rules.

Steps

Path A — the artifact exists, you just need to get it

1. Open the cycle, go to the Issues tab.
2. Click into the issue card. The Linked employee badge tells you whose change is missing the artifact.
3. Decide who has the document:
   • You have it — open the cycle's Files tab and click Upload file. Pick the right file kind (SUPPORTING_DOC, IR21_ACK, etc.) and upload. Then return to the issue and click Resolve with reason DOCS_PROVIDED_OOB ("documents provided out-of-band"). Pick the file you just uploaded as evidence.
   • The client has it — click Ask client on the check instead (see Ask the client for something mid-month). The client replies on the thread with the document; their reply shows under the check, which stays open until you clear it.
4. After uploading, the cycle's validation re-runs automatically. Reload the cycle.

Path B — you've confirmed the answer with the client over email or chat

Sometimes the resolution isn't a document; it's confirmation. ("Yes, we know that 25% raise looks aggressive — it's intentional, the new title is Director.")

1. Open the issue card and click Resolve.
2. Pick a reason:
   • DOCS_PROVIDED_OOB — they sent the file by email and you've uploaded it manually.
   • CLIENT_CONFIRMED — they confirmed by email/chat and no file is involved.
   • NOT_APPLICABLE — the rule doesn't apply to this cycle (rare; usually warrants an override instead).
3. Add a short free-text explanation. This goes verbatim onto the audit trail.
4. Click Resolve.

The issue card flips to Closed, the cycle re-validates, and you'll see the open-issue count tick down.

TIP

If clicking Resolve doesn't make the cycle move out of ACTION_REQUIRED, there's still at least one other open BLOCKING issue. The Issues tab badge in the cycle header shows the open count.

How to know it worked

• The issue card shows status CLOSED with a green check, your name, and your reason text.
• The cycle's status badge moves from ACTION_REQUIRED to READY_FOR_INTERNAL_REVIEW (and then READY_FOR_EXPORT after you click Confirm Review) once the last open BLOCKING issue is resolved.
• The cycle's Activity log records issue.resolved for each closed issue, plus a fresh validation.run.completed afterward.
• The Generate Export button on the cycle header becomes enabled once you're in READY_FOR_EXPORT. (Until then it's hidden.)

What the client sees

Resolving an issue in the dashboard does not by itself email the client. If you want to tell them what happened — for example, that you uploaded the missing IR21 acknowledgement on their behalf — send a one-line email outside the platform; or use Ask client (Ask the client for something mid-month) if you actually need them to act.

Common situations

If you see…	It means…	What to do
Issue card stays open after you click Resolve	Validation hasn't re-run yet, or another rule re-flagged it	Wait 10s and reload; if still open, check the issue card for a new fail message
You uploaded the file but the issue still says missing	The file kind or document type doesn't match what the rule expects	Open the file's row in the Files tab; confirm the kind is correct (e.g. IR21_ACK not SUPPORTING_DOC)
Generate Export still hidden after all issues resolved	Cycle is in READY_FOR_INTERNAL_REVIEW (one more click needed)	Click Confirm Review on the cycle header; cycle moves to READY_FOR_EXPORT
Issue is genuinely not applicable (e.g. IR21 for a contractor leaver)	This is the override case, not resolve	Use Override a blocking issue — Payroll Lead only
Multiple issues with the same root cause (e.g. a missing document affecting 3 employees)	Each issue resolves independently	Resolve each one; you can use the same reason text on all
Validation says variance is 12% but the client confirms it's correct	Variance threshold can't be resolved with a document — it's an override case	Override the issue with the client's confirmation in the justification

Related runbooks

• Override a blocking issue — when the rule genuinely shouldn't apply
• Ask the client for something mid-month — when the client needs to send something
• Validation rules reference — full rule list and what each one checks
• Generate the Infotech export — what comes after issues are clear
• Why is the Generate Export button greyed out? — common stuck states

Who clears each line of the month's strip

Since 28 Oct 2026 (stage review SX-10), each line of the strip under the month's title says who has to clear it, from the issues' owner roles: needs the Payroll Executive, needs a Payroll Lead (an issue owned by the Lead role or needing a Lead's approval), both with their counts, or waiting on the client when the question was asked by chat and not answered. Changes to decide need the Executive; a held change waits on a document from the client; a statutory finding needs the Executive, or a Lead to override it; an employee list to review needs the Executive; withheld pay waits on IRAS. Infotech tie-out differences say needs the Payroll Executive to investigate, or a Payroll Lead to release with a reason — the Executive brings back a corrected report, or a Lead who did not prepare the month releases them on the tie-out panel; mixed with other issues, they are counted apart. The strip is still hidden on a closed month, and held pay and Lead-only warnings still read as needs a look, not as stops.