# Epic OP-3313 - Work package import from CSV

Project: OpenProject
Status: tested
URL: https://community.openproject.org/work_packages/OP-3313

## Detailed specification

### Motivation and background information

### Acceptance criteria

### Out of scope

| Attribute | Value |
| --- | --- |
| Mockups |  |

## Planning

| Attribute | Value |
| --- | --- |
| Roadmap | 2026 Q3 |
| Date |  |
| Votes | 5 |
| List | TIB 2026 |
| Target versions | 18.0.0 |
| Sprint |  |
| Backlog bucket |  |
| Relevance |  |

## Subitems

_No work packages_

## Bugs and other work packages

| ID | Type | Subject | Status | Assignee | Target versions | Module |
| --- | --- | --- | --- | --- | --- | --- |
| OP-20503 | Bug | Import from CSV: impossible to import a work package with a mandatory custom field | closed |  | 18.0.0 |  |
| OP-20502 | Bug | Import from CSV: not all errors are shown at once | closed |  | 18.0.0 |  |
| OP-20496 | Bug | Import from CSV: Unclear message when user lacking permissions to assign versions tries to assign one | closed |  | 18.0.0 |  |
| OP-20495 | Bug | Import from CSV: Inconsistent capitalization/pluralization rules in Import summary | closed |  | 18.0.0 |  |
| OP-20518 | Bug | Import from CSV: imported work packages are ordered by ID descending | confirmed |  | 18.0.0 | Modules and project features / CSV Import |

## Details

| Attribute | Value |
| --- | --- |
| Module | Modules and project features / CSV Import |
| Enterprise plan | Community (COM) |
| Labels |  |

## People

| Attribute | Value |
| --- | --- |
| Assignee |  |
| Accountable |  |
| Product manager |  |
| Feature Lead |  |
| Designer |  |
| Developers | Andrej Sandorf |
| Requested by |  |
| Interest by | Bowling (40324) |

## Estimates and progress

| Attribute | Value |
| --- | --- |
| Work |  |

## Description

### Goal

Let users create work packages in bulk from a spreadsheet.

### Requirements

*   Accept `.csv` with UTF-8/UTF-16 encoding
    
    *   A file saved from a spreadsheet as &quot;CSV UTF-8&quot; is read as it is, and the template and the problem list are written in that same format so Excel opens them with the right encoding
        
    *   The separator is detected per file: comma, semicolon or tab, whichever resolves the most headers
        
    *   The browser-supplied content type is ignored (they are not consistent across brands); the encoding is detected from the file itself
        
*   Column contract
    
    *   Downloadable template for creating new CSV files
        
    *   Column reference in `docs/user-guide/work-packages/importing/`
        
    *   Date fields: ISO
        
    *   Date time fields: ISO `YYYY-MM-DDTHH:MM:SSZ` or `YYYY-MM-DD HH:MM:SS` or e.g. `YYYY-MM-DD HH:MM:SS UTC`
        
    *   Canonical English headers, but translations to the users&#x27; current language are also accepted
        
    *   Column matching is done by the column name, not by position
        
    *   Text/date only: Subject, Description, Work, Remaining work, % Complete, Start date, Finish date
        
    *   Must already exist in the project
        
        *   Type, Status, Priority, Category, Version by name
            
            *   Matched case- and whitespace-insensitively, against the types enabled in the project, all statuses, the active priorities, and the project&#x27;s categories and assignable versions
                
        *   Assignee, Accountable, Author by email address; an empty Author is the importing user
            
            *   Assignee and Accountable must be assignable in the project; Author is written directly and may be any non-builtin account
                
        *   Backdate journals if created\_at and/or updated\_at are part of the data
            
            *   Neither may be in the future, and Created on must not be later than Updated on
                
*   Error handling
    
    *   Validate the header row once, up front, and report unknown or ambiguous columns before any row is processed.
        
        *   Four header problems are distinguished: unnamed, unknown (with a &quot;Did you mean ...?&quot; suggestion), duplicate and ambiguous, each reported with its spreadsheet column letter
            
    *   Blank lines before and between the rows are skipped, trailing empty header cells are ignored, and a leading apostrophe on a header is stripped
        
    *   Report the line number of each error encountered
        
    *   A row holding more cells than the header is rejected rather than silently truncated
        
    *   Provide a download for the full errors list as well (UI errors rows are limited)
        
        *   The UI table shows the first 500 problems; the download carries the rest and is formula-sanitized
            
    *   An error rolls back all changes
        
    *   Row limit (5000 per default, change through env variable)
        
    *   File-size is the same as for work package attachments (5MB per default, change in Admin Settings)
        
    *   Setting.attachment\_whitelist must be ignored for the CSV import
        
*   Permission
    
    *   A dedicated `import_work_packages` permission depending on `add_work_packages`
        
        *   Migration adds this permission to every role that already has both &#x60;edit\_project&#x60; and &#x60;add\_work\_packages&#x60; - of the default roles that is only &quot;Project admin&quot;
            
*   UI
    
    *   New entry in the **project settings sidebar &quot;Work packages importer&quot;**
        
    *   Upload-page with a downloadable sample file
        
        *   Drag-and-drop or file picker, with the size checked in the browser before the upload; the submit button stays disabled until a file is chosen
            
    *   Dry-run toggle
        
        *   A dry run runs inside a rolled-back transaction, so a check never creates anything
            
    *   A successfully checked file is kept for the attachment grace period (180 minutes by default), so importing it does not need a second upload; in every other outcome the file is discarded
        
    *   Runs as a background job; the page announces the outcome once through a live region
        
    *   Notifications (e.g. assignee) to imported work packages are suppressed
        
    *   Tag journals with `Journal::CausedByImport` =&gt; entry in activity &quot;Imported by CSV&quot; with import date time by user &quot;System&quot;
        
    *   A wp view query is saved for all imported work packages and is linked in the success case
        
        *   The query is private to the importing user and named after the run&#x27;s date and time; it is only created on a real import
            
    *   The report shows the work package, type, account and dated-line counts as stat cards, plus a breakdown per type, status, priority and category
        

Note to **QA and marketing:** See the linked Nextcloud folder to find a bunch of problematic CSV demo files. There are also some that can be successful imported into the seeded &quot;Demo Project&quot;.

### Out of scope

*   Other csv file encodings as UTF8/UTF16
    
*   User specified column mapping
    
*   Attachments
    
*   API endpoint
    
*   Historic import (multiple rows for different states of the same work package)
    
*   XLS/XLSX/ODS/OTS
    
*   create fields/types/status on-the-fly - need admin rights
    
*   Parent / hierarchy by row number, external ID
    
*   Watchers
    
*   Relations by row number, external ID
    
*   Custom fields by name
    
*   Multiple Versions in one cell
    
*   Reports progress
    
*   Is abortable
    
*   UI to fix problem/blockers directly without changing and reuploading the file
    
*   Admin setting for the maximum allowed line count per upload
    
*   Round trip CSV export =&gt; CSV import
    
*   Updating work packages with CSV import
    
*   Follow up changes: [https://www.figma.com/design/TNBvs2ufiUcw1GUpkuVmOl/CSV-Importer?node-id=0-1](https://www.figma.com/design/TNBvs2ufiUcw1GUpkuVmOl/CSV-Importer?node-id=0-1)&nbsp;
    

<br>
