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
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) |
expirations_created | Number of expiration movements created for balances that passed their expiration date |
expiration_only_swept | Employees who no longer accrue (for example because their employment ended) but still held a balance past its expiration date, and were checked for expiration only |
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 the time off earned in January.
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 — running the job again never creates the same accrual twice. Check for manually created events |
| Balance seems wrong | Verify the accrual plugin configuration and proration settings |