Configure document rules per change type

Who does this: Payroll Lead · Platform Admin When: Onboarding a new client, or tightening / loosening evidence requirements after a SOP review Result: The validation engine will block any submission whose change items don't ship with the required documents — the client cannot reach SUBMITTED until they comply.

Document rules are a per-client policy that says "when the client submits a joiner, demand an offer letter, NRIC, and bank details; for a leaver, demand a resignation letter; for a salary change above 5%, demand a change letter." Configured once per client, applied on every cycle.

Rules drive the completeness gate — a BLOCKING rule prevents the submission from advancing; a WARNING rule lets it through but flags it on the issues tab. Use the strictness lever carefully: too strict and your clients get stuck in INTAKE_IN_PROGRESS forever; too loose and bad data sails into the Infotech export.

Before you start

• [ ] You're a Payroll Lead or Platform Admin — Payroll Executive cannot edit client config.
• [ ] The client record exists.
• [ ] You've agreed with the relationship manager which evidence categories are mandatory for this client (SOP defaults are usually fine; some clients negotiate carve-outs).

TIP

Most Singapore SMEs match one of the four built-in SOP presets (joiner / foreigner joiner / leaver / foreign leaver / salary change). Apply the preset first, then add only the bespoke rules that are unique to that client. It's far less error-prone than building from scratch.

Steps

1. Open Clients in the staff dashboard sidebar.
2. Find the client and click into the client detail page.
3. Click the Document rules tab.
4. (Optional but recommended) Under SOP presets, find the preset that matches your client's profile — for example "SG · Joiner (offer + identity + bank)" — and click Apply. The platform creates the bundle of rules in one shot. Repeat for other presets that apply (foreigner joiner, leaver, salary change).
5. To add a one-off rule, click Add rule in the top right and fill the dialog:
   • Change type — JOINER, LEAVER, SALARY_CHANGE, VARIABLE_PAY, DEDUCTION, or OTHER.
   • Document type — OFFER_LETTER, IDENTITY_NRIC, IDENTITY_FIN, BANK_DETAILS, RESIGNATION_LETTER, CHANGE_LETTER, IR21, NS_DOCUMENT, EMPLOYMENT_CONTRACT, or GENERIC_DOCUMENT.
   • Enforcement — BLOCKING (gates the submission) or WARNING (lets it through with a flag).
   • Conditions (optional) — narrow the rule, e.g. nationality FOREIGNER for IR21, or salary delta ≥ 5% for change letters.
6. Click Create rule.
7. Repeat for every required document. Existing rules show in the Rules table below; click Edit to adjust enforcement or Delete to remove.

How to know it worked

• The Rules table on the Document rules tab shows the new row immediately, with the right enforcement badge (red BLOCKING / amber WARNING).
• The Activity log records a client.document_rule.created (or .updated / .deleted) entry attributed to you.
• The next time anyone runs validation on a cycle for this client, the engine evaluates the new rules. Existing in-flight cycles are also re-evaluated when next validated — there is no version pin.

NOTE

Adding a BLOCKING rule after a client has already submitted will not retroactively reopen a closed cycle, but it will apply to a cycle currently in SUBMITTED or ACTION_REQUIRED the next time validation runs. If you tighten policy mid-cycle, expect at least one client to receive a fresh action-required email. Coordinate with the relationship manager.

What the client sees

The client never sees the rules directly — they see the consequence on the intake wizard:

• For each change item they add, the wizard shows a checklist of required document slots.
• A red asterisk + "Required" label sits next to slots backed by a BLOCKING rule. The Submit button stays disabled until every required slot has a file.
• An amber "Recommended" label sits next to slots backed by a WARNING rule. The Submit button works, but the client sees a confirmation dialog noting the warnings.

Common situations

If you see…	It means…	What to do
Apply preset confirms but one rule fails to create	A duplicate rule already exists for that change-type + document-type pair	Open the existing rule, adjust enforcement instead of creating a new one
Client portal shows "submission blocked: missing X" but the rule looks right	The rule is BLOCKING for a change type the client legitimately can't supply that document for	Either narrow the rule with a condition, or override the issue for this cycle
You want a rule only for foreigners	Default rule applies to everyone	Add a Nationality = FOREIGNER condition; the Singaporean carve-out is auto
You want a rule only for big salary changes	Default rule fires on every change row	Add a Salary delta min condition (e.g. 5 for 5%)
Validation keeps blocking the same submission even after upload	Rule is matching on a slot that the file isn't tagged against	See Validation keeps blocking

Related runbooks

• Validation rules reference — the four BLOCKING + one WARNING rules and how the document rule layer plugs into them
• Resolve a blocking validation issue
• Override a blocking issue — for one-off carve-outs without weakening policy
• Validation keeps blocking
• Payroll SOP — section on document evidence requirements