GoogleDriveManagement/wiki/Users-Tasks.md

Users - Tasks

• API documentation
• Notes
• Definitions
• Specifying task lists
• Create Tasks
• Update Tasks
• Delete Tasks
• Move Tasks
• Display Tasks
• Create Task Lists
• Update Task Lists
• Delete Task Lists
• Clear Task Lists
• Display Task Lists

API documentation

• Tasks API

Notes

To use these commands you must add the 'Tasks API' to your project and update your service account authorization.

gam update project
gam user user@domain.com update serviceaccount

Definitions

• <UserTypeEntity>

<TaskID> ::= <String>
<TaskListID> ::= <String>
<TaskListTitle> ::= tltitle:<String>
<TasklistTitleList> ::= "'<TasklistTitle>'(,'<TasklistTitle>')*"
<TasklistIDTaskID> ::= <TasklistID>/<TaskID>
<TasklistIDList> ::= "<TasklistID>(,<TasklistID>)*"
<TasklistIDTaskIDList> ::= "<TasklistIDTaskID>(,<TasklistIDTaskID>)*"
<TasklistEntity> ::=
        <TasklistIDList> | <TaskListTitleList> | <FileSelector> | <CSVFileSelector>
        See: https://github.com/GAM-team/GAM/wiki/Collections-of-Items
<TasklistIDTaskIDEntity> ::=
        <TasklistIDTaskIDList> | <FileSelector> | <CSVFileSelector>
        See: https://github.com/GAM-team/GAM/wiki/Collections-of-Items

<TaskAttribute> ::=
        (title <String>)|
        (notes <String>)|
        (status needsaction|completed)|
        (due <Time>)

<TasklistAttribute> ::=
        (title <String>)

Specifying task lists

The Tasks API requires that a task list be specified by its ID; GAM allows specification of a task list by its title and makes an additional API call to convert the title to an ID.

Note the quoting in <TasklistTitleList>; the entire list should be enclosed in " and each tltitle:<String> must be enclosed in ' if <String> contains a space.

gam user user@domain.com create task "'tltitle:My Tasks'" title "Task title" notes "Task Notes"
gam user user@domain.com info tasklist "'tltitle:My Tasks'"

Create Tasks

gam <UserTypeEntity> create task <TasklistEntity>
        <TaskAttribute>* [parent <TaskID>] [previous <TaskID>]
        [compact|formatjson|returnidonly]

The API only supports all-day tasks; you should specify: due YYYY-MM-DDT00:00:00Z.

By default, Gam displays the created task as an indented list of keys and values; the task notes text is displayed as individual lines.

• compact - Display the task notes text with escaped carriage returns as \r and newlines as \n
• formatjson - Display the task in JSON format
• returnidonly - Display the note name only

Update Tasks

gam <UserTypeEntity> update task <TasklistIDTaskIDEntity>
        <TaskAttribute>*
        [compact|formatjson]

By default, Gam displays the updated task as an indented list of keys and values; the task notes text is displayed as individual lines.

• compact - Display the task notes text with escaped carriage returns as \r and newlines as \n
• formatjson - Display the task in JSON format

Delete Tasks

gam <UserTypeEntity> delete task <TasklistIDTaskIDEntity>

Move Tasks

gam <UserTypeEntity> move task <TasklistIDTaskIDEntity>
        [parent <TaskID>] [previous <TaskID>]
        [compact|formatjson]

By default, Gam displays the moved task as an indented list of keys and values; the task notes text is displayed as individual lines.

• compact - Display the task notes text with escaped carriage returns as \r and newlines as \n
• formatjson - Display the task in JSON format

Display Tasks

All commands that display tasks display the due date in GMT as the time portion is not supported by the API and converting the due date to local time may display the wrong date.

Display selected tasks

gam <UserTypeEntity> info task <TasklistIDTaskIDEntity>
        [compact|formatjson]

By default, Gam displays the tasks as an indented list of keys and values; the task notes text is displayed as individual lines.

• compact - Display the task notes text with escaped carriage returns as \r and newlines as \n
• formatjson - Display the task in JSON format

Display all tasks

gam <UserTypeEntity> show tasks [tasklists <TasklistEntity>]
        [completedmin <Time>] [completedmax <Time>]
        [duemin <Time>] [duemax <Time>]
        [updatedmin <Time>]
        [showcompleted [<Boolean>]] [showdeleted [<Boolean>]] [showhidden [<Boolean>]] [showall]
        [orderby completed|due|updated]
        [countsonly|compact|formatjson]

