> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firstwork.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow Mapping

> Atomic workflow references for major Firstwork processes.

## Overview

This document maps major end-to-end workflows in the platform.

## 1. Hiring Pipeline

### How Candidates Enter

* **Job posting page** — Candidate views a public job listing and clicks "Start Application"
* **Direct link** — Candidate uses a registration link shared by the company
* **Custom link** — A unique link generated by the admin for targeted outreach
* **External API** — Application created by an external system
* **Bulk import** — Applications imported in bulk by an admin

### Step-by-Step

```mermaid theme={null}
sequenceDiagram
    participant Candidate
    participant Platform
    participant Rules as Compliance Rules
    participant Auto as Automations
    participant Admin

    Candidate->>Platform: View job posting
    Candidate->>Platform: Register or log in
    Platform->>Candidate: Show first form page
    loop Each Page
        Candidate->>Platform: Fill out and submit page
        Platform->>Rules: Evaluate compliance rules
        alt Rejection
            Rules->>Candidate: Show rejection status
        else Waiting List
            Rules->>Candidate: Show waiting list status
        else Manual Review
            Rules->>Admin: Create review task
            Rules->>Candidate: Show pending status
        else Pass
            Rules->>Platform: Advance to next page
        end
        Platform->>Auto: Trigger relevant automations
    end
    Platform->>Candidate: Show completion status
    Auto->>Auto: Execute post-completion actions
```

### Key Decision Points

* **Compliance rules** on each page can redirect the candidate to rejection, waiting list, manual review, or the next stage
* **Recollection** can be triggered at any point, requiring the candidate to re-submit specific documents or fields before continuing
* **Language preference** — if the flow requires a preferred language and one hasn't been set, the candidate is redirected to select one
* **Phone number** — if phone collection is required and the candidate hasn't provided one, they are redirected to their profile

### What Happens on Failure

* **Network error during submission** — The form preserves the candidate's current input
* **Compliance rule failure** — The candidate is blocked from advancing until the issue is resolved
* **Invalid document** — Validation error is displayed and the candidate can retry
* **Session expiry** — The candidate is redirected to log in and resumes where they left off

***

## 2. Automation Execution

### How Automations Are Triggered

| Trigger         | What Starts It                                                 |
| --------------- | -------------------------------------------------------------- |
| On Change       | A field value changes (e.g., application moves to a new stage) |
| Schedule        | A recurring timer fires (daily, weekly, monthly, etc.)         |
| Webhook         | An external system sends an HTTP request                       |
| External API    | An application is created via API                              |
| Form Submission | A specific form element is submitted                           |
| Recollection    | A recollection event occurs                                    |

### Step-by-Step

1. **Trigger fires** — The system detects the triggering event
2. **Active check** — The automation is verified to be active
3. **Concurrency policy applied**:
   * *Queue* — Wait for any running instance to finish
   * *Skip* — Ignore if already running
   * *Continue* — Run immediately alongside others
4. **Conditions evaluated** — Branch and filter nodes are checked
5. **Actions executed** — Each action runs in sequence (email, status update, webhook, etc.)
6. **Results recorded** — An execution record captures status, timing, and per-action results

### What Happens on Failure

* **Action failure** — The error is logged; depending on configuration, subsequent actions may still execute
* **Webhook timeout** — The backend retries according to its retry policy
* **Invalid data reference** — The resolution failure is logged in the execution record

***

## 3. AI Caller Screening

### How Calls Are Initiated

| Source       | Description                                                  |
| ------------ | ------------------------------------------------------------ |
| Form element | Candidate reaches an AI Caller step in a hiring flow form    |
| Automation   | The "AI Caller" action triggers a call as part of a workflow |
| Admin test   | Admin initiates a test call from the bot setup interface     |

### Step-by-Step (Phone Call)

1. **Data preparation** — Input variables are resolved from the candidate's profile
2. **Call placed** — The system dials the candidate's phone number via the telephony provider
3. **Conversation** — The AI bot follows its conversation script, asks questions, and listens to responses
4. **Data extraction** — The bot captures structured answers based on its output variable definitions
5. **Call ends** — Either the conversation completes naturally or the maximum call duration is reached
6. **Post-processing** — A transcript is generated; if summarization is enabled, an AI summary is produced
7. **Data written** — Output values are mapped to form fields (if form mappings are configured)

### Step-by-Step (Audio/Video In-Browser)

The same process, except the session takes place in the candidate's browser rather than over a phone call. The candidate speaks through their device's microphone (and camera, for video).

### What Happens on Failure

