In this article:
1. Introduction to the Import Tool
2. How to Access the Import Tool in Businessmap?
3. How to Format Your Spreadsheet for a Successful Import?
4. Types of Problems, Warnings, and Their Meaning
1. Introduction to the Import Tool
Importing cards and initiatives using a spreadsheet file is the quickest way to populate your board, without creating cards manually.
Note: There is a limit of 100 cards that can be created/updated in one go.
With this feature, you can easily import cards from external/legacy systems or update cards already on your boards. You can also move cards between boards in your account (export from one board and import in another) or export them to use elsewhere. This article explains how to do all of this using the built-in import tool.
If you are looking to import data using Google Sheets, please check our dedicated Businessmap for Sheets Add-On.
2. How to Access the Import Tool in Businessmap?
Open the board where cards and initiatives will be imported and go to the Board Sidebar, located on the right side of your Board. Select the Import icon as shown below.
Note: You can import items into both the Cards Workflow and the Initiatives Workflow. Just make sure the column names in the different workflows are not the same. If you don't explicitly specify a Workflow, the items will be imported into the Cards Workflow by default.
Once in the Import tab, click the "Browse" button and choose the xls or xlsx file you want to import from your computer.
When the file is uploaded, the system will validate your data for compatibility and the validation status will be displayed. Make sure to get familiar with the different types of disclaimers, warnings, and mistakes (check pt.4 below).
3. How to Format Your Spreadsheet for a Successful Import?
Step 1: Create an xls or xlsx file that needs to be properly formatted, so that your data can be matched to the card fields in Businessmap. In the spreadsheet, give descriptive names (column headers) to the columns matching any of the following Businessmap card properties:
Column header | Explanation / notes |
Title (mandatory) | Title of the card - can also be left blank*. |
Description | Description of the card |
Card ID | The standard (internal) Card ID |
Custom Card ID | Custom Card ID |
Priority | Priority of the card – low, average, high or critical. |
Owner | A valid username of a board member. If the user is not added to the board, the username is spelled incorrectly, or the user is disabled, the owner of the work item would not be set. |
Co-Owners | Valid usernames of board members. If a user is not added to the board, they will not be set as a co-owner of the work item. |
Color | Only hex values are accepted i.e. if you would like to set a blue color, you must use its hex value - #067DB7. |
Size |
The size of the card. If you are using T-shirt sizes on the board, for which the import is performed, you would need to provide the corresponding numerical values: 'S' => 1 |
Tags |
Can be used to apply existing tags (which are enabled for the board) to the card or create new ones if the specified tags do not exist yet. If the user (that performs the import) has the permissions to manage tags, the new tags will be created and applied to the cards. If the user does not have the permissions to manage tags and the specified tags do not exist, they will not be created. Tags should be separated by a comma or an interval. For example: tag1 tag2 tag3 - this will create 3 tags (if they do not exist yet) as the interval is used as a separator by default. |
Deadline | Sets the deadline value for the card – accepted formats are MM/DD/YYYY, DD-MM-YYYY, YYYY-MM-DD. Note that the value cannot be before 1970-01-01 and after 2037-12-31. |
Template | Applies a template for the card (only possible for new cards). Explicitly specified properties in the spreadsheet file will override the template values. Note that if the template contains linked cards, they will not be applied. |
Type | Set the type of card. The selected type must be enabled and added to the board, on which the import is performed. |
Type name | Same as the above. |
Column | The column in which the card should be created (or moved to). It is recommended that columns have unique names across the board, otherwise, cards might be imported to an undesired location. |
Column name | Same as above. |
Lane | The lane in which the card should be created (or moved to). It is recommended that lanes have unique names across the board, otherwise, cards might be imported to an undesired location. |
Lane name | Same as above. |
Comment | For adding a comment on cards – can only be used when creating a new card via import. Multiple 'comment' columns can be specified in the import file and will be added to the newly created card in that order. |
Board name | The name of the board on which the card should be created/updated/moved via import. Note that this parameter is case-sensitive. |
Board ID | The ID of the board on which the card should be created/updated/moved via import. Can be retrieved by the URL or on mouse hover over the board while on the dashboard. |
Workflow name | The name of the workflow, on which the card should be created/updated/moved. When moving a card between workflows, all location-related parameters (Column, Lane, Workflow name) must be provided. |
Links | Used when linking cards together via import. Accepted values for this header are Parents, Children, Relatives, Predecessors, Successors. Example: Parents: 1234; Children: 5678, 8765 Different types of links are separated by a semi-column (;) while different card IDs are separated with a comma (,). |
Parent | Similar to the above – used for specifying the parent card's ID whenever you would like to link a card from a row in the file as a child to an existing parent card. Example: 1234 |
Created at | Used for specifying the date on which a card has been created (in the past) [for cases when importing cards with historical metrics data] - kindly refer to the dedicated article on this. |
Creation Date | Same as above. |
Archived at | Used for specifying the date on which a card has been archived (for cases when importing cards with historical metrics data - kindly refer to the dedicated article on this. |
Archivation date | Same as above. |
Start Date | Used for specifying the date on which a card has been started (moved to In Progress) for cases when importing cards with historical metrics data - kindly refer to the dedicated article on this. Can also be used for Timeline and Portfolio initiatives in order to set the Actual Start date. |
End Date | Used for specifying the date on which a card has been completed (moved to Done) for cases when importing cards with historical metrics data - kindly refer to the dedicated article on this. Can also be used for Timeline and Portfolio initiatives in order to set the Actual End date. |
Planned Start* | Timeline and Portfolio initiative properties – sets the planned start date for an initiative. |
Planned End* | Timeline and Portfolio initiative properties – sets the planned end date for an initiative. |
Track | Timeline initiative property - used for specifying the track in which a Timeline initiative would be created. The counting of the timeline tracks starts from "0" i.e. if you have a Timeline workflow with three tracks, you need to insert "0" for the first track; "1" for the second one and "2" for the third one. |
* It is not currently possible to update the planned start and planned end dates of portfolio and timeline initiatives through the import tool. You can only import them when creating new initiatives.
Select the properties according to your specific needs.
Notes:
- Make sure that each column header in the spreadsheet file is typed correctly, otherwise, you will not be able to import the values of that column.
- When importing data, only valid column names will be translated. For example, if your account is in Portuguese, the system will automatically translate the column names of your import file into Portuguese. If there is a typo or you enter a non-supported column name, they will be colored in red and disregarded during the import.
-
The “Title” column is mandatory for a successful import. All other fields are optional.
That being said, you can still import cards with a blank value for the Title.- * If you have specified the Template property and your template contains a card title, you should leave the respective title cell in your file blank. Otherwise, it will override the Card Title of the selected template.
- * If you have specified the Template property and your template contains a card title, you should leave the respective title cell in your file blank. Otherwise, it will override the Card Title of the selected template.
- If you want to specify the position of the new items you create using the import, do not forget to define those properties that indicate location such as Workflow name, Column name, Lane name.
- If you don't specify the position, the card is placed using the Created at, Start Date, End Date properties, and the card is placed in the first column of the intended section
Step 2: Insert the respective properties' values in each of the columns.
Take a look at the table below to see what an example spreadsheet file should look like.
Title | Owner | Deadline | Priority | Column |
Team Discussion | Tom | 10/28/21 | average | Requested |
System Requirements | Tom | 12/28/21 | high | Requested |
System Design | Jake | 12/29/21 | high | Requested |
System Block Diagram | Jake | 12/30/21 | high | Requested |
Subsystem Requirements | Elly | 12/30/21 | high | Requested |
Subsystem design | Elly | 12/30/21 | high | Requested |
Example:
In the image below, the deadline from row 1 will not be populated as the date format is invalid. Additionally, the Tag column is not recognized as a valid card property (it should be Tags) and the values from that column will not be imported.
To cancel the import, close the import window, correct the mistake in your spreadsheet file, and import it again.
You will get a System Notification message: "Your import has started and you should see the cards appearing on your board. After the import is completed, you will receive an email with the status for all cards." Click OK to continue.
Note: When importing data, only valid column names will be translated. For example, if your account is in Portuguese, the system will automatically translate the column names of your import file into Portuguese. If there is a typo or you enter a non-supported column name, they will be colored in red and disregarded during the import.
4. Types of Problems, Warnings, and Their Meaning
Below are some of the most common possible problems you may encounter in the “System Checks” column of the import validator and how one can go about fixing them.
Note: If there is a single red problem with the data in the import, this message will show up:
Problems marked in red indicate that there is a problem with a specific row in the provided file, therefore the whole file will not be valid for import, and you will have to correct the red problems according to the description.
Wrong excel file format. Column named “title” is mandatory! | Add the column Title to the spreadsheet even if left empty. |
The specified board does not have a workflow with name “_____” | Check the spelling and change it or create this one on the board |
“_____” was not set correctly. | Date field was not written correctly |
The specified board does not exist or has been archived. | Make sure the Board Name or Board ID is correct. (Board Name is case sensitive) |
The specified board does not have a workflow with the name “_____” | Check the spelling and change it or create this one on the board |
Note: The Card ID column might also be colored in red in certain scenarios. This is not to be confused with the other errors mentioned above. The column gets highlighted in red, as the internal card IDs cannot be modified, but can still be used when a specific card needs to be updated.
Problems marked in beige are exclusive to the according row and the value of that cell will be ignored, but the file will still be rendered valid for import (other rows without beige problems will still be imported as configured).
Invalid date format for column “____”. The cell will be ignored. | Date field was not written in a valid date format, correct it and the import will succeed. |
This row will not create a card/initiative with history records. According to submitted dates: “______”, card/initiative should be created in “_____” section, which contradicts with the other parameters. | The date field of the card contradicts with the position field and the history of the card will not be imported. To fix this, look closely at the historical data of the card and make sure it is in the correct chronological order and it matches the correct location. |
Card/initiative will not be created on the desired location, due to inconsistency with required parameters. | The card parameters are not correct, and thus the position of the card will be different than the desired one. Make sure the parameters of the card are correct. |
Invalid “Lane (name)” specified. | There is a misspelling of the Lane Name or it doesn’t exist on this board. |
Invalid “Column (name)” specified. | There is a misspelling of the Column Name or it doesn’t exist on this board. |