mirror of
https://github.com/GAM-team/GAM.git
synced 2025-05-12 04:07:21 +00:00
336 lines
15 KiB
Markdown
336 lines
15 KiB
Markdown
# Users - Forms
|
|
- [API documentation](#api-documentation)
|
|
- [Notes](#notes)
|
|
- [Definitions](#definitions)
|
|
- [Create a Form](#create-a-form)
|
|
- [Update a Form](#update-a-form)
|
|
- [Extended Example](#extended-example)
|
|
- [Display Forms](#display-forms)
|
|
- [Display Form Responses](#display-form-responses)
|
|
- [Combine Form Information](#combine-form-information)
|
|
|
|
## API documentation
|
|
* [Forms API](https://developers.google.com/forms/api/reference/rest)
|
|
|
|
## Notes
|
|
To use these commands you must add the 'Forms API' to your project and update your service account authorization.
|
|
|
|
Forms are identified by their `<DriveFileID>`.
|
|
```
|
|
gam update project
|
|
gam user user@domain.com update serviceaccount
|
|
```
|
|
|
|
## Definitions
|
|
* [`<DriveFileEntity>`](Drive-File-Selection)
|
|
* [`<UserTypeEntity>`](Collections-of-Users)
|
|
|
|
```
|
|
<DriveFileParentAttribute> ::=
|
|
(parentid <DriveFolderID>)|
|
|
(parentname <DriveFolderName>)|
|
|
(anyownerparentname <DriveFolderName>)|
|
|
(teamdriveparentid <DriveFolderID>)|
|
|
(teamdriveparent <SharedDriveName>)|
|
|
(teamdriveparentid <SharedDriveID> teamdriveparentname <DriveFolderName>)|
|
|
(teamdriveparent <SharedDriveName> teamdriveparentname <DriveFolderName>))|
|
|
(teamdriveparentid <DriveFolderID>)|(teamdriveparent <SharedDriveName>)|
|
|
(teamdriveparentid <SharedDriveID> teamdriveparentname <DriveFolderName>)|
|
|
(teamdriveparent <SharedDriveName> teamdriveparentname <DriveFolderName>)
|
|
|
|
<Time> ::=
|
|
<Year>-<Month>-<Day>(<Space>|T)<Hour>:<Minute>:<Second>[.<MilliSeconds>](Z|(+|-(<Hour>:<Minute>))) |
|
|
(+|-)<Number>(m|h|d|w|y) |
|
|
never|
|
|
now|today
|
|
```
|
|
|
|
## Create a Form
|
|
```
|
|
gam <UserTypeEntity> create form
|
|
title <String> [description <String>] [isquiz [Boolean>]] [<JSONData>]
|
|
[drivefilename <DriveFileName>] [<DriveFileParentAttribute>]
|
|
[(csv [todrive <ToDriveAttribute>*]) | returnidonly]
|
|
```
|
|
|
|
`<JSONData>` is a list of form update requests.
|
|
|
|
* See: https://developers.google.com/forms/api/reference/rest/v1/forms/batchUpdate
|
|
|
|
If `drivefilename <DriveFileName>` is not specified, the file will be named `<String>` from `title`.
|
|
|
|
By default, the user, form title and file name/ID values are displayed on stdout.
|
|
* `csv [todrive <ToDriveAttribute>*]` - Write user, file ID, file name, form title and responderUri values to a CSV file.
|
|
* `returnidonly` - Display just the file ID of the created file as output
|
|
|
|
To retrieve the file ID with `returnidonly`:
|
|
```
|
|
Linux/MacOS
|
|
fileId=$(gam user user@domain.com create form title "xyz" ... returnidonly)
|
|
Windows PowerShell
|
|
$fileId = & gam user user@domain.com create form title "xyz" ... returnidonly
|
|
```
|
|
The file ID will only be valid when the return code of the command is 0; program accordingly.
|
|
|
|
## Update a Form
|
|
Select forms with `<DriveFileEntity>`:
|
|
* `<DriveFileID>` - Update a specific form
|
|
* `my_forms` - Update all forms owned by the user
|
|
```
|
|
gam <UserTypeEntity> update form <DriveFileEntity>
|
|
[title <String>] [description <String>] [isquiz [Boolean>]] [<JSONData>]
|
|
```
|
|
|
|
`<JSONData>` is a list of form update requests.
|
|
|
|
* See: https://developers.google.com/forms/api/reference/rest/v1/forms/batchUpdate
|
|
|
|
## Extended Example
|
|
|
|
This example illustrates the use of JSN data to create and update forms
|
|
concerning student classtoom attendance.
|
|
The form has two items: Absences and Notes.
|
|
In `Absences`, the teacher can check `All present.` or check individual student absences.
|
|
In `Notes`, explanatory notes can be entered.
|
|
|
|
### Create
|
|
This is the form create request JSON.
|
|
|
|
The `deleteItem` request deletes the default item on a newly created form.
|
|
```
|
|
{
|
|
"requests": [
|
|
{"deleteItem": {"location": {"index": 0}}},
|
|
{"createItem": {
|
|
"item": {
|
|
"title": "Absences?",
|
|
"description": "To report attendance adjustments for late arrivals, please email attendance@domain.com.",
|
|
"questionItem": {
|
|
"question": {
|
|
"choiceQuestion": {
|
|
"type": "CHECKBOX","options": [
|
|
{"value": "All present."},
|
|
{"value": "Student Name1"},
|
|
{"value": "Student Name2"},
|
|
{"value": "Student Name3"},
|
|
{"value": "Student Name4"}
|
|
]
|
|
},
|
|
"required": true}
|
|
}
|
|
},
|
|
"location": {"index": 0}
|
|
}},
|
|
{"createItem": {
|
|
"item": {
|
|
"title": "Notes?",
|
|
"questionItem": {"question": {"textQuestion": {"paragraph": true}}}},
|
|
"location": {"index": 1}
|
|
}}
|
|
]
|
|
}
|
|
```
|
|
|
|
This is the create CSV file with the compressed form creation request JSON.
|
|
Each row specifies:
|
|
* `User` - The form owner
|
|
* `name` - The form file name
|
|
* `title` and `description` - The form title and description
|
|
* `JSON` - The compressed JSON requests
|
|
|
|
If you are using a local CSV file, surround the JSON data with single quotes `'`;
|
|
do not use the quotes if you are using a Google Sheet.
|
|
```
|
|
User,name,title,description,JSON
|
|
attendance@domain.com,MathClassAttendance,Math Class Attendance,Daily Attendance Report,'{"requests": [{"deleteItem": {"location": {"index": 0}}}, {"createItem": {"item": {"title": "Absent?", "description": "To report attendance adjustments for late arrivals, please email attendance@domain.com.", "questionItem": {"question": {"choiceQuestion": {"type": "CHECKBOX","options": [{"value": "All present."}, {"value": "Student Name1"}, {"value": "Student Name2"}, {"value": "Student Name3"}, {"value": "Student Name4"}]}, "required": true}}}, "location": {"index": 0}}}, {"createItem": {"item": {"title": "Notes?", "questionItem": {"question": {"textQuestion": {"paragraph": true}}}}, "location": {"index": 1}}}]}'
|
|
```
|
|
|
|
Build the forms; this example builds the forms in the `User's` root folder, adjust as required.
|
|
|
|
If you are using a local CSV file, use the `quotechar "'"` option;
|
|
do not use the option if you are using a Google Sheet.
|
|
```
|
|
$ gam redirect csv ./UpdateForms.csv multiprocess redirect stdout ./CreateForms.txt multiprocess redirect stderr stdout csv CreateForms.csv quotechar "'" gam user "~User" create form drivefilename "~name" parentid root title "~title" description "~description" json "~JSON" csv
|
|
2025-01-05T09:36:18.723-08:00,0/1,Using 1 process...
|
|
2025-01-05T09:36:18.724-08:00,0,Processing item 1/1
|
|
2025-01-05T09:36:23.818-08:00,0/1,Processing complete
|
|
```
|
|
|
|
This is the output
|
|
```
|
|
$ more UpdateForms.csv
|
|
User,formId,name,title,responderUri
|
|
attendance@domain.com,1xWfG_7sDCgrWDd-oqDCGE328-CozoAmqYMtP3WY2liw,MathClassAttendance,Math Class Attendance,https://docs.google.com/forms/d/e/1FAIpQLScYqOI2A4TBFVC4YwSxES6-lOD3O_jrN4vhkX09wXkNk0Z66w/viewform
|
|
```
|
|
|
|
### Update
|
|
This is the form update request JSON; the data is similar to the form create JSON.
|
|
The `deleteItem` request is deleted, `createItem` is replaced with `updateItem`, the `updateMask`
|
|
key and value are added to each update item. You would typically add, delete or update the `Student Name` values.
|
|
```
|
|
{
|
|
"requests": [
|
|
{"updateItem": {
|
|
"item": {
|
|
"title": "Absent?",
|
|
"description": "To report attendance adjustments for late arrivals, please email attendance@domain.com.",
|
|
"questionItem": {
|
|
"question": {
|
|
"choiceQuestion": {
|
|
"type": "CHECKBOX","options": [
|
|
{"value": "All present."},
|
|
{"value": "Student Name1"},
|
|
{"value": "Student Name2"},
|
|
{"value": "Student Name3"},
|
|
{"value": "Student Name4"},
|
|
{"value": "Student Name5"}
|
|
]
|
|
},
|
|
"required": true}
|
|
}
|
|
},
|
|
"location": {"index": 0},
|
|
"updateMask": "title,description,questionItem"}},
|
|
{"updateItem": {
|
|
"item": {
|
|
"title": "Notes?",
|
|
"questionItem": {"question": {"textQuestion": {"paragraph": true}}}},
|
|
"location": {"index": 1},
|
|
"updateMask": "title,questionItem"}}
|
|
]
|
|
}
|
|
```
|
|
|
|
This is the update CSV file with the compressed form update request JSON.
|
|
Each row specifies:
|
|
* `User` - The form owner
|
|
* `name` - The form file name
|
|
* `title` and `description` - The form title and description
|
|
* `update` - Can be used to update selected rows
|
|
* `JSON` - The compressed JSON requests
|
|
|
|
If you are using a local CSV file, surround the JSON data with single quotes `'`;
|
|
do not use the quotes if you are using a Google Sheet.
|
|
```
|
|
User,formId,name,title,update,JSON
|
|
attendance@domain.com,1xWfG_7sDCgrWDd-oqDCGE328-CozoAmqYMtP3WY2liw,MathClassAttendance,Math Class Attendance,,'{"requests": [{"updateItem": {"item": {"title": "Absent?", "description": "To report attendance adjustments for late arrivals, please email attendance@domain.com.", "questionItem": {"question": {"choiceQuestion": {"type": "CHECKBOX","options": [{"value": "All present."}, {"value": "Student Name1"}, {"value": "Student Name2"}, {"value": "Student Name3"}, {"value": "Student Name4"}, {"value": "Student Name5"}]}, "required": true}}}, "location": {"index": 0}, "updateMask": "title,description,questionItem"}}, {"updateItem": {"item": {"title": "Notes?", "questionItem": {"question": {"textQuestion": {"paragraph": true}}}}, "location": {"index": 1}, "updateMask": "title,questionItem"}}]} '
|
|
```
|
|
|
|
Update all of the forms.
|
|
|
|
If you are using a local CSV file, use the `quotechar "'"` option;
|
|
do not use the option if you are using a Google Sheet.
|
|
```
|
|
$ gam redirect stdout ./UpdateForms.txt multiprocess redirect stderr stdout csv UpdateForms.csv quotechar "'" gam user "~User" update form "~formId" json "~JSON"
|
|
2025-01-05T10:07:00.037-08:00,0/1,Using 1 process...
|
|
2025-01-05T10:07:00.037-08:00,0,Processing item 1/1
|
|
2025-01-05T10:07:03.110-08:00,0/1,Processing complete
|
|
```
|
|
|
|
Update selected forms; put an `x` in the `update` column of the rows to be updated.
|
|
```
|
|
$ gam config csv_input_row_filter "update:text=x' redirect stdout ./UpdateForms.txt multiprocess redirect stderr stdout csv UpdateForms.csv quotechar "'" gam user "~User" update form "~formId" json "~JSON"
|
|
2025-01-05T10:07:00.037-08:00,0/1,Using 1 process...
|
|
2025-01-05T10:07:00.037-08:00,0,Processing item 1/1
|
|
2025-01-05T10:07:03.110-08:00,0/1,Processing complete
|
|
```
|
|
|
|
This is the output.
|
|
```
|
|
$ more UpdateForms.txt
|
|
User: attendance@domain.com, Update 1 Form
|
|
User: attendance@domain.com, Form: 1xWfG_7sDCgrWDd-oqDCGE328-CozoAmqYMtP3WY2liw, Updated
|
|
```
|
|
|
|
## Display Forms
|
|
Select forms with `<DriveFileEntity>`:
|
|
* `<DriveFileID>` - Display responses for a specific form
|
|
* `my_forms` - Display responses for all forms owned by the user
|
|
```
|
|
gam <UserTypeEntity> show forms <DriveFileEntity>
|
|
[formatjson]
|
|
```
|
|
By default, Gam displays the information as an indented list of keys and values.
|
|
* `formatjson` - Display the form in JSON format
|
|
|
|
```
|
|
gam <UserTypeEntity> print forms <DriveFileEntity> [todrive <ToDriveAttribute>*]
|
|
(addcsvdata <FieldName> <String>)*
|
|
[formatjson [quotechar <Character>]]
|
|
```
|
|
* `addcsvdata <FieldName> <String>` - Add additional columns of data from the command line to the output
|
|
|
|
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.
|
|
|
|
## Display Form Responses
|
|
Select forms with `<DriveFileEntity>`:
|
|
* `<DriveFileID>` - Display responses for a specific form
|
|
* `my_forms` - Display responses for all forms owned by the user
|
|
```
|
|
gam <UserTypeEntity> show formresponses <DriveFileEntity>
|
|
[filtertime.* <Time>] [filter <String>]
|
|
[countsonly|formatjson]
|
|
```
|
|
By default, GAM displays form response details, use the `countsonly` option to get the number of responses but no response details.
|
|
|
|
By default, GAM displays all form responses, you can filter by response time:
|
|
* `timestamp > <Time>` - Display all form responses submitted after `<Time>`
|
|
* `timestamp >= <Time>` - Display all form responses submitted at or after `<Time>`
|
|
|
|
For example, to get the form responses submitted since the beginning of the year:
|
|
* `filter timestamp >= 2022-01-01T00:00:00Z`
|
|
|
|
Use the `filtertime.* <Time>` option to allow times, usually relative, to be substituted into the `filter <String>` option.
|
|
The characters following `filtertime` can be any combination of lowercase letters and numbers.
|
|
|
|
For example, to get the responses subnitted in the last four hours:
|
|
* `filtertime4h -4h filter "timestamp >= #filtertime4h#`
|
|
|
|
By default, Gam displays the information as an indented list of keys and values.
|
|
* `formatjson` - Display the form response in JSON format
|
|
|
|
```
|
|
gam <UserTypeEntity> print formresponses <DriveFileEntity> [todrive <ToDriveAttribute>*]
|
|
(addcsvdata <FieldName> <String>)*
|
|
[filtertime.* <Time>] [filter <String>]
|
|
[countsonly|(formatjson [quotechar <Character>])]
|
|
```
|
|
By default, GAM displays form response details, use the `countsonly` option to get the number of responses but no response details.
|
|
|
|
* `addcsvdata <FieldName> <String>` - Add additional columns of data from the command line to the output
|
|
|
|
By default, GAM displays all form responses, you can filter by response time:
|
|
* `timestamp > <Time>` - Display all form responses submitted after `<Time>`
|
|
* `timestamp >= <Time>` - Display all form responses submitted at or after `<Time>`
|
|
|
|
For example, to get the form responses submitted since the beginning of the year:
|
|
* `filter timestamp >= 2022-01-01T00:00:00Z`
|
|
|
|
Use the `filtertime.* <Time>` option to allow times, usually relative, to be substituted into the `filter <String>` option.
|
|
The characters following `filtertime` can be any combination of lowercase letters and numbers.
|
|
|
|
For example, to get the responses subnitted in the last four hours:
|
|
* `filtertime4h -4h filter "timestamp >= #filtertime4h#`
|
|
|
|
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.
|
|
|
|
## Combine Form Information
|
|
Combine form information from several GAM commands.
|
|
|
|
```
|
|
# Get form Id and createdTime
|
|
gam redirect csv ./forms.csv user user@domain.com print filelist showmimetype gform fields id,name,createdtime
|
|
# Get number of responses, add createdTime
|
|
gam redirect csv ./formsresponses.csv multiprocess csv forms.csv gam user "~Owner" print formresponses "~id" countsonly addcsvdata createdTime "~createdTime"
|
|
# Get full form info, add createdTime and responses (count)
|
|
gam redirect csv ./formsinfo.csv multiprocess csv formsresponses.csv gam user "~User" print forms "~formId" addcsvdata createdTime "~createdTime" addcsvdata responses "~responses"
|
|
```
|