New Hire Onboarding Workflow¶

A step-by-step guide to building an IT/HR-triggered workflow that captures a new hire's name, email, username, and phone number, provisions an Active Directory account, grants a welcome role, sends a welcome SMS, and notifies an admin of the outcome. Every side-effecting step (account creation, role grant, SMS) routes its error transition to a shared admin notification, so a failure partway through never fails silently.

Prerequisites¶

A configured Active Directory connector (or the built-in test-activedirectory mock connector for a dry run without a real directory).
An SMS-capable connector (Twilio, Vonage, or the built-in test-sms mock connector for a dry run).
A role the new hire should receive on day one (e.g. "Employee Baseline Access"), created under People → Roles.
The workflow:create, workflow:update, workflow:publish, and workflow:read permissions on your admin account, and workflow:start plus workflow:provision_users on whichever account will run this workflow — the Provision Floh User step (§3.7) creates a new user record, and per Floh's auto-provisioning security model that requires the latter permission on the run initiator.

Overview¶

flowchart TD
  Start[Start]
  Name["Ask for New Hire's Name (user_prompt)"]
  Email["Ask for New Hire's Email (user_prompt)"]
  Username["Ask for New Hire's Username (user_prompt)"]
  Phone["Ask for New Hire's Phone (user_prompt)"]
  CreateAD["Create AD Account (connector)"]
  Provision["Provision Floh User (user_create)"]
  Grant["Grant Welcome Role (role_grant)"]
  Sms["Send Welcome SMS (send_sms)"]
  NotifyOk[Notify Admin — Onboarded]
  NotifyFail[Notify Admin — Failed]
  Success[End: Success]
  Failure[End: Failure]

  Start --> Name --> Email --> Username --> Phone --> CreateAD
  CreateAD -->|success| Provision
  CreateAD -->|error| NotifyFail
  Provision -->|success| Grant
  Provision -->|error| NotifyFail
  Grant -->|success| Sms
  Grant -->|error| NotifyFail
  Sms -->|success| NotifyOk
  Sms -->|error| NotifyFail
  NotifyOk --> Success
  NotifyFail --> Failure

Step 1 — Create the workflow¶

Navigate to Design in the sidebar (opens /workflows), open the Workflows tab, and click New Workflow:

Field	Value
Name	`New Hire Onboarding`
Description	`Provision a new hire's AD account, role, and welcome SMS`
Category	`user_self_service`
Error Strategy	`stop`
Trigger	`manual`

Leave Subject Variable unset. user_self_service auto-binds an implicit targetUser to the person who starts the run — typically the HR/IT admin kicking off onboarding, not the new hire — and this workflow never references that binding, so there's nothing to configure here. The new hire's identity comes entirely from the prompts in Step 3.

Step 2 — Variables¶

This workflow needs no workflow-level variables — every value it uses (name, email, username, phone) is captured live from the person running it via user_prompt steps, not collected up front on the request-catalog form. Leave the Variables tab empty and continue.

Step 3 — Add the workflow steps¶

3.1 — Start¶

Type: start. Entry point.

3.2 — Ask for New Hire's Name¶

Type: user_prompt.

Config Field	Value
Prompt Message	`What is the new hire's full name?`
Response Type	`Text`
Output Variable	`new_hire_name`

3.3 — Ask for New Hire's Email¶

Type: user_prompt.

Config Field	Value
Prompt Message	`What is the new hire's email address?`
Response Type	`Text`
Output Variable	`new_hire_email`

3.4 — Ask for New Hire's Username¶

Type: user_prompt.

Config Field	Value
Prompt Message	`What directory username should be created for the new hire (e.g. first initial + last name)?`
Response Type	`Text`
Output Variable	`new_hire_username`

3.5 — Ask for New Hire's Phone¶

Type: user_prompt.

Config Field	Value
Prompt Message	`What is the new hire's mobile number (E.164, e.g. +15551234567)?`
Response Type	`Text`
Output Variable	`new_hire_phone`

user_prompt is the one step type whose answer is not referenced through the step's Output Key — it's stored under whatever name you put in Output Variable (default promptResponse if left blank). Every prompt above needs a distinct Output Variable name; leaving two prompts on the default would silently overwrite each other's answer in the same variable. {{new_hire_name}}, {{new_hire_email}}, {{new_hire_username}}, and {{new_hire_phone}} below all resolve from these four Output Variable values, not from each step's Output Key.

3.6 — Create AD Account¶

Type: connector.

Config Field	Value
Connector	your Active Directory connector (or `test-activedirectory` for a dry run)
Command	`createAccount` — creates a new directory account
username	`{{new_hire_username}}`
email	`{{new_hire_email}}`
displayName	`{{new_hire_name}}`
department	`New Hire`
title	`New Hire`
Output Key	`create_account`

