Importing a backlog

Where the import is

NeedsView view

The import is on the project screen, in the section Import. The section header counts the runs, previews included, as 3 imports, and reads Latest 50 imports from 50 runs on. The upload form comes first, and Past imports lists the newest 50 runs 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 or .xlsx 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.

For a .csv 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.

For an .xlsx workbook, the paste box stays empty. A line under the file control reads Backlog.xlsx is ready. The product reads its first sheet only. If you then type in the paste box, the product drops the workbook and imports the text.

The product refuses a file larger than 2 MB at once, before it sends the file: That file is too large to import in one go. Split it.

Preview is disabled until the paste box holds text or a workbook is ready, 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 .csv 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. If you chose a workbook and then typed in the paste box, the product records the run as pasted.csv.

Check the column mapping

NeedsManage the project project_manage

The preview starts with Columns. For a workbook, a line under it names the sheet: Read from the sheet “Backlog”. Then comes 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 starts from the product's guess. It drops the mapping you made. The one exception is a check that failed after you changed a select: the columns stay, and Preview checks your mapping again.

• One column must feed Name. If none does, the product removes the preview, keeps the columns and shows Map one column to the item name before importing. Change a select to continue.
• 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.

In a .csv file, 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.

In a workbook, the row number is the number the sheet shows. The product drops a blank row, but the row keeps its number, so Row 7 is row 7 of the sheet.

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 .csv 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.
• A line has more than 1,000 cells: Line 7 has more than 1000 columns. Delete the columns you do not import, or the empty columns at the right of the sheet.
• 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.
• A column heading has more than 200 characters: A column heading is longer than 200 characters. Check that the first row of the file is the heading row. This applies to a workbook too.
• Another import into the project is running when you click the import button: Another import or change to this project is running. Wait for it to finish, then try again. Adding an item, changing the project or changing a sprint during an import can show the same message after a second.
• Other imports are using the server when you click the preview or the import button: Too many imports are running right now. Wait a minute, then try again. The product imports nothing from that click, so you can click the button again.
• A column heading holds a NUL character, which a spreadsheet tool can leave behind: A column heading holds a character that cannot be stored, such as a NUL. Retype the heading, then try again.

The workbook

The product reads one sheet: the first tab that is not hidden. It ignores the other sheets. Move the backlog to the first tab, or hide the tabs in front of it.

The first row that holds text is the header row. Rows above it that are empty do not count. Each row after it becomes one item. The product drops blank rows and trims every cell. The header row ends at its last cell with text. The product ignores a cell to the right of it.

A cell gives the value the workbook stores, not its format. A formula gives its last result. TRUE and FALSE stay as those words. A date gives the number Excel stores for it, such as 45937. The import has no date field, so this matters only for a date in a text column.

These problems block the whole workbook. The product shows the reason and imports nothing:

• An old .xls workbook, or a workbook with a password: That file is an old .xls workbook or is password-protected. Save it as .xlsx without a password, or as .csv.
• A file named .xlsx that is not a workbook: That file is not an .xlsx workbook.
• A workbook that is cut short or broken: The workbook is damaged and could not be read.
• Every sheet is hidden: The workbook has no visible sheet to import.
• The first tab is a chart: The first sheet, “Chart1”, is not a table of cells. Move the backlog to the first tab.
• The sheet has no text: The sheet “Backlog” is empty.
• A cell past column 1,000 holds text: Row 7 has a value past column 1000. Delete the columns you do not import.
• The sheet is too large when the product unpacks it, more than about 32 MB: That workbook unpacks to more than an import can read. Copy the rows you want into a new workbook, or save them as .csv.
• A cell holds more than 50,000 characters, even in a column you do not import: Row 7 has a cell longer than 50000 characters, more than any item field can hold. Shorten the cell.
• The sheet’s cells hold more than about 8 million characters together, the sheet has more than 2,100,000 cells, blank styled cells included, or one cell’s text in the file passes 350,000 characters. Text that repeats counts each time it appears: That workbook holds more than an import can read. Copy the rows you want into a new workbook, or split it.
• More than 2,000 data rows, and no column that feeds Name, as for a .csv file.

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 the letters and the digits in a name, in any language. It removes spaces and punctuation. It does not read é as e, so a cell that holds Cafe does not match a phase named Café. The product skips that row.

Capitalization does not matter. Two names that differ only in spaces, punctuation or capitalization match each other, and a cell takes the first of them. A name with no letter and no digit, such as ---, matches only a cell that holds the same text.

• 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. A reason quotes at most 80 characters of the cell, then ….

• No name: No name. A row needs at least a name to become an item.
• A cell the product imports holds a NUL character: This row holds a character that cannot be stored, such as a NUL. Remove it from the file, then preview again.
• 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 the newest 50 runs, 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.