Odoo Payroll — Payroll for Dolibarr

Summary: management of payroll rules and structures, payroll contracts, and payslips for Dolibarr internal users.
Module version: 1.0.0
Declared minimum Dolibarr version: 18.0
Declared minimum PHP version: 7.4
Versions actually verified: no Dolibarr or PHP version was tested during this documentation review.
Last reviewed: 2026-09-29

Publisher’s official website: 01 Consulting

Demonstration video:

1. Overview

Odoo Payroll is a native payroll module for Dolibarr, developed by 01 Consulting. Despite its name, it is installed in Dolibarr and does not require an Odoo instance. It lets administrators configure salary categories and rules, group them into structures, assign these structures to employee contracts, and calculate payslips.

The engine provides a configurable calculation framework; it does not guarantee compliance with any legislation, collective agreement, tax scale, or social contribution schedule. CNAS, IRG, and other applicable statutory rules must be designed and approved by a payroll specialist before production use.

2. Features

Salary rule categories, which can be organized hierarchically.
Salary structures containing rules and optionally inheriting from a parent structure.
Conditional rules with fixed amounts, percentages, or controlled arithmetic formulas.
Contracts linked to Dolibarr users, with salary, weekly hours, dates, contract type, and department.
Payslip line calculation, gross and net totals, validation, and status tracking.
Individual payslip creation and batch generation for multiple employees.
Moving a validated payslip back to draft, canceling validated payslips, and mass actions, subject to permissions and settings.
PDF payslip generation and integration with Dolibarr’s native salary payment workflow.
A Payroll tab on user cards, Dolibarr import profiles, and filtering by the active entity.

3. Requirements and compatibility

Dolibarr: the module descriptor declares Dolibarr 18.0 as the minimum version. The version actually verified for this wiki is “none”.
PHP: the descriptor declares PHP 7.4 as the minimum; no runtime testing was performed during this review.
Required Dolibarr modules: Users (modUser) and Salaries (modSalaries).
Database: initialization creates triggers using MySQL/MariaDB syntax. Compatibility with other SQL database engines has not been established. The database account must be able to create and drop triggers.
Documents: the generation process must be able to create files in the module’s output directory under Dolibarr documents.

4. Installation, update, and deactivation

4.1. Installation and activation

Check that Dolibarr’s Users and Salaries modules are available.
Install the module directory in htdocs/custom/payroll, or in the custom directory configured for external modules.
In Dolibarr, open Home > Setup > Modules/Applications, find Payroll, and enable the module.
On activation, the module loads its SQL tables, adds certain missing contract columns, adds a salary extra field for linking a payslip, and attempts to create three triggers on salary tables.
Check that HRM > Payroll appears and the setup page opens. Before processing real payroll, run a complete calculation with test data and verify the PDFs and payment triggers.

Activation also installs menus, permissions, and import profiles. If trigger creation fails, automatic status changes associated with payments will not work correctly; review the database error and Dolibarr logs.

4.2. Updating

Back up the Dolibarr database and documents before replacing module files.
Install the updated files. Deactivate and reactivate the module if initialization of new tables, columns, or triggers needs to run again.
Review existing categories, rules, contracts, and payslips, and check the triggers on salary tables.
Generate a test payslip, open its PDF, and verify the output path and user permissions.

The activation script checks for and adds certain missing contract columns, then makes the rule category mandatory after attempting to assign a category to orphaned rules. Migration details depend on the previous version and existing schema; back up the database before proceeding.

4.3. Deactivation and removal

Deactivation hides the salary-to-payslip linking extra field and removes the three triggers created by the module. The deactivation process does not delete the payroll tables. The effects of manually removing the tables or module directory have not been established; do not delete this data without a backup and a defined migration procedure.

5. Configuration

Open the module’s Setup page in Dolibarr. Access is limited to administrators and users with the payroll->setup permission. The values below are the module’s declared initial values or the fallbacks used by the page; a value already saved for an entity may differ.

