CSV Import

The CSV Import feature allows you to bulk upload data into ProBeya from comma-separated value files. Whether you are migrating from another tool, importing historical KPI data, or loading action items from a spreadsheet, the four-step import wizard guides you through the process with column mapping, validation preview, and execution summary.

Import Wizard Overview

The import process follows four sequential steps:

Step 1          Step 2           Step 3            Step 4
Upload    -->   Column Map  -->  Preview     -->   Execute
Drop file       Match columns    Validate rows     Import & summary
                to fields        Fix errors

Step 1: Upload File

1. Navigate to the import target (e.g., KPI board, action log, or table board).
2. Click Import CSV in the toolbar.
3. Upload your file using one of these methods:
   • Drag and drop the file onto the upload zone.
   • Click to browse and select the file from your file system.
   • Paste from clipboard — paste tab-separated data directly.

File Requirements

Requirement	Details
Formats	.csv, .tsv
Max file size	10 MB
Max rows	10,000 rows per import
Encoding	UTF-8 (recommended), UTF-8 BOM, Latin-1
Header row	Required — the first row must contain column names

After upload, the wizard auto-detects the delimiter and displays the first 5 rows as a preview to confirm the file was parsed correctly.

info

The delimiter is auto-detected from the first 10 lines of the file. If auto-detection fails (e.g., the file uses an uncommon delimiter), you can manually select the delimiter from a dropdown: comma (,), tab (\t), semicolon (;), or pipe (|).

Step 2: Column Mapping

In this step, you match each column in your CSV file to a field in ProBeya.

Mapping Interface

The mapping interface shows two columns side by side:

CSV Column (source)	ProBeya Field (target)	Status
Task Name	Title	Mapped
Responsible	Assignee	Mapped
Due	Due Date	Mapped
Status	Status	Mapped
Notes	Description	Mapped
Old ID	(skip)	Ignored

Auto-Mapping

The wizard attempts to auto-map columns based on name similarity:

• Exact match: title maps to Title
• Fuzzy match: task_name maps to Title, responsible maps to Assignee
• Date detection: columns containing "date", "due", "deadline" map to Date fields
• Status detection: columns with known status values map to the Status field

Manual Mapping

For columns that are not auto-mapped:

1. Click the dropdown next to the CSV column name.
2. Select the target ProBeya field from the list.
3. Or select Skip to ignore the column entirely.

Value Mapping

For fields with predefined options (status, priority, category), you may need to map source values to target values:

CSV Value	ProBeya Value
Todo	open
In Work	in_progress
Complete	done
On Hold	blocked

The wizard detects unique values in each mapped column and prompts for value mapping when the source values do not match the target field's options.

tipp

If your CSV uses consistent naming conventions, the auto-mapper handles most columns automatically. Invest time in standardizing your export format to make future imports faster.

Step 3: Preview with Validation

Before executing the import, the wizard displays a full preview of the parsed data with row-level validation.

Preview Table

Row	Title	Assignee	Due Date	Status	Validation
1	Fix conveyor belt	[email protected]	2026-03-25	open	Valid
2	Order spare parts	[email protected]	2026-03-28	assigned	Valid
3	(empty)	[email protected]	2026-04-01	open	Error: Title is required
4	Update SOP	[email protected]	invalid-date	open	Error: Invalid date; Warning: User not found

Validation Rules

The preview checks each row against these rules:

Rule	Severity	Description
Required fields	Error	Fields marked as required (e.g., Title) must not be empty
Date format	Error	Date values must be parseable (ISO 8601 recommended: YYYY-MM-DD)
Number format	Error	Numeric fields must contain valid numbers
User lookup	Warning	Email addresses or names are matched against organization members
Status values	Warning	Status values must match the target field's allowed options
Duplicate detection	Warning	Rows with identical key fields are flagged

Handling Errors

• Error rows are highlighted in red and will be skipped during import unless fixed.
• Warning rows are highlighted in yellow and will be imported, but the flagged values may be set to defaults.
• Click on any error cell to edit the value inline directly in the preview table.
• Use Fix All to apply a bulk correction (e.g., replace all empty titles with a default value).

Summary Before Execution

At the bottom of the preview, a summary shows:

Ready to import:     47 rows
Errors (will skip):   3 rows
Warnings:             5 rows
Total:               50 rows

warnung

Rows with errors will be skipped during import. Fix all errors in the preview step if you want a complete import. You can also re-import the skipped rows later.

Step 4: Execute Import

Click Import to execute the import. The system processes rows in batches and displays a live progress indicator.

During Import

Importing... [================----] 40/50 rows

• Rows are processed in batches of 100 for performance.
• Each row is validated again server-side before insertion.
• Failed rows are collected for the error report.

Import Summary

After completion, the summary shows:

Import Complete

  Imported:    47 rows
  Skipped:      3 rows (validation errors)
  Duration:     2.4 seconds

  Download error report (CSV)

