mirror of
https://github.com/keycloak/keycloak.git
synced 2026-02-03 20:39:33 -05:00
64 lines
4.5 KiB
Text
64 lines
4.5 KiB
Text
[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.
|
|
|
|
You can adjust this interval 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 step is set to *1 second*. If a step takes longer than this timeout to execute,
|
|
it will be marked as failed, and the workflow execution will be halted. If the step is scheduled, it will run again
|
|
in the next execution window of the background task. If the step is not scheduled, the workflow execution will be marked as failed
|
|
and that step won't be retried.
|
|
|
|
You can configure the timeout for step execution by setting the following server configuration option:
|
|
|
|
* `spi-workflow--default--executor-task-timeout`: Defines the timeout for executing a workflow step. 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.
|