FunctionalIntegration
Most Payroll Engine objects have an Identifier or Name field for their identification. References between payroll objects are made via these fields. It is recommended to use technical terms that are not intended to be user-facing.
The built-in localization makes it possible to provide user-friendly display text. In the following example, the case has the name MonthlySalary [#03] and various localized labels [#05-#09]:
01 "cases": [
02 {
03 "name": "MonthlySalary",
04 "nameLocalizations": {
05 "en": "Monthly salary",
06 "de": "Monatslohn",
07 "es": "Salario mensual",
08 "ru": "Месячная зарплата",
09 "zh": "月薪"
10 }
11 }
12 ]Object identification best practices:
- Follow the naming conventions of the base regulation
- Avoid special characters and spaces
- Apply a consistent naming pattern across all objects and areas
- Use a naming prefix to avoid conflicts, e.g.
MyNamespace.MonthlySalary
Payroll Engine objects only contain the minimum required data fields. Additional fields are provided via attributes — a name/value dictionary. In the following example, an ERP ID [#08] and a processing status [#09] are assigned to a user:
01 "users": [
02 {
03 "identifier": "peter.schmid@foo.com",
04 "firstName": "Peter",
05 "lastName": "Schmid",
06 "culture": "de-CH",
07 "attributes": {
08 "ErpId": "C52F4DB2-A677-4BFC-9E5C-A4713A2532F5",
09 "ErpProcessCode": 3
10 }
11 }
12 ]Attributes are part of an object. For the central payroll objects, dedicated REST endpoints are available for attributes, such as GetUserAttribute, SetUserAttribute and DeleteUserAttribute.
When querying object data, attribute fields with a defined prefix can be filtered like regular object fields, allowing queries to return only objects that match a given attribute value. See Base Concepts for the full attribute reference.
Attributes are suitable for values that do not change over time. For time-varying values, case fields are the appropriate choice.
In contrast to static modification of attributes via the REST API, attributes can also be generated dynamically at runtime (see Scripting). Common use cases include:
- Controlling user input (e.g. via web application input attributes)
- Enriching payroll results with additional financial data
The Payroll Engine stores case data in four domains: Global, National, Company and Employee. Unlike conventional systems that store values in CRUD mode, the Payroll Engine also stores the validity period for each case value.
The web method
GetPayrollTimeCaseValuesreturns the case value valid at a specific point in time.
Documents can be attached to case values and transferred as part of a case change:
01 "cases": [
02 "userIdentifier": "peter.schmid@foo.com",
03 "case": {
04 "caseName": "EmployeeProfile",
05 "values": [
06 {
07 "caseFieldName": "ProfilePicture",
08 "documents": [
09 {
10 "name" : "ProfilePicture",
11 "contentType": "image/png",
12 "contentFile": "docs/myimage.png"
13 }
14 ]
15 }
16 ]
17 }
18 ]Documents are immutable and can be queried via dedicated endpoints (e.g. QueryEmployeeCaseDocuments).
The import of business data is generally straightforward, since a classic mutation is simply a special case of time data:
"Create this value, valid indefinitely from today."
The export of time data requires that the receiving system is capable of handling time-bounded values.
For the payrun objects Collector and WageType, additional results can be generated beyond standard attributes. Custom result values are numerical and can be evaluated like regular collector and wage type results.
Usage scenarios:
- A company-level regulation enriches the wage type result of a base regulation with additional values
- Storing figures relevant for reporting or auditing
🤝 Thank you for supporting this project with a donation.
⚡ This is a pre-relase version of the initial development, please read the restrictions.
