# Components

The Onboarded™ package includes Lightning Web Components and Visualforce pages that provide user-facing functionality for managing and completing onboarding tasks.

> **Terminology — Workflow vs. Placement:** The user-facing labels on these components refer to "Workflows" rather than "Placements." The underlying Salesforce object (`Onboarded_Placement__c`), its fields (`placement_id`, etc.), and the Onboarded™ API object name (`placement`) are unchanged. When you configure object mappings, field mappings, Flows, or scheduled jobs, you will still see and reference "Placement"; when HR users interact with the components, they see "Workflow."


## Employee Tasks Component

Displays a list of onboarding tasks assigned to employees. Users can view their tasks and complete them through an embedded modal without leaving Salesforce.

### Key Features

- **Color-Coded Status:** Tasks display with visual indicators (red for overdue, orange for due soon)
- **Embedded Task Completion:** Opens Onboarded task forms in an iframe modal
- **Manual Refresh:** Sync button to fetch latest tasks from Onboarded API
- **Auto-reload:** Task list refreshes automatically after completing a task
- **User Context:** Automatically shows tasks for the logged-in user


### Setup Instructions

1. **Add to User Record Page.** Navigate to **Setup** → **Object Manager** → **User** → **Lightning Record Page**. Click **Edit** on your User record page layout.
2. **Drag Component to Page.** Find **Employee Tasks** in the Custom components section. Drag it to your desired location on the page (typically in a tab or bottom section).
3. **Save and Activate.** Click **Save** and activate the page for your users.


> **Tip:** This component can also be added to Lightning Community pages for external users to access their tasks.


## Employee Onboarded Component

The comprehensive hub for managing employee onboarding. Displays Workflows, form requirements, task progress, and provides controls for creating Workflows/tasks and syncing with Onboarded™.

### Key Features

- **Workflow Management:** View all employee Workflows in collapsible accordions
- **Form Requirements:** See required forms for each Workflow with progress indicators
- **Task Tracking:** Displays both Workflow-specific and general employee tasks
- **Create Operations:** Create new tasks and Workflows directly from the component
- **Link Sharing:** Generate shareable links for employees to complete tasks
- **Manual Sync:** Sync button to fetch latest data from Onboarded API
- **Send to Onboarded:** Push unmapped employee records to Onboarded system


### Configuration Options

| Property | Type | Required | Default | Description |
|  --- | --- | --- | --- | --- |
| Hide Create Task Button | Boolean | No | false | When enabled, hides the "Create Task" button from the UI. |
| Hide Create Workflow Button | Boolean | No | false | When enabled, hides the "Create Workflow" button from the UI. |
| Hide Send to Onboarded Button | Boolean | No | false | When enabled, hides the "Send to Onboarded" button and displays an informational message instead. Use this when automated Flows create employees to prevent race conditions. |
| Workflows to Show | Integer | No | 3 | Number of Workflows visible before scrolling. Additional Workflows are accessible by scrolling. |
| Show Error Logs | Boolean | No | false | When enabled, displays recent error logs (last 30 days) for the employee and each Workflow as a collapsible inline panel. |
| View Document Custom Permission API Name | String | No | (blank) | Optional. The DeveloperName of a Custom Permission. When set, the View Document button on completed task rows is shown only to users who have BOTH this Custom Permission AND the Onboarded™ HR Representative permission set. Leave blank to keep the default visibility. See Custom Permission Button Gating below for details. |
| Employer Task Custom Permission API Name | String | No | (blank) | Optional. The DeveloperName of a Custom Permission. When set, the Employer Task button is shown only to users who have BOTH this Custom Permission AND the Onboarded™ HR Representative permission set. Leave blank to keep the default visibility. See Custom Permission Button Gating below for details. |


### Setup Instructions

1. **Add to Record Page.** Navigate to **Setup** → **Object Manager** → Select your Employee object (e.g., `Onboarded_Employee__c`, `Contact`, etc.). Go to **Lightning Record Pages** and edit your record page layout.
2. **Drag Component to Page.** Find **Employee Onboarded** in the Custom components section. Drag it to your desired location (typically in a tab or full-width section).
3. **Configure Properties (Optional).** In the component properties panel:
  - Check **Hide Create Task Button** if you want to restrict task creation
  - Check **Hide Create Workflow Button** if you want to restrict Workflow creation
  - Check **Hide Send to Onboarded Button** if automated Flows create employees (see use case below)
4. **Save and Activate.** Click **Save** and activate the page.


