[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_added('/mygroup')
```

You can also combine multiple conditions using logical operators. For example, to trigger a workflow when a user is created or when they authenticate, 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_added` | 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_added` | User joined a group. | The group name or path
| `user_group_membership_removed` | User is removed from a group. | The group name or path
|===
