Import Roadmap Data from CSV

This feature is only available to Collaborators and Account Administrators.

Terms to Know

• Item - The initiatives, projects, tasks, releases, and general "things" that make up your roadmap.

• Milestone - One-time important single-day events that occur, like a release, launch, board meeting, or trade show (these will only appear on the Timeline visualization).

• Field - Categories or attributes that you can use to organize, group, filter, and pivot roadmap data in different ways. Simply put, Fields contain Item data.

• Bucket - Specifies a time period for an Item that does not use exact dates ('soon' or 'future' or 'never').

Importing Items from CSV

Format the CSV

To import Items from another application into Roadmunk, export the Items to a CSV file. The format of the CSV file is really simple. All it needs is:

• an Item Free-form Text Field that can be mapped to the roadmap's Items Field (this is the only required Field),

• a first row with the Field names (header row), and

• only Date, Free-form Text, List, and Multi-select List Fields (see Field types and Field mapping further on in the article).

We've even created a CSV template you can download here. The template has Items, Description, and Start and End  Date columns. It also has a Bucket column for Items without fixed dates that are assigned to time Buckets instead. To make the file your own, simply add columns for the custom Fields in your data, making sure they are one of the types listed above.

IMPORTANT: The Items in the CSV should have either Start and End Dates OR a time Bucket. If they have both an error will be generated indicating "An item must not have both a bucket and dates" and the CSV import will not be successful. For more on Item Buckets vs. Dates, see Create and add roadmap Items.

Roadmunk has a handful of application-specific Field names that cannot be used for Fields on your import. If any of these Field names exist on the CSV, they will not be imported. These Field names include: Error, Internal ID, External ID, Child Of, Source, Item, Milestone, Description, Start Date, End Date, and Date.

Start the Import

All Item imports start in the roadmap's Items Table. 

1. Click the Import from CSV button (appears only if the roadmap has no Items).
OR

2. On the View navbar, click the Import icon.

3. In the dropdown, select Import from CSV.

Upload the CSV

The Import CSV dialog walks you through the three steps in the import, starting with uploading the CSV file.

1. In the Import CSV dialog, drop the CSV file onto the Upload CSV tab OR click to browse and select the file.

If you see a message that looks like this, it means Roadmunk is having trouble importing the file or finding a match between Fields. To download error details in a CSV file, click the link in the message. 

Error message of “Argument passed in must be a string of 12 bytes or a string of 24 hex characters” typically indicates the external ID values are in the internal ID column. Simply switch these values to the correct column in the CSV, and re-upload. 

Map Fields

The next step is mapping the Fields in the CSV file to Fields in Roadmunk.

1. In the Field Mapping tab, you'll see the CSV File Item Field mapped to the Roadmunk Item Field.

2. You'll also see the remaining CSV File Fields mapped to the corresponding Roadmunk Fields.
   TIP: If you decide you don't want to import any one of the Fields in the CSV, click Remove in the corresponding Roadmunk Field's dropdown. Remember that Item is required, so you can't remove it.

3. If the CSV file has values in both Start and End Date AND Bucket, you must choose one or the other. Delete the values from the Field you don't want to import or remove the Field.
   IMPORTANT: If they have both an error will be generated indicating "An item must not have both a bucket and dates" and the CSV import will not be successful. 

4. Roadmunk auto-detects the date format in the CSV file and sets the format in Roadmunk to match. If the formats don't match, select the right one in the Date Format dropdown.

5. If everything looks good, click Next.

Tip: The 'Next' blue button will be unresponsive if you have a blank header as the title of a column. Please note that all columns must have a title to be properly mapped and ultimately uploaded.  

Note: Error message of “Status: insufficient permissions to add a new value to this Field” indicates a Field error. You may not have ownership of that Field and permissions to add a new value. 

For more on Field mapping, see Field types and Field mapping and More about Field mapping below.

Finish the Import

1. The Import tab shows a quick summary of how the Items will be imported.  

2. To finish the import, click Update & Overwrite All. 

Importing Milestones from CSV

Set up the CSV

There's some simple formatting the CSV file needs to follow for the import to work.

The file must have:

• a Milestone Free-form Text Field that can be mapped to the roadmap's Milestones Field in Roadmunk (this is the only required Field) 

• a first row with the Field names (header row)

• only Date, Free-form Text, List, and Multi-select custom Fields  (see Field types and Field mapping further on in the article)

The file should have (to make things easier):

• a Description Free-form Text Field

• a Date Field with a single date

• a Milestone Type List Field (e.g., Tradeshow, Release, etc.)

Start the Import

Start the import of the CSV file in the Milestones Table. 

1. Click the Import from CSV button (appears only if the roadmap has no Milestones).
OR

2. On the View navbar, click the Import icon.

3. In the dropdown, select Import from CSV.

Upload the CSV

The Import CSV dialog walks you through the import, starting with uploading the CSV file.

