Background information about Google Tasks data

Note that this information is based on my own discoveries and conclusions as at May 2012. I hope that this information helps people, but I cannot guarantee the accuracy or completeness of this information. Note also that Google may change their specifications, in which case this information may be out of date.

Understanding the Raw and Python data formats

Most of the properties are self-explanatory, however the relationship between status, hidden and deleted may require some additional explanation.
Table 1 lists the various states and the corresponding task property values.
Table 1: Task states
Task properties (Note 1, 2) DescriptionVisible in View:
status deleted hidden My order
Sort by date
Completed tasks Trash
(Note 3)
needsActionTo be completed, visible in main windowYesNoNo
needsActionTrueDeleted incomplete task. Visible only in [Trash]NoNoYes
completedMarked complete, before clicking [Clear completed]YesYesNo
completedTrueDeleted completed task. Visible only in [Trash]NoNoYes
completedTrueMarked complete, after clicking [Clear completed]NoYesNo
needsActionTrueTrue ======= Not valid =======
needsActionTrue ======= Not valid =======
completedTrueTrue ======= Not valid =======

Other problems

Date/time properties such as the completed property have occassionally contained invalid timestamps, where the year is stored as a large negative number such as -1701567. In this case, the application exports the value "1900-01-01 00:00:00" instead.

Importing and exporting

Google Tasks Backup supports 2 different Import/Export formats; GTBak and CSV.

Import/Export GTBak format

Files exported from Google Tasks Backup in the Import/Export GTBak format have a filename format of tasks_gtb_XXXXXX.GTBak, where XXXXXX identifies the account name and export date.
The GTBak file uses Python pickle serialisation to ensure that no extended character information is lost or modified (which can happen with the CSV format). This format is not easily editable by humans.
The GTBak format is strongly recommended, especially where tasks may contain international or extended characters, such as accents or special symbols.

Import/Export CSV format

Files exported from Google Tasks Backup in the Import/Export CSV format have a filename format of tasks_import_export_XXXXXX.csv, where XXXXXX identifies the account name and export date.
The file is a standard Windows-format CSV (comma-separated-values) file, and includes all task properties required to recreate the tasks, including tasklist name and task/sub-task relationships.
The file can be edited in a text editor such as Notepad++ before being imported. It is not recommended to edit this file with a spreadsheet program, as programs such as Excel and OpenOffice Calc tend to corrupt the data. The import file must observe the following rules;

Cautions when importing;

Table 2: Import file format
Column name Description
tasklist_name If this is the name of an existing tasklist, tasks will be added to that list.
If the tasklist does not exist, a new tasklist will be created.
title Task title.
notes Task notes. May be multi-line, using \n as the line break.
status Can be either "needsAction" or "completed"
due If the task has a due date, the date that the task is due, in the format "UTC YYYY-mm-dd"
If the task does not have a due date, leave this field blank
The due date field must start with UTC
completed If the task has been completed, the date and time that the task was completed, in the format "UTC YYYY-mm-dd HH:MM:SS"
If the task has not been completed, leave this field blank
The completed date-time field must start with UTC
deleted If the task has been deleted (see above), the single word "True"
If the task has not been deleted, leave this field blank
hidden If the task has been hidden (see above), the single word "True"
If the task has not been hidden, leave this field blank
depth The depth of the task indicates the parent-child relationship between tasks.
Depth is a positive number. Higher numbers indicate greater depth.
Tasks with depth 0 are root tasks.
Example import/export file;

Note the \n in the multi-line notes in "Second subtask", and the escaped double-quotes in the notes for "Second task"