The API only supports dates in duemin and `duemax' but you must supply a null time:

• duemin YYYY-MM-DDT00:00:00Z - Specify the starting due date
• duemax YYYY-MM-DDT00:00:00Z - Specify one day beyond the ending due date

For example: duemin 2024-05-01T00:00:00Z duemax 2024-05-02T00:00:00Z will display all tasks on 2024-05-01.

By default, tasks are displayed in hierarchical order.

• orderby completed - Display tasks in completed date order regardless of the hierarchy.
• orderby due - Display tasks in due date order regardless of the hierarchy.
• orderby updated - Display tasks in updated date order regardless of the hierarchy.

By default, Gam displays the tasks as an indented list of keys and values; the task notes text is displayed as individual lines.

• compact - Display the task notes text with escaped carriage returns as \r and newlines as \n
• formatjson - Display the task in JSON format

By default, only tasks with status needsAction are displayed.

• showdeleted - Add deleted tasks to the display
• showhidden - Add hidden tasls to the display
• showcompleted - Add completed tasks to the display. showHidden must also be True to show tasks completed in first party clients, such as the web UI and Google's mobile apps.
• showall - Equivalent to showdeleted showhidden showcompleted

gam <UserTypeEntity> print tasks [tasklists <TasklistEntity>] [todrive <ToDriveAttribute>*]
        [completedmin <Time>] [completedmax <Time>]
        [duemin <Time>] [duemax <Time>]
        [updatedmin <Time>]
        [showcompleted [<Boolean>]] [showdeleted [<Boolean>]] [showhidden [<Boolean>]] [showall]
        [orderby completed|due|updated]
        [countsonly | (formatjson [quotechar <Character>])]

The API only supports dates in duemin and `duemax' but you must supply a null time:

• duemin YYYY-MM-DDT00:00:00Z - Specify the starting due date
• duemax YYYY-MM-DDT00:00:00Z - Specify one day beyond the ending due date

For example: duemin 2024-05-01T00:00:00Z duemax 2024-05-02T00:00:00Z will display all tasks on 2024-05-01.

By default, tasks are displayed in hierarchical order.

• orderby completed - Display tasks in completed date order regardless of the hierarchy.
• orderby due - Display tasks in due date order regardless of the hierarchy.
• orderby updated - Display tasks in updated date order regardless of the hierarchy.

By default, only tasks with status needsAction are displayed.

• showdeleted - Add deleted tasks to the display
• showhidden - Add hidden tasls to the display
• showcompleted - Add completed tasks to the display. showHidden must also be True to show tasks completed in first party clients, such as the web UI and Google's mobile apps.
• showall - Equivalent to showdeleted showhidden showcompleted

By default, Gam displays the information as columns of fields; the following option causes the output to be in JSON format,

• formatjson - Display the fields in JSON format.

By default, when writing CSV files, Gam uses a quote character of double quote ". The quote character is used to enclose columns that contain the quote character itself, the column delimiter (comma by default) and new-line characters. Any quote characters within the column are doubled. When using the formatjson option, double quotes are used extensively in the data resulting in hard to read/process output. The quotechar <Character> option allows you to choose an alternate quote character, single quote for instance, that makes for readable/processable output. quotechar defaults to gam.cfg/csv_output_quote_char. When uploading CSV files to Google, double quote " should be used.

Create Task Lists

gam <UserTypeEntity> create tasklist
        <TasklistAttribute>*
        [returnidonly] [formatjson]

By default, Gam displays the created task list as an indented list of keys and values.

• formatjson - Display the task list in JSON format
• returnidonly - Display the task list ID only

Update Task Lists

gam <UserTypeEntity> update tasklist <TasklistEntity>
        <TasklistAttribute>*
        [formatjson]

By default, Gam displays the updated task list as an indented list of keys and values.

• formatjson - Display the task list in JSON format

Delete Task Lists

gam <UserTypeEntity> delete tasklist <TasklistEntity>

Clear Task Lists

Clears all completed tasks from the specified task lists.

gam <UserTypeEntity> clear tasklist <TasklistEntity>

Display Task Lists

Display selected task lists

gam <UserTypeEntity> info tasklist <TasklistEntity>
        [formatjson]

By default, Gam displays the task lists as an indented list of keys and values.

• formatjson - Display the task list in JSON format

Display all Task Lists

gam <UserTypeEntity> show tasklists
        [countsonly|formatjson]

By default, Gam displays the task lists as an indented list of keys and values.

• formatjson - Display the task lists in JSON format

gam <UserTypeEntity> print tasklists [todrive <ToDriveAttribute>*]
        [countsonly | (formatjson [quotechar <Character>])]

By default, Gam displays the information as columns of fields; the following option causes the output to be in JSON format,

• formatjson - Display the fields in JSON format.

By default, when writing CSV files, Gam uses a quote character of double quote ". The quote character is used to enclose columns that contain the quote character itself, the column delimiter (comma by default) and new-line characters. Any quote characters within the column are doubled. When using the formatjson option, double quotes are used extensively in the data resulting in hard to read/process output. The quotechar <Character> option allows you to choose an alternate quote character, single quote for instance, that makes for readable/processable output. quotechar defaults to gam.cfg/csv_output_quote_char. When uploading CSV files to Google, double quote " should be used.