1. In the Import CSV dialog, drop the CSV file onto the Upload CSV tab or click to browse and select the file.

Map Fields between the CSV and Roadmunk

The next step is mapping CSV File Milestone Field to Roadmunk Milestone Fields.

1. In the Field Mapping tab, you should see the CSV File Milestone Field mapped to the Roadmunk Milestone Field.

2. You should also see any custom Fields in the CSV File Fields mapped to the corresponding Roadmunk Fields. If a corresponding Field doesn't exist, Roadmunk creates a New one.
   TIP: If you decide you don't want to import one of the custom CSV File Fields, click Remove in the corresponding Roadmunk Field's dropdown.

3. The CSV File Date Field is mapped to the Roadmunk Date Field.

4. Roadmunk auto-detects the Date format in the CSV file and sets the format in Roadmunk to match. If the formats don't match, select the right one in the Date Format dropdown.

5. If everything looks good, click Next.

For detailed help on mapping Fields, see Field types and Field mapping and More about Field mapping below.

Finish the Import

1. The Import tab shows a quick summary of how the Milestones will be imported.  

2. To finish the import, click Update & Overwrite All.

Field Types and Field Mapping

Field types in the CSV file must be mappable to the Field types currently supported by Roadmunk.

Date

Dates in the CSV file should be in two separate columns, one for the Start Date and one for the End Date. Dates must be a numerical value in one of these formats: 

• YYYY-M-D

• M-D-YYYY

• M-D-YY

• D-M-YYYY

• D-M-YY

• YYYY-MMM-D

• MMM-D-YYYY

• MMM-D-YY

• D-MMM-YYYY

• D-MMM-YY

All dates must be in the same format, and only dates between 2010 and 2040 can be imported.

Buckets vs. Dates

The CSV file format also supports a Bucket Field for Items that are assigned to a time Bucket instead of having a Date. Bucket is a List Field (see below), so each Item in the file must contain a single value (for example, Soon or Future).

Free-Form Text

Free-form Text Fields can contain any alphanumeric value including URLs.

List

A List Field can contain a single value from a list of values.

Multi-select List

A Multi-select List Field is like a List Field except that it contain one or more values from a list. In the CSV file, each value selected from the list must be in quotation marks and multiple values must be separated by commas.

Numeric
A numeric Field allows you to enter numerical values including percentages, currencies, and numbers. 

Team Members

The Team Members Field is like a Multi-select List Field except that it contains the all of the users in your account. In the CSV file, the values must be the the users specific email for them to match with the import and be automatically assigned to Items.

More about Field Mapping

1. Roadmunk does most of the Field mapping for you by auto-detecting Field types and finding a match. 

2. Roadmunk automatically matches each CSV File Field to an existing Field in Roadmunk of the same type.
If a matching Field doesn't exist, Roadmunk creates a New Field with a matching type. The new Field is added to Roadmunk during the import using the name in the CSV File Field's header. For example, if a new Field is created to match a Product Team Field in the CSV file, the Field will be named "Product Team" in Roadmunk.

3. If a match doesn't look right, you can select a different Field in the CSV File dropdown and/or the Roadmunk dropdown. Just make sure the Fields are the same type.

4. You can change the order of the Fields in the CSV file by changing the Field headers as needed and then re-matching the Roadmunk Fields.

Who can import roadmap Items from a CSV?

Importing Items to a roadmap is the same as creating and adding roadmap Items. You must be the roadmap's Owner OR the roadmap must be shared with you as an Editor. 

If a roadmap has been shared with you as Viewer, you have view-only access to the roadmap and can't import Items to it. You'll see a View Only icon on the Roadmap navbar, and the Import icon on the View navbar will be grayed-out and disabled.

CSV Separator Defaults in Roadmunk

Any CSV file exported from Roadmunk will default to the North American standard settings for separators; however, many of our users are setup on systems that don’t support this standard and may face issues when opening their CSV files in Excel, Numbers, or other spreadsheet software. The guides below will walk you through the process of setting up your system so that you can successfully import Roadmunk’s CSV files in both Windows and Mac OS.

Changing CSV Defaults on Windows

In order to change the CSV separator defaults in your system for Windows:

1. Click the Start button or press the Windows key, and then click/type Control Panel.

2. Open the dialog box for changing Regional and Language Settings.

3. In the List Separator box, type or select a standard comma ( , ).

4. Click Ok twice.

Changing CSV Defaults on Mac (Mojave & newer)

In order to change the CSV separator defaults in your system for Mac:

1. Navigate to your System Preferences and select the Language & Region option. Alternatively, press Command + Space and type in “Language”.

2. Click the Advanced button in the bottom-right corner.

3. In the Number separators options, change the decimal setting from a comma ( , ) to a period ( . )

4. Click OK in the bottom right corner

Note:  After you change the list separator character for your Mac or PC, all programs will use the new character as a list separator. You can change the character back to the default character by following the same procedures listed above.