wip - workflows doc (#44685)

Signed-off-by: Pedro Igor <pigor.craveiro@gmail.com>
Co-authored-by: Stan Silvert <ssilvert@redhat.com>

docs/documentation/server_admin/topics.adoc

@@ -65,6 +65,7 @@ ifeval::[{project_community}==true]
 include::topics/admin-console-permissions/fine-grain.adoc[]
 endif::[]
 include::topics/assembly-managing-organizations.adoc[]
+include::topics/assembly-managing-workflows.adoc[]
 include::topics/assembly-managing-clients.adoc[]
 ifeval::[{project_community}==true]
 include::topics/oid4vci/vc-issuer-configuration.adoc[]

docs/documentation/server_admin/topics/assembly-managing-workflows.adoc

@@ -0,0 +1,15 @@
+[id="assembly-managing-workflows_{context}"]
+[[_managing_workflows]]
+==  Managing workflows
+
+include::workflows/intro.adoc[leveloffset=+2]
+include::workflows/understanding-workflow.adoc[leveloffset=+2]
+include::workflows/understanding-workflow-definition.adoc[leveloffset=+2]
+include::workflows/understanding-workflow-expression.adoc[leveloffset=+2]
+include::workflows/managing-workflows.adoc[leveloffset=+2]
+include::workflows/listening-workflow-events.adoc[leveloffset=+2]
+include::workflows/defining-conditions.adoc[leveloffset=+2]
+include::workflows/defining-steps.adoc[leveloffset=+2]
+include::workflows/understanding-workflows-engine.adoc[leveloffset=+2]
+include::workflows/understanding-common-use-cases.adoc[leveloffset=+2]
+

docs/documentation/server_admin/topics/workflows/defining-conditions.adoc

@@ -0,0 +1,43 @@
+[id="defining-workflow-conditions_{context}"]
+
+[[_workflow_conditions_]]
+= Defining conditions
+
+The optional `if` setting allows you to define a condition using an expression language that must be met for the workflow to be triggered.
+It allows more fine-grained control over when a workflow execution should be created based on the context of the event.
+
+Conditions provide fine-grained control over whether a workflow execution should be created.
+They allow you to inspect the context of the event and the state of the resource.
+For example, you can create conditions to check:
+* If a user has a specific attribute.
+* If a specific role is granted to a user or if the user is joining a specific group.
+
+If the condition evaluates to `true`, the workflow execution is created. If it evaluates to `false`, no workflow execution is created, even though
+the expression from the `on` setting evaluates to `true`.
+
+Just like the `on` setting, the condition is written using an expression that supports a variety of checks on the realm resource associated with the event.
+For instance, considering a `user_group_membership_created` event, you can define a condition to trigger the workflow only if the user has a specific attribute:
+
+```yaml
+on: user_created
+if: has-user-attribute('plan', 'gold')
+```
+
+In this example, the workflow will only be triggered when a new user is created and that user has an attribute `plan` with the value `gold`.
+
+{project_name} provides a set of built-in conditions that you can use in your workflows.
+The conditions are also based on the realm resource associated with the event.
+
+[[_workflow_user_functions_]]
+== User functions
+
+[cols="3*", options="header"]
+|===
+|Condition
+|Description
+|Parameters
+| `has-user-attribute` | If the user has an attribute set. | The attribute name and optionally the attribute value using a properties format. If multiple values, they should be separated by comma. If the value is omitted, only the presence of the attribute is checked.
+| `has-role` | If the user is granted with a specific role | The name of the role.
+| `has-identity-provider-link` | If the user is linked to an identity provider. | The alias of the identity provider.
+| `is-member-of` | If the user is member of a specific group. | The name or path of the group.
+|===

docs/documentation/server_admin/topics/workflows/defining-steps.adoc

@@ -0,0 +1,102 @@
+[id="defining-workflow-steps_{context}"]
+
+[[_workflow_steps_]]
+= Defining steps
+
+The `steps` setting allows you to define the step chain, which is a sequence of actions to be executed during the lifetime of a workflow execution.
+Each step represents a specific action that can be performed, such as sending a notification, updating user attributes, or interacting with external systems.
+
+Each step in the step chain is defined using the following structure:
+
+```yaml
+steps:
+  - uses: <step>
+    with:
+      <param>: <value>
+      ...
+    after: <duration>
+  ...
+```
+
+In its simplest form, a step is defined using only the `uses` field:
+
+```yaml
+steps:
+  - uses: disable-user
+```
+
+However, some steps also support additional settings to customize their behavior:
+
+```yaml
+steps:
+  - uses: notify-user
+    with:
+      message: "Welcome to the platform!"
+```
+
+Here is a more detailed look at all fields available from defining a step:
+
+`uses`::
+The name of the step to be executed. This field is mandatory.
+
+`with`::
+Key/value pairs to be passed to the step. The available parameters depend on the step being used. This field is optional.
+
+`after`::
+An optional duration to wait before executing the step. The duration is defined using a number followed by a time unit:
+*   `ms`: milliseconds
+*   `s`: seconds (default if no unit is specified)
+*   `m`: minutes
+*   `h`: hours
+*   `d`: days
+
+{project_name} provides a set of built-in steps that you can use in your workflows. The steps are targeted at performing actions
+on the realm resource associated with the event, so that each realm resource type has its own set of steps.
+
+[[_workflow_user_steps_]]
+== User steps
+
+[cols="3*", options="header"]
+|===
+|Step
+|Description
+|Configuration
+| `set-user-required-action` | Set a required action to the user a|
+* `action`: The name of the required action
+| `delete-user` | Delete the user | None
+| `disable-user` | Disable the user | None
+| `notify-user` | Notify the user by email a|
+- `subject`: The email subject
+- `message`: The email message in plain text or HTML format
+| `set-user-attribute` | Set an attribute to the user. Allows providing multiple `<name>`/`<value>` pairs a|
+- `<name>`: The attribute name
+- `<value>`: The value of the attribute
+|===
+
+[[_workflow_immediate_steps_]]
+== Understanding immediate steps
+
+A step can run immediately whenever it is reached in the step chain. A immediate step is executed as soon as the previous step is completed,
+without any delay. This is the default behavior for steps in a workflow.
+
+For example, in the following workflow definition, both steps are immediate steps:
+
+```yaml
+steps:
+  - uses: notify-user
+  - uses: disable-user
+```
+
+== Understanding scheduled steps
+
+A step can be scheduled to run after a specific duration using the `after` field. A scheduled step is executed after waiting for the defined duration
+once the previous step is completed.
+
+For example, in the following workflow definition, the `disable-user` step is a scheduled step that will run 7 days after notifying the user:
+
+```yaml
+steps:
+  - uses: notify-user
+  - uses: disable-user
+    after: 7d
+```

docs/documentation/server_admin/topics/workflows/intro.adoc

@@ -0,0 +1,20 @@
+[role="_abstract"]
+{project_name} Workflows is a powerful engine to automate and orchestrate realm administrative tasks, bringing key
+capabilities of Identity Governance and Administration (IGA) to your identity and access management infrastructure.
+By using workflows, you can implement policies and processes that govern the lifecycle of realm resources, such as users and clients,
+helping you to improve security, meet compliance requirements, and reduce administrative costs.
+
+As a core component of IGA, identity lifecycle management is fully supported by workflows so that you can easily automate
+onboarding and offboarding processes, and other recurring administrative tasks. For example, you can define workflows to:
+
+* Provision and de-provision realm resources, such as users, automatically based on specific events or conditions.
+* Automate Joiner-Mover-Leaver (JML) processes to ensure that users are granted the appropriate access rights based on their roles and responsibilities.
+* Enforce access reviews and certifications to ensure that users have the appropriate access rights.
+* Enforce Just-In-Time and Least Privilege access by automating role assignments and revocations.
+* Enforce strong authentication policies for realm users.
+* Prevent insider data breaches by automating the removal of inactive or obsolete users.
+
+By leveraging workflows, realm administrators can ensure that security policies are consistently enforced and based on
+the least privilege principle, reduce the risk of human error, and free up valuable time to focus on other important administrative tasks.
+This guide will walk you through the process of creating and managing workflows to automate your administrative tasks
+and implement IGA best practices when managing realms.

docs/documentation/server_admin/topics/workflows/listening-workflow-events.adoc

@@ -0,0 +1,56 @@
+[id="triggering-workflow-events_{context}"]
+
+[[_workflow_events_]]
+= Triggering workflows on events
+
+The `on` setting defines the event that will trigger the workflow. You should choose the event accordingly to the realm resource and the intent
+of the workflow.
+
+The value of the `on' setting is an expression that must evaluate to true. In its basic form, the expression is simply
+the name of the event.
+
+```yaml
+on: user_created
+```
+
+As you can see, events are functions in an expression and, as such, they also support parameters to provide more specific conditions.
+For example, to trigger a workflow when a user is added to a specific group, you can use the following expression:
+
+```yaml
+on: user_group_membership_created('/mygroup')
+```
+
+You can also combine multiple conditions using logical operators. For example, to trigger a workflow when a user is created or when authenticates, you can use:
+
+```yaml
+on: user_created or user_authenticated
+```
+
+[NOTE]
+====
+Even though the `on` setting can be defined using expressions, keep in mind that a single event triggers a workflow.
+====
+
+If this setting is not specified, the workflow will not be triggered by any event, but workflow
+executions can still be created manually for a specific realm resource.
+
+At the moment, workflows support event functions for the following realm resources:
+
+[[_workflow_event_functions_]]
+== Event functions
+
+[cols="3*", options="header"]
+|===
+|Event
+|Description
+|Parameters
+| `user_created` | User is added to the realm. | None
+| `user_removed` | User is removed from the realm. | None
+| `user_authenticated` | User authenticates to the realm. | The client id of the client acting on behalf of the user when authenticating.
+| `user_federated_identity_created` | User is federated or when the account is linked to an identity provider. | The identity provider alias.
+| `user_federated_identity_removed` | User's federated identity is removed or unlinked from an identity provider. | The identity provider alias.
+| `user_role_granted` | A role is granted to the user. | The role name.
+| `user_role_revoked` | A role is revoked from the user. | The role name.
+| `user_group_membership_created` | User joined a group. | The group name or path
+| `user_group_membership_removed` | User is removed from a group. | The group name or path
+|===

docs/documentation/server_admin/topics/workflows/managing-workflows.adoc

@@ -0,0 +1,41 @@
+[id="managing-workflows_{context}"]
+
+[[_managing_workflows_]]
+=  Managing workflows
+[role="_abstract"]
+
+Workflows can be managed through the Admin Console or the Admin REST API.
+
+== Managing workflows through the Admin Console
+
+To manage workflows through the Admin Console, you can follow these steps:
+
+.Procedure
+
+. Click *Workflows* in the menu.
+
+.Empty workflows list
+image:images/workflows-empty-list.png[alt="Empty workflows list"]
+
+If your realm does not have any workflows defined yet, you will see an empty list. To create a new workflow, click *Create*.
+
+. Creating a new workflow
+image:images/workflows-create.png[alt="Creating a new workflow"]
+
+This will open the workflow creation screen where you can define the workflow using YAML format. To save the workflow, click *Save*.
+
+Once you have created one or more workflows, they will be listed in the workflows list.
+
+.List of workflows
+image:images/workflows-list.png[alt="List of workflows"]
+
+From the workflows list, you can perform the following actions:
+
+*   **Create**: Click *Create workflow* to create a new workflow.
+*   **Update**: Click on the name of an existing workflow to update it.
+*   **Enable/Disable**: Use the toggle button on the *Status* column to enable or disable a workflow.
+*   **Copy**: Click on the *Copy* button next to a workflow to create a copy of it. This is useful if you want to create a new workflow based on an existing one.
+*   **Delete**: Click on the *Delete* button next to a workflow to delete it.
+
+
+

docs/documentation/server_admin/topics/workflows/understanding-common-use-cases.adoc

@@ -0,0 +1,62 @@
+[id="understanding-common-use-cases_{context}"]
+
+[[_understanding_common_use_cases_]]
+=  Understanding common use cases
+[role="_abstract"]
+
+Workflows can be used to automate a wide range of administrative tasks within a realm. Here are some common use cases where workflows can be particularly beneficial:
+
+== User Onboarding
+
+When a new user is created, a workflow can automatically send a welcome email, and assign initial roles or groups to the user. This ensures that new users have the necessary access and information from the moment they join.
+
+```yaml
+name: Onboarding gold members
+on: user_created
+if: has-user-attribute('membership','gold')
+steps:
+  - uses: notify-user
+    with:
+      message: "Welcome to the Gold Membership program!"
+  - uses: assign-user-role
+    with:
+      role: gold-member
+```
+
+== User Offboarding
+
+When a user is removed from a specific group, a workflow can automatically revoke certain roles or permissions associated with that group.
+
+```yaml
+name: Offboarding sales members
+on: user_group_membership_removed('/Sales')
+steps:
+  - uses: revoke-role
+    with:
+      role: "manager,sales-rep,sales-intern"
+```
+
+== Tracking user activity and taking actions on inactivity
+
+When a user has been inactive for a certain period, a workflow can send reminder emails and deactivate the account.
+
+```yaml
+name: Track inactive users
+on: user_authenticated
+concurrency:
+  restart-in-progress: true
+steps:
+  - uses: notify-user
+    after: 180d
+    with:
+      message: It has been a while since your last login. We miss you!
+  - uses: notify-user
+    after: 60d
+    with:
+      message: Your account will be disabled in ${workflow.daysUntilNextStep} days!
+  - uses: disable-user
+    after: 7d
+  - uses: notify-user
+    with:
+      message: Your account was disabled. Sorry to see you go.
+```

docs/documentation/server_admin/topics/workflows/understanding-workflow-definition.adoc

@@ -0,0 +1,78 @@
+[id="understanding-workflow-definition_{context}"]
+
+[[_understanding_workflow_definition_]]
+=  Understanding the workflow definition
+[role="_abstract"]
+
+Workflows are defined in YAML format. This format allows for a clear and human-readable way to specify the automation process
+represented by a workflow.
+
+In its simplest form, a workflow definition can be defined as follows:
+
+```yaml
+name: Onboarding new users
+on: user_added
+steps:
+  - uses: notify-user
+    with:
+      message: |
+        <p>Dear ${user.firstName} ${user.lastName}, </p>
+
+        <p>Welcome to ${realm.displayName}!</p>
+
+        <p>
+           Best regards,<br/>
+           ${realm.displayName} Team
+        </p>
+  - uses: set-user-required-action
+    after: 30d
+    with:
+      action: UPDATE_PASSWORD
+  - uses: restart
+    with:
+      position: 1
+```
+
+The example above is very simple but illustrates the core structure and the flexibility of a workflow to automate administrative tasks.
+It is composed of three main sections:
+
+*   `name`: A unique and user-friendly name to identify the workflow within the realm.
+*   `on`: The event that will trigger the workflow. In this case, the workflow is triggered when a new user is added to the realm.
+*   `steps`: A set of one or more steps to be executed when executing a workflow execution. In this example, three steps are defined:
+    1. The first step uses the built-in `notify-user` action to send a welcome message to the new user.
+    2. The second step uses the built-in `set-user-required-action` action to require the user to update their password after 30 days.
+    3. The third step uses the built-in `restart` action to restart the workflow from the second step so that the user is forced to update their password every 30 days.
+
+Here is a more detailed look at all settings available from the workflow definition:
+
+`name`::
+A unique and user-friendly name to identify the workflow within the realm.
+This name is crucial for management and logging purposes.
+This setting is mandatory.
+
+`on`::
+Define a condition that determines the event that will trigger the workflow.
+The condition is written using an expression language that supports a variety of checks on the event.
+This setting is optional.
+
+`if`::
+Define a condition that must be met for the workflow to be triggered.
+The condition is written using an expression language that supports a variety of checks on the realm resource
+associated with the event.
+A workflow execution is only created if the expression evaluates to `true`.
+If this setting is omitted, the event defined in the `on` setting will always create the workflow execution.
+This setting is optional.
+
+`steps`::
+Define the step chain consisting of one or more steps to be sequentially executed during the lifetime of a workflow.
+This setting is mandatory.
+
+`concurrency`::
+This setting controls the behavior when multiple events that would trigger the same workflow occur for the same realm resource while a workflow execution is already active for that resource. This setting is optional.
++ The available options are:
+*   `restart-in-progress`: A new event causes the current workflow execution to restart from the beginning.
+*   `cancel-in-progress`: A new event causes the current workflow execution to be canceled and disassociated from the realm resource.
+
+`enabled`::
+This setting enables or disables the workflow. If set to `false`, new workflow executions will not be created for the workflow and any active workflow execution will be paused.
+This setting is optional and defaults to `true`.

docs/documentation/server_admin/topics/workflows/understanding-workflow-expression.adoc

@@ -0,0 +1,32 @@
+[id="understanding-workflow-expression_{context}"]
+
+[[_workflow_expression_language_]]
+= Understanding the workflow expression language
+
+Some settings from the workflow definition can be defined using a boolean expression language, the Workflow Expression Language.
+Expressions are defined using functions, operands, and logical operators. The functions available in an expression will
+depend on the setting where it is being defined.
+
+The functions can have zero or more arguments, and they can be combined with the following logical operators and symbols to define
+complex expressions:
+
+[cols="2*", options="header"]
+|===
+|Operator
+|Description
+| `and` | Logical `AND`
+| `or` | Logical `OR`
+| `not` | Logical `NOT`
+| `()` | Grouping and delimiting conditional logic
+|===
+
+These examples are all valid expressions:
+
+```yaml
+f1
+f1 and f2
+not (f1 and f2)
+(f1 and f2) or f3
+```
+
+The settings that supports expressions provide its own set of functions as you will see in the following sections.

docs/documentation/server_admin/topics/workflows/understanding-workflow.adoc

@@ -0,0 +1,36 @@
+[id="understanding-workflow_{context}"]
+
+[[_understanding_workflows_]]
+=  Understanding workflows
+[role="_abstract"]
+
+A workflow is an activity or process within {project_name} that executes a series of predefined steps on a
+specific realm resource in response to specific events and based on the defined conditions.
+
+In {project_name}, there are two main types of events:
+
+*   **User Events**: These events are initiated by users, such as login in or registering a new account.
+*   **Admin Events**: These events are initiated by administrators through the Admin Console and API, such as creating or updating a user or any other realm resource.
+
+Workflows are designed to respond to these events by automating tasks and processes that need to be performed and executed on the
+realm resources associated with these events.
+
+Once an event is fired, the workflow engine evaluates all defined workflows in the realm to determine if any should be
+triggered based on the event type and the specified conditions. If the event matches the conditions defined in a workflow,
+a workflow execution is created and assigned with an identifier. The workflow execution
+is bound to the realm resource associated with the event, and only a single instance of a workflow can be active for that
+realm resource at any given time.
+
+A realm resource can be any entity within the realm, such as a user, client, group, or a role.
+At the moment, workflows can be defined for the following realm resources:
+
+*   Users
+
+Once a workflow is active for a realm resource, its step chain is processed. The steps run sequentially, and they will
+run immediately or be scheduled to execute later in time, depending on each step configuration.
+Once all the steps are executed, the workflow execution is completed and the realm resource
+is no longer bound to that workflow.
+
+That is the main gist of {project_name} Workflows. There are more details and settings that can be
+configured to customize the behavior and the lifecycle of a workflow, how their instances are created, managed,
+and bound to realm resources, as well as how their steps are executed.

docs/documentation/server_admin/topics/workflows/understanding-workflows-engine.adoc

@@ -0,0 +1,61 @@
+[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, in milliseconds, at which the background task runs to check for workflow steps that are due for execution.
+
+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, in milliseconds, for executing a workflow step.
+
+== 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.