Setting	Initial value or fallback	Effect
Payslip numbering	Standard model; declared mask `PSL{00000}`. The page falls back to `PAY{00000}` if no mask is saved.	Sets generated payslip references. Check the value shown in Setup after installation.
Contract numbering	Standard model, mask `CTR{00000}`.	Sets contract references.
`PAYROLL_ALLOW_CANCEL_CONFIRMED_PAYSLIPS`	Disabled (`0`).	Allows a validated payslip to be returned to draft or canceled.
`PAYROLL_CONFIRM_PAYSLIPS_WITHOUT_RECOMPUTING`	Enabled (`1`).	Prevents automatic recalculation during validation. When disabled, validation recalculates the payslip.
`PAYROLL_ALLOW_EDIT_PAYSLIP_LINES`	Disabled (`0`).	When enabled, allows selected fields on draft payslip lines to be edited manually.
Default bank account	None.	Value proposed in the payment workflow; this setting is shown when the Bank module is enabled.
Default payment method	None.	Payment method proposed in the salary payment workflow.
Contract types and departments	Dictionaries managed in Setup.	Add active codes and labels; an entry used by a contract cannot be deleted.

Numbering masks must contain at least four zeroes inside braces, for example PAY{00000}. Available numbering models can be selected on the Setup page. Configuration constants are saved for the current Dolibarr entity.

6. Preparing payroll configuration

6.1. Categories

In HRM > Payroll > Salary Rule Categories, create a category with a code and label.
Optionally choose a parent category to organize the hierarchy.
Enable or disable the category according to its use.

Codes are used in formulas as category totals prefixed with CAT_, for example CAT_BASIC. A code used in a formula must follow the characters accepted by the page and import profiles.

6.2. Salary structures

In Structures, create a structure with a reference and label.
Link rules to the structure and set their sequence order.
Optionally select a parent structure. The engine loads rules linked to the structure and its chain of parent structures.
Save the structure and assign it to a contract.

A structure referenced by a contract or child structure is protected from deletion by the module’s dependency checks.

6.3. Salary rules and calculations

A rule has a code, label, category, sequence number, condition, and computation type. Only active rules linked to the structure are loaded. Rules are calculated in ascending sequence order; rules already calculated are available by their code to later rules.

Always true: applies the rule without an additional condition.
Range: compares the salary with configured minimum and maximum values; both endpoints are inclusive.
Expression: evaluates a condition such as WAGE >= 90000.
Fixed amount: configured amount multiplied by the quantity expression; the model’s default quantity is 1.
Percentage: applies a rate to a base expression; a negative percentage can represent a deduction.
Formula: evaluates a configured arithmetic expression.
Show on payslip: controls whether the corresponding line appears in the PDF.

The engine accepts numbers, variables, parentheses, and the + - * / operators. Comparison operators >, >=, <, <=, ==, and != are accepted in a condition. It does not execute PHP, Python, or arbitrary functions. An unknown variable, invalid operator, or division by zero stops the calculation with an error.

Variable	Value used	Example
`WAGE`	Salary from the contract linked to the payslip.	`WAGE`
`WORK_HOURS`	Contract’s weekly hours.	`WAGE / WORK_HOURS`
`WORKED_DAYS`	Worked days entered on the payslip.	`WAGE * WORKED_DAYS / MONTH_DAYS`
`MONTH_DAYS`	Weekdays, Monday through Friday, in the payslip period.	`WORKED_DAYS / MONTH_DAYS`
Earlier rule codes	Amount calculated by an earlier rule in sequence order.	`BASIC + PRIME`
`CAT_CODE`	Calculated total for a category; an empty total starts at zero.	`CAT_BASIC + CAT_ALW + CAT_DED`

MONTH_DAYS does not exclude public holidays: only Saturdays and Sundays are excluded. Formula examples illustrate syntax and are not recommended payroll scales.

Gross and net totals are taken from rules with the codes GROSS and NET. If these rules do not provide the totals, the engine falls back to categories with those codes.

6.4. Contracts

In Contracts, create a contract for an internal Dolibarr user.
Enter the structure, salary, weekly hours, start date, and, if applicable, end date.
Optionally select a contract type and department from the configured dictionaries.
Save and activate the contract if it should be offered for batch generation.

A contract must have an employee and a start date. The module’s forms and classes prevent deleting certain referenced records, including a contract linked to payslips.

7. Managing payslips

