Functional Integration

Payroll Engine Functional Integration

Payroll Object Identification

Most Payroll Engine objects have the field Identifier or Name for their identification. References between Payroll objects are made via these fields. It is better to use technical terms but not intended for the user.

The integrated localisation makes it possible to offer an understandable and user-friendly text. In the following example, the case has the name MonthlySalary [#03] and various localised identifiers [#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:

• Adoption of the naming conventions from the basic regulation
• Avoidance of special characters and spaces
• Consistent naming pattern for all objects and areas
• Naming conflicts can be avoided with a naming prefix, e.g. MayNamespace.MonthlySalary

Object Attributes

The Payroll Engine objects only have the most necessary data fields. The extension of these data fields is done via attributes. An attribute is a name with a value (dictionary). In the following example, an ERP ID [#08] and the processing status [#09] are assigned to the 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, there are additional REST endpoints for attributes, such as the web methods GetUserAttribute, SetUserAttribute and DeleteUserAttribute.

When querying object data, attribute fields with a prefix can be queried like normal object fields. When querying with an attribute field in the filter, only the corresponding objects are displayed in the result.

Attributes are suitable for unchanging values. If a value can change over time, case fields are more suitable.

Dynamic Object Attribute

In contrast to the static modification of attributes via the REST API, attributes can be generated dynamically at runtime (see Scripting). Attributes can be used in a variety of ways:

• Controlling user input (see Web application input attributes).
• Enrichment of the settlement result with financial data.

Case Values and Documents

The Payroll Engine stores the case data in the domains 'Global', 'National', 'Company' and 'Employee'. In contrast to conventional systems that store the values in CRUD mode, the Payroll Engine also stores the validity period for each case value.

The web method GetPayrollTimeCaseValues returns the case value at a specific time.

Documents are assigned to case values and can be transferred during a case change:

01 "cases": [
02   "userIdentifier": "peter.schmid@foo.com",
03   "case": {
04     "caseName": "EmployeeProfile",
05     "values": [
06       {
07         "caseFieldName": "ProfilePicture",
08         "documents": [
08           {
09             "name" : "ProfilePicture",
10             "contentType": "image/png",
11             "contentFile": "docs/myimage.png"
12           }
13         ]
14       }
15     ]
16   }
17 ]

Documents are immutable and can be queried via specific endpoints (e.g. QueryEmployeeCaseDocuments).

Time data

The import of business data should usually not be a problem, since classical mutation is only a special case of time data:

"Create this value for me that is valid indefinitely from today".

The export of time data requires that the conversion system can handle time values.

Payrun Results

For the wage run objects Collector and WageType, additional results can be generated in addition to the attributes. Custom result values are numerical and can be evaluated like the usual collector and wage type results.

Usage scenarios

• Company settlement supplements the wage type of a basic settlement with additional values
• Saving of figures relevant to evaluation or to be checked