Self-Serve Invite Link Feature — #348

This feature enables admins to generate an invite link for contractors

Admin Flow

1. Generate Invite Link

   Navigate to the People page. Click on the Invite Link button.
   
   

2. Generate or Reset Invite Link

   Confirm the reset in the dialog.
   

Contractor Flow

1. Open Invite Link

   • The contractor opens the provided invite link in their browser.

2. Authentication

   • If not already signed in, clicking Accept Invite redirects the contractor to the signup/login page.

3. Onboarding

   • After authenticating, the contractor is guided through the initial onboarding steps.

4. Document Upload

   • Once onboarding is complete, the user is redirected to the document upload page to continue the process.
   • 

5. Confirmation

   • After submitting required documents, the contractor sees a confirmation screen indicating successful onboarding.
   • 

Approach

1. Invite Link Model

A dedicated model stores invite tokens, along with the inviter, company, and an optional document template ID.

This enables tracking and management of invitations independently from users.

2. Invite Link Usage Scenarios

When a user opens an invite link, two scenarios are handled:

• a) Unauthenticated User:

  • The user is redirected to the sign-up flow.
  • The invitation_token is stored in a cookie for later use.

• b) Authenticated User:

  • The invite accept API is called immediately.
  • A company_worker entry is created for the current user, and the company context is switched.

3. Invite Acceptance and Onboarding

• For unauthenticated users:

  • After sign-up, the system detects the invitation_token and uses it to create a company_worker entry using the AcceptInviteLink service

• For authenticated users:

  • The invite is accepted directly, and the company_worker entry is created.

4. Incomplete Contractor Profile

The initial company_worker instance created from an invite is incomplete (missing role, rates, etc.).

The user is required to complete onboarding by filling out a modal form with these details.

5. Contract Creation (if applicable)

If the invite includes a document template, a contract is generated once the onboarding form is completed.

6. Completion

After onboarding, the contractor’s profile is complete, and they can access all relevant features and actions within the company workspace.

Demo

Summary by CodeRabbit

• New Features

  • Introduced contractor invite links, allowing company administrators to generate, copy, and reset invitation links for onboarding contractors.
  • Added a modal interface for managing contractor invite links, including contract options and template selection.
  • Enabled contractors to join a company via invite links, supporting both authenticated and unauthenticated flows.
  • Implemented a two-step onboarding process for contractors joining via invite links.
  • Added invite link verification and acceptance endpoints, with relevant UI feedback for invite status.

• Improvements

  • Updated the People page to include both "Invite link" and "Add contractor" options.
  • Enhanced onboarding flows to support contractors without predefined roles.
  • Improved UI elements for buttons and dialogs for consistency and clarity.

• Bug Fixes

  • Adjusted contractor listing to exclude workers without assigned roles.

• Tests

  • Added comprehensive backend, frontend, and end-to-end tests covering invite link generation, acceptance, onboarding, and UI interactions.

• Chores

  • Updated button labels from "Invite contractor" to "Add contractor" throughout the application and tests for consistency.