7.1. Create and calculate an individual payslip

Open HRM > Payroll > Employee Payslips, then create a payslip.
Select the employee and contract, set the period, and enter the number of worked days. Creating a payslip requires payroll->write.
Save the payslip; it starts in Draft status.
Click Compute. Calculation requires a contract and an available salary structure. If no structure is saved on the payslip yet, the contract’s structure is assigned to it.
Review the lines, gross, and net amounts. While the payslip is a draft, correct the configuration or data and compute it again.
Validate it with a user who has the payroll->validate permission. Review the result before validation because the initial setting prevents recalculation at this step.

If the period is reversed, a contract or structure is missing, a variable is unknown, or an expression is invalid, calculation displays an error and must not be treated as complete.

7.2. Generate payslips in a batch

Open HRM > Payroll > Payslip Batches and create a batch with a label and valid period.
On the batch card, run Generate. The module selects active contracts with a structure whose dates overlap all or part of the batch period, and for which the batch does not already contain a payslip.
The module creates one draft per eligible contract with 22 worked days, then attempts to compute the batch’s draft payslips. Review and correct worked days if the actual situation differs.
Review calculation errors and correct the affected contracts, structures, or rules before validation.
Validate the batch payslips. The action is refused if there are no drafts or if a draft has no calculated lines. When validation succeeds, the batch is closed.

Running generation again in the same batch does not add a second payslip for a contract already included in that batch. This check is by contract and batch; it does not generally prevent two separate batches from covering the same period.

7.3. Statuses, returning to draft, and cancellation

Draft (0): can be computed and deleted individually; lines can be edited if PAYROLL_ALLOW_EDIT_PAYSLIP_LINES is enabled.
Validated (1): status reached after validation. Whether validation recalculates the payslip depends on the setting described above.
Paid (2): status associated with the Dolibarr salary payment when the payslip is linked to the corresponding salary.
Canceled (9): canceled payslip status.

When PAYROLL_ALLOW_CANCEL_CONFIRMED_PAYSLIPS is enabled, a user with validation permission can return a validated payslip to draft, cancel it, and use the Set to draft mass action from the payslip list. The mass action only processes selected validated payslips. The individual action checks the permission and setting before changing the status; review the payslip and any linked salary before using it.

A paid payslip must not be treated like an ordinary validated payslip: salary synchronization may change its status, and a batch cannot be reopened or deleted if it contains paid payslips. Individual payslip deletion is limited to drafts and also deletes their calculation lines.

7.4. Reopen or delete a batch

A closed batch can be reopened by a user with validation permission if none of its payslips are paid. Reopening returns the batch’s validated payslips to draft. Deleting a batch requires delete permission and deletes the batch, its payslips, and their lines; deletion is refused if a paid payslip is present. This deletion is permanent: review the list shown in the confirmation before proceeding.

8. Employee card, payment, and PDF

8.1. Employee Payroll tab

The module adds a Payroll tab to user cards. A user with Payroll read permission can view the tab; an employee can also open their own card. The tab lists that employee’s contracts and payslips. Creation buttons depend on the payroll->write permission. The page filters results by the active Dolibarr entity.

8.2. Link a payslip to Dolibarr’s native salary payment

When activated, the module adds an extra field to a Dolibarr salary for selecting a paid payslip belonging to the same employee. A constraint prevents linking the same payslip to multiple salaries. The SQL trigger synchronizes the payslip status when the salary’s paid value changes: it changes the linked payslip from validated to paid when the salary is marked paid, and back to validated when the salary is marked unpaid.

The Dolibarr trigger associated with creating a salary payment also sets the linked payslip status to paid. These automations depend on the extra field, the selected link, and successful trigger installation.

8.3. Generate and view the PDF

Open the payslip card and start document generation.
The module produces an A4 PDF showing the company, employee, status, contract, structure, period, worked days, visible lines, and gross/net totals.
Rules marked “show on payslip” are included; other rules are omitted from the detailed table.
The PDF is saved in the module output directory for the active entity, or, if none is configured, in DOL_DATA_ROOT/payroll, inside a directory named after the payslip reference. The card can then display or download it.

Generating the PDF again writes to the same payslip reference. Existing documents are not automatically deleted when the payslip status changes.

