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

# Onboarding Workspaces at Scale

> Onboard a single customer workspace with a profile applied automatically, or import a whole batch of customers from a CSV file.

Onboard customers one at a time or hundreds at once, and have each new workspace land already configured. Pick a **Workspace Profile** during onboarding and ContraForce applies its access, module, notification, and Gamebook settings as soon as the workspace exists.

<Info>
  **Who is this for?**

  * MSP/MSSP partners bringing on new customers
  * Organizational Admins and Workspace Admins responsible for onboarding
</Info>

***

## What Can You Do Here?

<CardGroup cols={3}>
  <Card icon="user-plus" title="Onboard One Customer">
    Add a workspace and pick the profile that should configure it.
  </Card>

  <Card icon="file-csv" title="Import a Batch">
    Upload a CSV and pre-onboard up to 200 workspaces in one action.
  </Card>

  <Card icon="list-check" title="Watch Every Row">
    Track each import row's outcome and re-import only what failed.
  </Card>
</CardGroup>

***

## Prerequisites

| Requirement                                 | Description                                                                                                                             |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **Organizational Admin or Workspace Admin** | Required to onboard workspaces and run imports.                                                                                         |
| **Customer tenant IDs**                     | You need each customer's Microsoft Entra tenant ID.                                                                                     |
| **A Workspace Profile (optional)**          | Only needed if you want new workspaces configured automatically. See [Workspace Profiles](/guides/fleet-management/workspace-profiles). |

***

## Onboarding a Single Workspace with a Profile

<Steps>
  <Step title="Open the Onboarding tab">
    From the left navigation, select **Workspaces**, then click the **Onboarding** tab.
  </Step>

  <Step title="Click Add workspace">
    The **Add a workspace** panel opens.
  </Step>

  <Step title="Identify the customer tenant">
    | Field                               | Description                                                                                    |
    | ----------------------------------- | ---------------------------------------------------------------------------------------------- |
    | **Workspace name**                  | Display name for this workspace. Enter a domain and ContraForce looks up the tenant ID for you |
    | **Tenant ID**                       | The customer's Microsoft Entra tenant ID                                                       |
    | **Customer admin email** (optional) | Where the invite link is sent. You can use your own email                                      |
    | **Workspace profile** (optional)    | The profile that should configure this workspace once it is created                            |
  </Step>

  <Step title="Finish the wizard">
    Choose the modules to seed on the next step and send the invite. The workspace appears on the **Onboarding** tab with a pending badge.
  </Step>
</Steps>

<Frame caption="Choosing a Workspace Profile while adding a workspace">
  <img src="https://mintcdn.com/contraforce/VGCdp5T8nvIgjDl-/images/fleet-management/onboard-with-profile.png?fit=max&auto=format&n=VGCdp5T8nvIgjDl-&q=85&s=35729bf5de2f0dbf6743e46e565158cc" alt="Add a workspace panel with the Workspace profile dropdown selected" width="885" height="1172" data-path="images/fleet-management/onboard-with-profile.png" />
</Frame>

The profile's access, notification, Gamebook approver, and module settings are applied once the workspace is created. You do not need to apply the profile by hand.

<Note>
  If the profile's modules would move the workspace onto a higher-priced plan, that part is left for you to confirm. Open the profile, click **Apply**, and acknowledge the charge. Creating a workspace is never treated as consent to a recurring charge.
</Note>

