Working version v32.1.X v32.0.X v29.1.X
Working version v32.1.X v32.0.X v29.1.X Dutch

Geplande taken en onderhoudstaken

Vooraf

Niet alle maatwerk hangt aan een stap in een workflow. Soms moet je applicatie iets doen op een vast tijdstip, of moet je één keer een correctie uitvoeren op dossiers die al bestaan. Daarvoor zijn er twee soorten backend-extensies:


Geplande taak

Onderhoudstaak

Wanneer?

Automatisch, op vaste tijdstippen

Op vraag, wanneer een beheerder ze start

Hoe vaak?

Doorlopend

Eenmalig of zelden

Voorbeelden

Een referentielijst bijwerken vanuit een externe bron, een dagelijkse export klaarzetten, wachtende dossiers doorsturen naar een extern systeem

Een veld aanvullen op oude dossiers, gegevens rechtzetten na een fout in de configuratie

Beide bouw je als Spring bean, zoals beschreven op Backend-extensie bouwen.

Een geplande taak toevoegen

Stap 1: annoteer de methode met @Scheduled

Een geplande taak is een methode met de Spring-annotatie @Scheduled. Je haalt de cron-expressie uit een eigenschap, zodat je het tijdstip per omgeving kunt instellen zonder de code te wijzigen:

Java
@Service
@RequiredArgsConstructor
@Slf4j
public class ExportScheduler {

    private final ExportService exportService;

    @Scheduled(cron = "${mijnapp.export.cron}", zone = "Europe/Brussels")
    public void maakDagelijkseExport() {
        LOGGER.info("Start dagelijkse export");
        try {
            exportService.maakExport();
        } catch (Exception e) {
            LOGGER.error("Dagelijkse export mislukt", e);
        }
    }
}

Geef de tijdzone expliciet mee. Zonder zone gebruikt Spring de tijdzone van de server, en die is in een cloudomgeving vaak UTC.

Stap 2: stel de cron-expressie in

Spring gebruikt cron-expressies met zes velden: seconde, minuut, uur, dag van de maand, maand en dag van de week. Enkele voorbeelden:

Eigenschap

Betekenis

mijnapp.export.cron=0 0 6 * * *

Elke dag om 06:00

mijnapp.export.cron=0 */15 * * * *

Elk kwartier

mijnapp.export.cron=0 0 22 * * MON-FRI

Elke werkdag om 22:00

mijnapp.export.cron=-

Uitgeschakeld

Met de waarde - schakel je de taak uit, bijvoorbeeld op een testomgeving zonder verbinding met het externe systeem. De volledige syntax vind je in de Spring-documentatie over Task Execution and Scheduling.

Stap 3: maak de taak robuust

Een geplande taak draait zonder dat iemand meekijkt. Fouten moet je dus zelf opvangen en duidelijk loggen:

  • Vang fouten op in de taak zelf. Een mislukte uitvoering mag de volgende niet tegenhouden.

  • Overschrijf geen goede gegevens met lege. Geeft een externe bron een leeg antwoord, sla de update dan over en log een fout, in plaats van bijvoorbeeld een referentielijst leeg te maken.

  • Denk na over de opstart. Wil je de taak ook meteen bij het opstarten van de applicatie uitvoeren, bijvoorbeeld met @PostConstruct? Vang dan elke fout op, zodat een onbereikbaar extern systeem de opstart niet blokkeert.

Een onderhoudstaak toevoegen

Stap 1: bouw de taak volgens het vaste patroon

Een onderhoudstaak raakt vaak alle dossiers in de applicatie. Een fout heeft dus grote gevolgen. Bouw ze daarom volgens dit patroon:

  • Idempotent. Je kunt de taak meerdere keren uitvoeren zonder schade. Dossiers die al in orde zijn, sla je over.

  • Eerst een dry-run. In een dry-run telt en logt de taak wat ze zou doen, zonder iets weg te schrijven. Pas daarna voer je ze echt uit.

  • Per dossier afgeschermd. Een fout bij één dossier stopt de rest niet. Je telt de mislukte dossiers en logt ze.

  • Asynchroon bij grote volumes. Een uitvoering over alle dossiers duurt al snel langer dan de time-out van een HTTP-aanvraag. Start de taak op de achtergrond en vraag het resultaat later op.

  • Maximaal één uitvoering tegelijk. Een tweede start terwijl de eerste nog loopt, weiger je.

Een vereenvoudigd skelet:

Java
@Service
@RequiredArgsConstructor
@Slf4j
public class VeldAanvullenService {

    private final DossierRepository dossierRepository;
    private final DossierService dossierService;

    private final AtomicBoolean running = new AtomicBoolean(false);
    private final AtomicReference<Map<String, Object>> lastResult = new AtomicReference<>();
    private final Executor executor = Executors.newSingleThreadExecutor();

    public Map<String, Object> startAsync(boolean dryRun) {
        if (!running.compareAndSet(false, true)) {
            return Map.of("started", false, "reason", "already running");
        }
        executor.execute(() -> {
            try {
                lastResult.set(run(dryRun));
            } finally {
                running.set(false);
            }
        });
        return Map.of("started", true, "dryRun", dryRun);
    }

    public Map<String, Object> status() {
        Map<String, Object> status = new LinkedHashMap<>();
        status.put("running", running.get());
        status.put("lastResult", lastResult.get());
        return status;
    }

    Map<String, Object> run(boolean dryRun) {
        int updated = 0, skipped = 0, failed = 0;
        for (Dossier dossier : dossierRepository.findAll()) {
            try {
                if (isAlInOrde(dossier)) {
                    skipped++;
                    continue;
                }
                if (!dryRun) {
                    vulAan(dossier);
                    dossierService.update(dossier);
                }
                updated++;
            } catch (Exception e) {
                failed++;
                LOGGER.error("Aanvullen mislukt voor dossier {}", dossier.getId(), e);
            }
        }
        return Map.of("dryRun", dryRun, "updated", updated, "skipped", skipped, "failed", failed);
    }
}

Schrijf je wijziging weg via DossierService.update(dossier), niet via de repository. Anders staat de nieuwe waarde wel in de database, maar niet in de zoekindex.

Stap 2: maak de taak bereikbaar

Een beheerder start de taak via een eigen endpoint, bijvoorbeeld een REST-controller met drie acties: een dry-run starten, de echte uitvoering starten en de status opvragen.

Stap 3: voer de taak uit

  1. Start een dry-run op een testomgeving en controleer het resultaat en de logs.

  2. Herhaal de dry-run op productie en vergelijk de aantallen.

  3. Start de echte uitvoering.

  4. Vraag de status op tot running op false staat, en controleer updated, skipped en failed.

  5. Voer de dry-run nog eens uit. Als alles gelukt is, staat updated nu op nul.

Resultaat

Je geplande taak draait op de ingestelde tijdstippen en vangt haar eigen fouten op. Je onderhoudstaak kun je veilig testen, uitvoeren en opnieuw uitvoeren zonder schade.