Roadmunk's Import step-through dialog makes importing items from a CSV as easy as 1, 2, 3: Upload, map, import.
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, only the Buckets will be imported. For more on item Buckets vs. Dates, see Create and add roadmap items.
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).
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.
The details will help you figure out what went wrong and whether you can fix the errors by adjusting field mappings or whether you need to edit and re-import the CSV file.
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 an item has both, only the Bucket will be imported.
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 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.
Field types and field mapping
Field types in the CSV file must be mappable to the field types currently supported by Roadmunk.
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:
IMPORTANT: All dates must be in the same format, and only dates between 2010 and 2040 can be imported.
Time 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 fields can contain any alphanumeric value including URLs.
A List field can contain a single value from a list of values.
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.
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.