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	A submission item (joiner / change / leaver) is missing a document type your client requires	Identify which item; collect the specific document
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	Two or more uploaded files have the same content hash — likely a re-upload	Confirm with the client which is canonical; remove the duplicates
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 field on an uploaded document came back with low OCR confidence	Open the file, manually verify or correct the field
CPF_AW_CEILING	An employee is at risk of breaching the CPF Additional Wage ceiling	Confirm with the client whether to cap; needs deliberate action

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 — use Request more info from a client instead. The client uploads through their portal link, and the platform auto-resolves the issue when validation re-runs.
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 Request more info from client 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
• Request more info from a client — when the client needs to upload 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