Appearance
Custom payroll logic
Beta
Custom payroll logic is in beta. In the test environment, scripts run for every customer. In production, they run only for customers that Salaxy has turned the feature on for. Ask Salaxy before you plan a production customer on it.
Salaxy applies the Finnish pay rules for you. Some customers also need their own rules: a collective agreement with a special overtime price, a default row that must always be there, a company's own way of accruing holidays. For these, you write scripts: small pieces of JavaScript that Salaxy runs on its servers as part of the calculation.
- Simple rules are one line. For example,
sxy.prices.employment("hourlySalary") * 0.5sets the price of an overtime row to half the hourly salary. - Hard rules are full JavaScript. You can write classes, functions and helper methods.
- The types are TypeScript. The interfaces and helpers come from the
@salaxy/expressionslibrary, so an editor or a coding agent can check a script before it runs.
Accounting firms usually edit row type formulas in Salaxy Pro, on the customer's row types page, and test them there against a real employment. You can also write all scripts over the REST API, because they are part of the company settings.
When the scripts run
Salaxy recalculates a draft calculation each time you save or recalculate it, and sometimes when you load it and its values are out of date. A recalculation usually takes less than a second.
| Script | What it changes | Page |
|---|---|---|
| Before calculation | The whole list of rows: add, remove or change rows | Before-calculation scripts |
| Row type | One value of each row of a row type: price, count, message, data and more | Row type scripts |
| Holiday accruals, holiday pay, pay statistics | Results that are calculated from many calculations | After-calculation scripts |
Most rules are row type scripts. Use a before-calculation script only when you must change the list of rows itself.
Where the scripts are stored
Before-calculation and row type scripts are stored in the company settings, in calc.bleConfigs. Each entry is one set of scripts with the rules for when it applies:
json
{
"calc": {
"bleConfigs": [
{
"description": "Overtime rules of our collective agreement",
"disabled": false,
"cbaCode": null,
"employeeGroup": null,
"startDate": null,
"endDate": null,
"scripts": {
"code": "class Overtime { price(row, ctx, sxy) { return sxy.prices.employment(\"hourlySalary\") * 0.5; } }",
"metadata": [
{ "interface": "rowTypeScripts", "class": "Overtime", "methods": ["price"] }
]
}
}
]
}
}codeis the JavaScript source of all the classes.metadatatells Salaxy which class implements which script interface, and which of its methods to call. Salaxy calls only the methods you list here.- When it applies. For each calculation, Salaxy uses the first entry that is not disabled and matches the employment's collective agreement (
cbaCode), its employee group (employeeGroup) and the payment date (startDate,endDate). An empty rule matches everything. Put the most specific entries first.
The after-calculation scripts are stored in the holiday and pay statistics settings. See After-calculation scripts.
To write the settings, use the read, change and post round trip of company settings: post the whole settings object back, not only calc.
What a script gets
Each script method gets three arguments:
rowor the current value: the thing the method may change.ctx: the context. For a calculation it holdsctx.calculation,ctx.employment,ctx.settings(the company settings) andctx.validation.sxy: helper functions.
| Helper | What it does |
|---|---|
sxy.prices.employment(rowType) | The price of a row type in the employment. If the employment has none, the company's price. |
sxy.prices.company(rowType) | The price of a row type in the company settings. |
sxy.prices.standardHourlySalary(factor) | The employment's hourly salary that is valid on the work date, times factor. |
sxy.prices.averageHourlyPay(factor, period) | The average hourly pay of the last quarter or month, or the standard hourly salary if it is higher, times factor. |
sxy.prices.round(value, decimals) | Rounds a number; two decimals by default. |
sxy.rows.get(rowType), first, last | The calculation's rows of a row type. |
sxy.rows.sum(rowType), count | The total (price × count) or the number of rows of a row type. |
sxy.dates | Date helpers. |
A row type argument is a row type name such as "hourlySalary", or a function that selects rows: (r) => r.rowType === "hourlySalary".
Errors and limits
- A script error stops the save. If a script throws an error, Salaxy does not save the calculation and returns the error message. Test new scripts on a test customer first.
- Scripts run in a sandbox. Salaxy limits the memory, the number of statements, the recursion depth and the run time of each script. A script cannot call the API or read other customers' data.
- Return
undefinedto keep a value. A method that returnsundefinedleaves the value as Salaxy calculated it.

