Skip to content

Basic Payroll

Jump to bottom
Jani Giannoudis edited this page Jul 31, 2023 · 29 revisions

Basic Payroll Example

This example shows how to set up and test a payroll for a company that pays its employees monthly. The sample data is located in the installation folder Examples\StartPayroll. Please make sure that the Backend-Server of the Payroll Engine is available.

Payroll Model

The Payroll Engine calculates the salary with the following objects.

Payroll Model

The employees of a tenant are assigned to one or more divisions. The payroll runs refer to a division, so that an employee can be accounted for from different divisions.

Payroll Setup

The salary calculation can be done in three ways:

  • HTTP Rest API queries with a tool, e.g. Postman
  • Console/JSON - text editor, e.g. VS Code and transfer with the Payroll Console
  • Interactive with the web application (requires the Web Application Server)

The following steps describe how to set up the start payroll:

Step JSON Web Application REST Endpoint
Set JSON schema 02 - -
Set object creation date 03 - -
Add Tenant 05-95 Tenants > Add 1) CreateTenant
Add User 08-15 Users > Add CreateUser
Add Division 18-20 Divisons > Add CreateDivision
Add Employee 23-30 Employees > Add CreateEmployee
Add Regulation 33-75 Regulations > Add CreateRegulation
Add Case 36-54 Regulation > Cases > Add CreateCase
Add Case Field 42-52 Regulation > Case Fields > Add CreateCaseField
Add Collector 57-63 Regulation > Collectors > Add CreateCollector
Add Wage Type 66-73 Regulation > Wage Types > Add CreateWageType
Add Payroll Layer 82-85 Payroll Layers > Add CreatePayrollLayer
Add Payroll 78-87 Payrolls > Add CreatePayroll
Add Payrun 90-93 Payruns > Add CreatePayrun

1) The initial tenant must be created using the REST API or Payroll Console.

Example payroll Basic.json:

1 {
2   "$schema": "../../Schemas/PayrollEngine.Exchange.schema.json",
3   "createdObjectDate": "2023-01-01T00:00:00.0Z",
4   "tenants": [
5     {
6       "identifier": "StartTenant",
7       "culture": "en-US",
8       "users": [
9         {
10           "identifier": "lucy.smith@foo.com",
11           "firstName": "Lucy",
12           "lastName": "Smith",
13           "culture": "en-US",
14           "userType": "Supervisor"
15         }
16       ],
17       "divisions": [
18         {
19           "name": "StartDivision"
20         }
21       ],
22       "employees": [
23         {
24           "identifier": "mario.nuñez@foo.com",
25           "firstName": "Mario",
26           "lastName": "Nuñez",
27           "divisions": [
28             "StartDivision"
29           ]
30         }
31       ],
32       "regulations": [
33         {
34           "name": "StartRegulation",
35           "cases": [
36             {
37               "name": "Salary",
38               "caseType": "Employee",
39               "buildExpression": "true",
40               "validateExpression": "true",
41               "fields": [
42                 {
43                   "name": "Salary",
44                   "valueType": "Money",
45                   "timeType": "CalendarPeriod"
46                 }
47               ]
48             }
49           ],
50           "collectors": [
51             {
52               "name": "Income"
53             },
54             {
55               "name": "Deduction",
56               "negated": true
57             }
58           ],
59           "wageTypes": [
60             {
61               "wageTypeNumber": 100,
62               "name": "Salary",
63               "valueExpression": "CaseValue[\"Salary\"]",
64               "collectors": [
65                 "Income"
66               ]
67             }
68           ]
69         }
70       ],
71       "payrolls": [
72         {
73           "name": "StartPayroll",
74           "divisionName": "StartDivision",
75           "layers": [
76             {
77               "level": 1,
78               "regulationName": "StartRegulation"
79             }
80           ]
81         }
82       ],
83       "payruns": [
84         {
85           "name": "StartPayrun",
86           "payrollName": "StartPayroll"
87         }
88       ]
89     }
90   ]
91}