9. Menus, permissions, and visibility

Dolibarr permission	Purpose
`payroll->read`	View the dashboard, payslips, batches, and documents; access help; grants read access to several lists.
`payroll->setup`	Configure categories, rules, structures, contracts, and settings. Administrators also have access to setup.
`payroll->write`	Create and edit payslips, contracts, and batches according to each page’s checks; run calculations.
`payroll->validate`	Validate payslips; subject to the setting, return or cancel validated payslips; validate or reopen batches.
`payroll->delete`	Delete records allowed by their status and dependencies.

Category, rule, structure, and contract menus are under HRM > Payroll and require the setup permission. Access to payslips and batches requires read permission; creation requires the corresponding write permission. Native Dolibarr permissions for Users and Salaries are also relevant.

10. Data, imports, triggers, and logs

Stored data: categories, rules, structures, structure-rule links, contracts, payslips, calculation lines, and batches in module tables; the payslip link is stored in an extra field on the Salary object.
Imports: import profiles are declared for categories, rules, structures, and structure-rule links. Contracts and payslips are not listed among the import profiles in the module descriptor.
SQL triggers: one trigger synchronizes certain status changes between the paid salary and linked payslip. Two other triggers prevent a payslip from being linked to different salaries.
Dolibarr trigger: when a salary payment is created, the module sets the linked payslip to paid.
Observed technical log: the payment trigger writes timestamps, salary identifiers, SQL results, and error messages to /tmp/payroll_debug.log. The module does not manage this file’s rotation, retention, or permissions; the server administrator should review them.
Files: generated PDFs are written under the module document output directory described in the PDF section. The module descriptor declares no scheduled job or purge policy for payslips, payroll data, or PDFs.
Multi-entity: operations and lists are filtered by the active Dolibarr entity; configuration constants are saved for that entity.

11. Troubleshooting

Symptom	Checks
The Payroll menu or a page is inaccessible.	Check that the module is enabled, the user has the required Payroll permission, and the native Users and Salaries modules are enabled.
Calculation does not start or returns an error.	Check the employee, contract, structure, dates, active rules, sequences, and expression syntax. An unknown variable or division by zero stops calculation.
Validation does not update the amounts.	The initial setting disables recalculation during validation. Recompute the draft first or change this setting according to the payroll procedure.
The batch generates no payslips.	Check the batch period and whether active contracts have a structure and overlap the period. Also check whether a payslip for the contract already exists in this batch.
Batch validation is refused.	Each draft must have at least one calculated line. Recompute or correct the indicated payslips before retrying validation.
The payslip selection field is missing from a salary.	Check module activation and whether the extra field was installed/enabled on the Salary object. Reactivate the module if needed, with sufficient SQL permissions.
The paid status does not follow a Dolibarr payment.	Check that the payslip is linked to the correct salary, that triggers are installed, and review Dolibarr logs and `/tmp/payroll_debug.log`.
The PDF is missing or cannot be opened.	Check the web server’s write access to the output directory and whether the document exists. Review the error message and Dolibarr logs.

12. Limitations and precautions

Have all payroll formulas reviewed by a specialist familiar with the applicable legislation before processing real salaries.
MONTH_DAYS excludes Saturdays and Sundays but includes public holidays; it does not use a leave calendar.
With the initial configuration, validating a payslip does not recalculate it. Review the lines and recompute explicitly before validation if the data has changed.
Batch generation initially uses 22 worked days for each payslip it creates. Adjust this value to the actual situation before validation.
Returning a payslip to draft or canceling it depends on a setting that is disabled by default. Coordinate status changes for payslips linked to salaries with Dolibarr’s accounting and payment tracking.
Deleting a batch deletes its payslips and calculations unless a paid payslip blocks the operation. Review the batch before confirming deletion.
Automatic status synchronization depends on MySQL/MariaDB triggers and database permissions to create triggers; compatibility with other database engines remains unconfirmed.

13. Support

When reporting a problem, provide the module version, Dolibarr and PHP versions, affected entity, reproduction steps, and an error message with names, salary amounts, and other personal data removed. The module is published by 01 Consulting. No support email address was found in the reviewed module files.