• Imported rows are immediately visible in the board/table.
• Skipped rows can be downloaded as a CSV file with error descriptions appended, so you can fix and re-import them.
• All imported records are tagged with source = "import" for audit trail purposes.

info

Each import creates a batch record in the system. You can view import history in Settings > Import History, including who imported, when, how many rows, and a link to the error report.

Supported Import Targets

CSV Import is available for the following board types and data:

Target	Key Fields	Optional Fields
KPI Values	KPI Name/ID, Date, Value	Comment
Action Log	Title, Type	Status, Priority, Assignee, Due Date, Category, Source, Description
Table Board Items	Title	Any custom field columns defined on the board
People / Members	Email	Name, Role

KPI Value Import Details

When importing KPI values:

• The KPI Name or KPI ID column identifies which KPI definition to write to.
• If a value already exists for the same KPI and date, the import performs an upsert (update the existing value).
• Date format should be ISO 8601 (YYYY-MM-DD). Other formats (MM/DD/YYYY, DD/MM/YYYY) are supported but may be ambiguous.

Supported Formats and Delimiters

Format	Delimiter	Extension	Notes
Comma-separated	,	.csv	Most common; auto-detected
Tab-separated	\t	.tsv	Best for data containing commas
Semicolon-separated	;	.csv	Common in European locales where comma is the decimal separator
Pipe-separated	|	.csv	Rare; must be manually selected

Encoding

• UTF-8 is the recommended encoding.
• UTF-8 with BOM (byte order mark) is automatically handled.
• Latin-1 / ISO-8859-1 is supported as a fallback for legacy exports.
• If special characters (accents, umlauts) appear garbled in the preview, switch the encoding selector to match your file's encoding.

Date Format Support

The importer recognizes multiple date formats:

Format	Example	Notes
YYYY-MM-DD	2026-03-23	ISO 8601 — recommended, unambiguous
DD/MM/YYYY	23/03/2026	European — may be ambiguous
MM/DD/YYYY	03/23/2026	US — may be ambiguous
Full ISO timestamp	2026-03-23T14:30:00Z	Time portion is ignored for date fields

tipp

Use ISO 8601 dates (YYYY-MM-DD) to avoid ambiguity between MM/DD and DD/MM formats. When the format is ambiguous, the importer uses the locale setting of the importing user.

CSV Injection Protection

All imported cell values are sanitized to prevent CSV injection (also known as formula injection):

Pattern	Risk	Mitigation
Cell starts with =	Formula execution in spreadsheet tools	Prefixed with ' (single quote)
Cell starts with +	Formula execution	Prefixed with '
Cell starts with -	Formula execution (if followed by specific chars)	Prefixed with ' if followed by = or function-like pattern
Cell starts with @	External data reference	Prefixed with '
Cell contains \t, \r, \n	Cell content manipulation	Stripped

warnung

CSV injection protection is applied automatically on import. If your data legitimately starts with =, +, or @ (e.g., chemical formulas, email addresses), verify that the imported values are correct in the preview step. The prefix is applied only in contexts where the value would be re-exported; internally, the original value is preserved.

Error Handling

Common Import Errors

Error	Cause	Resolution
"Title is required"	Empty title cell	Fill in the title in the preview or source file
"Invalid date format"	Unparseable date string	Use ISO 8601 format: YYYY-MM-DD
"User not found"	Email does not match any organization member	Invite the user first, or map to an existing member
"Invalid status value"	Status value not in allowed options	Use the value mapping in Step 2
"Duplicate row"	Another row has the same key fields	Remove the duplicate or update the key field
"KPI not found"	KPI name/ID does not match any definition on the board	Check spelling or create the KPI definition first
"File too large"	File exceeds 10 MB limit	Split into smaller files
"Too many rows"	More than 10,000 data rows	Split into batches of 10,000 or fewer

Retry Failed Rows

1. After import, click Download Error Report.
2. The error CSV contains the original rows plus an _error column describing each issue.
3. Fix the issues in your spreadsheet application.
4. Re-import the corrected file. Existing rows are updated (upsert), not duplicated.

Permissions

Action	Required Role
Import CSV data	Board admin or workspace admin
View import history	Board admin or workspace admin
Download error reports	Board admin or workspace admin

Best Practices

1. Use ISO 8601 dates (YYYY-MM-DD) to avoid ambiguity between MM/DD and DD/MM formats.
2. Include a header row — the import wizard requires it for column mapping.
3. Standardize status and priority values before import to minimize manual value mapping.
4. Test with a small file first (5-10 rows) to verify column mapping before importing thousands of rows.
5. Keep a backup of your original CSV file before making corrections.
6. UTF-8 encoding avoids character encoding issues with accented characters.

Related Features

• KPI Boards — Import historical KPI measurements in bulk
• Action Log — Import action items from external tracking systems
• Templates — Set up the board structure before importing data