Skip to content

Users Forms

Jump to bottom
Ross Scroggs edited this page Jan 5, 2025 · 17 revisions

Users - Forms

API documentation

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 [email protected] update serviceaccount

Definitions

<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.

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 [email protected] create form title "xyz" ... returnidonly)
Windows PowerShell
$fileId = & gam user [email protected] 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.

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 [email protected].",
              "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
User,name,title,description,JSON
[email protected],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 [email protected].", "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.

$ 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
[email protected],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 [email protected].",
              "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
User,formId,name,title,update,JSON
[email protected],1xWfG_7sDCgrWDd-oqDCGE328-CozoAmqYMtP3WY2liw,MathClassAttendance,Math Class Attendance,,'{"requests": [{"updateItem": {"item": {"title": "Absent?", "description": "To report attendance adjustments for late arrivals, please email [email protected].", "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.

$ 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: [email protected], Update 1 Form
  User: [email protected], 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 [email protected] 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"

Need more help? Ask on the GAM Discussion Group

Update History

Installation

Configuration

Notes and Information

Definitions

Command Processing

Collections

Client Access

Special Service Account Access

Service Account Access

Clone this wiki locally