Importing a backlog

Where the import is

NeedsView view

The import is on the project screen, in the section Import. The section header counts every run, previews included, as 3 imports. The upload form comes first, and Past imports lists every run below it.

The upload form is absent for people without Manage the project. They still see the section header, its description and Past imports.

Choose the file

NeedsManage the project project_manage

1. On the project screen, go to Import.
2. Find the caption Choose a .csv file. The file control sits under it, and the browser gives that control its own button name.
3. Click the file control.
4. Choose the file.
5. If you have the text instead of a file, paste it into Or paste CSV, header row first.
6. Click Preview. The button reads Checking… while the product checks the file.

The file control and the paste box hold one text between them. The browser reads the file you choose and writes its text into the paste box. That text is what the product imports, and you can edit it there first.

Preview is disabled until the paste box holds text, and while a check runs. The product guesses the column mapping, checks every row, and shows what it will create and what it will skip. It writes no items at this step.

The form has no Cancel and no Back. To drop a preview and begin again, reload the page.

The product records pasted text under the name pasted.csv. If you chose a file and then changed the text in the paste box, the run keeps the chosen file's name. The file control still shows that name.

Check the column mapping

NeedsManage the project project_manage

The preview starts with Columns: one line per header in your file, with a select beside it. The select offers Ignore and the ten fields under “The columns the product knows” below.

1. Read each header and the field the product chose for it.
2. If a column feeds the wrong field, change its select.
3. If a column has no place in the backlog, set its select to Ignore.

Each change runs the check again at once. There is no button to click. The preview disappears until the new check answers.

Preview always starts from the product's guess. It drops the mapping you made.

• One column must feed Name. If none does, the product removes the preview and shows Map one column to the item name before importing.
• If two columns feed the same field, the product uses the first one in file order.
• Two columns with the same header text share one select. A change to one of them changes both, and the product reads the first of the two. To map them apart, give one of them a new header in the file.
• If you change the file or the text in the paste box, the product removes the preview and the mapping at once. No new check starts. Click Preview again.

Read the preview

NeedsManage the project project_manage

Under the columns, a summary line says 40 of 43 rows will become items. When any row fails, it continues: 3 will be skipped; the rest import anyway.

Under the summary line, a list names each skipped row as Row 7 with its reason. The list has no heading. The header row is row 1, so the first data row is Row 2.

The product counts rows, not lines in the file. It drops blank lines, and a line break inside a quoted cell stays in that cell. Each one moves a row number away from the line number in the file.

A table shows the first 20 rows that will become items, with the columns Row, Name, Phase, Type, Priority and Size. A row with no size shows —. When more than 20 rows will become items, the table ends with Showing the first 20 of 40.

Import the items

NeedsManage the project project_manage

1. Make sure the summary line and the mapping are what you want.
2. Click Import 40 items at the bottom of the preview. The button reads Importing… while the product writes.
3. Read the result line. It ends with the link Open the backlog.

With one row the button reads Import 1 item. If no row will become an item, the button is disabled. The result line reads Imported 40 items. Open the backlog. When the run skipped rows, it reads Imported 40 items, skipping 3. Open the backlog.

• The import checks the file the same way the preview did. What the preview showed is what the import creates.
• The product creates all the items together. If the write fails before the end, the product creates nothing.
• A skipped row never stops the other rows.
• After an import, the upload form and the preview disappear, and the run appears at the top of Past imports at once. Reload the page to import another file.

When the write fails, the product records no run. The preview stays on the screen, and the product shows An unexpected error occurred. above the upload form. A duplicate external id is one cause. Fix the file, then click Preview again. See The Product Backlog for what the imported items look like there.

Messages that are not about the file

Four messages above the upload form mean that nothing is wrong with the file.

• You do not have permission to perform this action. Somebody withdrew Manage the project from you after the page loaded. Reload the page.
• Too many requests. Each Preview and each change to a select is one change. The product accepts 60 changes from you in a minute, counting every screen. Reading a screen does not count. Wait a minute, then click Preview again.
• Could not reach the server. Check your connection and try again. The request got no answer.
• Authentication required. Your session ended. A session lasts 15 minutes, and it also ends when you sign out in another tab, or when you reset your password. Sign in again. Then start the import again from the file. See Getting started.

The file

The first row is the header row. Each row after it becomes one item. A cell can be in double quotes. A quoted cell can hold commas, line breaks and doubled quotes. Both Windows and Unix line endings work. The product drops a byte-order mark, ignores blank lines, and trims every cell.

The paste box shows a two-line example as its placeholder: Name,Priority,Size over Checkout,high,3. That file makes one item named Checkout, with the priority high and the size 3.

A comma separates the cells, and the product reads no other separator. A file that uses semicolons becomes one column. The product then blocks it with Map one column to the item name before importing.

The product pads a short row to the width of the header row. A long row loses the cells past that width.

