Import Cards from CSV or Excel

Overview

You can import cards from CSV or Excel (XLSX) files directly into a board. The import process validates your data before creating cards, so you can fix issues upfront.

The flow works like this: Upload → Preview (dry-run) → Import → Done.

Step 1: Open the Import Dialog

1. Navigate to the board where you want to import cards
2. Open the board menu and click Import
3. Choose Excel or CSV as the format

If you've saved import configurations before, they also appear in this menu — click one to reuse its settings.

Step 2: Download a Template (Optional)

Before preparing your file, you can download a template that matches the board's structure:

• Click Download CSV template or Download XLSX template
• The template contains column headers matching the board's dimension labels
• Fill in your data under those headers and save

Using a template avoids mapping issues since the column names already match your dimensions.

Step 3: Upload Your File

Drag and drop your file onto the upload area, or click to browse. The system accepts:

• CSV files (.csv, comma-separated)
• Excel files (.xlsx, modern Excel format)

Once uploaded, the system immediately performs a dry-run — it reads your file, maps columns to dimensions, and validates every row without creating anything yet.

Step 4: Review the Dry-Run Results

The preview screen shows you exactly what will happen:

• New cards to create — rows that don't match existing cards
• Cards to update — rows that match existing cards (by identifier)
• New dimension values — values that don't exist yet and will be created automatically
• Errors — rows that can't be imported, with details

Understanding Errors

If some rows have issues, you'll see an error table showing:

Common error causes:

• Unknown dimension value — your file contains a value that doesn't exist for that dimension (e.g., "Urgent" when only "Low", "Medium", "High" are defined). If the dimension allows tagging, new values are created automatically; otherwise, it's an error.
• Type mismatch — a date column contains something that isn't a date, or a number column contains text.
• Empty required field — a required dimension (like the card title) is blank for that row.

Partial Import

If some rows are valid and others have errors, you can choose to import the valid lines only and skip the problematic ones. Or go back, fix your file, and try again.

Step 5: Confirm and Import

Click Import everything (or Import valid lines if there are errors). The system creates or updates cards in bulk.

After import, click Refresh board to see the changes to load the new cards on your board.

How Column Mapping Works

The system automatically maps your spreadsheet columns to dimensions by matching:

1. Dimension labels — the human-readable name (e.g., "Priority", "Due Date")
2. Dimension codes — the technical name (e.g., "priority", "due_date")

The first match wins. Columns that don't match any dimension are silently ignored.

Special Columns

• Card title — mapped from columns named "Card title", "title", "Card summary", or "summary". If multiple are found, they're joined.
• Identifier — if your board has an Identifier dimension and your file includes an identifier column, the system uses it to update existing cards rather than creating duplicates.

Multiple Values

For dimensions that support multiple values (e.g., Tags, Assignees), separate values with commas in a single cell:

Alice, Bob, Charlie

Each value is trimmed, mapped to its dimension value, and validated independently.

Updating Existing Cards

The import can update cards instead of creating new ones. This happens when:

1. Your board has an Identifier dimension
2. Your file includes a column for that identifier
3. The identifier value matches an existing card

Matched rows update the existing card's dimensions. Unmatched rows create new cards.

Default Values from Filters

When you import into a board that has active filters, those filter values are applied as defaults to every imported card. For example, if your board is filtered to show only Status = To Do, all imported cards will get Status = To Do automatically.

You can disable this behavior in the Advanced Options.

Advanced Options

Click Advanced options before importing to access:

• Don't enforce required dimensions — skip validation of required fields, useful for partial imports
• Ignore unsaved board filters for default values — only apply saved (permanent) filters as defaults, not temporary ones
• Custom data transformer — upload a YAML file (using the Monolens format) to transform your data before import. This is for advanced users who need custom column mappings or value transformations.

Saving an Import Configuration

If you plan to import regularly with the same settings, you can save the import configuration after a successful import:

1. After import, enter a name for the configuration (up to 25 characters)
2. Click Save

The saved configuration appears in the Import dropdown menu for future use. It remembers your options and any custom transformers.

Tips for a Smooth Import

• Start with the template — download the CSV or XLSX template to get the correct column headers
• Check your date formats — dates should follow a standard format (e.g., 2026-04-15)
• Watch for typos in category values — if a dimension isn't taggable, values must match exactly
• Use the dry-run — always review the preview before importing; it catches issues early
• Use identifiers for updates — include an identifier column if you want to update existing cards rather than create duplicates