[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.
