Specifications – business validations of the Incomes Register
The Tax Administration in cooperation with other data users publishes business validations not included in the payroll report schema of the Incomes Register. Implementation of business validations is not mandatory. Implemented in payroll administration software, additional validations ensure that data users can use the information submitted to the Incomes Register as such.
Where should an IT developer start?
First you should read the documents included in the zip file (updated 25.06.2019):
- data user validations v1.062.xlxs
- documented schema v1.06.2.xsd
- schematron file v1.06.2.sch and XSLT file v1.06.2.xsl
- you can find the corresponding files of the previous version in the archives folder
The first three digits following the name of the file indicate the schema version in the Incomes Register, and the fourth digit stands for the number of versions created because of business validation changes.
Version 1.062, corrected and transferred to production:
- Incomes Register schema validation: The payer’s date of birth (BirthData) is mandatory information, if in the ‘Payer identifiers’ data group the user has not specified an identifier where the ‘Identifier type’ would be ‘Finnish personal identification number’ but has entered data in ‘First name’ and ‘Last name’. In the same validation, an error resulting from language selection has been corrected.
Version 1.061, corrected and transferred to production on 8 Nov. 2018:
- Incomes Register schema validation: If even one report included in the record specifies a payment type value (PaymentType) for reimbursement application data (ReimbApp) relating to a paid absence (PaidAbsencePeriod), record contact person details must be given, stating that Responsibility area = 1 (content issues) and specifying Name and E-mail address
- Determining of cash wages, used in lines 5 and 6 of the Tax Administration rules: Income type 101 = amount of cash wages. (Rule: The amount of cash wages is the same as the value of income type 101 or the total of income types 201–225, 227–237, 308, 309, 310, 313, 314, 316, 319, 326, 328, 332, 335–340, 351–356 and 359)
How can the IT developer make sure the data generated by the software is right for the data users?
- By implementing validations in the software, utilising the documents above.
- By testing the functionality of the validations in the checkup service on ilmoitin.fi or at the ApiTamo interface.
What should the IT developer decide or consider in advance?
- Some of the additional validations should preferably be implemented in the software so that they function when data is being entered. In an accounting firm, for example, it is easier for a person using the software to correct a typing error immediately rather than when the returns are ready to be submitted.
- Some of the checkups, however, can or must be carried out during the sending step. Those include checkups that cannot be carried out until all relevant data has been submitted.
- The ApiTamo interface can be accessed when data is being produced or when data is being transmitted to the Incomes Register. The checkups should be implemented so that they take place as close to the data production step as possible. This ensures that the data producer using the software does not need to edit a file generated by the software, and instead the software provides instructions in accordance with the validations to supplement and correct data directly in the software.
- The software can also generate material in line with the Incomes Register schema without any additional validations. In these situations the data producer should preferably be instructed to use the checkup service on ilmoitin.fi or to check alternatives provided by other TYVI service providers before transmitting the material generated by the software to the Incomes Register. In addition, the system should state that if data is not corrected before the transmission, the data user will probably ask for explanation later on directly from the data producer/filer.
How to act if you have questions about business validations
Questions about business validations of the Tax Administration and other data users
- ohjelmistotalot(at)vero.fi or
Questions about how the Tax Administration in the role of data user processes data received from the Incomes Register
- tax.fi - Tax reforms
- tax.fi chat
Questions about reporting to the Incomes Register
- incomesregister.fi chat
- technical observations from payers form
- testing: yht_tulorekisteri_testaus(at)vero.fi
In your message
- briefly describe the error and state the exact error message if you have received one (attaching a screen capture is a good idea)
- also briefly describe the process, i.e. how the file travels between the software, ilmoitin.fi and the Incomes Register
- state how ilmoitin.fi is used: for example, if ilmoitin.fi rejects the file, can it still be submitted to the Incomes Register or is this prevented?
- this shows us how critical the error is!
- state if you received the error from the ilmoitin.fi interface or the Incomes Register
- this helps us in troubleshooting and detecting whether the error is in ilmoitin.fi or the Incomes Register
Good to know!
- Some Kela validations can be found in the XSLT files (ZIP).
- Errors found by the checkup service are shown on the Payer's report reference (ReportId) level.
Business validation routines were transferred to the check-and-test environment of Ilmoitin.fi on 15 May. As of 27 September, checking is also available in the validation interface provided by Ilmoitin.fi. At present, applications can be programmed for testing the functionality of the validations at the Ilmoitin.fi interface, and also at the checkup interface (https://www.ilmoitin.fi/webtamo/sivut/Esittelysivu?kieli=en).
The Ilmoitin user interface:
- this is the recommended test environment for those who wish to run tests manually, before submittal, to make sure their payroll reporting meets the Tax Administration’s requirements (commercial software vendors or accounting firms)
The Ilmoitin validation interface:
- is recommended when a software application is being tested for the first time in order to ensure that its interface for data submittal works; the software application is expected to carry out an automatic check process – without secure login – on the data to be transmitted to the Incomes Register
The interface for data submittal:
- recommended for software that already contain a functional interface for submittal of data. Requires secure login even if the data will actually not be sent via this interface (i.e. data are sent via the Incomes Register interface). NOT recommended for software that has been created as new software to accommodate the new reporting to the Incomes Register.
Send questions and feedback to