Skip to content

Regulation Design

Regulator|Scripting API · C# 14

Contents

Section Description
Regulation Identification Name + ValidFrom date as version key
Regulation Objects Lookups, cases, payruns, reports by regulation type
Regulation Namespace Namespace prefix and cross-regulation references
Regulation Splitting Separate logic and data for independent release cycles
Regulation Versioning Naming strategies and version history table

Regulation Identification

Within a tenant, the regulation has the following identification features:

  • Name
  • Valid-from date

If there are several regulations with the same name, the version is determined based on the valid-from date.

# Import date Regulation name Valid-from
1 1. Dec 2026 MyRegulation 1. Jan 2027
2 1. Mar 2027 MyRegulation 1. Apr 2027

When accessing the regulations, the evaluation date, i.e., the payrun date, is decisive:

  • Evaluation on January 15, 2027 -> #1
  • Evaluation on April 15, 2027 -> #2
  • Evaluation on April 15, 2027 with retro-payrun effect to March 2027 -> #1

Regulation Objects

A regulation can contain the following objects:

  • Lookup data
  • Input objects with company and employee cases (logic)
  • Payrun objects with collector and wage types (logic)
  • Reports (logic)

Which objects are included in the regulation depends on its use.

Regulation type Lookup Input Payrun Report
Country yes yes yes yes
Business domain optional optional optional optional
Lookup data yes no no no
Lookup data with logic yes optional optional no
Tenant optional optional optional optional

Regulation Namespace

To prevent name conflicts, regulations are assigned to a Namespace. This is then prefixed to each object identifier automatically.

The namespace follows the regulation layer hierarchy:

Layer Convention Owner
Country DE Legislator
Tenant DE.Acme Company

The following example shows a two-layer setup with country and tenant regulations:

# Layer 1: Country regulation
Regulation:
  name: DE.Labor 2025.1
  namespace: DE
  objects:
    - WageType: GrossPay          # stored as DE.GrossPay
    - WageType: IncomeTax         # stored as DE.IncomeTax
    - CaseField: TaxClass         # stored as DE.TaxClass

# Layer 2: Tenant regulation
Regulation:
  name: DE.Acme 2025.1
  namespace: DE.Acme
  baseRegulations: [DE.Labor 2025.1]
  objects:
    - CaseField: BasePay          # stored as DE.Acme.BasePay
    - WageType: Bonus             # stored as DE.Acme.Bonus

    - WageType: GrossPay          # Override DE.GrossPay: add bonus
      valueScript: |
        // Cross-namespace: reference country wage type
        return GetWageTypeValue("DE.GrossPay")
             + GetWageTypeValue("DE.Acme.Bonus");

    - CaseField: TaxClass         # Override DE.TaxClass: tenant default
      defaultValue: '1'
      valueActions:
        // Same-namespace: short form (namespace prefix implicit)
        - '= ^$TaxClass'
        // Cross-namespace: fully qualified
        - '? ^$DE.Acme.BasePay > 0 : ^$DE.TaxClass'

Reference rules:

Context Reference Form
Action Same namespace ^$TaxClass
Action Foreign namespace ^$DE.TaxClass
Script Any namespace Always fully qualified: "DE.Acme.Bonus"

An object name must not contain a period ., as this is reserved for namespace separation.

Regulation Splitting

If a regulation contains lookup data that changes often, it may make sense to separate this data from the rest of the regulation objects. This separates logic and data and makes updates easier.

Name Lookup Input Payrun Report
MyRegulation optional 1) yes yes yes
MyRegulation data yes no no no

1) Static lookups.

The dependency created by this approach between the MyRegulation and the MyRegulation data regulation is entered in the regulation property BaseRegulations. Additional criteria for dividing a regulation:

  • Separation of partner data
  • Separate release cycles

Regulation Versioning

Regulations can have their own version number or use the calendar year as a suffix. The following example shows a split regulation with isolated versioning:

Regulation name Type Base regulation Start date Description
2024.1 main Jan. 2024 Main regulation initial release 2024
data 2024.1 data 2024.1 Jan. 2024 Data regulation initial release 2024
data 2024.2 data 2024.1 Aug. 2024 Data regulation 2024 first update
2024.2 main Nov. 2024 Main regulation 2024 update
data 2025.1 data 2024.2 Jan. 2025 Data regulation initial release 2025
data 2025.2 data 2024.2 Jul. 2025 Data regulation 2025 first update
data 2025.3 data 2024.2 Oct. 2025 Data regulation 2025 second update
2026.1 main Jan. 2026 Main regulation initial release 2026
data 2026.1 data 2026.1 Jan. 2026 Data regulation initial release 2026

Next Steps