Skip to content

Functional Integration

Provider|REST API · OpenAPI 3.1

Payroll Object Identification

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 technical name MonthlySalary and various localized labels:

cases:
- name: MonthlySalary       # technical identifier — PascalCase, no spaces
  nameLocalizations:
    en: Monthly salary
    de: Monatslohn
    es: Salario mensual
    ru: Месячная зарплата
    zh: 月薪

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

Object Attributes

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 and a processing status are assigned to a user:

users:
- identifier: peter.schmid@foo.com
  firstName: Peter
  lastName: Schmid
  culture: de-CH
  attributes:
    ErpId: C52F4DB2-A677-4BFC-9E5C-A4713A2532F5    # external ERP reference
    ErpProcessCode: 3                                # processing status in ERP

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.

Dynamic Object Attributes

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

Case Values and Documents

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 GetPayrollTimeCaseValues returns 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:

cases:
- userIdentifier: peter.schmid@foo.com
  case:
    caseName: EmployeeProfile
    values:
    - caseFieldName: ProfilePicture
      documents:
      - name: ProfilePicture
        contentType: image/png
        contentFile: docs/myimage.png    # path relative to the import file

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

Time Data

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.

Payrun Results

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

See Also