> **Important:** This component works on Employee, Employer, Job, or Placement record pages. Ensure your object has the necessary field mappings configured in Onboarded Setup. If you're working with a single Placement (Workflow) record, consider also using the Workflow Onboarded component for a single-Workflow view — see Workflow Onboarded Component below.


The component performs several prerequisite checks before it appears on a record page. If any check fails — for example, the running user is not assigned the Onboarded™ HR Representative or Onboarded™ Admin permission set, the host record does not yield an Onboarded™ employee mapping, or the current context (such as a Business Account in a Person-Account-enabled org) does not match what the component supports — the component is suppressed entirely and will not render on the page. The states below describe what users see when the prerequisites are met.

### Component States

#### Wrong Object

- **When:** Component is placed on an unsupported object
- **Display:** Error message explaining component placement requirements
- **Action:** Move component to a supported object record page


#### No Employee ID (Button Visible)

- **When:** Record exists but has no Onboarded Employee ID, and `Hide Send to Onboarded Button` is **disabled** (default)
- **Display:** "Send to Onboarded" button
- **Action:** Click button to create employee record in Onboarded system


#### No Employee ID (Button Hidden)

- **When:** Record exists but has no Onboarded Employee ID, and `Hide Send to Onboarded Button` is **enabled**
- **Display:** Informational message: "This record does not yet have an Onboarded Employee ID. The ID will be assigned automatically when the record is synced to Onboarded."
- **Use Case:** Organizations using automated Flows to create employees should enable this setting. When a Flow creates an employee record and queues it for sync, there is a brief period before the queueable job fires. During this window, users might click "Send to Onboarded" manually, causing a race condition or duplicate record. Hiding the button prevents this scenario.
- **Action:** No user action required. The employee will be synced automatically by the scheduled process or Flow.


#### Full UI (Normal Operation)

- **When:** Record has Onboarded Employee ID
- **Display:** Full interface with Workflows, tasks, and all controls
- **Actions Available:**
  - View Workflows and form requirements
  - Assign forms to employees (creates a Task in Onboarded™)
  - Create new tasks and Workflows
  - Generate Workflow-wide task links (Get Tasks Link button) and per-task links (Get Link button)
  - Open employer-action tasks inline through the Employer Task button
  - View stored PDFs of completed tasks through the View Document button
  - Unlock specific form sections on a completed task through the Unlock Task button
  - Sync with the Onboarded™ API


## Workflow Onboarded Component

A focused, single-Workflow view for tracking and completing the tasks that belong to one Onboarded™ Workflow. Unlike the Employee Onboarded component — which shows every Workflow tied to an employee — this component lives on a record page for any object that stores an Onboarded™ Placement ID (such as your custom Hire, Assignment, or Offer record) and presents only that Workflow's tasks.

### Key Features

- **Single-Workflow Focus:** Renders the tasks for one Workflow on whatever record page you place the component on
- **Header Resolution:** Automatically displays "Employee Name — Job Name" derived from the Workflow record, with optional override (see Configuration Options)
- **Per-Task Actions:** Surfaces Assign, Get Link, Employer Task, View Document, and Unlock Task buttons inline (see Task Row Actions below)
- **Workflow-Level Get Tasks Link:** Generates a single onboarding URL covering all assigned tasks for the Workflow
- **Inline Error Logs:** Optional collapsible panel showing the last 30 days of Onboarded™ Error Log entries for the Workflow record
- **Strict Permission Gating:** Optional Custom Permission gates for sensitive buttons (View Document and Employer Task)


### Configuration Options

| Property | Type | Required | Default | Description |
|  --- | --- | --- | --- | --- |
| Placement ID Field API Name | String | Yes | — | API name of the field on the host record that stores the Onboarded™ Placement ID (e.g., `Onboarded_Id__c`). The component reads this field to resolve which Workflow's tasks to display. |
| Placement Name Field API Name | String | No | (blank) | Optional. API name of a field on the host record to use as the Workflow header. This is the admin-customizable Workflow name. **If populated:** the field's value is displayed as the Workflow header (you can use a Text field, a formula field that produces a human-readable name, or a relationship field path like `Account.Title`). **If blank or the field value is empty:** the component falls back to a computed header in the form "Employee Name — Job Name" using the mapped fields on the underlying Workflow (Placement) record. |
| Show Error Logs | Boolean | No | false | When enabled, displays a collapsible panel of recent Onboarded™ Error Log entries (last 30 days) for the Workflow record. |
| View Document Custom Permission API Name | String | No | (blank) | Optional. The DeveloperName of a Custom Permission. When set, the View Document button on completed task rows is shown only to users who have BOTH this Custom Permission AND the Onboarded™ HR Representative permission set. Leave blank to keep the default visibility. See Custom Permission Button Gating below. |
| Employer Task Custom Permission API Name | String | No | (blank) | Optional. The DeveloperName of a Custom Permission. When set, the Employer Task button is shown only to users who have BOTH this Custom Permission AND the Onboarded™ HR Representative permission set. Leave blank to keep the default visibility. See Custom Permission Button Gating below. |


