How to import the payroll history from the previous program

What is it for?

When a company changes payroll program part-way through the year, fiscaldoo needs to know how much has already been paid to each employee so that the annual statement of income and withholdings to the employee is right. This assistant reads the file exported by the previous program, with employees, contract versions and payslips, validates it line by line and imports only the valid lines.

The imported payslips are read-only, marked as coming from the previous program. Nothing is recalculated, no DMR or Social Security return is generated for the past, and no journal entry is created (the accounting comes from the migrated ledger).

When to use it?

• When the company starts processing payroll in fiscaldoo after having already paid salaries in the same year or in previous years, and needs those payslips for the annual totals.
• To have the previous program's payslips at hand, for consultation.
• Do not use it to process new payroll: see Payslip.
• Do not use it for health, trade union membership or strike data: a file with columns, keys or pay items of those types is refused entirely. Union dues go in as a pay item of type union.

Where to find it?

Payroll › Configure › Migration › Import payroll history. The imported payslips are looked up in Payroll › Close and review › Payslips of the previous software.

Before you start

• Your profile is Payroll Administrator (or Administrator). No other test profile creates an import or sees this entry. Pending validation by a certified accountant: who should be able to import the payroll history.

• You have the file exported by the previous program, in JSON or CSV (UTF-8). Dates as AAAA-MM-DD; amounts with a point or a decimal comma, at most 2 decimals, without a thousands separator; nothing is rounded. Each employee has ref (the key in the previous program), name, vat (tax number, NIF), admission_date; each version, effective_date and wage; each payslip, ref, period_start, period_end, payment_date (decides the year of the annual statement) and the five totals gross, ss_worker, ss_employer, irs, net (write 0 when there is no amount). The file fields, with an example of made-up data:

  Field	What it is	Example
  employees	List of employees; each one has the following fields	1 employee
  ref	Employee key in the previous program	W1
  name	Employee name	Teresa Exemplo Lima
  vat	Tax number (NIF)	245987657
  niss	Social Security number (NISS)	12345678901
  department	Department	Administrativo
  admission_date	Hire date	2022-03-01
  versions	Contract versions; each one has effective_date and wage	2 versions
  effective_date	Date from which the version applies	2022-03-01 and 2024-01-01
  wage	Wage of the version	1000.00 and 1100.00
  payslips	Payslips; each one has the following fields	2 payslips
  ref	Payslip key in the previous program	2025-11 and 2025-12
  period_start	Start of the period	2025-11-01 and 2025-12-01
  period_end	End of the period	2025-11-30 and 2025-12-31
  payment_date	Payment date	2025-11-28 and 2025-12-29
  gross	Gross total	1100.00
  ss_worker	Employee Social Security	121.00
  ss_employer	Employer Social Security	261.25
  irs	Personal Income Tax (IRS) withheld	90.00
  net	Net	889.00
  lines	Payslip pay items; each one has code, name, kind and amount	On payslip 2025-11: 100, Vencimento, earning, 1100.00

  The complete example, in JSON, is in this sample payroll history file, which you can download and use as a template.

  The pay items (lines) are optional; the type of each one is earning (earning), deduction (deduction), union (union dues) or employer_cost (employer charge).

• An employee who already exists with the same tax number is linked to the file and is never changed. An employee without a valid NIF or NISS is not refused: they go in as history, flagged “Tax number to fix”, and do not go into any return.

How to use it

1. In Import payroll history, click New. Fill in the Previous software (the name and version, for example “Programa de salários anterior 12.3”; it goes on every payslip) and choose the File (CSV or JSON). Click Validate.
2. Nothing is saved at this step. The report says “5 rows: 5 valid, 0 rejected, 0 already there.” and lists, per line, the Type (employee, contract version or payslip), the Reference in the origin, the Result (Valid or Refused) and the reason. Check the number of payslips against the previous program and click Import.
3. At the question “Import the valid rows? The payslips are created read only and cannot be changed afterwards.”, click Confirm.
4. The batch changes to Imported and no longer has buttons: it is history, it cannot be changed or deleted.
5. Open Payslips of the previous software to look them up: employee, period, payment date, gross, employee Social Security, IRS withheld and net, with the name of the previous program. Open a payslip to see the totals and the pay items “tal como o programa anterior os emitiu” (as the previous program issued them); the warning “This record is already closed (validated, approved, paid or sent), so it can no longer be changed. To correct it, use the actions of the document: cancel it or create a correction.” appears. These payslips have no cancel or correction actions, for any profile: if an imported payslip is wrong, talk to the certified accountant.

