Schedule workflow executions

The Serverless Workflow specification allows you to define workflows that execute automatically on a recurring schedule.

By default, the Quarkus Flow engine uses a lightweight, in-memory implementation (based on ScheduledExecutorService and the cron-utils library) to trigger these executions. However, for a production-grade Quarkus application, we highly recommend replacing this with the native Quarkus Scheduler integration.

This guide shows how to:

Enable the native Quarkus Flow Scheduler.
Configure the scheduler to comply with the specification CRON standards.
Define a recurring schedule in your workflow.

Prerequisites

A Quarkus application with Quarkus Flow set up.

1. Add the Scheduler dependency

To replace the default engine scheduler with the native Quarkus Scheduler, simply add the quarkus-flow-scheduler extension to your project.

pom.xml

<dependency>
  <groupId>io.quarkiverse.flow</groupId>
  <artifactId>quarkus-flow-scheduler</artifactId>
</dependency>

Adding this dependency automatically wires Quarkus Flow to use the underlying Quarkus scheduling infrastructure. This gives you access to robust application lifecycle management and all standard Quarkus Scheduler configuration properties.

2. Configure for specification compliance

The Serverless Workflow specification mandates that CRON expressions follow the standard Unix format.

The Quarkus Scheduler, however, defaults to the quartz format. To ensure your workflow definitions behave exactly as specified by the standard, you must configure the CRON type in your application properties:

application.properties

# Force the Quarkus scheduler to use Unix cron syntax for CNCF compliance
quarkus.scheduler.cron-type=unix

3. Define a schedule in your workflow

You can define a schedule directly in your workflow definition. The specification supports three scheduling formats:

cron: A standard CRON expression.
every: An ISO-8601 duration (e.g., PT15M for every 15 minutes) representing the interval between executions.
after: An ISO-8601 duration representing a delay before the workflow starts.

Example: YAML Definition

Here is an example of a workflow that executes automatically every 15 minutes using a CRON expression:

document:
  dsl: '1.0.0'
  namespace: org.acme
  name: ScheduledJob
  version: '1.0'
schedule:
  cron: "0/15 * * * *"
do:
  - runTask:
      call: http
      with:
        method: POST
        endpoint: "https://api.example.com/sync"