Action templates

Which templates are ready, which are reference skeletons, and when each one makes sense.

Not every template serves the same purpose.

This catalog splits them into:

Ready starting points — realistic defaults, worth trying first
Reference patterns — useful integration scaffolds that still need project-specific wiring

Ready starting points

Template	Trigger	Use it when...	Notes
`hello-world`	`EVENT:user.human.added`	you want to verify a trigger and inspect payload shape	safest first step
`auto-group-by-department`	`EVENT:user.human.added`	you want first-time onboarding into Atrium groups (login-time mirroring already runs in `flatten-roles`)	one-time lifecycle action
`prefill-from-entra`	`EVENT:user.human.added`	you want default app access for newly created Entra-backed users	adjust project/role constants
`flatten-roles`	`FUNCTION:preuserinfo`	you need v1 `flatRoles` parity on userinfo / ID-token-adjacent flows	canonical claim migration template
`flatten-roles-access-token`	`FUNCTION:preaccesstoken`	the same claims must exist in the access token	twin of `flatten-roles` for access-token consumers

Reference patterns

Template	Trigger	What it demonstrates
`welcome-email`	`EVENT:user.human.added`	transactional email via `ctx.fetch` + secrets
`scim-fanout-on-grant`	`EVENT:user.grant.added`	downstream provisioning through Atrium's SCIM sync path
`sentry-grant-fanout`	`EVENT:user.grant.added`	non-SCIM SaaS provisioning via REST API
`dokploy-grant-fanout`	`EVENT:user.grant.added`	custom grant fan-out to a non-SCIM API
`slack-notify-on-grant`	`EVENT:user.grant.added`	lightweight audit notifications

Treat these as integration patterns, not drop-in business logic.

Department → Atrium-group mapping

In this deployment, mirroring a user's Zitadel department metadata into the matching Atrium group runs as a side-effect of the flatten-roles action (FUNCTION:preuserinfo) — it fires on every userinfo call, so login-time catch-up is already covered.

The auto-group-by-department template (EVENT:user.human.added) is the companion that closes the first-login gap: it places the user in the group at account creation time, so the very first SAML sign-in already sees the membership. Activate this one when sign-in-time provisioning (e.g. sentry-team-sync) needs the group to exist before the user has touched userinfo.

The previous auto-group-by-department-on-login template (EVENT:oidc_session.added) was removed in 2026-06: it overlapped with the flatten-roles side-effect and created two writers for the same data, which made group descriptions point at the wrong owner.

The `flatRoles` pair

These are the most important OMMAX-specific templates now.

`flatten-roles`

Use when the consuming app reads claims from:

userinfo
ID-token-adjacent flows
a path backed by preuserinfo

`flatten-roles-access-token`

Use when the consuming app reads claims from:

the access token

Often the correct migration is:

activate both
keep the logic aligned
let each Function slot serve its own surface

The slot rule

Atrium only routes one ACTIVE script per exact trigger slot.

That means:

one ACTIVE FUNCTION:preuserinfo
one ACTIVE FUNCTION:preaccesstoken
one ACTIVE EVENT:user.human.added

So if you need multiple behaviours in one live slot, combine them into one script instead of trying to stack multiple active scripts.

How to choose quickly

Need claims? Start with flatten-roles / flatten-roles-access-token.
Need lifecycle automation? Start with auto-group-by-department or prefill-from-entra.
Need to explore payload shape first? Start with hello-world.
Need third-party provisioning? Use one of the reference fan-out templates and customize it.