Payroll Script
Introduction
In the previous chapter, we talked about the payroll Entry Code and how to configure it in Adonis.
Now we are going to talk about the Payroll Script as an essential part of any complex Entry Code.
The purpose of a script is to allow the user to make complex payroll calculations based on various conditions, considering numerous fields that exist in the APM application.
Location and general characteristics
All the scripts are located under Payroll > Scripts Editor.
Here you can:
Add new Packages and Scripts;
Export/Import existing Script Packages;
Add content to the newly created Payroll Scripts or edit the existing ones etc.
Script Package Description
All payroll scripts are logically grouped into packages and you can add as many script packages into the system as you need. Each package consists of a maximum of 999 scripts.
Script package is a text file containing small sentences written in Basic, normally used for Payroll calculations.
Each package has (.DEF) file format and can be exported/ imported out/into the system. The DEF file can be freely opened and adjusted with the help of Windows Notepad.
Commonly we have one package for all the Entry Code scripts and one for the sub-scripts.
The structure of the script package file
Let’s take PWSCRADO.DEF package as an example.
1) PWSCRADO.DEF – is a file name where PWSCR is used to identify that this is a package, the following text before the dot is script package Code (ADO in this case) and (.DEF) is definition of the file format.
2) The inside of the package is as follows:
#####001þ???????? Is the structure for the first line of a script.
#####001 means the number of the script, while þ???????? is the name (e.g. #####001þBasic Wages)
Components & Operators
Each payroll script should follow certain system rules and have a specific structure. There is also a limited number of operators and fields that can be used in the script.
To view all the fields that can be used in the payroll scripts, use the following URL:
https://adonishr.atlassian.net/wiki/spaces/KB/pages/3205562565
½ Simple arithmetical conditions
The Payroll script works with basic arithmetic operations such as addition, subtraction, multiplication, and division.
The below table will give you an overview of all the operators that are supported in the APM script, along with an example of its usage.
Operator | Description | Example of use |
= | to say that parameter 1 equals to parameter 2 (the position of the parameter matters) | L61=L21 |
< | to identify that parameter 1 is less than parameter 2 | L21<PR1 |
> | to identify that parameter 1 is greater than parameter 2 | L21>PR1 |
+ | to plus the values of parameter 2 with parameter 1 | L61=L21+PR1 |
- | to deduct the value of parameter 2 from parameter 1 | L61=L21-PR1 |
* | to multiply parameter 1 with parameter 2 | L61= L21*GB1 |
/ | to divide parameter 1 by parameter 2 | L61= L21/GB2 |
() | to separate the condition into a separate clause | L61=(GB1/30)+PR2 |
[] | to round the amount withing those brackets +0,5 is usually added to round to whole/integer number To round the amount to 2 decimals the expression can be multiplied by 100 and divided by 100 (for 1 decimal - by 10 etc) | L61=[((GB1/30)*L22)+0,5]
L61=[((GB1/30)*L22)*100+0,5]/100 |
"" | All the plain text values should be put into quotes. Numbers can be used without the quotes. Empty value can be identified with "" without a space between them. | H1="SAIL" L21="" |
// | Any line starting with // will be considered as a comment line. (the commented part of a script will be inactive) | //this is a test script // L61=L21 |
If-clause
A simple script may contain lines where one value equals another, without special conditions applied.
Example: L23=H1 |
However, such an approach doesn’t always help to solve complex calculation problems.
For this purpose, we use an “if-clause”.
“If-clause” is a conditional statement that, if proved true, performs a calculation function within the script. It consists of a conditional clause and the consequence.
Let’s take a closer look at the below table to get more understanding:
Operator | Description | Example of use |
IF | to identify the start of the condition clause | IF PR1<>0 |
THEN | to identify the result of the condition clause | THEN L21=(PR1/30)*L22 |
ENDIF | to identify the ending of the condition clause | ENDIF |
AND | to add several equal parameters to the IF clause The clause will work only if all the conditions are true. | IF PR1<>0 AND H1=”SAIL” THEN L21=(PR1/30)*L22 ENDIF |
OR | to add several equal parameters to the IF clause The clause will work if at least one of the conditions is true. | IF H1=’SAIL’ OR H1=’LEAVE’ THEN L21=(PR1/30)*L22 ENDIF |
Reference to a sub-script
Operator | Description | Example of use |
@@ | to make a reference to another script | @@ADO:005 |
In APM it is possible to include one script within another.
When the subscript is added, it will be calculated based on its position within the main script and affect the result of the calculation.
The sub-scripts are usually added when some part of the script should be repeated in several main scripts, making it easier to modify it. An example of a sub-script can be a script for department, nationality, rank, employer calculation, etc.
Functions
It is possible to use functions within the scripts that calculate needed value based on hardcoded formulas.
Here are the functions that we have so far.
Function | Description | Example |
|---|---|---|
IncDateBy (Date: String; Type: String; NumberOf: Integer): String | The function converts the date calculations (made in days) into a text format. Returns a date shifted by a specified number of days or months or years.
| L25=IncDateBy (P603a,"d",W2) - can be used to show the date that corresponds to Current period start date (P603a) + nr of days ("d") defined by internal accumulator W2. E.g.: P603a=20210101 |
Application and usage
The main purpose of a script is to be used for payroll calculations. The script thus needs to be linked to a corresponding Entry Code under the Entry Code Maintenance > Calculation tab.
The script can also be used in other places within APM, but to do this it is necessary to input the formula of the following pattern @@ADO:005 where:
Component | Description |
@@ | script package identifier |
ADO | script package code |
: | Separator (between script package code and the order number of a script) |
005 | script number in the package PWSCRADO.DEF (always 3 digits) |
! (optional component) | @@!ADO:005 is used to tell the script object to return a result as integer. If the result is in decimals, then the system truncates it to integer. |
We can refer to a script with the above formula in:
Leave factor field at any level (Individual, Payscale Table/Code, Company, Activity).
In any field under Entry Code Maintenance -> Entry code details -> Input, Calculation, Pay slip, Accumulators tab.
Inside one payroll script to refer to another script (so-called sub-script).