### Setup Instructions

1. **Add to Record Page.** Navigate to **Setup** → **Object Manager** → select the object that hosts your Workflow records (this could be `Onboarded_Placement__c` directly, or any custom object where you store an Onboarded™ Placement ID). Open **Lightning Record Pages** and edit your record page layout.
2. **Drag Component to Page.** Find **Workflow Onboarded** in the Custom components section and drag it to your desired location on the page.
3. **Configure the Placement ID Field.** In the component properties panel, populate **Placement ID Field API Name** with the field on this record that stores the Onboarded™ Placement ID (for example, `Onboarded_Id__c` on `Onboarded_Placement__c`, or your custom field on a Hire/Offer object).
4. **Configure Optional Properties.** Populate **Placement Name Field API Name** if you want to override the default "Employee Name — Job Name" header. Enable **Show Error Logs** for inline visibility into recent sync failures. Populate the two Custom Permission properties if you want strict gating on the View Document and Employer Task buttons.
5. **Save and Activate.** Click **Save** and activate the page for your users.


> **Tip:** The component can be placed on any object whose record has a field that stores an Onboarded™ Placement ID. Common hosts include `Onboarded_Placement__c`, your custom Hire/Offer object, or a junction record created via the Junction Object pattern (see the Junction Object Patterns page).


Like the Employee Onboarded component, the Workflow Onboarded component performs prerequisite checks before it appears on a record page. If the user lacks the required permission set, or the host record does not have an Onboarded™ Placement ID populated in the configured field, the component will display a configuration message or be suppressed entirely.

## Task Row Actions

Each task in the Employee Onboarded and Workflow Onboarded components is rendered as a self-contained Task Row. The row chooses which action buttons appear based on the task's state and the running user's permissions. Because every task is rendered the same way regardless of which component you reach it through, HR users see consistent affordances whether they navigate to a task from the Employee record or from the Workflow record.

### Available Actions

| Button | When It Appears | What It Does | Permission |
|  --- | --- | --- | --- |
| **Assign** | Unassigned form requirement (Workflow Onboarded component) | Creates a Task in Onboarded™ from the form requirement, then refreshes the Workflow's task list. | Onboarded™ HR Representative |
| **Get Link** | Incomplete task (non-employer-action) | Opens the OTP Configuration modal (choose whether to require one-time-password verification, select email or SMS delivery, and choose Employee or Employer assignee). On submit, generates a single-task onboarding URL and presents it in a copy-to-clipboard modal. | Onboarded™ HR Representative |
| **Employer Task** | Incomplete task where the next required action is by an employer (`next_action = "employer_action"`) | Opens the task in an inline iframe modal so HR users can complete it without leaving Salesforce. For I-9 tasks, the click also triggers a background refresh of the Work Authorization Expiration date (see Authorized Until Enrichment below). | Onboarded™ HR Representative; gated by `employerTaskCustomPermission` if configured. |
| **View Document** | Completed task with a stored PDF | Fetches the rendered PDF of the completed task and opens it in a new browser tab. | Onboarded™ HR Representative; gated by `documentViewCustomPermission` if configured. Requires **PDF Storage** to be enabled (see the PDF Storage page). |
| **Unlock Task** | Completed task with a form | Opens the Unlock Task modal showing each section of the form. The HR user checks one or more sections to unlock; on submit, the component issues an unlock request for each selected section. The row optimistically reverts to "incomplete" state on first success, and a toast reports all-succeeded, partial success, or all-failed. | Onboarded™ HR Representative |


> **Unlock behavior:** Unlock requests are processed asynchronously by Onboarded™. The task row optimistically shows the task as incomplete (with a Get Link button) immediately after a successful unlock request, but the authoritative new state propagates back through the next sync cycle.


### Custom Permission Button Gating

Both the Employee Onboarded and Workflow Onboarded components expose two optional *strict gate* properties for buttons that surface candidate or employee PII: **View Document Custom Permission API Name** and **Employer Task Custom Permission API Name**. Each property takes the DeveloperName of a Custom Permission you have created in your org.