Transitions: success → Provision Floh User; error → Notify Admin — Failed.

createAccount requires username as a distinct param — it is not derived from email automatically. Omitting it fails the step with Missing required field: username before an account is ever created, which is why Step 3.4 exists as its own prompt rather than folding into the email prompt.

3.7 — Provision Floh User¶

Type: user_create.

Config Field	Value
Email	`{{new_hire_email}}`
Display name	`{{new_hire_name}}`
When the email already exists	`Reuse existing user`
Output Key	`provision_user`

Transitions: success → Grant Welcome Role; error → Notify Admin — Failed.

This step bridges the AD account created above to a Floh user record — role_grant needs a Floh user id, not a directory account, and a brand-new hire has no Floh account yet. On success it exposes userCreateUserId, referenced in the next step.

3.8 — Grant Welcome Role¶

Type: role_grant.

Config Field	Value
Role Definition	your "day one" role (e.g. `Employee Baseline Access`)
User	`{{userCreateUserId}}`
Output Key	`grant_role`

Transitions: success → Send Welcome SMS; error → Notify Admin — Failed.

3.9 — Send Welcome SMS¶

Type: send_sms.

Config Field	Value
Connector	your SMS connector (or `test-sms` for a dry run)
Recipient	`{{new_hire_phone}}`
Body	`Welcome to the team, {{new_hire_name}}! Your account is ready.`
Category	`Transactional (default)`
Output Key	`welcome_sms`

Transitions: success → Notify Admin — Onboarded; error → Notify Admin — Failed.

3.10 — Notify Admin — Onboarded¶

Type: notification.

Config Field	Value
Recipient Type	`Internal User`
Recipient User	the admin/HR user to notify
Subject Override	`New hire onboarded: {{new_hire_name}}`
Custom Body	`{{new_hire_name}} ({{new_hire_email}}) has been onboarded successfully.`
Output Key	`notify_success`

Transitions: success → End (Success).

3.11 — Notify Admin — Failed¶

Type: notification. This is the single failure sink every side-effecting step above routes into on error.

Config Field	Value
Recipient Type	`Internal User`
Recipient User	the admin/HR user to notify
Subject Override	`New hire onboarding failed for {{new_hire_name}}`
Custom Body	`Step {{lastStepError.stepId}} failed: {{lastStepError.message}}.`
Output Key	`notify_failure`

Transitions: success → End (Failure).

3.12 — End (Success) / End (Failure)¶

Type: end. Two exit points — one per outcome — so run history clearly distinguishes a completed onboarding from a failed one.

Step 4 — Wire the graph¶

In the Graph tab, draw these transitions:

Start → Ask for New Hire's Name
Ask for New Hire's Name → Ask for New Hire's Email
Ask for New Hire's Email → Ask for New Hire's Username
Ask for New Hire's Username → Ask for New Hire's Phone
Ask for New Hire's Phone → Create AD Account
Create AD Account → success → Provision Floh User
Create AD Account → error → Notify Admin — Failed
Provision Floh User → success → Grant Welcome Role
Provision Floh User → error → Notify Admin — Failed
Grant Welcome Role → success → Send Welcome SMS
Grant Welcome Role → error → Notify Admin — Failed
Send Welcome SMS → success → Notify Admin — Onboarded
Send Welcome SMS → error → Notify Admin — Failed
Notify Admin — Onboarded → End (Success)
Notify Admin — Failed → End (Failure)

Every side-effecting step (6, 8, 10, 12) has both a success edge deeper into the chain and an error edge back to the shared Notify Admin — Failed step. Skipping either edge on any one of them means that failure mode notifies nobody.

Step 5 — Save, test, publish¶

Click Save. Fix any validation errors — a missing error transition on a connector-backed step, or a missing role/connector selection, will block save.
Point Create AD Account at test-activedirectory and Send Welcome SMS at test-sms before the first Test Run. Do not aim these steps at a live directory or SMS provider until the mock run succeeds.
Click Test Run and answer the four prompts with reserved values that cannot collide with a real person, for example: name Test Newhire, email newhire.test@example.com, username newhire.test, phone +15555550100.
Confirm the run ends at End (Success) and that the admin notification arrives with the new hire's name and email in the body.
Force a failure (e.g. temporarily point Create AD Account at a disconnected connector) and confirm the run ends at End (Failure) with the admin notification naming the failed step.
After the mock path is green, you may re-point the connector steps at real AD/SMS connectors. Use a disposable test account and a phone number you control. A failure after Create AD Account succeeds leaves the directory account in place; a retry with the same username can collide, and SMS delivery is not reversible. Before retrying a live run, delete the directory account and the Floh user (if Provision Floh User created one) so the next attempt does not reuse those identities.
Click Publish.