Notes
Config
General
To change the settings of gam.cfg use the format below. Variable Names can be obtained here https://github.com/taers232c/GAMADV-XTD3/wiki/gam.cfg. Don't forget the save option. Run without the save option to check for errors.
gam config <VariableName> <NewSetting> save
View
gam config verify
todrive_upload_nodata
Set the todrive_upload_nodata options to false to prevent blank files being uploaded.
gam config todrive_upload_nodata false save
timezone
In Advanced GAM, run this command and GAM will translate GMT to your local time zone in both directions. But, I think, based on the server time.
gam config timezone local save
So if you are running GAM, online, such as in Cloud Shell or Compute Engine you need to change this, for example if you local time is GMT+8, then
gam config timezone +08:00 save
todrive_noemail
Enable/disable sending an email when todrive is specified. Default is true, so specify false to stop all emails.
todrive_timestamp
Turn on timestamps for Google Sheet files. Select as needed.
gam config todrive_timestamp [true or false] save
todrive_parent id
The folder to save all the report files in. This can be another users Drive.
gam config todrive_parent id:<Folder ID> save
todrive_user
The user that will receive the CSV files etc when the todrive option is used.
gam config todrive_user <Another User Email> save
show_gettings
Hide the messages/notifications while a command is running, such as "Getting Owners for ..."
gam config show_gettings false save
no_update_check
Change true or false as needed. If no_update_check = true then there will be no automatic check.
gam config no_update_check [true | false] save
CSV
ZSH Error
If you see an error message zsh: no such user or named directory: <ColumnName> you may need to surround the variables in single (') or double (") quotes.
Embed CSV Value
When you want to embed a CSV value in an argument use an extra "~", e.g. ~~ColumnName~~
gam csv email.csv gam user ~email sendemail subject "New email group" message "You have been added to the school email group ~~group~~"
Wrapping Lines
Some fields may have text fields that are translated incorrectly when converting the output to a TXT file. The option csv_output_convert_cr_nl [true|false] may be needed to correct this. For example, the description may containg formatting (cr and/ or nl) that will cause additional lines in the TXT file.
This command will output the fields in a fomat (where needed) so that if they contain line breaks etc the field is surrounded by ".
gam config csv_output_convert_cr_nl true csv_output_row_filter "OwnersCount:count=0" redirect csv ./owner_less_groups.csv print groups fields name,description ownerscount
Google Sheet
Commands can be run against Google Sheets, instead of CSV, for example;-
gam csv gsheet <User Email Address> <File ID> <Sheet Name> gam user ~user print delegates
Loop
The loop option will run through the CSV processing one row at a time. For example;-
gam loop gsheet <Owner Email address> <File ID> '<Sheet Name>' gam delete org ~orgUnitPath
gam loop email.csv gam user ~email sendemail subject "New email group" message "You have been added to the school email group ~~group~~"
Alternatively you can use config num_threads 1 to acheive the same effect.
gam config num_threads 1 csv gsheet <Owner Email address> <File ID> '<Sheet Name>' gam delete org ~orgUnitPath
Debug
Add config debug_level 1 after the first gam in a command to record the error info. For example
gam config debug_level 1 csv gsheet <Sheet Owner Email> <File ID> <Sheet ID> gam update group ~email whoCanViewGroup ALL_MEMBERS_CAN_VIEW
Output
stdout or stderr
Save output or errors of a command
gam redirect [stdout | stderr] ./<File Name (TXT or CSV)> <Rest of the GAM Command>
Example 1
Create CSV of the files and folders copied with this command. Using ./ before the file name will create the file in the current folder.
gam redirect stdout ./<File Name>.csv user <User Email Address> copy drivefile <Drive Folder ID> recursive mergewithparent depth -1 teamdriveparentid <Shared Drive Folder ID> copyfilepermissions false excludetrashed
Example 2
Using a CSV of file IDs (filelist.csv) set wll these files to Anyone With the link Can View.
gam redirect stdout SetAOWLV.log redirect stderr stdout user <Owner Email Address> add drivefileacl csvfile filelist.csv:id anyone role reader withlink nodetails
redirect stdout SetAOWLV.log redirect stderr stdout - log commands
user <Owner Email Address> - owner
add drivefileacl - what to do
csvfile filelist.csv:id - where's the data
anyone role reader withlink - access
nodetails - concise output
Query
Search query terms and operators
https://developers.google.com/drive/api/guides/ref-search-terms
Query
Assumes that the owner is me, the user the command is run against.
FullQuery
Need to specify who the owner is.
'<Email Address>' in owners
Redirect CSV
An example of this can be found in the Find User of Analytic Tracking ID section.
todrive
gam redirect csv - todrive tdfileid <File ID> tdretaintitle tdtimestamp false tdsheet id:<Accounts Tab ID> tdupdatesheet <Rest of GAM Command>
Multiprocess todrive
gam redirect csv - multiprocess todrive tdfileid <File ID> tdretaintitle tdtimestamp false tdsheet id:<Properties Tab ID> tdupdatesheet csv gsheet <File Owner Email> <File ID> id:<Accounts Tab ID> gam <Rest of GAM Command>
REGEX
From the Wiki https://github.com/taers232c/GAMADV-XTD3/wiki/Python-Regular-Expressions#match-function
When matching, Gam uses the match function which always looks for a match at the beginning of a string.
"^Foo Bar$" - match the entire string "Foo Bar"
"Foo Bar" - match a string that starts with "Foo Bar"
".*Foo Bar" - match a string that contains "Foo Bar"
".*Foo Bar$" - match a string that ends with "Foo Bar"
Test your regex expression.
Sendemail
To
This basic command will send a blank email to the user from the GAM user account.
gam sendemail to <User Email Address>
To, Subject
Include subject text.
gam sendemail to <User Email Address> subject "<Email Subject>"
To, Subject, Message
Send a message with a Subject and Message.
gam sendemail to <User Email Address> subject "<Email Subject>" message "<Message Text>"
To, Subject, Message, Attach
gam sendemail to <User Email Address> subject "<Email Subject>" message "<Message Text>" attach <File Name>
To, Subject, Message, From
Send a message with a Subject and Message.
gam sendemail to <User Email Address> subject "<Email Subject>" message "<Message Text>" from <Sender Email Address>
Add to GAM Command
The sendemail command can be combined with other GAM commands to notify when the GAM command has finished. If running in on Linux you can use the && option to join two GAM commands together. The sendemail command will only run after the first command has finished. For example;-
gam user <User Email Address> show contacts && gam sendemail to <To Email Address> from <From Email Address> subject "GAM Command Finished" message "View the Contacts now"
TODRIVE
The todrive option allows the output of the GAM command to be saved to Google Drive.
Some options are;-
tdclearfilter true - removes any filter on the Sheet before updating.
tdfileid - update a specific file already created
tdtitle - specify a file name.
tdsheet - specify a sheet name. If the Sheet already exists, then this name must be specified here.
tdtimestamp false - prevent the date showing in the File name
tdsheettimestamp false - prevent the date showing on the Tab name.
tdtimeformat <string> - For the File name. View the different string options here. Example %Y-%m-%d produces 2020-09-03
gam <Add your GAM command here> print todrive tdfileid <File ID> tdtitle "<File Name>" tdtimeformat %Y-%m-%d
tdnoemail [true or false]. This option can be configured in the Config file as well. So use this on an individual command to override the config file settings.
tdshare <Email Address> <role>. Share the file with a user and asign a role.
tdparent - Create the file in a specific Drive folder
tdcellnumberformat - options are text or number
tdfrom <Senders Email Address> - if tdnoemail true is configured then this will need to be over-ridden.
Printing Files
I use the todrive option to create Google Sheet of the CSV info, in the Google Drive of my account. You can replace this > file_name.csv if you are running GAM locally.
File Title - (tdtitle)
This will create a file with the name Your File Name - 2019-03-06T10:31:44+08:00.
gam print printers todrive tdtitle "<Your File Name>"
Remove the date & time - (tdtimestamp)
In the config.cfg file you can specifiy the timestamp globally. By default it will be added to the file name, so to remove for a file use this command.
gam print printers todrive tdtitle "<Your File Name>" tdtimestamp false
Update an Existing Google Sheet - (tdfileid)
gam print printers todrive tdfileid <file id>
Add Tab (Sheet)
tdaddsheet - creates a new sheet (tab) in an existing Google Sheet
tdsheet - gives the new sheet a title
tdsheettimeformat - specify a different timeformat for the tab/sheet, e.g. "%B %Y" will apend the tab/sheet name with (for example) November 2020.
Curently the timestamp on the new tab (sheet) will be the same as the Google Sheet.
gam crosqueries status:active print cros todrive tdfileid <File ID> tdtitle "<Google Sheet Title>" tdaddsheet tdsheet "<New Sheet/Tab Title>" tdsheettimeformat "%B %Y"
Another User
To output from todrive to another users Google Drive you need to use an existing <Folder ID> in the command or create a new folder. To create a new folder, use this command.
gam user <Another User Email> add drivefile drivefilename "<New Folder Name>" mimetype gfolder
If you then need access to this file you can get the <File ID> from the output of the above command and use this. Change the role (editor) as required.
gam user <Another User Email> add drivefileacl <File ID> user <Your Email Address> role editor
Add to Shared (Team) Drive
<Shared Drive User> must have at least writer permission of the Shared Drive folder
gam <Full GAM Comand> todrive tduser <Shared Drive User> tdparent id:<Shared Drive Folder ID>
tdshare
The <role> is either commenter|reader|writer
gam crosqueries "status:active" print cros todrive tdshare <User Email Address><role>
tdparent
Create the file in a specific folder. The option id:<Folder ID> can be replaced with the folder name.
tdparent id:<Folder ID>
tduser & tdparent
The tduser option requires the tdparent option to be stated at the same time.
gam crosqueries "status:active" print cros todrive tdtitle "<File Name>" tduser <Another User Email> tdparent id:<Folder ID>
Update Existing File
Add to the end of the GAM command.
... todrive tdfileid <Existing File ID> tdsheet id:<Existing Tab ID> tdupdatesheet tdtitle "<File Title>" tdtimeformat %Y-%m-%d tdclearfilter true