Skip to content

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.5 sets 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/expressions library, 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 ​

Where scripts run in a recalculationFour steps. One: before-calculation scripts can change the rows. Two: row type scripts set the values of each row. Three: Salaxy calculates the salary with the Finnish pay rules. Four: after the calculation, scripts can set holiday accruals, holiday pay and pay statistics.1234Before calcadd or remove rowsRow type scriptsprice, count, data…Salaxy calculatesFinnish pay rulesAfter calcholidays, pay stats
Your scripts run in the light boxes; Salaxy's own calculation runs in the middle.

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.

ScriptWhat it changesPage
Before calculationThe whole list of rows: add, remove or change rowsBefore-calculation scripts
Row typeOne value of each row of a row type: price, count, message, data and moreRow type scripts
Holiday accruals, holiday pay, pay statisticsResults that are calculated from many calculationsAfter-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"] }
          ]
        }
      }
    ]
  }
}
  • code is the JavaScript source of all the classes.
  • metadata tells 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:

  • row or the current value: the thing the method may change.
  • ctx: the context. For a calculation it holds ctx.calculation, ctx.employment, ctx.settings (the company settings) and ctx.validation.
  • sxy: helper functions.
HelperWhat 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, lastThe calculation's rows of a row type.
sxy.rows.sum(rowType), countThe total (price × count) or the number of rows of a row type.
sxy.datesDate 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 undefined to keep a value. A method that returns undefined leaves the value as Salaxy calculated it.

Every page is also available as Markdown: add .md to its URL — a folder page such as white-label/ is white-label/index.md. Index for LLMs: llms.txt. Questions: Support.