When a property is **blank**, the corresponding button is visible to any user with the Onboarded™ HR Representative or Onboarded™ Admin permission set (the default behavior). When a property is **populated**, the button is shown only to users who have BOTH the Onboarded™ HR Representative permission set AND the named Custom Permission. Neither the Onboarded™ Admin permission set nor the System Administrator profile alone bypass this gate — gating is strict and intentional, so that PII access can be audited at the Custom Permission level.

### Authorized Until Enrichment (I-9 Tasks)

When an HR user clicks the Employer Task button on an I-9 task, the application opportunistically refreshes the task's Work Authorization Expiration date from Onboarded™. If you have mapped a Task field to `authorized_until` in Object & Field Mapping, the application writes the latest expiration date returned by Onboarded™ to your Salesforce Date field. The refresh runs in the background and never blocks the user; if the API call fails or the mapping is incomplete, the click still opens the task as expected and any failure is recorded in the Onboarded™ Error Log for review.

## Mass Action Page (Visualforce)

Enables HR representatives to complete tasks that require employer action. This Visualforce page is designed to work with tasks where `next_action = "employer_action"` — tasks that need an HR user to perform an action before the employee can continue. Admins configure this as a list view quick action button.

### Key Features

- **Employer Action Tasks:** Designed for tasks requiring HR/employer completion
- **List View Integration:** Works as a quick action button on Task list views
- **Auto-open in New Tab:** Automatically opens the task URL in a new browser tab
- **Pop-up Detection:** Alerts users if browser blocks the new window
- **Auto-redirect:** Returns to the task list after opening the URL


### Setup Instructions

1. **Create List View Button.** Navigate to **Setup** → **Object Manager** → **Onboarded_Task__c** (or your mapped task object). Go to **Buttons, Links, and Actions** → **New Button or Link**.
2. **Configure Button.**
| Setting | Value |
|  --- | --- |
| Label | `Start Task` (or your preferred label) |
| Name | `Start_Task` |
| Display Type | List Button |
| Behavior | Display in existing window without sidebar or header |
| Content Source | Visualforce Page |
| Content | `MassActionPage` |
Click **Save**.
3. **Add Button to List View Layout.** Go to **Search Layouts** for the Task object. Edit **List View** layout. Add your new button to the **Selected Buttons** section. Click **Save**.
4. **Test the Button.** Navigate to a Task list view (consider creating a view filtered to `next_action = "employer_action"`). Select a task record that requires employer action. Click your new "Start Task" button. The task should open in a new browser tab for the HR rep to complete.


> **Pop-up Blockers:** Ensure users allow pop-ups from your Salesforce domain. The page will alert users if pop-ups are blocked and provide the URL for manual access.


## Component Comparison

| Component | Type | Primary Use | Placement | Configuration |
|  --- | --- | --- | --- | --- |
| Employee Tasks | LWC | View and complete employee tasks | User record page, Community | None |
| Employee Onboarded | LWC | Manage Workflows, tasks, syncs | Employee/Employer/Job/Placement pages | Hide button properties, optional Custom Permission gates |
| Workflow Onboarded | LWC | Single-Workflow task management | Any object hosting an Onboarded™ Placement ID (custom Hire/Offer, `Onboarded_Placement__c`, etc.) | Placement ID field (required), optional name field, Show Error Logs, optional Custom Permission gates |
| Mass Action Page | Visualforce | Complete employer action tasks | Task list view button | Button label customization |


## Best Practices

### Permission Management

- Only users with **Onboarded Admin** or **Onboarded HR Representative** permission sets can see these components
- The **Employee Onboarded** component checks permissions at runtime and hides if insufficient
- Assign appropriate permission sets based on user roles


### Component Placement

- Place the **Employee Onboarded** component in a dedicated tab (e.g., "Onboarding") for better organization
- Consider creating record page variants for different user profiles
- Use the **Hide Create Task Button** and **Hide Create Workflow Button** properties for users who should only view data


For more granular gating of sensitive buttons (View Document and Employer Task) that surface employee PII, see Custom Permission Button Gating above — you can require both the Onboarded™ HR Representative permission set AND a Custom Permission for visibility, which gives you per-user audit-friendly control.

### User Training

- Train users on the "Sync Now" button to refresh data when needed
- Explain to employees/candidates what the color-coding of tasks represents (red = overdue, orange = due soon)
- Show users how to generate and share task links with employees/candidates
- Demonstrate the Mass Action button for completing tasks that require employer action