CSV Syntax

The character encoding used for both import and export is UTF-8. Values in UTF-8 encoding ensure character integrity in the import and export results.

Each line represents an object. An import will create, update, or delete the corresponding object depending on the value of the URI, External Id, and Operation columns. For more about these columns, see Line Values.

Some columns are ignored during an update. For example, the Assignee and Dependencies columns are ignored except during creation.

Each line (except for the root project line) must have a "level" value.

The "level" value represents the tree structure of the project and contents to import:

• For elements directly under the root project, the "level" value is an integer, starting from 1. It corresponds to the display order of the element under the root-project.
• For elements under a subproject, the "level" value is built by adding to the parent project’s "level" value a dot character ( . ) and the position integer of the element under its parent project.

For example:

Level,type,NAME
 ,Project,Main Project
1,Task,First main Task
2,Task,Second main Task
2,Project,sub-project
2.1,Task,First task of sub-project
2.2,Task,Second, and last, task of sub-project
2.3,Project,deeper project
2.3.1,Task,”Unique task, inside deeper project”

Here is the imported structure:

Each line must have a nonempty "name" value.

The "name" value is free text used as the element's Title in Project Planning.

Starting and trailing blanks are removed.

Each line (except for the root project’s line) must have a "type" value.

Type is mapped as follows:

The "dependencies" column contains the description of dependencies applying to the element.

Each dependency is specified by:

• A number indicating the constraining element by its definition order in the CSV file: root project as 0, the element defined on the next line as 1, the element defined on the following line is 2, etc.
• The column ( : ) character.
• A type given by 2 letters (case insensitive):
  • FS (Finish-to-Start): this element (the one defined in the current line) cannot start until the "number" element finishes.
  • SF (Start-to-Finish): this element cannot finish until the "number" element starts.
  • FF (Finish-to-Finish): this element cannot finish until the "number" element finishes.
  • SS (Start-to-Start): this element cannot start until the "number" element starts

Optionally:

• A plus ( + ) or a minus ( – ) character.
• A delay expressed as an integer, optionally followed by a unit: "D" for days (default) or "H" for hours.

If 2 or more dependencies are defined, they must be separated by a comma ( , ).

For example:

Level,Type,Name,Dependencies 
0,Project,Main Project,
1,Gate,First main Milestone,
2,Task,First main Task,1:FS
3,Phase,sub-project,
3.1,Gate,First Milestone of sub-project,1:FS+1D
3.2,Task,First task of sub-project,"1:FS-1,4:SF+5D"
3.3,Project,deeper project,
3.3.1,Task,Unique task of deeper project,4:SS+4h

The "status" can contain a keyword indicating the assessment on an element.

The "state" can contain only one of these values (case insensitive):

If another value is given, a warning will occur. If the "state" column is missing, or the "state" value is incorrect or empty, the Project Planning "Open" state will be set by default.

The "%" is an integer indicating the percentage of completion of a Task. The "%" is ignored in Project Planning for Gate/Milestone or Project/Phase.

If the "%" column is missing, incorrect, or empty, a 0% percentage will be used by default.

For example:

Level,type,NAME,state,%
0, ,Main Project,,
1,Gate,First main Milestone,,
2,Task,First main Task,In Work,30
3,Phase,sub-project,Ready,
3.1,Gate,First Milestone of sub-project,Preliminary,
3.2,Task,First task of sub-project,In Review,0
4,Task,Last main Task,Complete,100

A line defining a Task must have a valid "duration" value. Duration is ignored on lines describing a Gate/Milestone or a Project/Phase.

A duration is expressed as an integer, optionally followed by a unit. The unit is case insensitive and can be:

• "D" or "Day" or "Days" (by default)
• "H" or "Hour" or "Hours"

For example:

Level,type,Name,Start,End Date,duration
0, ,Main Project,,,
1,Gate,First Main Milestone,2018-12-01,,
2,Task,First Main Task,2018-12-01,2018-12-15,10D
3,Phase,sub-project,,,
3.1,Gate,First Milestone of sub-project,2018-12-07,, 
3.2,Task,First task of sub-project,2018-12-07T08:00Z,2018-12-07T12:00Z,4 hours
3.3,Task,Last  task of sub-project,2018-12-07,2018-12-09,2