* **No answer** — The enrollment is marked as failed
* **Network drop** — The session may reconnect or be marked as failed
* **Data extraction issue** — Admins can re-process the transcript to re-extract answers

***

## 4. Event Scheduling

### Step-by-Step

1. **Candidate reaches scheduling step** in their application form
2. **Available dates** are shown in a calendar view
3. **Candidate selects a date** — Available time slots for that date are loaded
4. **Candidate selects a time slot** and confirms
5. **Booking is created** and the candidate returns to the form

### Rescheduling

1. System checks whether rescheduling is allowed (a maximum may be configured)
2. Candidate selects a new date and time slot
3. The previous booking time is shown for reference
4. The booking is updated

### Cancellation

1. Candidate provides a cancellation reason
2. The booking is marked as cancelled

### Live Meeting

1. Candidate joins a meeting queue and enters a virtual waiting room
2. The waiting room shows queue position and estimated wait time
3. When admitted, a "Join Meeting" button appears
4. The video meeting opens in a new window
5. The candidate can cancel their enrollment while waiting

***

## 5. Course Completion (LMS)

### Step-by-Step

```mermaid theme={null}
sequenceDiagram
    participant Learner
    participant Platform
    participant Quiz as Quiz Engine

    Learner->>Platform: Open course enrollment
    Platform->>Learner: Show course details
    Learner->>Platform: Click "Start Course"
    loop Each Lesson
        Platform->>Learner: Display lesson content
        Learner->>Platform: Complete and submit
        alt Quiz lesson
            Platform->>Quiz: Score answers
            alt Below passing threshold
                Quiz->>Learner: Show retry page with score
                Learner->>Platform: "Try Again"
            else Passes
                Quiz->>Platform: Advance to next lesson
            end
        else Content lesson
            Platform->>Platform: Advance to next lesson
        end
    end
    Platform->>Learner: Show completion status
    Platform->>Platform: Generate certificate (if configured)
```

### What Happens on Failure

* **Mid-course exit** — Progress is saved; the learner resumes from their last lesson
* **Quiz failure** — The learner sees their score and can retry
* **Enrollment cancelled** — The learner sees a blocked status page

***

## 6. AI Agent Execution

### Step-by-Step

1. **Trigger** — The agent is triggered by an automation, a form element, a manual trigger, or a test
2. **Input resolution** — Input variables are populated with data from the application context
3. **Instruction execution** — The agent follows its instruction workflow step by step:
   * Visits URLs, clicks elements, types text, uploads files
   * For **conditional branches**: evaluates the condition and follows the appropriate path
   * For **loops**: iterates over the data array, executing child instructions for each item
   * For **AI instructions**: uses AI to determine the appropriate browser action
4. **Output capture** — Data extracted during execution is collected as output variables
5. **Completion** — The execution record is created with status, timing, and all input/output data

### What Happens on Failure

* **Element not found** — The agent halts at the failed instruction
* **CAPTCHA encountered** — The agent attempts to solve it automatically
* **Timeout** — The execution is marked as failed after the timeout period

***

## 7. Worker Onboarding

### Step-by-Step

1. **Contract created** — Via automation, admin action, or API call
2. **Worker receives notification** — An invite or email directs them to the platform
3. **Worker logs in** — They are automatically directed to their onboarding flow
4. **Form completion** — The worker fills out onboarding pages (forms, documents, signatures, etc.)
5. **Completion** — The worker transitions to active status and can access the full worker dashboard

### Recollection

If documents need to be re-submitted during or after onboarding, the worker is prompted to re-collect those items when they next log in.

***

## 8. Authentication

### Login Methods

| Method               | Description                                    |
| -------------------- | ---------------------------------------------- |
| **Email + Password** | Traditional email and password combination     |
| **Email OTP**        | A one-time password sent to the user's email   |
| **Phone OTP**        | A one-time password sent via SMS               |
| **Google Login**     | OAuth-based sign-in with Google                |
| **Dual OTP**         | Requires both email and phone verification     |
| **Magic Link**       | A one-click authentication link sent via email |
| **Invite Link**      | A pre-shared link for new user registration    |

### Registration

New candidates register by providing their name and email, with optional phone number and middle name fields (configurable per company). They can set a password or authenticate via OTP. Google sign-up is also supported if enabled.

### Password Reset

1. User requests a reset by entering their email
2. A reset link is sent to their email
3. They set a new password (minimum 8 characters, must include uppercase, lowercase, number, and special character)

### Session

Users are authenticated via secure tokens. Sessions persist until explicitly logged out or until the token expires. If a session becomes invalid, the user is redirected to the login page.