<Tip>
  Agent policy lands after an agent exists for the workspace. If the profile is set to **Provision**, ContraForce creates the agent for you. See [Agents in a Profile](/guides/fleet-management/workspace-profiles#agents-in-a-profile).
</Tip>

***

## Importing a Batch from CSV

Use an import when you are bringing on many customers at once. Every row is pre-onboarded exactly as if you had typed it into the form.

<Steps>
  <Step title="Open the import dialog">
    From the **Workspaces** page, choose **Import workspaces**.
  </Step>

  <Step title="Download the template">
    Click **Download template** to get a CSV with the right columns and a sample row.
  </Step>

  <Step title="Fill in one workspace per row">
    Replace the sample row with your customers. The sample tenant ID is intentionally an all-zero placeholder, so a file saved without editing fails loudly instead of onboarding the wrong tenant.
  </Step>

  <Step title="Upload the file and import">
    Select the file and click **Import workspaces**. ContraForce validates the whole file before anything is created.
  </Step>

  <Step title="Watch the import">
    The import runs in the background, one row at a time. Open it to see each row's status and result.
  </Step>
</Steps>

<Frame caption="Import workspaces dialog">
  <img src="https://mintcdn.com/contraforce/VGCdp5T8nvIgjDl-/images/fleet-management/bulk-import-with-csv.png?fit=max&auto=format&n=VGCdp5T8nvIgjDl-&q=85&s=97f08413fd979408bb6d750f646a3883" alt="Import workspaces dialog with template download and file picker" width="1257" height="1365" data-path="images/fleet-management/bulk-import-with-csv.png" />
</Frame>

### CSV columns

| Column           | Required | Description                                                                                   |
| ---------------- | -------- | --------------------------------------------------------------------------------------------- |
| **Tenant name**  | Yes      | The customer's display name in ContraForce                                                    |
| **Tenant ID**    | Yes      | The customer's Microsoft Entra tenant ID, as a GUID                                           |
| **Profile name** | No       | The Workspace Profile that should configure this workspace. Must match a profile name exactly |
| **Admin email**  | No       | Where the invite link is sent for this customer                                               |

```csv theme={null}
Tenant name,Tenant ID,Profile name,Admin email
Contoso Ltd,3f2504e0-4f89-11d3-9a0c-0305e82c3301,Managed XDR baseline,admin@contoso.example
Fabrikam Inc,7c9e6679-7425-40de-944b-e07fc1f90ae7,Managed XDR baseline,admin@fabrikam.example
```

<Tip>
  Column **order does not matter**, and ContraForce recognizes the usual header spellings (`Tenant ID`, `tenantid`, `Directory ID`, and similar). Comma, semicolon, and tab-separated files all work, so a spreadsheet exported from a European locale imports without editing.
</Tip>

### Limits

| Limit              | Value          |
| ------------------ | -------------- |
| Rows per import    | 200            |
| File size          | 512 KB         |
| Tenant name length | 200 characters |

### What is validated before anything is created

| Check                                        | Behavior                                                                |
| -------------------------------------------- | ----------------------------------------------------------------------- |
| **Missing name or tenant ID**                | That row fails; the rest of the file still imports                      |
| **Tenant ID is not a valid GUID**            | That row fails rather than being guessed at                             |
| **Duplicate tenant ID in the file**          | Flagged against the later row, naming the earlier row it duplicates     |
| **Row numbers**                              | Count the header as row 1, so they match your spreadsheet's row numbers |
| **Tenant not recognized in Microsoft Entra** | Shown as a warning only. The row still imports                          |

***

## Tracking an Import

Each import has its own activity page listing every row with its outcome.

| Row status    | Meaning                                                         |
| ------------- | --------------------------------------------------------------- |
| **Queued**    | Waiting its turn                                                |
| **Running**   | Being created now                                               |
| **Succeeded** | The workspace was created and appears on the **Onboarding** tab |
| **Failed**    | The row could not be created, with the reason shown on the row  |

Rows are processed one at a time, so a large import takes a few minutes. Successful rows are created immediately, so you do not have to wait for the whole file to finish before working with them.

If an import stops making progress, a **Resume** option appears after a few minutes. Resuming picks up where the import left off and never re-creates a workspace that already exists.

<Warning>
  Do not re-upload the whole file to fix a few failures. Create a new CSV containing only the failed rows. Re-importing an existing tenant is rejected as a duplicate.
</Warning>

***

## What Happens Next

Importing pre-onboards each customer. The customer admin still completes their own setup wizard using the invite link.

<Steps>
  <Step title="The customer admin accepts the invite">
    They grant ContraForce access to their Microsoft tenant. See [Customer Workspace Onboarding](/guides/onboarding/customer-workspace-onboarding).
  </Step>

  <Step title="The workspace goes live">
    The card moves from the **Onboarding** tab to the **Workspaces** tab.
  </Step>

  <Step title="Verify the profile landed">
    Open the profile and check the **Activity** tab. Anything still waiting shows as not yet on the current version. Click **Apply now**.
  </Step>
</Steps>

***

## Troubleshooting

| Issue                                   | Cause                                                  | Solution                                                                      |
| --------------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------- |
| "Missing Tenant ID column"              | The header row was not recognized                      | Start from **Download template** and keep the header row intact               |
| Every row failed with a tenant ID error | The tenant ID column holds names or truncated values   | Confirm each value is a full Microsoft Entra tenant GUID                      |
| Profile name not matched                | The name in the CSV does not match a profile exactly   | Copy the name from the **Profiles** tab, including spacing and capitalization |
| Row failed with a plan charge message   | The workspace is beyond your plan's included allowance | Re-import that row once the additional charge is acknowledged                 |
| Import stuck at Running                 | The import stalled                                     | Wait for the **Resume** option to appear, then resume it                      |
| Workspaces created but not configured   | The profile has not been applied yet                   | Open the profile and click **Apply**, acknowledging any charge in the preview |

Still stuck? Contact [support@contraforce.com](mailto:support@contraforce.com) with the import file and the row numbers that failed.

***

## Related Guides

<CardGroup cols={2}>
  <Card icon="layer-group" href="/guides/fleet-management/workspace-profiles" title="Workspace Profiles">
    Build the template that configures every new workspace.
  </Card>

  <Card icon="grid-2" href="/guides/getting-started/workspace-manager" title="Workspace Center">
    Monitor workspace health and manage per-workspace settings.
  </Card>

  <Card icon="user-check" href="/guides/onboarding/customer-workspace-onboarding" title="Customer Workspace Onboarding">
    What your customer admin sees after they receive the invite.
  </Card>

  <Card icon="clipboard-check" href="/guides/onboarding/workspace-onboarding-checklist" title="Onboarding Verification">
    Confirm a new workspace is fully live and ingesting.
  </Card>
</CardGroup>

***

Questions about onboarding at scale? Contact us at [support@contraforce.com](mailto:support@contraforce.com).