"tasklist_name","title","notes","status","due","completed","deleted","hidden",depth
"My Tasklist","First task","This is a root task","needsAction","UTC 2012-08-23",,,,0
"My Tasklist","First subtask","This is a subtask of the first task","needsAction","UTC 2012-08-19",,,,1
"My Tasklist","Second subtask","This is a subtask\nof the first subtask","needsAction","UTC 2012-04-21",,,,2
"My Tasklist","Third subtask","This is a subtask of the second subtask","needsAction",,,,,3
"My Tasklist","Fourth subtask","This is a 2nd subtask of the first subtask","needsAction","UTC 2012-07-25",,,,1
"My Tasklist","Second task","This is another ""root"" task","completed",,"UTC 2012-04-22 02:42:36",,,0
This is displayed in Google Tasks as;
Google Tasks Backup displays this as;
Task List: My Tasklist - 6 tasks.
[  ] First task
This is a root task
Due: Thu, 23 Aug 2012 UTC
[  ] First subtask
This is a subtask of the first task
Due: Sun, 19 Aug 2012 UTC
[  ] Second subtask
This is a subtask
of the first subtask
Due: Sat, 21 Apr 2012 UTC
[  ] Third subtask
This is a subtask of the second subtask
[  ] Fourth subtask
This is a 2nd subtask of the first subtask
Due: Wed, 25 Jul 2012 UTC
Second task
COMPLETED: 02:42 Sun, 22 Apr 2012 UTC
This is another "root" task

Notes
Note 1 - CAUTION: The Outlook, RTM and iCalendar file formats do not have fields for deleted or hidden, so those programs will display deleted and/or hidden tasks as normal tasks. Unless you have a specific reason, do not include deleted or hidden tasks when downloading for applications such as Outlook, RTM or iCalendar.
Note 2 - All 3 properties are stored by Google as strings. The status field may be either "needsAction" or "completed". The deleted and hidden properties can be either an empty string (indicating false), or the word "True".
Note 3 - When tasks are deleted, they are marked as Hidden and moved to the [Trash] view.
According to Google, deleted tasks stay in the Trash (deleted = True) for "some period of time" and are then auto deleted. I have noticed deleted tasks in my Trash that are up to 10 months old. There does not appear to be any way to force a task to be actually deleted. That is, the Trash bin cannot be emptied by the user.
Note 4 - CAUTION: Sometimes, tasks can become corrupted, leaving an invalid parent value. These tasks still exist in the Google Tasks database, although Google does not display them.
When a sub-task is deleted or hidden, the sub-task retains the parent value, so that Google can restore the task to the correct parent. However, that parent value may be invalid for a task that has been deleted or hidden, or whose parent was hidden, deleted or moved whilst the subtask was deleted. It may even refer to a task in another tasklist!
One common way that tasks become corrupted is;
  1. Start with nested tasks A/B/C/D
  2. Delete D
  3. Delete C
  4. Restore D from Trash
Since task D's parent no longer exists, Google doesn't know where to put the task, so it becomes an (invisible) orphan.
Invalid tasks are not exported to file or email, however the tasks display page provides an option to display invalid/corrupted tasks.
Note 5 - Tasks may also be corrupted by some third-party task organiser programs, especially those that do not (properly) support sub-tasks, or if communications is interrupted during a sync.
Normally, a completed task cannot have incomplete sub-tasks (which makes sense). The Google Tasks web interface at mail.google.com/tasks/canvas?pli=1 takes care of that; marking a parent task complete automatically marks all it's subtasks complete. Some third party apps don't do that, thereby leaving a completed task with incompleted subtasks.
If the user then clears completed tasks, the completed parent is marked as hidden. If the user exports with hidden tasks excluded, then the exported sub-tasks no longer have parents.
Simarly, if exporting tasks with the "Include completed tasks?" option unchecked, the completed parent task will not be exported, but the incomplete sub-tasks will, resulting in orphaned tasks which cannot be properly processed, because the sub-task's parent does not exist.
Invalid tasks are not exported to file or email, however the tasks display page provides an option to display invalid/corrupted tasks.

Icons thanks to Visual Pharm, Deleket and Creative Freedom
Popup help window script thanks to yendesign
Popup calendar script thanks to TengYong Ng