Example: Project Onboarding Workflow¶

An end-to-end onboarding workflow that invites a user to a project, collects a required training certificate, routes it through an approval, provisions the user's group membership in Authifi, and sends a welcome email.

Use Case¶

A project manager wants to grant a new team member access to Project XYZ. Before the user is added to the XYZ-team group in Authifi, they must complete an online training course and submit their certificate of completion. A designated approver reviews the certificate, and only upon approval is the user provisioned into the group and welcomed.

Prerequisites¶

The Authifi connector is configured with valid client credentials and the target tenant.
The XYZ-team group exists in Authifi.
(Optional) A document template uploaded to Document Templates containing a blank certificate form, or omit it and have the user upload a certificate directly from the training provider.

Workflow Settings¶

When creating the workflow, configure these fields in the designer:

Field	Value
Name	e.g. "Project Onboarding"
Category	`user`
Subject Variable	`user` (auto-created)
Error Strategy	`stop`
Trigger	`manual`

When you select the user category, the designer automatically creates a context variable named user of type User and selects it as the subject variable. Every run of this workflow is tracked against that user. Administrators can view all onboarding activity for a person via GET /api/users/:id/workflow-activity, and runs can be filtered with GET /api/runs?subjectType=user&subjectId=....

Context Variables¶

The user variable is auto-created when you select the user category. Add these additional variables:

Name	Type	Required	Description
`user`	User	yes	The person being onboarded to the project (auto-created, workflow subject)
`approver`	User	yes	The person who reviews the training certificate

User variables support dot-notation to access attributes: {{user.email}}, {{user.id}}, {{user.displayName}}, etc.

Workflow Steps¶

#	Step Name	Type	Purpose
1	Start	`start`	Entry point
2	Send Project Invitation	`notification`	Sends invitation email; pauses until the user accepts or rejects
3	Check Invitation Response	`condition`	Branches on whether the user accepted
4	Request Training Certificate	`document_submission`	Asks the user to complete online training and upload their certificate; routes to approver
5	Add to XYZ-Team	`connector`	Calls Authifi `addToGroup` to provision the user in the XYZ-team group
6	Send Welcome Email	`notification`	Sends a welcome message confirming access has been granted
7	Send Rejection Notice	`notification`	Sends an email if the training certificate is rejected
8	Send Declined Notice	`notification`	Sends an email if the user declined the invitation
9	End	`end`	Exit point

Flow Diagram¶

Start
  │
  ▼
Send Project Invitation (notification, requiresAcceptance)
  │
  ▼
Check Invitation Response (condition: acceptance_status == "accepted")
  │
  ├── true ──►  Request Training Certificate (document_submission)
  │               │
  │               ├── success ──► Add to XYZ-Team (connector: authifi.addToGroup)
  │               │                  │
  │               │                  └──► Send Welcome Email (notification) ──► End
  │               │
  │               └── error ──► Send Rejection Notice (notification) ──► End
  │
  └── false ──► Send Declined Notice (notification) ──► End

Step-by-Step Configuration¶

Step 2: Send Project Invitation¶

Config Field	Value
Type	`notification`
Recipient Type	Internal User
Recipient User	`{{user.id}}`
Subject Override	`You've been invited to join Project XYZ`
Custom Body	`You have been invited to join Project XYZ. Before we can grant access, you will need to complete a required training course. Click the link below to accept this invitation and begin the process.`
Require User Acceptance	Checked (true)
Acceptance Expiry (hours)	`72`
Next Step	Check Invitation Response

The workflow pauses here with status waiting_acceptance until the recipient clicks the acceptance link in the email.

Step 3: Check Invitation Response¶

Config Field	Value
Type	`condition`
Expression	`acceptance_status == "accepted"`
True → Go To	Request Training Certificate
False → Go To	Send Declined Notice

Step 4: Request Training Certificate¶

Config Field	Value
Type	`document_submission`
Document Label	`Training Completion Certificate`
Instructions	`Complete the Project XYZ safety training at https://training.example.com/xyz-course and upload your certificate of completion as a PDF.`
Template URL	`https://training.example.com/xyz-course`
Submitter Email	`{{user.email}}`
Submitter User ID	`{{user.id}}`
Allowed MIME Types	`application/pdf, image/*`
Max File Size	`5242880` (5 MB)
Approvers	`{{approver.id}}`
Notify Submitter	Checked
Notify Approvers	Checked

