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

# Onboarding Forms

> Build reusable, structured forms that clients complete inside their portal, with optional mapping to Hudu and IT Glue

Onboarding Forms are reusable, structured data-collection definitions you build once and attach to onboarding tasks. Unlike a free-text task, a form has typed fields (text, select, date, email, and more) so the answers you collect are clean and consistent. You can also **map** form fields to your documentation platform so client answers flow into Hudu or IT Glue automatically.

<Note>
  Forms are the structured successor to linking a Survey on a task. When a form task has a form attached, clients fill out the form; if no form is attached, the task falls back to the older inline survey experience.
</Note>

## Why Use Forms

* **Collect structured data** — typed fields instead of free text, so answers are consistent across clients
* **Reuse across portals** — build a form once and attach it to any template's tasks
* **Map to documentation** — push client answers straight into Hudu asset layouts or IT Glue flexible asset types
* **Allow repeat entries** — let clients submit multiple records (e.g. one entry per location or per admin account)

## Building a Form

Forms are managed in **Settings > Onboarding > Forms**, a workspace with a list of forms on the left and the selected form's details on the right.

<Steps>
  <Step title="Open the Forms tab">
    Go to **Settings > Onboarding** and click the **Forms** tab.
  </Step>

  <Step title="Create a form">
    Click **New**. A draft form named "New Form" is created and selected.
  </Step>

  <Step title="Set form details">
    In **Form Settings**, set:

    * **Name** — the form's display name
    * **Status** — **Draft** while you build, **Active** when ready to use
    * **Repeat Entries** — toggle on (**+ One More**) to let clients submit multiple entries, or off (**Single**) for one
    * **Description** — optional context
  </Step>

  <Step title="Add fields">
    Click **Add Field** for each piece of information you want to collect. Configure each field, then click **Save**.
  </Step>

  <Step title="Save the form">
    Click **Save**. Set the status to **Active** when the form is ready to attach to tasks.
  </Step>
</Steps>

### Field Types

Each field has a **Type** that controls how clients answer it:

| Type              | Use for                      |
| ----------------- | ---------------------------- |
| **Short Text**    | Names, short identifiers     |
| **Long Text**     | Notes, descriptions          |
| **Single Select** | One choice from a list       |
| **Multi Select**  | Multiple choices from a list |
| **Yes / No**      | Boolean answers              |
| **Date**          | Dates                        |
| **Email**         | Email addresses              |
| **Phone**         | Phone numbers                |
| **Number**        | Numeric values               |
| **URL**           | Web links                    |

### Field Settings

Each field supports:

* **Label** — what the client sees
* **Required** — whether an answer is mandatory
* **Placeholder** — example text inside the input
* **Help Text** — guidance shown under the field
* **Options** — for select fields, one option per line or comma-separated
* **Key** (under **Advanced**) — an internal identifier used to store the answer; clients never see it. The key is derived from the label automatically.

<Tip>
  Write labels and help text from the client's perspective. "Microsoft 365 admin email" is clearer than "M365 UPN".
</Tip>

## Mapping Fields to Hudu or IT Glue

Mapping lets a field's answers populate your documentation platform. Each field has a **Field Mappings** subsection.

<Steps>
  <Step title="Add a mapping">
    Under a field, click **Hudu** or **IT Glue** to add a mapping for that provider.
  </Step>

  <Step title="Choose the target">
    Select the **Asset layout** (Hudu) or **Flexible asset type** (IT Glue), then pick the **Field Name** to map to. These options come from your synced documentation data — you pick from dropdowns, never type IDs.
  </Step>

  <Step title="Save">
    Click **Save** on the mapping.
  </Step>
</Steps>

<Note>
  Mapping requires synced documentation data. If you haven't run a Hudu or IT Glue sync yet, you'll see a prompt to run the documentation integration sync first, then return to map fields.
</Note>

## Attaching a Form to a Task

Forms attach to tasks in the **template builder**. When editing a task with the **Form** evidence type, select the form to attach. You can also override whether that specific task allows multiple entries.

See [Onboarding Templates](/user-guides/client-onboarding/templates) for task configuration details.

## What the Client Sees

When a client opens a form task in their portal, the form renders inline with all its fields laid out by type — dropdowns for selects, toggles for Yes/No, date pickers, and so on. Required fields are marked.

* Clients fill out the fields and click **Save Form**
* A **Saved** badge confirms the submission
* If the form allows repeat entries, submitted entries appear as chips (Entry 1, Entry 2, …) and a **One More** button lets clients add another

## Permissions

| Permission                  | Capability                  |
| --------------------------- | --------------------------- |
| `read_settings_onboarding`  | View forms                  |
| `write_settings_onboarding` | Create, edit, and map forms |

## Related Resources

<CardGroup cols={2}>
  <Card title="Onboarding Templates" icon="copy" href="/user-guides/client-onboarding/templates">
    Attach forms to tasks in your templates
  </Card>

  <Card title="Client Portal" icon="browser" href="/user-guides/client-onboarding/client-portal">
    How forms appear to your clients
  </Card>
</CardGroup>