Project

Profile

Help

Import issues into Planio via CSV files » History » Sprint/Milestone 75

Gregor Schmidt, 03/13/2018 04:55 PM

1 23 Thomas Carney
# Import issues into Planio via CSV files
2
3 46 Thomas Carney
This is a guide on how you can import tasks, issues, tickets or stories from Comma Separated Values (CSV) files using the importer in Planio. You'll be able to move data between different software packages easily. For instance, you could plan a project in Microsoft Project, and then you could import all the tasks into Planio as issues.
4 23 Thomas Carney
5 1 Thomas Carney
{{>toc}}
6 32 Thomas Carney
7 47 Thomas Carney
There are two steps to this process. First, you need to prepare a CSV file for import. Second, you have to carry out the import. We’ll cover both in this guide.
8 23 Thomas Carney
9 1 Thomas Carney
## Preparing the CSV file
10
11 56 Thomas Carney
You need to export your tasks, issues or tickets in the CSV format. You can save most Excel sheets as CSV files by clicking on **File -\> Save As…** and then selecting **Comma Separated Values** as the format from the drop-down menu.
12 1 Thomas Carney
13 62 Thomas Carney
Your CSV file can have the following headers. You’ll find a sample CSV file here: attachment:example.csv.
14 1 Thomas Carney
15 75 Gregor Schmidt
| Values           | Notes                                                                                                                                                                                                                                                                     |
16
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
17
| Tracker          | The tracker of the issue. This is needs to map a name of an existing tracker in your project. You’ll find their names in **Administration -\> Trackers**. If you don't provide this column within the CSV, you may select a tracker for all new issues during the import. |
18
| Status           | The status of the issue. This is needs to map a name of an existing status available for the selected tracker. You’ll find their names in **Administration -\> Issue statuses**. If you don't provide this column within the CSV, the default status will be used.        |
19
| Subject          | The subject of the issue. This is required                                                                                                                                                                                                                                |
20
| Description      | Enter the text describing the issue.                                                                                                                                                                                                                                      |
21
| Priority         | Enter the name of one of the priorities listed in your Planio account. You’ll find their names in **Administration -\> Enumerations**                                                                                                                                     |
22
| Category         | The category of the issue. New categories may created automatically during the import, if need be.                                                                                                                                                                        |
23
| Assignee         | Enter the First and Last Name, login or email of the person to whom you want to assign the issue. You’ll find those details in **Administration -\> Users**. Make sure the person is a member of the project before assigning them issues via the importer.               |
24
| Sprint/Milestone | Enter the name of the milestone or sprint to which the issue should be assigned. New sprints/milestones may be created automatically during the import, if need be.                                                                                                       |
25
| Private          | This selects whether the issue will be private for the assignee or not. Enter `1` to make the issue private or `0` otherwise.                                                                                                                                             |
26
| Start date       | Enter the start date in your preferred date format (e.g. MM/DD/YYYY or DD.MM.YYYY).                                                                                                                                                                                       |
27
| Due date         | Enter the due date in your preferred date format (e.g. MM/DD/YYYY or DD.MM.YYYY).                                                                                                                                                                                         |
28
| Estimated time   | Enter a number for the estimated number of hours (e.g. 15).                                                                                                                                                                                                               |
29
| % Done           | Enter a number for the percentage done (e.g. 27).                                                                                                                                                                                                                         |
30 59 Thomas Carney
31 75 Gregor Schmidt
> Please note: You may also import issue relations. This topic is [[Import_issues_into_Planio_via_CSV_files#Import-issue-relations|covered below]].
32
33 38 Thomas Carney
## Importing the CSV File
34 5 Thomas Carney
35 39 Thomas Carney
Now, you have a CSV file ready for import. The next step is to import it into Planio. You’ll find the button for the Import on the issues page in the sidebar.
36 1 Thomas Carney
37 74 Jan Schulz-Hofen
{{figure(Click on Import in the sidebar on the right)
38
!issues-page@2x.png!
39
}}
40 1 Thomas Carney
41
Then, select your CSV file using the file picker.
42 2 Thomas Carney
43 74 Jan Schulz-Hofen
{{figure(Upload the CSV file using the file picker)
44
!file-selector@2x.png!
45 24 Thomas Carney
}}
46 1 Thomas Carney
47
On the next page, you can select options for importing the CSV File
48
49 74 Jan Schulz-Hofen
{{figure(Select the options for importing the CSV file based on how your CSV file is formatted)
50
!import-options@2x.png!
51
}}
52 2 Thomas Carney
53 55 Thomas Carney
| Option          | Notes                                                                                                |
54 1 Thomas Carney
| --------------- | ---------------------------------------------------------------------------------------------------- |
55
| Field separator | You can select between comma separated values or semicolon separated values                          |
56
| Field wrapper   | You can select between double quotes or single quotes.                                               |
57 55 Thomas Carney
| Encoding        | You can select the encoding for the CSV file                                                         |
58 1 Thomas Carney
| Date format     | You can select one of five date formats (YYYY-MM-DD, DD/MM/YYYY, MM/DD/YYY, DD.MM.YYY or DD-MM-YYYY) |
59 56 Thomas Carney
60 75 Gregor Schmidt
First you have to select a target project for the import. Then, you have to map the values from the CSV files to issue fields in Planio. You can select each value from the drop-down menu beside each attribute. You’ll also see a file content preview further down, so you can make sure you’re importing the right data.
61 1 Thomas Carney
62 74 Jan Schulz-Hofen
{{figure(Assign each column in the CSV file to an issue field)
63
!field-mapping@2x.png!
64
}}
65 1 Thomas Carney
66
Once you’re done assigning the values to each field, you can click on import to start the import.
67
68
If you encounter any issues, you'll see a page with the errors and the import will not be carried out. You can restart the import once you've fixed the problems in the CSV file.
69
70
{{figure(A list of the errors encountered during the import)
71
!import-error@2x.png!
72
}}
73
74
If all goes well, you’ll see a list of the imported issues.
75
76
{{figure(You'll see a list of the created issues.)
77
!successful-import@2x.png!
78
}}
79
80
That's how you can import tasks, issues, bugs or stories into Planio using the CSV importer.
81 75 Gregor Schmidt
82
# Import issue relations
83
84
The issue import may also set up issue hierarchies as well as any other issue relation supported by Planio. You may store the relationship information in dedicated columns within your CSV file.
85
86
## Preparing the CSV file
87
88
### Issue hierarchies
89
90
Issue hierarchies may be specified via a parent issue column. Each issue may have exactly on parent issue. To reference already existing issues within your projects, you may use the issue number with a `#` in front, e.g. `#13`. To reference issues, which are part of the same CSV, you may either use the row number or you may specify a special "Unique ID" column, which contains the reference text.
91
92
**Referencing existing issues**
93
94
|                                 |           |
95
| ------------------------------- | --------- |
96
| Subject                         | Parent ID |
97
| Rocket booster firmware upgrade | #13       |
98
| Attach booster to rocket        | #13       |
99
100
Issue `#13` would have been created before the import.
101
102
**Referencing new issues via row number**
103
104
|                                 |           |
105
| ------------------------------- | --------- |
106
| Subject                         | Parent ID |
107
| Install new rocket booster      |           |
108
| Rocket booster firmware upgrade | 1         |
109
| Attach booster to rocket        | 1         |
110
111
Please note, that numbering starts with the first non-header row.
112
113
**Referencing new issues via Unique ID column**
114
115
|            |                                 |            |
116
| ---------- | ------------------------------- | ---------- |
117
| ID         | Subject                         | Parent ID  |
118
| ROCKET-101 | Install new rocket booster      |            |
119
| ROCKET-201 | Rocket booster firmware upgrade | ROCKET-101 |
120
| ROCKET-202 | Attach booster to rocket        | ROCKET-101 |
121
122
Please be aware, that the unique ID may not start with a `#` sign. Otherwise it would be mistaken for a reference to an existing issue.
123
124
### Issue relations
125
126
Planio supports the following issue relations:
127
128
  - Related to
129
  - Duplicates / Duplicated by
130
  - Blocks / Blocked by
131
  - Copied to / Copied from
132
  - Precedes / Follows
133
134
Each issue may be part of many relations, although there are logical restrictions, e.g. an issue cannot block a preceding task. Each relation type should be presented in a different column within the CSV. You may reference other issues using the same three techniques mentioned above. Multiple relations of the same type should be separated by comma.
135
136
Please be aware, when using a dedicated Unique ID column, that said ID may not contain commas, since that is used as a separator.
137
138
For the follows and precedes relation, you may also add the delay incorporated.
139
140
**Example defining relations with delay**
141
142
|            |                                 |            |               |
143
| ---------- | ------------------------------- | ---------- | ------------- |
144
| ID         | Subject                         | Blocked by | Follows       |
145
| ROCKET-201 | Rocket booster firmware upgrade |            |               |
146
| ROCKET-202 | Paint rocket red                |            |               |
147
| ROCKET-203 | Attach booster to rocket        | ROCKET-201 | ROCKET-202 2d |
148
149
The booster may only be attached after the firmware was upgraded and after the paint dried for two day.
150
151
## Importing the CSV file
152
153
Follow the steps described above. When mapping the values from the CSV files to issue fields in Planio, you may also define, which CSV column contains defines which issue relation. When selecting a column for Unique ID, it is assumed, that you're using these value to reference other issues. If that mapping is left blank, it is assumed that row numbers are used.
154
155
{{figure(Assign CSV columns to relationship types)
156
!relations-mapping@2x.png!
157
}}
158
159
The rest of the import works as described above.