Basic Payroll

Basic Payroll Example

Dieses Beispiel zeigt das Einrichten und Testen einer Payroll für eine Firma, welche die Mitarbeiter monatlich bezahlt (Quelldateien).

Payroll Model

Die Payroll Engine bildet die Gehaltsabrechnung mit folgenden Objekten ab:

Die Mitarbeiter eines Mandanten sind einer oder mehrerer Divisions zugeordnet. Die Lohläufe beziehen sich auf eine Division, so dass ein Mitarbeiter aus verschiedenen Divisions den Lohn beziehen kann.

Requirements

Um eine Payroll zu erstellen muss der Backend Server der Payroll Engine gestartet sein.

Die Payroll kann auf drei Arten eingerichtet werden:

• Rest API
  • REST API Development Tool, z.B. Postman
• Payroll Console
  • Lokaler Zugriff auf das Payroll Engine Exchange JSON Schema
  • JSON Editor, z.B. Visual Studio Code
• Web Applikation
  • Der Web Application Server ist gestartet

Payroll Setup

Die folgenden Schritte beschreiben das Einrichten einer Payroll:

Step	JSON	Web Application	REST API
Set JSON schema	02	-	-
Set object creation date	03	-	-
Add Tenant	04-87	Tenants > Add 1)	CreateTenant
Add User	08-14	Users > Add	CreateUser
Add Division	15-19	Divisons > Add	CreateDivision
Add Employee	20-29	Employees > Add	CreateEmployee
Add Regulation	30-67	Regulations > Add	CreateRegulation
Add Case	33-47	Regulation > Cases > Add	CreateCase
Add Case Field	39-45	Regulation > Case Fields > Add	CreateCaseField
Add Collector	48-55	Regulation > Collectors > Add	CreateCollector
Add Wage Type	56-65	Regulation > Wage Types > Add	CreateWageType
Add Payroll Layer	72-77	Payroll Layers > Add	CreatePayrollLayer
Add Payroll	68-79	Payrolls > Add	CreatePayroll
Add Payrun	80-85	Payruns > Add	CreatePayrun

¹⁾ Der initiale Tenant muss mittels REST API oder Payroll Console erstellt werden.

Beispiel 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": "[email protected]",
11           "firstName": "Lucy",
12           "lastName": "Smith"
13         }
14       ],
15       "divisions": [
16         {
17           "name": "StartDivision"
18         }
19       ],
20       "employees": [
21         {
22           "identifier": "mario.nuñ[email protected]",
23           "firstName": "Mario",
24           "lastName": "Nuñez",
25           "divisions": [
26             "StartDivision"
27           ]
28         }
29       ],
30       "regulations": [
31         {
32           "name": "StartRegulation",
33           "cases": [
34             {
35               "name": "Salary",
36               "caseType": "Employee",
37               "buildExpression": "true",
38               "validateExpression": "true",
39               "fields": [
40                 {
41                   "name": "Salary",
42                   "valueType": "Money",
43                   "timeType": "CalendarPeriod"
44                 }
45               ]
46             }
47           ],
48           "collectors": [
49             {
50               "name": "Income"
51             },
52             {
53               "name": "Deduction"
54             }
55           ],
56           "wageTypes": [
57             {
58               "wageTypeNumber": 100,
59               "name": "Salary",
60               "valueExpression": "CaseValue[\"Salary\"]",
61               "collectors": [
62                 "Income"
63               ]
64             }
65           ]
66         }
67       ],
68       "payrolls": [
69         {
70           "name": "StartPayroll",
71           "divisionName": "StartDivision",
72           "layers": [
73             {
74               "level": 1,
75               "regulationName": "StartRegulation"
76             }
77           ]
78         }
79       ],
80       "payruns": [
81         {
82           "name": "StartPayrun",
83           "payrollName": "StartPayroll"
84         }
85       ]
86     }
87   ]
88 }

Die Payroll Definition im Detail:

• 2: Path to the JSON schema (adjust this to your local environment)
• 3: Default creation date for any object
• 6: The unique tenant identifier StartTenant
• 7: The tenant culture en-US
• 10: The user identifier [email protected]
• 17: The division identifier StartDivision
• 26: Employee association to the division(s)
• 32: The regulation identifier StartRegulation
• 35: The Salary case name
• 36: The case type employee (further types: global, national and company)
• 42: The case field value type: money
• 43: The case field time type calendar period
• 50: The income collector
• 50: The deduction collector
• 58: The wage type number 100, controls the payrun process order
• 60: The wage type value expression: calculated from case value
• 62: The wage type collector Income
• 71: Payroll association to the division
• 74: Payroll layer association to the regulation
• 83: Payrun association to the payroll

Die Felder Identifier, Name und WageTypeNumber müssen im jeweiligen Kontext eindeutig sein.

Die JSON Datei wird mit der Payroll Konsole Kommando PayrollImport zum Backend übermittelt:

PayrollConsole PayrollImport Payroll.json

Payroll Test

Der Payroll Test erfolgt in drei Schritten:

1. Simmulation des Mitarbeiter-Falles Salary
2. Lohnlauf für den Monat Januar 2023
3. Test der Benutzereingaben und der Lohnlauf simmuliert und überprüft, ob die berechneten Lohndaten korrekt sind: | Step | JSON | |:--|:--:| | Set link to JSON schema | 02 | | Add Employee Case | 11-28 | | Add Payrun Job | 31-44 | | Test Payrun Results | 45-56 |

Beispiel Payroll JSON 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": "[email protected]",
14               "employeeIdentifier": "mario.nuñ[email protected]",
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": "[email protected]",
36           "employeeIdentifiers": [
37             "mario.nuñ[email protected]"
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ñ[email protected]",
49           "wageTypeResults": [
50             {
51               "wageTypeNumber": 100,
52               "value": 5000
53             }
54           ]
55         }
56       ]
57     }
58   ]
59 }

Der Payroll Test im Detail:

• 2: Path to the JSON schema (adjust this to your local environment)
• 6: Do not update the tenant ¹⁾
• 10: Do not update the payroll ¹⁾
• 14: The employee of the case
• 15: The divisivion(s) of the employee case
• 21: The new employee salary
• 22: The salary start date
• 23: The change created data, simulation of past salary change
• 34: Payrun job association to the payrun
• 37: Payrun job employee(s)
• 40: Complete the payrun job, test scenario
• 41: Payrun period date
• 42: Payrun execution date, simulation of past payrun execution
• 48: Employee to test the result
• 51: The wage type to test
• 52: The expected wage type value

¹⁾ Der UpdateMode bietet die Möglichkeit ein Objekt in mehrere JSON-Dateien aufzuteilen. Im Root-JSON ist der Basisstruktur (Tenant, Regulation...) definiert, welche immer aktualsiert werden. Kinderobjekte werden in getrennten JSON Datein geführt und deaktivieren bei den Basisobjekten den Updatemodus. Beim Import bleibt das Root-Objekt unverändert, nur Kinderobjekte mit aktivem Updatemodus werden aktualisiert.

Der Payroll Konsole Kommando PayrunEmployeeTest erstellt für jeden Testlauf eine Kopie des Mitarbeiters.

PayrollConsole PayrunEmployeeTest Test.et.json

Next steps

• Advanced Payroll
• Report
• Explore the Payroll Engine Resources