Skip to content

Forecasts

Forecasts let you run parallel what-if payruns against real regulation and employee data — without touching production results. This makes them useful for salary planning, budget projections, and testing regulation changes before they go live.

Forecast case data is never visible to legally valid payruns. Any number of named forecast scenarios can run concurrently within the same period.

The examples on this page assume a running backend. See Container Setup for installation instructions.

The Forecasts feature can be enabled or disabled per user in the web application's user administration.

How It Works

Forecasts introduce two tagged concepts to the standard payroll flow:

Concept Production Forecast
Case data No forecast: tag forecast: ScenarioName
Payrun job jobStatus: Complete jobStatus: Forecast + forecast: ScenarioName
Result isolation Legally valid results Stored separately, never merged into production
Parallelism One active job per period Unlimited forecast jobs per period
Approval process Multi-stage None — executed immediately

A forecast payrun reads case data tagged with its scenario name. Case data without a tag (production data) is also visible to forecast runs — the scenario data simply overrides it where present.

Step 1 — Create Forecast Case Data

To enter data for a forecast, add a forecast: tag with a scenario name to the case change. The name is freely chosen and identifies the scenario. Multiple case changes can share the same forecast name to build up a complete scenario.

Example — two parallel scenarios for fictitious PlanSoft GmbH (ForecastPayroll):

# Production baseline — no forecast tag
- userIdentifier: hr@plansoft.com
  employeeIdentifier: sophie.kramer@plansoft.com
  divisionName: PlanSoft.HR
  reason: Current salary — production baseline
  case:
    caseName: Salary
    values:
    - caseFieldName: Salary
      value: "5000"
      start: 2026-01-01T00:00:00Z
      created: 2025-12-01T00:00:00Z

# Scenario 1 — salary raised to 6000, isolated from production
- userIdentifier: hr@plansoft.com
  employeeIdentifier: sophie.kramer@plansoft.com
  divisionName: PlanSoft.HR
  forecast: SalaryIncrease2026
  case:
    caseName: Salary
    values:
    - caseFieldName: Salary
      value: "6000"
      start: 2026-01-01T00:00:00Z
      created: 2025-12-15T00:00:00Z

# Scenario 2 — monthly bonus 500 for Q1, salary unchanged
- userIdentifier: hr@plansoft.com
  employeeIdentifier: sophie.kramer@plansoft.com
  divisionName: PlanSoft.HR
  forecast: BonusScenario2026
  case:
    caseName: PlannedBonus
    values:
    - caseFieldName: PlannedBonus
      value: "500"
      start: 2026-01-01T00:00:00Z
      end: 2026-03-31T00:00:00Z
      created: 2025-12-15T00:00:00Z

The detail:

  • Production case data has no forecast: tag — it is the baseline for all runs
  • SalaryIncrease2026 overrides the Salary case field for its scenario only
  • BonusScenario2026 adds a PlannedBonus value with a fixed validity window
  • Both scenarios are independent — neither affects the other or production

In the web application, a history of previously used forecast names is available when entering case data.

Step 2 — Run a Forecast Payrun

Forecast payrun jobs use jobStatus: Forecast and the same forecast: tag as the case data. They are executed and completed immediately — no approval process, no effect on production results.

# Production run — baseline
- name: PlanSoftPayrun.Prod.Jan26
  payrunName: PlanSoftPayrun
  userIdentifier: hr@plansoft.com
  jobStatus: Complete
  periodStart: 2026-01-01T00:00:00Z
  evaluationDate: 2026-01-31T00:00:00Z
  storeEmptyResults: true

# Forecast run — scenario 1
- name: PlanSoftPayrun.SalaryIncrease.Jan26
  payrunName: PlanSoftPayrun
  userIdentifier: hr@plansoft.com
  jobStatus: Forecast
  forecast: SalaryIncrease2026
  periodStart: 2026-01-01T00:00:00Z
  evaluationDate: 2026-01-31T00:00:00Z
  storeEmptyResults: true

# Forecast run — scenario 2
- name: PlanSoftPayrun.BonusScenario.Jan26
  payrunName: PlanSoftPayrun
  userIdentifier: hr@plansoft.com
  jobStatus: Forecast
  forecast: BonusScenario2026
  periodStart: 2026-01-01T00:00:00Z
  evaluationDate: 2026-01-31T00:00:00Z
  storeEmptyResults: true

The detail:

  • The production job and both forecast jobs target the same period — this is only possible for forecast jobs
  • forecast: SalaryIncrease2026 tells the engine to include case data tagged with that name
  • storeEmptyResults: true ensures wage types with zero results are stored — required for scenario comparison
  • Data from the previous production payrun can be used as a template for a forecast run in the web application

Step 3 — Analyze Results

The results of all three runs for January 2026:

Wage Type Production Salary Increase 2026 Bonus Scenario 2026
100 BaseSalary 5 000 6 000 5 000
110 PlannedBonus 0 0 500
200 IncomeTax (20 %) 1 000 1 200 1 100
210 SocialContribution (8 %) 400 480 440
300 NetSalary 3 600 4 320 3 960
GrossIncome 5 000 6 000 5 500
Deductions 1 400 1 680 1 540

Forecast results can be filtered by scenario name in the web application's data grid and exported to Excel. All report templates that work on production payruns also work on forecast results — no separate report definitions required.

ForecastPayroll Example

GitHub — fully No-Code, two parallel what-if scenarios for fictitious PlanSoft GmbH.

Feature Detail
Forecast isolation forecast: tag on case changes; invisible to production
Parallel scenarios SalaryIncrease2026 and BonusScenario2026 — same regulation, same payrun
Optional wage type ? ^^PlannedBonus > 0 guard suppresses the bonus WT in production and unrelated scenarios
Net comparison Dedicated NetSalary WT (300) as single bottom-line figure per scenario
Planning horizon Three months (Jan–Mar 2026) per scenario 
# Install and run the example
ForecastPayroll/Setup.pecmd
ForecastPayroll/Test.pecmd

Next Steps