Release Notes

What changed

Newest release first. Active licences receive updates automatically: download the latest release from the Customer Portal.

A payment kind for a reimbursed notice buy-out, and clearer words in both workbooks

  • A new payment kind. sg.ir8a_item and the IR8A helper have a kind for the reimbursement a new employer gives a new hire for the payment in lieu of notice the hire made to the former employer. It is taxable and goes in the lump sum item with the inducement to join. CPF is not payable on it, so the IR8A helper asks you to add it rather than adjust IRAS's pre-filled record. The inducement to join now means a sign-on bonus.
  • A change to the C interface. The new kind comes straight after the inducement to join, so the number of every later payment kind moves up by one. Code that uses the generated names picks up the new numbers when you rebuild against this release. Code or stored data that holds a payment kind as a number needs those numbers changed.
  • The Payments drop-down in Skedula's words. "Compensation For Loss Of Office" is now "Payment for losing a job or office", and the inducement to join reads "Inducement to join, such as a sign-on bonus". A Payments row that holds either old label is no longer on the list: pick its kind again from the list.
  • A refusal that says what it was worked out on. Sometimes sg.payroll_month cannot work out the CPF share on the wages without this month's overtime paid with next month's pay. Its message now says it is about those wages, so it no longer seems to contradict the month's own wages. A refused month shows each reason once, and this message only when it is that share alone that can't be worked out.
  • The carry-in's pay date has its own finding. In the payroll year workbook, a person's first month reports the pay date for the overtime carried in from Employees apart from next month's pay date, so each date that needs fixing is named.

