mirror of
https://github.com/keycloak/keycloak.git
synced 2026-07-25 18:26:11 +00:00
75 lines
5.6 KiB
Plaintext
75 lines
5.6 KiB
Plaintext
[id="understanding-workflow_{context}"]
|
|
|
|
[[_understanding_workflows_engine_]]
|
|
= Understanding the workflows engine
|
|
[role="_abstract"]
|
|
|
|
The lifecycle and execution of workflows in {project_name} is managed by the Workflows Engine.
|
|
The engine is responsible for processing events, creating workflow executions, and processing their steps.
|
|
Once a workflow execution is created, the engine takes over and manages the execution of its steps chain.
|
|
|
|
The execution of the steps chain is done asynchronously and detached from the request that originated the event that
|
|
triggered the workflow. This means that workflows are not scheduled nor executed immediately within the context of the request,
|
|
but rather sent to a task thread pool and scheduled to be executed later by the engine. This allows for better performance and scalability, as the steps can be executed
|
|
in the background without blocking the main request thread.
|
|
|
|
For immediate steps, the engine processes them as soon as the workflow execution is submitted to the task thread pool. This means that immediate steps are executed
|
|
right away, as soon as the workflow execution is picked up by a worker thread from the pool.
|
|
|
|
For scheduled steps, the engine continuously monitors the state of all active workflow executions in the realm. This is done by a background
|
|
task that runs periodically to check for any workflow executions that have steps ready to be executed. The schedule steps of a workflow are also executed asynchronously
|
|
by the background task, using the same task thread pool as immediate steps.
|
|
|
|
== Configuring the scheduled steps execution interval
|
|
|
|
By default, the background task tracking due steps runs every 12 hours, but this interval can be configured by setting the following server configuration option:
|
|
|
|
* `spi-events-listener--workflow-event-listener--step-runner-task-interval`: Defines the interval at which the background task runs to check for workflow steps that are due for execution.
|
|
It follows the same format used in the workflow step `after` field, where you can specify the interval as a number followed by a time unit (`ms`, `s` - default, `m`, `h`, `d`) or using the ISO-8601 duration format.
|
|
|
|
By default, the first execution of the background task occurs after one full interval has elapsed since the server started.
|
|
You can control this by setting a start time that acts as an anchor for aligning executions to a predictable schedule:
|
|
|
|
* `spi-events-listener--workflow-event-listener--step-runner-task-start-time`: Defines the time of day used to align the background task executions, in `HH:mm` format (e.g., `02:00`, `14:30`), using the server's local timezone.
|
|
|
|
When a start time is set, the task interval is aligned to a grid of execution times anchored at the specified time. For example, with a start time of `02:00` and an interval of `12h`, the task always runs at 02:00 and 14:00 regardless of when the server was started. If the server starts at 10:30, the first execution would occur at 14:00.
|
|
|
|
You can adjust these options based on your realm's needs and the expected frequency of workflow executions.
|
|
|
|
== Configuring the task execution timeout
|
|
|
|
Most of the time, steps are executed in a short amount of time. However, there might be cases where a step takes longer
|
|
to execute due to various reasons, such as network latency depending on an external service delays, or complex processing logic.
|
|
|
|
By default, the timeout for executing a workflow is set to *5 seconds*. The amount of steps that are processed in a single run
|
|
depends on the number of immediate steps that are defined in the workflow, as they are executed sequentially in the same run. Once
|
|
the workflow encounters a scheduled step, it schedules the step and terminates the execution.
|
|
|
|
If a workflow execution takes longer than the defined timeout, the engine will fail the current step, and it will attempt
|
|
to run this step in the next execution of the workflow. This is done to prevent long-running executions from blocking the workflow task thread pool
|
|
and impacting the execution of other workflows.
|
|
|
|
You can configure the timeout for the workflow executor task by setting the following server configuration option:
|
|
|
|
* `spi-workflow--default--executor-task-timeout`: Defines the timeout for executing a workflow. It follows the same format
|
|
used in the workflow step `after` field, where you can specify the interval as a number followed by a time unit (`ms`, `s` - default, `m`, `h`, `d`)
|
|
or using the ISO-8601 duration format.
|
|
|
|
== Performance considerations
|
|
|
|
Workflows can introduce additional processing overhead. This is mainly true when workflows are triggered frequently
|
|
such as when users are authenticating. Even though workflows are scheduled and executed asynchronously, they still consume
|
|
system resources. Therefore, it's important to monitor the performance of your realm and adjust your workflow definitions
|
|
accordingly to ensure optimal performance.
|
|
|
|
Consider the following best practices when defining workflows:
|
|
|
|
* Keep workflows simple and focused on specific tasks and avoid long-running transactions when executing steps in a workflow.
|
|
This is specially true for steps that are executed immediately upon workflow execution creation.
|
|
|
|
* Consider using short timeouts for the step execution to avoid blocking the workflow execution for too long and potentially
|
|
exhaust the workflow task thread pool and impacting the execution of other workflows.
|
|
|
|
* Adjust the background task interval based on the expected frequency of workflow executions in your realm. If your realm has a high volume of workflow executions,
|
|
consider reducing the interval to avoid processing multiple workflows at once.
|