From d8d997cc40ead963aa5563a4ea4cfd2df0f4fe94 Mon Sep 17 00:00:00 2001 From: danciaclara Date: Fri, 27 Mar 2026 17:45:41 +0530 Subject: [PATCH 1/2] Updated the Flatfile importer --- docs/importers/csv.md | 6 +- docs/importers/flatfile.md | 129 +++++++++++++----- .../workspaces-and-users/billing-and-plans.md | 2 +- 3 files changed, 102 insertions(+), 35 deletions(-) diff --git a/docs/importers/csv.md b/docs/importers/csv.md index 143d42b..e92aaa5 100644 --- a/docs/importers/csv.md +++ b/docs/importers/csv.md @@ -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 `

` tags if you want paragraph formatting preserved. @@ -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. diff --git a/docs/importers/flatfile.md b/docs/importers/flatfile.md index 352e029..68ca18c 100644 --- a/docs/importers/flatfile.md +++ b/docs/importers/flatfile.md @@ -1,59 +1,111 @@ --- 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** -4. You'll see several import options - look for the **Flatfile Importer** tile and click the **Import** button. + Click **Upload CSV** to begin the upload process. -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. + ![Upload CSV screen](https://media.docs.plane.so/importers/flatfile/upload-csv.webp#hero) -6. Click the **Upload CSV** button. + 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. - ::: 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. + ::: 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. 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. +7. **Map your fields** + + The field mapping screen appears with two columns: + - **INCOMING FIELDS** (left): Your CSV column headers + - **DESTINATION FIELDS** (right): Corresponding Plane fields + + ![Map fields screen](https://media.docs.plane.so/importers/flatfile/map-fields.webp#hero) + + 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. + + 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. + ::: + +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") -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 (\*). + ![Validate field values](https://media.docs.plane.so/importers/flatfile/validate-fields.webp#hero) -9. Once you've mapped your fields, click **Continue** to proceed. + Continue mapping until all values are matched to valid Plane options. -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. + Click **Continue** when all fields are properly mapped. -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. +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 + + When you're satisfied, click **Submit** to start the import. + +10. **Track your import** + + 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 + + ![Migrations list](https://media.docs.plane.so/importers/flatfile/migrations-list.webp#hero) + + 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. -12. Once it's done, go to **Work Items** in your Plane project to confirm that the data import is successful. ## Imported fields @@ -64,13 +116,24 @@ 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 | +| 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. diff --git a/docs/workspaces-and-users/billing-and-plans.md b/docs/workspaces-and-users/billing-and-plans.md index 883a34a..5c4c4a9 100644 --- a/docs/workspaces-and-users/billing-and-plans.md +++ b/docs/workspaces-and-users/billing-and-plans.md @@ -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 From 7f8cbc98857160dd9629c54c8b218cc17f6a158f Mon Sep 17 00:00:00 2001 From: danciaclara Date: Fri, 27 Mar 2026 17:48:57 +0530 Subject: [PATCH 2/2] formatting fixes --- docs/importers/flatfile.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/docs/importers/flatfile.md b/docs/importers/flatfile.md index 68ca18c..0b3efbc 100644 --- a/docs/importers/flatfile.md +++ b/docs/importers/flatfile.md @@ -44,8 +44,8 @@ Here's how to get started: 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. - + 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. ::: @@ -59,7 +59,7 @@ Here's how to get started: 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. - Required fields are marked with an asterisk (*). + 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. @@ -83,7 +83,6 @@ Here's how to get started: 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 @@ -106,7 +105,6 @@ Here's how to get started: After the import shows "Finished" status, navigate to **Work Items** in your Plane project to confirm your data imported successfully. - ## Imported fields When bringing your data from CSV into Plane, here's exactly what you can transfer over: @@ -127,7 +125,6 @@ When bringing your data from CSV into Plane, here's exactly what you can transfe | Module | | | Created At | | - ## Managing your imports After completing imports, you can: