Skip to content

Updated the Flatfile importer #421

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sriramveeraghanta merged 2 commits into from
Mar 27, 2026
Merged

Updated the Flatfile importer #421

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d8d997c
Updated the Flatfile importer
danciaclara Mar 27, 2026
7f8cbc9
formatting fixes
danciaclara Mar 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion docs/importers/csv.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,10 @@ Update vendor contracts,,medium,2025-04-05,2025-04-20,unstarted
Office supply restock,,low,,,backlog
```

:::tip
Save your CSV file with UTF-8 encoding.
:::

A few things to note:

- **description_html** supports HTML markup. Plain text works too, but wrap it in `<p>` tags if you want paragraph formatting preserved.
Expand All @@ -45,7 +49,7 @@ Make sure your CSV is properly formatted before uploading. Malformed rows or mis

2. Find the **CSV** tile and click **Import**.

![CSV Importer](https://media.docs.plane.so/csv-importer/csv-importer-landing.webp#hero)
![CSV Importer](https://media.docs.plane.so/importers/csv/csv-importer-landing.webp#hero)

3. On the **Select Project** step, choose the Plane project where you want to import your work items. The project must already exist — create it first if needed.

Expand Down
126 changes: 93 additions & 33 deletions docs/importers/flatfile.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,59 +1,109 @@
---
title: Import data from CSV file
description: Import work items from CSV files to Plane.
description: Import work items from CSV files to Plane using the Flatfile importer.
---

# Import your CSV data to Plane

With the Flatfile importer, you can easily import work items from your CSV file to Plane.
The Flatfile importer provides a streamlined way to bring your work items into Plane from CSV files. With intelligent field mapping and data validation, you can migrate your data accurately and efficiently.

::: info
The Flatfile importer is only available on Plane Cloud. A separate [CSV importer](/importers/csv) is available on both Cloud and the self-hosted Commercial Edition.
The Flatfile importer is only available on Plane Cloud. If you're using the self-hosted Commercial Edition, use the [CSV importer](/importers/csv) instead.
:::

## Import from CSV

> **Role**: Workspace admins

::: warning Work Item Types
To import work item types, make sure the [Work item types](/core-concepts/issues/issue-types) feature is enabled in your Plane project.
:::

Here's how to get started:

1. Click your Workspace name at the top left on the sidebar.

2. Select **Settings**.

3. In the right pane, click on **Imports**.
3. In the right pane, click **Imports**.

4. Look for the **Flatfile Importer** tile (marked Beta) and click the **Import** button.

![Flatfile Importer on Imports page](https://media.docs.plane.so/importers/flatfile/flatfile-imports-page.webp#hero)

5. **Configure your destination project**

Select the Plane project where you want your CSV data to go. If you haven't created your destination project yet, you'll need to create it first before proceeding.

![Configure Plane project](https://media.docs.plane.so/importers/flatfile/configure-plane.webp#hero)

Click **Next** to continue.

6. **Upload your CSV file**

Click **Upload CSV** to begin the upload process.

![Upload CSV screen](https://media.docs.plane.so/importers/flatfile/upload-csv.webp#hero)

You can either drag and drop your file onto the upload area, click to browse your files, or manually enter data if you prefer to input information directly.

::: tip Sample CSV template
Download our [sample CSV file](https://media.docs.plane.so/importers/flatfile/flatfile-import-sample.csv) to see the correct format and field structure for importing your data.

Make sure your CSV is properly formatted before uploading. Save your CSV file with UTF-8 encoding. Malformed rows or mismatched columns may cause individual rows to fail during import.
:::

7. **Map your fields**

4. You'll see several import options - look for the **Flatfile Importer** tile and click the **Import** button.
The field mapping screen appears with two columns:
- **INCOMING FIELDS** (left): Your CSV column headers
- **DESTINATION FIELDS** (right): Corresponding Plane fields

5. Use the dropdown to select the project where you want your CSV data to go. If you haven't created your destination project yet, you'll need to create it first.
![Map fields screen](https://media.docs.plane.so/importers/flatfile/map-fields.webp#hero)

6. Click the **Upload CSV** button.
The importer automatically maps fields when column names match Plane's field names. You can adjust any mapping by clicking the dropdown next to each incoming field.

::: warning Prepare your CSV
When importing user fields like **Assignee**, make sure to use email addresses rather than usernames. This ensures your team members are correctly linked to their work items.
Required fields are marked with an asterisk (\*).

::: warning User fields require email addresses
For fields like **Assignees** and **Created By**, you must use email addresses rather than usernames. This ensures team members are correctly linked to their work items in Plane.
:::

7. You can either drag and drop your file onto the upload area or click **Upload file** to browse your files. Alternatively, you can click **Manually enter data** if you prefer to input information directly.
8. **Validate field values**

For fields like State and Priority, you'll need to map your CSV values to valid Plane options:
- The screen shows each unique value from your CSV under "Incoming Values"
- Select the matching Plane value from the "Destination Values" dropdown
- The mapping count shows your progress (e.g., "0 of 2 values mapped")

![Validate field values](https://media.docs.plane.so/importers/flatfile/validate-fields.webp#hero)

Continue mapping until all values are matched to valid Plane options.

Click **Continue** when all fields are properly mapped.

9. **Review your data**

You'll see a table preview of your data with all mapped fields. This is your last chance to verify everything looks correct before import.

![Data preview table](https://media.docs.plane.so/importers/flatfile/data-preview.webp#hero)
- Review each row to ensure the data appears as expected
- Check that field mappings are correct
- If something's not right, click **Back** to adjust your field mapping

8. You'll need to match your CSV columns to Plane fields:
- You'll see your CSV fields listed under **INCOMING FIELDS** on the left.
- On the right, under **DESTINATION FIELDS**, select the corresponding Plane field for each item. Fields will be automatically mapped when names match, but you can adjust as needed.
- Required fields are marked with an asterisk (\*).
When you're satisfied, click **Submit** to start the import.

9. Once you've mapped your fields, click **Continue** to proceed.
10. **Track your import**

10. You'll see a preview of your data in a table view:
- Review the data to make sure everything looks correct.
- If something's not right, you can click Back to adjust your field mapping.
- When you're ready, click **Submit** to import your data.
Once submitted, your import appears in the Migrations list with:
- Status indicator (Finished, In Progress, or Failed)
- Total batches and imported batches count
- Start time
- Options to **Re Run** or **Cancel** the migration

11. That's it! Your CSV data is now imported into your Plane project. For very large datasets, the import might take a few minutes to process.
![Migrations list](https://media.docs.plane.so/importers/flatfile/migrations-list.webp#hero)

12. Once it's done, go to **Work Items** in your Plane project to confirm that the data import is successful.
For large datasets, the import might take a few minutes to process. You can monitor progress from this screen.

11. **Verify your data**

After the import shows "Finished" status, navigate to **Work Items** in your Plane project to confirm your data imported successfully.

## Imported fields

Expand All @@ -64,13 +114,23 @@ When bringing your data from CSV into Plane, here's exactly what you can transfe
| Title | Required for all items |
| Description | Plain text only - any formatting, images, or tags will be imported as raw text |
| Work Item Type | Make sure the [Work item types](/core-concepts/issues/issue-types) feature is enabled in your Plane project |
| State | |
| Assignee | **Must be email addresses**, not usernames - this is how Plane connects work items to users |
| Priority | |
| Created by | **Must be email addresses** - allows Plane to track who originally created the item |
| Start date | |
| Due date | |
| Modules | |
| Cycle | |
| State | Must map to valid states in your Plane project |
| Assignees | **Must be email addresses**, not usernames - this is how Plane connects work items to users |
| Priority | Must map to valid priority values in your Plane project |
| Created By | **Must be email addresses** - allows Plane to track who originally created the item |
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Mar 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Tighten redundant phrasing in field note.

Line 122 reads a bit verbose (“originally created the item”). Consider “track who created the item” for clarity and brevity.

🧰 Tools
🪛 LanguageTool

[style] ~122-~122: This phrase is redundant. Consider writing “created”.
Context: ...addresses** - allows Plane to track who originally created the item | | St...

(ORIGINALLY_CREATED)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/importers/flatfile.md` at line 122, Update the table cell that currently
reads "Created By | **Must be email addresses** - allows Plane to track who
originally created the item" to the tightened wording "Created By | **Must be
email addresses** - allows Plane to track who created the item"; locate the
string in docs/importers/flatfile.md (the "Created By" table row) and replace
the redundant phrase "originally created the item" with "created the item".

| Start Date | |
| Target Date | |
| Labels | |
| Cycle | |
| Module | |
| Created At | |

## Managing your imports

After completing imports, you can:

- **View import history**: All your imports appear in the Migrations list on the Flatfile Importer page.
- **Re-run imports**: Click **Re Run** if you need to import the same data again.
- **Cancel imports**: Use **Cancel** to stop an in-progress import.

This migration history helps you track when data was imported and troubleshoot any issues that arise.
2 changes: 1 addition & 1 deletion docs/workspaces-and-users/billing-and-plans.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -150,7 +150,7 @@ When you create a new Plane workspace on our Cloud, you automatically start a 14

The trial includes all Business plan features, full seat capacity for your team, and AI credits for Plane AI features. No payment method is required.

After 14 days, your workspace automatically reverts to the Free plan if you haven't upgraded to a paid subscription.
After 14 days, your workspace automatically reverts to the Free plan if you haven't upgraded to a paid subscription, and you won’t be charged if a payment method was never added.

### Free plan seat limits

Expand Down
Loading