Payroll Automation

Regulator|Scripting API · C# 14

This page covers the technical details of regulation automation: actions, scripting, sharing and versioning. For the role-based entry point, see the Regulator documentation.

Contents

Section	Description
Case Actions (No-Code)	Predefined actions for case build and validation
Excel Regulation Import	Spreadsheet-based regulation authoring
Exchange Formats	JSON, YAML, Excel — import and export
Scripting	C# scripts for cases, payruns and reports
Regulation Sharing	Cross-tenant regulation sharing
Regulation Versioning	ValidFrom date and retro-safe history

---

Case Actions (No-Code)

Case Actions are comparable to Excel functions and offer various functions to control user input and validate data.

In the example Basic Payroll the wage value is constrained between 500 and 25,000:

cases:
- name: Salary
  caseType: Employee
  buildExpression: "true"        # activate build actions for case fields
  validateExpression: "true"     # activate validate actions for case fields
  fields:
  - name: Salary
    valueType: Money
    timeType: CalendarPeriod
    buildActions:
    - Limit(500, 25000)          # clamp input value to valid range on entry
    validateActions:
    - ValueBetween(500, 25000)   # reject values outside valid range

buildExpression: "true" activates build actions on case fields; Limit(min, max) clamps the entered value to the allowed range. validateExpression: "true" activates validate actions; ValueBetween(min, max) rejects values outside the range.

Build actions improve usability, but validate actions are more important as they enforce data validity.

In addition to the large number of predefined actions, custom actions are also possible — for example, to format and validate a policy number. The Payroll Console can list all actions of a regulation assembly using the command ActionReport.

Read the article No-code and low-code development for payroll providers.

Excel Regulation Import

Regulations can be imported from Excel workbooks using the RegulationExcelImport command in the Payroll Console. The Excel format supports the full regulation object model:

• Cases and case fields
• Case relations
• Collectors and wage types
• Lookups and lookup values
• Reports, report parameters, and report templates
• Scripts

This provides a spreadsheet-based alternative to JSON/YAML for regulation authoring, which is particularly useful for payroll professionals who are more comfortable with Excel than with code editors.

RegulationExcelImport MyRegulation.xlsx
RegulationExcelImport MyRegulation.xlsx /upload

The command can either convert the Excel file to a JSON exchange file or upload the regulation directly to the backend.

Exchange Formats

Regulations and payroll data can be authored and exchanged in multiple formats:

Format	Import	Export	Use Case
JSON	✓	✓	Full payroll exchange, regulations, test data
YAML	✓	✓	Human-readable alternative to JSON with schema support
Excel	✓	—	Spreadsheet-based regulation authoring

The Payroll Console command PayrollConvert converts between JSON and YAML, including support for file masks and recursive conversions:

PayrollConvert MyRegulation.json
PayrollConvert *.json /recursive

Scripting

The runtime behavior of cases, payruns and reports is controlled by scripts. Scripts are written in C# and provide the following capabilities:

• Access to backend data such as regulation lookups, case values and payroll results.
• Use of time data calculations.
• Implementation of custom actions (see above).
• Querying webhook data within scripts.
• Central management and reuse of business functions via the regulation object Script.
• Compilation at object creation time (POST/PUT) for good runtime performance.
• Development and debugging in modern IDEs (debug support for case and report scripts).

Scripting Functions

A function is a programmed sequence invoked by an engine process at a specific point. See No-Code/Low-Code Development for a role-based overview. The complete reference with override behavior:

Object	Function	Description	Type	Override
Case	Available	Test whether a case is available	bool?	Top-Down
Case	Build	Build a case	bool?	Top-Down
Case	Validate	Test whether a case is valid	bool?	Top-Down
CaseRelation	Build	Build a case relation	bool?	Top-Down
CaseRelation	Validate	Test whether a case relation is valid	bool?	Top-Down
Payrun	Start	Payrun start	bool?	—
Payrun	EmployeeAvailable	Test whether the employee is available	bool?	—
Payrun	EmployeeStart	Payrun employee start	bool?	—
Payrun	WageTypeAvailable	Test whether a wage type is available	bool?	—
Payrun	EmployeeEnd	Payrun employee end	—	—
Payrun	End	Payrun end	—	—
Collector	Start	Collector start	—	Top-Down
Collector	Apply	Apply wage type value to collector	decimal?	Top-Down
Collector	End	Collector end	—	Top-Down
WageType	Value	Calculate wage type value	decimal?	Top-Down
WageType	Result	Determine wage type results	—	Bottom-Up
Report	Build	Build report	bool?	—
Report	Start	Start of report generation	—	—
Report	End	End of report generation	—	—

Top-Down override: the first function that returns a non-null value is used. When null is returned, the function from the next underlying regulation layer is executed.

Bottom-Up override: values are merged starting from the lowest regulation layer, with higher-level regulations able to override individual entries.

The built-in functions can be extended via scripts using C# Extension Methods or Partial Classes.

Case Scripting

Case scripts control user input and validate case data before it is stored in the backend:

• Determine case availability: Case Available.
• Build and update the case: Case Build and Case Relation Build
  The case is initially built and re-evaluated whenever data changes.
• Validate the case: Case Validate and Case Relation Validate.

Payrun Scripting

Payrun scripts are integrated into the payroll processing sequence:

• Determine employee availability: Employee Available.
• Start payrun: Payrun Start.
• For each employee:
  • Start employee: Employee Start
  • Start collector: Collector Start
  • For each wage type:
    • Determine wage type availability: Wage Type Available
    • Calculate the wage type value: Wage Type Value
    • Determine additional wage type results: Wage Type Result
    • Consolidate wage type value: Collector Apply
  • End collector: Collector End
  • End employee: Employee End
• End payrun: Payrun End

The following aspects apply to payrun scripts:

• All scripts except Wage Type Value are optional.
• Collectors consolidate wage type results, e.g. for wage bases.
• Processing data can be accumulated per payrun (PayrunRuntime) or per employee (EmployeeRuntime) and saved at the end of the sequence as attributes or results (PayrunResult).
• Payruns can be restarted so that a wage type is calculated more than once.
• Payruns can be triggered automatically (via case value start date) or explicitly via scripting.

Report Scripting

The report scripts are:

• Create and update report parameters: Report Build
  Report parameters are initially created and re-evaluated with every data change.
• Start report generation: Report Start
• Finalize report generation: Report End

Regulation Sharing

Regulation sharing enables regulations to be shared between tenants.

The Regulation Share contains the following values:

• Provider Tenant: The tenant providing the regulation.
• Provider Regulation: The shared regulation of the provider (must be marked as SharedRegulation).
• Consumer Tenant: The tenant consuming the regulation.
• Consumer Division: The division of the consumer (optional restriction).

A consumer tenant can reference a shared regulation as a layer in its payroll.

Changes to shared regulations are critical and should be introduced with a new effective date (see Regulation Versioning).

Example regulation share:

regulationShares:
- providerTenantIdentifier: StartTenant
  providerRegulationName: InsuranceRegulation    # must be marked as SharedRegulation
  consumerTenantIdentifier: OtherTenant

Regulation Versioning

A regulation contains a validity date ValidFrom from which the data becomes effective. Future updates can set a validity date in the future using the same regulation name. This validity history ensures correct time data for retroactive payroll calculations.

The validity date of the regulation must align with the payroll Calendar Periods. See Regulation Design for versioning guidelines.

See also

• Regulator Role — role-based entry point
• Custom Actions — tutorial for building custom actions
• Regulations
• Regulation Design
• Extended Functions
• Examples — payroll examples and demos
• Articles — blog posts and technical articles