Expected result

• In the demo, the sample file created 1 employee (Teresa Exemplo Lima), 2 contract versions (€1,000.00 from 01/03/2022 and €1,100.00 from 01/01/2024) and 2 payslips of €1,100.00 gross, €121.00 Social Security, €90.00 IRS and €889.00 net, for November and December 2025.
• The payslips are read-only and go into the annual statement to the employee for the year of the payment date (here, 2025). Pending validation by a certified accountant: confirm that the employee's annual totals, combining the imported payslips with those of the new program, match the annual statement.
• The imported payslips count in the cost of the Human resources report, except in months in which the employee already has a closed payslip in fiscaldoo.
• Importing the same file again duplicates nothing: in the demo, the validation said “5 rows: 0 valid, 0 rejected, 5 already there.”

Important notes

An imported batch cannot be undone

Imported payslips cannot be changed or deleted. Validate first, check against the previous program and only then click Import.

• The assistant does not recalculate anything: net, IRS and Social Security stay as they came. If there are pay items, the report may flag “totais não batem” (totals do not match) when gross minus Social Security, IRS and deductions is not equal to net: it is for information only.
• Contract migration (Payroll › Configure › Migration) does not import anything from another program: it is an internal product step, which converts old contract versions to Odoo contract versions. Run in the demo, it shows “Legacy versions 0”, “Native versions created 0” and “Already migrated 0”. Pending validation on screen: what Contract migration does with existing old versions, because the demo has none.
• The CSV format (one line per pay item) exists, but was not proven in this demo. Pending validation on screen: importing the payroll history in CSV.

Common problems

Refused lines

• Symptom: the report says “8 rows: 5 valid, 3 rejected, 0 already there.” and each refused line gives the reason. In the demo, in a test file:

  Line	Reason
  Version with wage 1100.999	“The wage "1100.999" of the version of 01/01/2024 of Paulo Exemplo Faria is not an amount (at most 2 decimals, not negative).”
  Payslip with net equal to abc	“The amount "abc" of “net” in the payslip Paulo Exemplo Faria / 2025-11 is not valid. Every total is required, with at most 2 decimals (write 0 when the origin had none).”
  Payslip without payment_date	“The dates of the payslip Paulo Exemplo Faria / 2025-12 are not valid: period start, period end (not before the start) and payment date, all as AAAA-MM-DD.”

• What to do: correct the file and validate it again. You can also import only the valid lines and add the others in a new file: those already imported show as “already there”.

Employee without a valid tax number

• Symptom: an employee with tax number 123456789, which fails the check digit, is Valid and is flagged “Tax number to fix” in the report.
• What to do: after importing, correct the NIF on the employee record (Workers with a tax number to fix). Until you correct it, their payslips do not go into the annual statement.

Empty file or invalid JSON

• Symptom: with a file with no employees, the “Invalid Operation” window says “The file is empty or has no workers. Upload the export of the previous software (see the format in the module's documentation) and validate again.” With a truncated JSON: “The file is not valid JSON: Expecting value: line 2 column 1 (char 18). Correct it and upload it again.” (the technical part comes in English). A file that is not UTF-8 has its own message, which was not triggered.
• What to do: export the file again in UTF-8, check that the JSON opens and closes all braces and validate again.

Empty import list

• Symptom: “No import of payroll history yet. Traga os trabalhadores, os contratos e os recibos do software usado antes: carregue o ficheiro CSV ou JSON, valide para ver o que liga e o que é recusado, e importe. Os recibos ficam só de leitura.” (bring in the employees, contracts and payslips from the software used before: load the CSV or JSON file, validate to see what matches and what is refused, and import; the payslips stay read-only).
• What to do: click New.