A line defining a task may have a valid "duration offset" value. Duration is ignored on lines describing a Gate/Milestone or a Project/Phase.

A duration offset is expressed as an integer, optionally followed by a unit. The unit is case insensitive and can be:

• "D" or "Day" or "Days" (by default)
• "H" or "Hour" or "Hours"

The duration offset value should be less than or equal to the duration value.

For example:

level,type,name,start,end date,duration,duration offset
0, ,Main Project,,,
1,Gate,First main Milestone,2018-12-01,,
2,Task,First main Task,2018-12-01,2018-12-15,10D
3,Phase,sub-project,,,
3.1,Gate,First Milestone of sub-project,2018-12-07,, 
3.2,Task,First task of sub-project,2018-12-07T08:00Z,2018-12-07T12:00Z,4 hours,2H
3.3,Task,Last  task of sub-project,2018-12-07,2018-12-09,2,1

A TRUE value sets the corresponding date as fixed.

An empty value on update does not change whether a date is fixed or not.

An empty value on create sets the date to not fixed.

A FALSE value sets the corresponding date to not fixed.

The line defining a Gate or Milestone must have a valid "start" value.

The line defining a Task must have a valid "start" value and a valid "end" value.

Dates are ignored on lines describing a Project or Phase.

The start value for an existing project or phase sets the start date of the project.

Most date and time formats supported by ECMA script are supported here, but it is recommended to use the ISO-8601 YYYY-MM-DD format. For example, September 27, 2012 is represented as 2012-09-27. You can also add time by appending the letter "T" followed by hh:mm or hh:mm:ss. For example, March 2, 2017 at 10 hours, 35 minutes and 2 seconds is represented as 2017-03-02T10:35:02.

If you add time, you can also specify a time zone by adding letter "Z" for UTC time (the default if no time zone is specified) or an offset to it in the expression "+" or "-" hh:mm (or only hh). For example, May 12, 2015 at 12:30 in Hawaii is represented as 2015-05-12T12:30-10:00.

Dates in the CSV are handled as follows:

• If the date format has a timestamp associated with it, the date will be the same as it exists in the file. Examples of date formats that are saved as found are: 2021-02-03T09:23:12Z, 2021-02-03T09:23:12.002Z, and 2021-03-11T16:26:04+00:00.
• If the date format does not have a timestamp associated with it, the time (12:00 hours) will be added to it. For example, if the date provided in the CSV is 2021-03-09, it is saved as 2021-03-09T12:00:00Z.

Project Planning supports both actual and estimated dates for tasks and milestones.

Which date is used depends on the state of the object:

These are required date values for the estimated start and end dates.

The "owner" can contain the login of the person who owns the element.

The "assignee" can contain the login of the person assigned to the element. If more than one person is assigned, you must separate the logins by commas.

Only persons who have launched the Project Planning widget at least once or are member of at least one project or assigned to at least one task can be assigned through import this way. If a person’s login is added to an assignee field and that person does not meet this condition, a warning is shown in the report window and the person is not assigned.

The "Description" value is free text used as an element’s Description in Project Planning.

Starting and trailing blanks will be removed.

For example:

Level,Type,Name,Description
0,Project,Root Project,some text about this project
1,Gate,First Main Milestone,"comments on ""this"" 
gate"

Here is the imported structure:

Priority only applies to tasks and is ignored for other objects. Priority can contain one of these values (case-insensitive):

• Low
• Medium
• High
• Urgent

If another value is used, a warning occurs. If the "priority" column is missing, or the "priority" value is incorrect or empty, the "Medium" priority is set by default.

If the URI column contains a valid Project Planning URI, and an object with this URI exists, it is updated.

If no object with this URI is found, an error is displayed and the line is ignored.

This is intended for projects that are first created in Project Planning, then exported, and later reimported after the CSV file is modified. Do not fill in this column manually.

The external Id column is intended for importing projects from an external system. This column should contain a string that is unique to the object in question within its native system. This should use only characters in the following list:

• Basic alphanumeric (a-zA-Z0-9, no accented characters)
• -:.;&_?#/

If a line has a value in the External Id, the import looks for an existing object with the same combination External Id/External System and, if found it, updates it. If no object with this combination is found, a new one is created.

The external system column is used with the External Id. It is highly recommended to always have an External System value when you have an External Id.

All objects from the same system should have the same string in that column.