Some problems block the whole file. The product shows the reason above the upload form and imports nothing:

• The file has rows, but no cell holds text: The file is empty.
• A quote appears after other text in a cell: A quote appeared in the middle of a field on line 7.
• A quote never closes: A quoted field starting on line 7 was never closed. That line is the end of the file, not the line where the quote opened. Look for the first cell that starts with a quote and has no quote at its end.
• More than 2,000 data rows: That file has 2417 rows; an import takes at most 2000. Split it.
• More than 2,097,152 characters, about 2 MB of plain text: Invalid request body. Split the file.
• About 6 MB or more: Request body is too large. The product refuses the text before it reads it. Split the file.
• No column feeds Name: Map one column to the item name before importing.

The columns the product knows

A column can feed one of ten item fields. The product guesses the field from the header. Capitalization, spaces and punctuation in the header do not matter. The product ignores any other header until you map it yourself.

Name

Name, Title, Item or Story. One column must feed this field.

Summary

Summary.

Description

Description or Details.

Notes

Notes or Note.

Priority

Priority.

Size

Size, Points, Story points or Estimate.

External id

External id, Ext id, External, Id, Key or Ref.

Phase

Phase.

Item type

Type or Item type.

Epic

Epic.

A header cell can be empty. A comma at the end of the header row makes one. Its line in Columns carries no name. Leave that line on Ignore. If you give it a field, the next check fails with Invalid request body. To map the column, give it a header in the file.

Phases, item types and epics

The import never asks for a phase, an item type or an epic. The cells in each row decide, and a blank cell takes the project's default.

The product compares only the letters a to z and the digits in a name. It removes every other character, and it removes an accented letter with them. It does not read é as e. A phase named Café therefore compares as caf, and a cell that holds Cafe does not match it. The product skips that row.

Capitalization does not matter. Two names that differ only in the characters the product removes match each other. Name each phase, item type and epic in the letters a to z and the digits.

• Phase: the product matches it by name. A blank cell takes the default phase. If the name is unknown, the product skips the row: No phase named “Launch” in this project.
• Item type: the product matches it by name first, then by the key that the Item types section shows beside the name. A key with an underscore in it, such as user_story, never matches. Use the name. A blank cell takes the built-in User Story type, even after a rename. If neither matches, the product skips the row: No item type named “Defect” in this project.
• Epic: the product matches it by name. A blank cell gives the item no epic. If the name is unknown, the product skips the row: No epic named “Checkout” in this project.
• If the project's Epics setting is off, the product skips every row with an epic: Epics are turned off for this project.

What a row needs

A row needs a name. Every other cell can be blank. The product skips a row that fails a rule, gives the reason, and still imports the other rows.

• No name: No name. A row needs at least a name to become an item.
• Priority is low, medium, high or critical, in any capitalization. A blank cell means medium. Anything else: “urgent” is not a priority. Use low, medium, high or critical.
• Size is a number. A point is the decimal mark. A comma works only inside a quoted cell, because a bare comma ends the cell. A blank cell means no size. Text that is not a number: “big” is not a size. Use a number like 3 or 0.5.
• Zero or less: A size must be greater than zero. Over 9999.99: That size is out of range. More than two decimals: A size may have at most two decimal places.
• The product refuses some sizes with one or two decimals as well, 1.1 and 2.2 among them: A size may have at most two decimal places. Use a whole number or a half, such as 3 or 0.5.
• Length caps, each with its own reason: Keep the name under 200 characters. Keep the summary under 1000 characters. Keep the description under 20000 characters. Keep the notes under 20000 characters. Keep the external id under 64 characters.

What an imported item looks like

• Its status is Draft. The rules for leaving Draft apply later, not at import. An item needs a summary and a description to leave Draft. When the file has a summary and a description, map those two columns.
• If the project setting Require a size to leave Draft is on, an item imported without a size stays a Draft until somebody sizes it. The setting is in the Settings section of the project screen. See Project settings.
• Its number is the next in sequence after the project's existing items.
• Its position is the end of its phase, in file order.
• Its phase, type, priority and size are what the preview showed. The preview does not show the epic. Its epic, summary, description, notes and external id come from the mapped columns.
• Its history holds one line, created the item as PROJ-127, with your name and the time of the import. An item added on the backlog gets the same line.
• The activity feed does not record an import.

Past imports

NeedsView view

Past imports lists every run, newest first. Each line shows the file name, the status previewed or applied, then 40 of 43 rows. When the run skipped rows, the line adds , 3 skipped. A previewed run shows 0 of 43 rows. With no runs, the list reads Nothing has been imported into this project yet.

The line gives a count of the skipped rows and no reason for any of them. An applied run appears at the top of the list at once. A previewed run appears after you reload the page.

The time on each line is in UTC, unlike the rest of the product. See Time and timezones.