Skip to main content

Workflow Recipes

The Workflow Service allows you to define complex business processes using a YAML-based DSL. This page documents common recipes used in the Citadel platform.

Recipe Format​

Each workflow definition consists of metadata and a list of steps.

  • id / name: Unique identifier for the workflow.
  • steps: Ordered list of operations to execute.
    • type: action (backend op), form (UI input), or completion (end state).
    • component: Frontend component to render (for UI steps).
    • resource/operation: Backend service to call (for action steps).
    • parameters: Input data, supporting expression interpolation (e.g., ${previous_step.output}).

1. Tenant Signup (B2B)​

This workflow orchestrates the creation of a new tenant and its administrative owner.

File: tenant_signup.yaml

id: tenant_signup
name: tenant_signup
description: "Standard B2B Tenant Signup Flow"
steps:
  - id: create_user
    type: action
    component: ActionStep
    resource: user
    operation: create
    parameters:
      email: "${data.owner.email}"
      first_name: "${data.owner.first_name}"
      last_name: "${data.owner.last_name}"

  - id: create_tenant
    type: action
    component: ActionStep
    resource: tenant
    operation: create
    parameters:
      name: "${data.tenant.name}"
      slug: "${data.tenant.slug}"

  - id: assign_owner
    type: action
    component: ActionStep
    resource: iam
    operation: assign_role
    parameters:
      user_id: "${steps.create_user.id}"
      tenant_id: "${steps.create_tenant.id}"
      role: "owner"

Key Concepts​

  • Chaining: The output of create_user (the user ID) and create_tenant (the tenant ID) are fed into the assign_owner step.
  • Actions: All steps are action type, meaning this runs as a background process (or via Temporal) without user intervention after trigger.

2. Invite Redemption (User Onboarding)​

This workflow handles the user journey when clicking an email invitation link. It combines UI steps (Form) with backend actions.

File: invite_redemption.yaml

name: invite_redemption
version: "1.0"
description: "Workflow for redeeming a user invitation and completing the profile."

steps:
  - id: profile_completion
    type: form
    component: ProfileCompletion
    title: "Complete Your Profile"
    description: "Please provide your details to finish setting up your account."
    fields:
      - name: full_name
        label: "Full Name"
        type: text
        required: true
        validation:
          min_length: 2
    action:
      label: "Join Organization"
    next: redeem_token

  - id: redeem_token
    type: action
    component: ActionStep
    resource: invite
    operation: accept
    parameters:
      token: "${context.token}"
      full_name: "${steps.profile_completion.full_name}"
    next: success

  - id: success
    type: completion
    component: SuccessMessage
    props:
      title: "Welcome!"
      description: "You have successfully joined the organization."
      redirect_url: "/dashboard"

Key Concepts​

  • Hybrid Flow: Step 1 (profile_completion) renders a UI form to the user.
  • Context: The redeem_token step uses ${context.token}, which is passed into the workflow execution context (usually from the URL query param).
  • Transitions: Explicit next fields control the flow.

3. Public Registration (Citizen)​

Coming soon. (Available in onboarding_v1.yaml)