[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-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
| `client-created` | Client is added to the realm. | None
| `client-authenticated` | Client authenticates to the realm. | None
|===