Overtime counts with the month it was worked, in sg.payroll_month and the payroll year workbook

  • Overtime is entered on the row of the month it was worked. Each month's overtime has its hours, its pay and whether it is paid with that month's pay or the next month's, on that month's row. A blank choice follows the setting on Start. December's overtime paid with January's pay needs January's pay date, a new cell on Start.
  • As CPF Board counts it. Overtime paid with the next month's pay by the CPF due date counts with the month it was worked: ordinary wages of that month, with that month's CPF, fund and levy. The workbook shows the CPF top-up for that month (and the fund's), and the employee's share is deducted on the next month's payslip, with the payslip of that month showing what it deducted. Paid later, it is additional wages of the month it is paid in.
  • Late overtime is flagged. Overtime paid later than the Employment Act allows is flagged (PY10). A top-up for a month that may already have been submitted is a notice (PY11), and overtime paid with next month's pay in a person's last month is refused (PY12).
  • A year to the next. Employees takes the overtime of the month before a person's first month, and Totals gives December's overtime paid with January's pay, to carry into next year's Employees.
  • A change to the C interface. sg.payroll_month's overtime_for_previous_month is replaced by new inputs and outputs for overtime paid with the next month's pay, so code that sets the old input no longer compiles or runs against this release. Rebuild after you move to the new inputs. The workbook's layout also moved: this release's payroll year workbook is not a drop-in copy of an earlier one.
  • No contribution in a month with no wages paid. sg.shg gives no self-help group contribution for a month in which no wages are paid, for all four funds, as CPF Board says the contributions are payable as long as the employee is paid wages in the month. The EZPay preview likewise has no row for a person paid no wages in the month, as CPF Board asks that such an employee is not included in the submission.
  • The carried employee share is deducted as given. The employee's CPF on overtime carried to the next month is deducted from that month's pay as it was worked out, without being worked out again.

Public-sector CPF withdrawn, the domestic-helper programs, a renamed pack and the IR8A helper's marks

  • Withdrawn. sg.cpf_public_sector and sg.cpf_public_medisave, the CPF rates for pensionable public-sector staff and SAF regulars and their extra MediSave contributions, are no longer in any edition. Private-sector and non-pensionable staff use sg.cpf, as before.
  • Domestic-helper programs. sg.mdw_levy and sg.mdw_rest_day are in the Home Pack, both SDK editions and the free pack, and no longer in the Complete SME Suite or the Corporate & BPO Edition.
  • IR8A helper marks. The IR8A helper now asks to add, not adjust, notice pay, compensation for loss of office and retirement benefits, because CPF is not paid on them, so IRAS's pre-fill doesn't hold them. A lump sum that holds a gratuity, an ex-gratia payment or an inducement to join is still adjusted for a pre-filled person.
  • A renamed pack. The Foreign Workers, PWM & Wage Credits Pack is now the Foreign Workers & PWM Pack, and its ZIP is skedula-sg-sme-pack-3-foreign-workers-pwm.zip. It holds the same programs. The licence terms are now version 2.3, whose only change is the pack's new name in the SME Pack schedule.

The Enabling Employment Credit estimate follows IRAS's terms for each year

The Enabling Employment Credit estimate in sg.employer_credits follows the terms IRAS has published for each year it covers.

  • A renamed input. The input eec_first_nine_months is now eec_temporary_offset. It says whether IRAS pays the temporary offset for this employee in the month. Set it for each month IRAS pays the offset for; the notes of each year's rules give how long that period is.
  • SDK callers must update. The name is part of the C interface (and of the same input in every other language), so code that sets the old name no longer compiles or runs against this release. Change it to the new name and rebuild.

A Progressive Wage Credit estimate

A new program, sg.pwcs, estimates the Progressive Wage Credit for one employee and qualifying year, for planning. You give it the averages and CPF months that you work out, and it gives back an estimate with its calculation trace. IRAS works out and pays the credit itself, and its amount is the one that counts. IRAS also gives employers a free calculator for the credit; this estimate is for code and planning. The program is in the Foreign Workers & PWM Pack, the Complete SME Suite, the Corporate & BPO Edition, both SDK Editions and the free pack, with its workbooks and reference PDF.

A folder of workbooks for each year

The Excel workbooks now come in a folder for each year. excel/ holds a folder named after each year the pack covers. Each folder holds the workbooks of the programs in force in that year, the same workbooks for older Excel in compatible/, and the year's empty template, template.xlsx. The SDK editions have the folders in excel_reference/, without the compatible/ copies. The payroll year workbook and the IR8A helper stay where they were, in excel/ (or excel_reference/) itself.

  • A workbook covers its own year. Each year's workbook works out the months of that year, with the rules in force in them. For a period in another year it gives status 2 (no rule for the period), and the note on its status names the months the workbook covers: open the workbook of the same name in that year's folder, where your pack has one. A run that spans a year end, such as December and January, uses one workbook from each year's folder.
  • The same names every year. A program's workbook has the same name in each year's folder, such as sg_cpf.xlsx.
  • Much smaller files. The workbooks are now compressed, and each holds only its own year's rules and test rows, so each file takes much less space on your computer than before. The download itself is not smaller, because it holds a workbook for each year.

The payroll year workbook, sg.payroll_month and calls between programs

The payroll year workbook works out a year of monthly payroll in one Microsoft Excel workbook. It is in excel/ of the Monthly Payroll Pack, the Complete SME Suite and the Corporate & BPO Edition, and in excel_reference/ of the SME SDK and Engineering SDK Editions. The free pack doesn't have it. It needs Microsoft 365 or Excel 2024, and holds up to 200 people.

  • Enter what each person was due, and read off the rest. Once a year, and for each new hire, you enter the employer's name and each person's details. Each month you enter, for each person, the days to work and the days worked in a part month, the hours of hourly staff, overtime hours and overtime pay, pay items such as allowances, commission, bonus and director's fees, and deductions. The workbook works out basic pay, prorated for a month not worked in full, ordinary and additional wages, CPF with the year so far carried from month to month, the self-help group fund, SDL and net pay. A change to a person's salary, fixed allowances, work status or other standing details, entered in one month, carries to the months after and leaves earlier months as they were.
  • Check what you paid. Beside each person's figures you can enter what you actually paid in total pay, CPF, fund and net pay, and any difference is flagged. A month that can't be worked out, such as one with a fact missing, says why, and so do that person's later months, because the year so far can't carry past it.
  • Overtime is yours to enter, for now. The workbook doesn't yet work overtime out from hours. Each month's overtime goes on the row of the month it was worked, with whether it is paid with that month's pay or the next month's.
  • Payslips. The Payslip sheet shows one person's payslip for a month on one A4 page, with the employer's CPF for information, and the Payslips sheet prints every payslip of a month, a page each. A payslip shows no NRIC.
  • Figures for CPF EZPay (preview). For each month, the EZPay sheet lists what to key into CPF EZPay for each person paid, the CPF and fund EZPay should then show, and the month's SDL. EZPay works out CPF itself from the wages you key in, so compare its figures with these. The sheet is a preview: its field words and figures have not yet been compared with a real EZPay entry.
  • The year, and how a figure was reached. The Totals sheet adds up each person's year so far, and the Explain sheet shows each step behind one person's month.
  • Moving to a newer copy. If we send a newer copy of the workbook during the year, you copy your entries across block by block, as the Start sheet lists them. A newer copy never moves an entry cell, so each block goes back where it was.
  • What it doesn't do. Skedula files nothing: the workbook makes no file to upload, and you key the figures into EZPay yourself. It holds your employees' details, NRIC or FIN included, in the file on your computer, and Skedula receives none of them.

The figures come from a new program:

  • One person's month: sg.payroll_month. From the days or hours worked, the pay items and the deductions, it works out basic pay, ordinary and additional wages, CPF, the self-help group fund, SDL and net pay, and the year's ordinary and additional wages subject to CPF so far, to carry to the next month. It is in every language of the SDK editions, with its test vectors, in the workbooks and rule books of the Monthly Payroll Pack and the editions that include it, and in the free pack for the years the free pack covers.
  • Calls between programs. sg.payroll_month calls sg.ea_incomplete_month, sg.cpf_wage_class, sg.cpf, sg.shg and sg.sdl, and restates none of their rules. In the code, the steps of each program it calls are part of it, named after the call, such as cpf_ for those of sg.cpf, and its trace lists them so. In its rule book each call is one entry: the program that works it out, what it is given and what it gives back.
  • Two new outputs of sg.cpf. ow_ceiling is the month's Ordinary Wage ceiling as sg.cpf applies it, and spr_status_year is the year of SPR status in the pay period: 1, 2, or 3 from the third year, and 0 for a citizen or a foreigner. They come after its other outputs. In the C library this is an addition only: a program built against the earlier header keeps working with the new library.

The IR8A helper

The IR8A helper works out what goes in each box of Form IR8A and Appendix 8A, and marks what IRAS's Data Link-up pre-fills. It is a Microsoft Excel workbook in excel/ of the Year-End & Leavers Pack, the Complete SME Suite and the Corporate & BPO Edition, and in excel_reference/ of the SME SDK and Engineering SDK Editions. The free pack doesn't have it. It needs Microsoft 365 or Excel 2024.

  • From your payments to each box. You answer three questions about the employer, then enter each person you paid in the year, their payment totals by kind, such as salary, bonus, allowances and director's fees, and their benefits in kind. For each person the workbook gives the figure for each box of Form IR8A and each field of Appendix 8A. It uses the same rules as Skedula's other workbooks for the IR8A item of each payment, the value of benefits in kind and excess employer CPF.
  • What to do with each figure. If you are in AIS and on the Data Link-up, IRAS pre-fills some figures from CPF Board for staff who hold an NRIC. Each figure is marked by what IRAS pre-fills: check it against IRAS's figure, adjust IRAS's record to it, add it, or leave it for myTax to work out. IRAS pre-fills no figure for staff without an NRIC, nor for an employer outside AIS or off the Data Link-up.
  • One page per person. The Person sheet shows one person's figures box by box, in the order of Form IR8A, with what to do with each, and prints on one A4 page. Outside AIS, you copy the figures onto IRAS's Form IR8A. The Explain sheet lists the payments behind a box.
  • What it doesn't do. Skedula files nothing, and the helper makes no file to upload: you enter or check the figures in myTax yourself or, outside AIS, give each employee a Form IR8A. It doesn't cover share gains (Appendix 8B), tax borne by the employer, exempt income or amendments: for a person with share gains or tax borne by the employer it shows no figures, and says why. It asks for no NRIC or FIN number, date of birth or address.

The CPF EZPay contribution file (preview)

The writer, the checker, their test vectors and the integration kit come in the SME SDK and Engineering SDK ZIPs only. No other pack has them, the free pack included.

They are a preview: no file the writer makes has yet been uploaded to CPF EZPay. Until one is, the line ending and the order of characters in the sequence are our readings, and only CPF's upload confirms that a file is accepted.

  • Write the CPF EZPay file. The libraries of the SME SDK and Engineering SDK editions now write the CPF EZPay contribution file, the file an employer uploads to CPF EZPay, in all nine production languages: TypeScript, Python, PHP, Java, C#, C, C++, Rust and Haskell. The experimental COBOL has none. You pass each payment advice, with the month's figures from the CPF programs and each employee's CPF account number, name and employment status. The writer gives the file's name and records, or refuses the file and gives every reason. It never cuts, rounds or replaces a value.
  • Check a file before you upload it. The checker reads any EZPay file offline, also one another system wrote, and reports each problem with its code and its place in the file. Each rule names its source: the clause of CPF Board's published specifications it follows, or, for the size limit, CPF Board's article on uploading by FTP. A file the checker passes may still be rejected by CPF: only an upload confirms acceptance.
  • Size and sequence. The writer refuses, and the checker reports, a file over 2 MB, the limit CPF gives for uploading a file by FTP. The writer writes the advices and their records in the order CPF's specification lists, whatever order you pass the advices in, and the checker reports a record out of that order. The specification says only "ascending", so comparing characters in ASCII order, digits before letters, is our reading, to be confirmed when a file is first uploaded to CPF EZPay.
  • Tested byte for byte. Each language's writer and checker are tested against the reference writer and checker on the filing test vectors, vectors/filing/cpf_ezpay.filing.
  • In the kit. Each quick start shows the calls. The worked example in each language now ends by writing and checking the EZPay file for its example month, and kit/examples/expected.DTL holds that file's bytes. kit/TROUBLESHOOTING.md covers a refused file, line endings, records out of sequence and reading a file for the checker.
  • Line endings. The writer ends every record with CR LF. The specification names no line ending, so this is our reading, to be confirmed when a file is first uploaded to CPF EZPay. Save the file as bytes, and upload it in binary mode.

Two packs make the suite; upgrades, reminders, past downloads and payment disputes

  • Two packs make the Complete SME Suite. If you hold two SME Packs for the same year, you have the Complete SME Suite for that year: all three packs and the suite's download, at no extra charge. Each pack keeps renewing on its own, or being reminded if paid by PayNow, and you have the suite for each year both are paid for. If you stop one, you keep the other. If one is refunded or taken back in a dispute, the suite ends for its years, and we email you which packs you still have.
  • A purchase of what you already hold is refunded. If you order on the pricing page an edition you already hold for every year the order covers, such as a third pack while two packs make the suite, we refund it in full automatically, cancel its subscription and email you why. An order from October that also covers a year you don't hold yet is kept. The same goes for an upgrade that completes for an edition you already hold, and for a claim paid wholly with credit, which charges nothing: it is cancelled and your credit stays as it was. Each time a renewal is charged, the renewals charged for that year by then that you don't need for what you hold are refunded automatically, keeping the cheapest that give you the same. A purchase counts only for renewals charged after it and is never refunded this way, nor is a renewal that is credit towards an upgrade. A renewal in a payment dispute is decided when the dispute ends.
  • An upgrade keeps your prices. An upgrade in the Customer Portal no longer moves an existing subscription to the new edition. Paid by card, the new edition gets its own yearly subscription, with your credit taken off its first payment. Your subscriptions for the editions it includes keep their price and stop at their own renewal dates. Paid by PayNow, nothing renews the new edition, and we remind you before it ends.
  • A refunded upgrade switches your subscriptions back on. If an upgrade is refunded, the subscriptions it had set to end renew again where they can. One that renews again stops, at their own renewal dates, your subscriptions for the editions it includes, as an upgrade does, and they renew again if a refund or dispute later ends it. If one can't while you still hold its licence, we tell you once nothing else renews it or reminds you of it, and send whatever reminders are still to come before it ends. If you stopped one yourself after an upgrade or a pricing-page order set it to end, it stays stopped, and if you switched it back on yourself, it keeps renewing unless a payment dispute or a later order sets it to end. Once we have told you a subscription no longer renews, we don't switch it back on later. The exception is a later order of yours that takes it over: its confirmation says so, and if that order is refunded, the subscription renews again. If you stop the subscription of an upgrade or a pricing-page order that set another of yours to end, we don't email you that the other one no longer renews, and we don't send reminders for it: the subscription you stopped renewed it in its place.
  • An upgrade that ends with its credit is explained. If a payment is refunded or taken back in a dispute, and that ends an upgrade its credit paid for, we email you why. What is left of what you paid for that upgrade counts as credit toward the same edition, or one that includes it, in the same licensing cycle, or we refund it if you ask.
  • A purchase counts from the day you start it. The day in Singapore on which you open a checkout decides which years it covers and when it first renews, even if the payment completes the next day: a checkout started in September is a September purchase, one started in December a December purchase.
  • Up to three reminders. A purchase or upgrade that nothing renews, a Home Pack among them, now gets up to three reminder emails before its licence or cover ends, with every purchase that is due in one email, and the last one says it is the last. A card subscription you cancel gets none. The link in any reminder stops them all.
  • Past years stay available. The years you paid for stay available to download from the Customer Portal, also after your licence or cover ends. Updates still end with it.
  • Payment disputes can be undone. A question from your card issuer that takes no money back changes nothing. While a dispute is open, downloads for that payment are paused and its renewal is stopped. A renewal still being collected when the dispute opens is cancelled instead and not charged, whatever the dispute decides. If the dispute ends with the payment standing, both come back, unless the subscription reached its renewal date meanwhile or another of your subscriptions now renews that edition; then we tell you once nothing else renews it. If we can't switch a subscription back on ourselves before its renewal date, we tell you how to switch it back on in Link, which keeps the same subscription and price. If you stopped the subscription yourself while the dispute was open, it stays stopped.
  • A refund ends a renewal still being collected. If a payment is refunded in full while the renewal of its subscription is still being collected, that renewal is cancelled with the subscription and can't be paid afterwards. If it is charged all the same, we refund it.

The SME SDK Edition, the integration kit and the self-check

  • A new edition for your own payroll. The SME SDK Edition holds the same libraries, test vectors and reference material as the Engineering SDK Edition, in the same nine languages. Its licence covers the payroll of your own business and its group companies in Singapore. It does not cover distributing the code or running it as a service for others; for that, use the Engineering SDK Edition.
  • An integration kit. kit/ has a quick start for each language, a worked example for each language, a troubleshooting guide and a description of the results format. It is in both SDK editions.
  • A self-check. tools/skedula-check.py compares the results of your integration with the test vectors and prints a report of every difference. The report holds only the vector inputs, so you can send it to support instead of your code.
  • Version and change files. Every download now includes VERSION.txt and these release notes, so you can see which release you have and what changed.
  • A "what changed" page. The release notes are also on the website at /changes/, newest first, and support emails SDK customers when a release changes a rule or a rate.