Accrual materialize
Converts forecasted accruals into actual time account events, crediting employees’ time-off balances.
How it works
The accrual materialize job runs daily and performs the following:
- Finds due accruals — forecasts with a next accrual date on or before the run date
- Creates events — converts each due forecast entry into an actual time account event
- Updates tracking — records the last materialized date to prevent duplicate processing
This is the job that actually credits time-off balances. Until materialization occurs, accruals exist only as projections in the forecast.
Daily vs backfill processing
The job handles two scenarios:
Daily processing
For employees with existing materialization history, the job:
- Finds accruals with
next_accrual_date <= run_date - Creates events only for the due accruals
- Updates the forecast’s
last_materialized_date
Backfill processing
For employees without any materialization history (new setups or migrations), the job:
- Materializes all accruals from the forecast start through the run date
- This allows catching up on historical accruals in a single run
Run date behavior
The run date is critical for this job:
| Scenario | Run date | Effect |
|---|---|---|
| Normal daily run | Today | Materializes accruals due up to today |
| Catch-up run | Past date | Materializes only up to that date (useful for controlled rollout) |
| Future date | Future date | Materializes accruals into the future (use with caution) |
Backfilling historical accruals
To materialize accruals for past periods:
- Ensure Accrual forecast has been run for the historical period
- Trigger this job manually with the run date set to the target historical date
- Run again with progressively later dates if you want controlled, incremental materialization
Running with a future date will create accrual events for dates that haven’t occurred yet. This is rarely desired and may need to be reversed manually.
Job results
| Metric | Description |
|---|---|
forecasts_processed | Number of employee forecasts evaluated |
accruals_materialized | Number of accrual events created (daily processing) |
accruals_backfilled | Number of accrual events created (backfill processing) |
errors | Number of failures during materialization |
Accrual timing
Accruals are assigned on the first of the following month. For example:
- January work → accrual dated February 1
- December work → accrual dated January 1 (of the next year)
This means the materialize job running on February 1 will create the accrual event for January’s earned time-off.
Troubleshooting
| Issue | Solution |
|---|---|
| Accruals not appearing | Verify the Accrual forecast job has run first |
| Missing historical accruals | Check that last_materialized_date is null to trigger backfill, or re-run forecast with historical run date |
| Duplicate accruals | This shouldn’t happen — the job is idempotent. Check for manual event creation |
| Balance seems wrong | Verify the accrual plugin configuration and proration settings |