The workflow pauses at waiting_submission until the user uploads their certificate. Once uploaded, it transitions to waiting_approval and the approver is notified. The approver reviews the document and approves or rejects.

success transition (approved) → Add to XYZ-Team
error transition (rejected) → Send Rejection Notice

Note: The templateUrl field is used here to provide a link to the online training course rather than a downloadable form. The submitter sees an "Open Form" link that opens the training site in a new tab. If you have a blank certificate template stored in Document Templates, use templateId instead.

Step 5: Add to XYZ-Team¶

Config Field	Value
Type	`connector`
Connector	`authifi`
Command	`addToGroup`
groupId	(use the autocomplete lookup to select the `XYZ-team` group)
userId	`{{user.id}}`
role	`member`
Create user profile if missing	Checked
userEmail	`{{user.email}}`
identityIssuer	`{{user.upstreamIssuer}}`
Output Key	`authifiResult`
Next Step	Send Welcome Email

The groupId field uses the Authifi group autocomplete — start typing the group name and select it from the dropdown. The designer queries the connected Authifi instance for matching groups, so you don't need to know the numeric ID.

With createIfMissing enabled, if the user doesn't already have an account in the target Authifi tenant, one is provisioned automatically before the group membership is added.

Step 6: Send Welcome Email¶

Config Field	Value
Type	`notification`
Recipient Type	Internal User
Recipient User	`{{user.id}}`
Subject Override	`Welcome to Project XYZ!`
Custom Body	`Your training certificate has been approved and you have been added to the XYZ team. You now have access to Project XYZ resources. Welcome aboard!`
Require User Acceptance	Unchecked (false)
Next Step	End

Step 7: Send Rejection Notice¶

Config Field	Value
Type	`notification`
Recipient Type	Internal User
Recipient User	`{{user.id}}`
Subject Override	`Training certificate not approved`
Custom Body	`Your submitted training certificate for Project XYZ was not approved. Please review the feedback, retake the training if needed, and contact your project manager for next steps.`
Require User Acceptance	Unchecked (false)
Next Step	End

Step 8: Send Declined Notice¶

Config Field	Value
Type	`notification`
Recipient Type	Internal User
Recipient User	`{{user.id}}`
Subject Override	`Invitation to Project XYZ declined`
Custom Body	`We received your response declining the invitation to Project XYZ. If this was a mistake or you change your mind, please contact your project manager.`
Require User Acceptance	Unchecked (false)
Next Step	End

Wiring the Graph¶

In the graph editor, connect the steps:

Start → Send Project Invitation
Send Project Invitation → Check Invitation Response
Check Invitation Response → true → Request Training Certificate
Check Invitation Response → false → Send Declined Notice
Request Training Certificate → success → Add to XYZ-Team
Request Training Certificate → error → Send Rejection Notice
Add to XYZ-Team → Send Welcome Email
Send Welcome Email → End
Send Rejection Notice → End
Send Declined Notice → End

Starting a Run¶

Start the workflow manually or via API with the required variables. For user-type variables, supply the user's ID; the engine resolves it to a full user object before execution begins.

{
  "variables": {
    "user": "uuid-of-user",
    "approver": "uuid-of-approver-user"
  }
}

Because the workflow category is user and the subject variable is user, the engine automatically sets subject_type = "user" and subject_id on the run record. This allows efficient lookups like "show all runs for this person."

Runtime Walkthrough¶

The engine sends an invitation email to user.email (jane.doe@example.com) with an accept/reject link. The run pauses.
Jane clicks the link and accepts. The engine resumes.
The condition checks acceptance_status == "accepted" → true.
The engine reaches Request Training Certificate. Jane receives an email asking her to complete the training. The task appears in her My Tasks inbox with a link to the training course and an upload area.
Jane completes the online training, downloads her certificate PDF, and uploads it. The system stores the document and creates an approval record.
The approver receives a notification and sees the pending approval in My Tasks > Approvals. They download Jane's certificate, review it, and click Approve.
The engine resumes and calls the Authifi connector's addToGroup command, adding Jane to the XYZ-team group (provisioning her account if needed).
Jane receives a welcome email confirming her access.
The run completes.

If Jane had declined the invitation at step 2, she would receive a "declined" notice and the workflow would end. If the approver rejected the certificate at step 6, Jane would receive a rejection notice and the workflow would end without granting access.