The payroll definition in detail:

  • 2: Path to the JSON schema (adapt this to your local environment)
  • 3: Default creation date for each object
  • 6: The unique tenant identifier StartTenant
  • 7: The tenant culture en-US
  • 10: The user identifier lucy.smith@foo.com
  • 13: The user culture en-US
  • 14: The user type Supervisor
  • 19: The division identifier StartDivision
  • 28: The employee's assignment to the division(s)
  • 34: The regulation identifier StartRegulation
  • 37: The Salary case name
  • 38: The case type employee (other types: global, national and company)
  • 44: The case field value type: money
  • 45: The case field time type calendar period
  • 52: The income collector
  • 55: The deduction collector
  • 55: Negated deduction collector
  • 61: Wage type number 100, controls the process order of the payrun
  • 63: Wage type value expression: calculated from case value
  • 65: Wage type collector Income
  • 74: Payroll assignment to the division
  • 78: Payroll layer assignment to the regulation
  • 86: Payrun assignment to the payroll

The fields Identifier, Name and WageTypeNumber must each be unique.

With the command 1 Basic.Setup.cmd the Payroll Console sends the data of the JSON file to the backend.

Payroll Test

The payroll test is carried out in three steps:

Step Description JSON
1 Add employee case Salary 12-27
2 Add payrun job for January 2023 32-43
3 Test the payrun wage type and collector results 45-56

Exampe payroll test Basic.Test.et.json:

1 {
2   "$schema": "../../Schemas/PayrollEngine.Exchange.schema.json",
3   "tenants": [
4     {
5       "identifier": "StartTenant",
6       "updateMode": "NoUpdate",
7       "payrolls": [
8         {
9           "name": "StartPayroll",
10            "updateMode": "NoUpdate",
11            "cases": [
12              {
13                "userIdentifier": "lucy.smith@foo.com",
14                "employeeIdentifier": "mario.nuñez@foo.com",
15                "divisionName": "StartDivision",
16                "case": {
17                  "caseName": "Salary",
18                  "values": [
19                    {
20                      "caseFieldName": "Salary",
21                      "value": "5000",
22                      "start": "2023-01-01T00:00:00.0Z",
23                      "created": "2022-11-04T00:00:00.0Z"
24                    }
25                  ]
26                }
27              }
28            ]
29          }
30        ],
31        "payrunJobInvocations": [
32          {
33            "name": "StartPayrunJob.Jan23",
34            "payrunName": "StartPayrun",
35            "userIdentifier": "lucy.smith@foo.com",
36            "employeeIdentifiers": [
37              "mario.nuñez@foo.com"
38            ],
39            "reason": "Test Payrun Jan 23",
40            "jobStatus": "Complete",
41            "periodStart": "2023-01-01T00:00:00.0Z",
42            "evaluationDate": "2023-02-01T00:00:00.0Z"
43          }
44        ],
45        "payrollResults": [
46          {
47            "payrunJobName": "StartPayrunJob.Jan23",
48            "employeeIdentifier": "mario.nuñez@foo.com",
49            "wageTypeResults": [
50              {
51                "wageTypeNumber": 100,
52                "value": 5000
53              }
54            ],
55            "collectorResults": [
56              {
57                "collectorName": "Income",
58                "value": 5000
59              },
60              {
61                "collectorName": "Deduction",
62                "value": 0
63              }
64            ]
65          }
66        ]
67      }
68    ]
69}

Der payroll test in detail:

  • 2: Path to the JSON schema (adjust this to your local environment)
  • 6: Prevent tenant update 1)
  • 10: Prevent payroll update 1)
  • 14: The employee of the case
  • 15: The division(s) of the employee's case
  • 21: The new employee's salary
  • 22: The salary start date
  • 23: The creation date of the change, simulation of the previous salary change
  • 33: Payrun job name
  • 34: Payrun job assignment to the payrun
  • 37: Employee(s) of the payrun job
  • 40: Complete the payrun job, test scenario
  • 41: Payrun period date
  • 42: Payrun execution date, simulation of past payrun execution
  • 33: Name of the payrun job to be tested
  • 48: Employee to test the result
  • 51: Wage type to be tested
  • 52: The expected wage type (100) value 5'000
  • 56: The expected colletor (Income) value 5'000
  • 62: The expected colletor (Deduction) value 0

1) The UpdateMode offers the possibility to split an object into several JSON files. In the root JSON, the base structure (tenant, regulation...) is defined, the child objects are managed in separate JSON files and deactivate the update mode for the base objects. When importing, the root object remains unchanged, only the child objects with active update mode are updated.

The command 1 Basic.Test.cmd runs the test on a copy of the employee mario.nuñez@foo.com.

Next steps

🤝 Thank you for supporting this project with a donation.
⚡ This is a pre-relase version of the initial development, please read the restrictions.

Clone this wiki locally