Updated `Meet API` scopes.
[*] 34) Meet API - Read Only
[*] 35) Meet API - Read Write
`Meet API - Read Only` - Allow apps to read metadata about any meeting space the user has access to.
`Meet API - Read Write` - Allow apps to create, modify, and read metadata about meeting spaces *created by your app*.
Updated `Meet API` scopes.
[*] 34) Meet API - Read Only
[*] 35) Meet API - Read Write
`Meet API - Read Only` - Allow apps to read metadata about any meeting space the user has access to.
`Meet API - Read Write` - Allow apps to create, modify, and read metadata about meeting spaces *created by your app*.
Updated `gam <UserTypeEntity> copy|move drivefile` to hanndle additional instances of
the `cannotModifyInheritedPermission` error.
Added license SKU `Google AI Ultra for Business`
Updated `gam report <ActivityApplicationName>` to display `id:<actor.profileId>` in the `emailAddress` column
when `actor.email` is empty. This typically occurs when the actor is not in your workspace.
Updated `gam <UserTypeEntity> copy drivefile` to ignore ACLs referencing deleted user/groups.
We currently only have 13 JID accounts available for testing but after Linux arm64 changes needed 14 runners.
I'm disabling Python 3.9 tests for now since it's the oldest and due for deprecation in October.
If there's any concerns we can re-enable and disable something else or else Jay can rebuild the auth files to add a 14th JID Google account and credentials (not hard but cumbersome and time consuming).
read -p "Please enter the email address of a regular Google Workspace user: " regularuser
fi
echo_yellow "Great! Checking service account scopes.This will fail the first time. Follow the steps to authorize and retry. It can take a few minutes for scopes to PASS after they've been authorized in the admin console."
# "$target_dir/$target_gam" $config_cmd user $regularuser check serviceaccount
"$target_dir/$target_gam" user $regularuser check serviceaccount
# "$target_gam" $config_cmd user $regularuser check serviceaccount
"$target_gam" user $regularuser check serviceaccount
# Issuer: CN=Entrust Root Certification Authority - EC1 O=Entrust, Inc. OU=See www.entrust.net/legal-terms/(c) 2012 Entrust, Inc. - for authorized use only
# Subject: CN=Entrust Root Certification Authority - EC1 O=Entrust, Inc. OU=See www.entrust.net/legal-terms/(c) 2012 Entrust, Inc. - for authorized use only
# Issuer: CN=Entrust Root Certification Authority - G2 O=Entrust, Inc. OU=See www.entrust.net/legal-terms/(c) 2009 Entrust, Inc. - for authorized use only
# Subject: CN=Entrust Root Certification Authority - G2 O=Entrust, Inc. OU=See www.entrust.net/legal-terms/(c) 2009 Entrust, Inc. - for authorized use only
1. Choose "Desktop App" or "Other" for "Application type".
2. Enter"GAM" or another desired value for "Name".
3. Click the blue "Create" button.
4. Copy your "Client ID" value that shows on the next page.
1. If "+ CREATE CLIENT" is on the screen, skip to step 14
2. Click"GET STARTED"
3. Under "App Information", enter {1} or another value in "App name *"
4. Under "App Information", enter {2} in "User support email *"
5. Click "NEXT"
6. Under "Audience", choose INTERNAL
7. Click "NEXT"
8. Under, "Contact Information", enter {2} or another value in "Email addresses *"
9. Click "NEXT"
10. Under "Finish", click "I agree to the Google API Services: User Data Policy."
11. Click "CONTINUE"
12. Click "CREATE"
13. Click "Clients" in the left-hand column
14. Click "+ CREATE CLIENT"
15. Choose "Desktop App" for "Application type"
16. Enter {1} or another value in "Name *"
17. Click "Create"
18. Under "Name", click your client name
19. Copy the "Client ID" value under "Additional information"
20. Paste it at the "Enter your Client ID: " prompt in your terminal
21. Press return/enter in your terminal
22. Switch back to the browser
23. Copy the "Client secret" value under "Client Secrets"
24. Paste it at the "Enter your Client Secret: " prompt in your terminal
25. Press return/enter in your terminal
26. Switch back to the browser
27. Click "OK"
28. These steps are complete
'''
ENTER_YOUR_CLIENT_ID='\nEnter your Client ID: '
GO_BACK_TO_YOUR_BROWSER_AND_COPY_YOUR_CLIENT_SECRET_VALUE='\n5. Go back to your browser and copy your "Client Secret" value.\n'
ENTER_YOUR_CLIENT_SECRET='\nEnter your Client Secret: '
GO_BACK_TO_YOUR_BROWSER_AND_CLICK_OK_TO_CLOSE_THE_OAUTH_CLIENT_POPUP='\n6. Go back to your browser and click OK to close the "OAuth client" popup if it\'s still open.\n'
ALREADY_EXISTS_USE_MERGE_ARGUMENT='Already exists; use the "merge" argument to merge the labels'
API_ACCESS_DENIED='API access Denied'
API_CALLS_RETRY_DATA='API calls retry data\n'
API_CHECK_CLIENT_AUTHORIZATION='Please make sure the Client ID: {0} is authorized for the appropriate API or scopes:\n{1}\n\nRun: gam oauth create\n'
API_CHECK_SVCACCT_AUTHORIZATION='Please make sure the Service Account Client ID: {0} is authorized for the appropriate API or scopes:\n{1}\n\nRun: gam user {2} update serviceaccount\n'
API_CHECK_CLIENT_AUTHORIZATION='Please make sure the Client ID: {0} is authorized for the appropriate API or scopes:{1}\n\nRun: gam oauth create\n'
API_CHECK_SVCACCT_AUTHORIZATION='Please make sure the Service Account Client ID: {0} is authorized for the appropriate API or scopes:{1}\n\nRun: gam user {2} update serviceaccount\n'
API_ERROR_SETTINGS='API error, some settings not set'
ARE_BOTH_REQUIRED='Arguments {0} and {1} are both required'
ARE_MUTUALLY_EXCLUSIVE='Arguments {0} and {1} are mutually exclusive'
@@ -265,6 +288,7 @@ GAM_OUT_OF_MEMORY = 'GAM has run out of memory. If this is a large Google Worksp
GENERATING_NEW_PRIVATE_KEY='Generating new private key'
GETTING='Getting'
GETTING_ALL='Getting all'
GRANTING_RIGHTS_TO_ROTATE_ITS_OWN_PRIVATE_KEY='{0} rights to rotate its own private key'
GOOGLE_DELEGATION_ERROR='Google delegation error, delegator and delegate both exist and are valid for delegation'
GUARDIAN_INVITATION_STATUS_NOT_PENDING='Guardian invitation status is not PENDING'
HAS_CHILD_ORGS='Has child {0}'
HAS_INVALID_FORMAT='{0}: {1}, Has invalid format'
HAS_RIGHTS_TO_ROTATE_OWN_PRIVATE_KEY='Giving account {0} rights to rotate {1} private key'
HEADER_NOT_FOUND_IN_CSV_HEADERS='Header "{0}" not found in CSV headers of "{1}".'
HELP_SYNTAX='Help: Syntax in file {0}\n'
HELP_WIKI='Help: Documentation is at {0}\n'
IGNORED='Ignored'
INSTRUCTIONS_CLIENT_SECRETS_JSON='Please run\n\ngam create|use project\ngam oauth create\n\nto create and authorize a Client account.\n'
INSTRUCTIONS_OAUTH2SERVICE_JSON='Please run\n\ngam create|use project\ngam user <user> check serviceaccount\n\nto create and authorize a Service account.\n'
INSTRUCTIONS_OAUTH2SERVICE_JSON='Please run\n\ngam create|use project\ngam user <user> update serviceaccount\n\nto create and authorize a Service account.\n'
INSUFFICIENT_PERMISSIONS_TO_PERFORM_TASK='Insufficient permissions to perform this task'
INTER_BATCH_WAIT_INCREASED='inter_batch_wait increased to {0:.2f}'
NO_TRANSFER_LACK_OF_DISK_SPACE='Transfer not performed due to lack of target drive space.'
NO_USAGE_PARAMETERS_DATA_AVAILABLE='No usage parameters data available.'
NO_USER_COUNTS_DATA_AVAILABLE='No User counts data available.'
NUM_SELECTED_CLIENT_SCOPES='\n{0} scopes are selected, if more than {1} scopes are selected, Google will probably generate a "Something went wrong" error\n'
OAUTH2_GO_TO_LINK_MESSAGE="""
Go to the following link in a browser on this computer or on another computer:
'product':'101034','aliases':['gseau','enterprisearchived','gsuiteenterprisearchived'],'displayName':'Google Workspace Enterprise Plus - Archived User'},
'1010340002':{
@@ -148,14 +160,16 @@ _SKUS = {
'product':'101034','aliases':['wsbizstarterarchived','workspacebusinessstarterarchived'],'displayName':'Google Workspace Business Starter - Archived User'},
'1010340006':{
'product':'101034','aliases':['wsbizstanarchived','workspacebusinessstanarchived'],'displayName':'Google Workspace Business Standard - Archived User'},
'1010340007':{
'product':'101034','aliases':['gwefau','gwefarchived','workspaceeducationfundamentalsarchived'],'displayName':'Google Workspace for Education Fundamentals - Archived User'},
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.
### Eliminate unwanted fields
You can use [CSV Print Filtering](CSV-Print-Filtering) to reduce the amount of output.
This command will drop all of the data.messages columns.
*`alert <AlertID>` - Display feedback for the selected alert
*`filter <QueryAlert>` - Display feebback for the filtered alerts
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.
## Configuring settings
Alert Center can be configured to send notifications to a Google Cloud Pub/Sub topic, but it first requires configuration.
* See https://developers.google.com/workspace/admin/alertcenter/guides/notifications for information.
Gam can be used to display or modify the settings:
There are two types of batch processing, one that uses processes and one that uses threads. Using processes is higher performance but `gam csv` commands are not supported.
*`gam batch` - gam commands are run as processes, gam csv commands are not allowed in the batch file
*`gam tbatch` - gam commands are run as threads, gam csv commands are allowed in the batch file
*`<FileName>` - A flat file containing Gam commands
*`-` - Gam commands coming from stdin
*`gdoc <UserGoogleDoc>` - A Google Doc containing Gam commands
*`showcmds` - Write `timestamp,command number/number of commands,command` to stderr when each command starts; write `timestamp, command number/numberof commands,complete` to stderr when command completes
Batch files can contain the following types of lines:
* Blank lines - Ignored
* \# Comment line - Ignored
* gam \<GAMArgumentList\> - Execute a GAM command
* commit-batch
* GAM waits for all running GAM commands to complete
* GAM continues
* commit-batch \<String\>
* GAM waits for all running GAM commands to complete
* GAM prints \<String\> and waits for the user to press any key
* GAM continues
* sleep \<Integer\> - Batch processing will suspend for \<Integer\> seconds before the next command line is processed
* To be effective, this should immediately follow commit-batch
* print \<String\> - Print \<String\> on stderr
* datetime \<DateTimeFormat\>
* The current time is formatted with \<DateTimeFormat\> and subsequent lines will have `%datetime%` replaced with the formatted time value.
*`<FileName>` - A CSV file and the one or more columns that contain data
*`-` - The one or more columns that contain data from stdin
*`gsheet <UserGoogleSheet>` - A Google Sheet and the one or more columns that contain data
*`gdoc <UserGoogleDoc>` - A Google Doc and the one or more columns that contain data
*`columndelimiter <Character>` - Columns are separated by `<Character>`; if not specified, the value of `csv_input_column_delimiter` from `gam.cfg` will be used
*`noescapechar <Boolean>` - Should `\` be ignored as an escape character; if not specified, the value of `csv_input_no_escape_char` from `gam.cfg` will be used
*`quotechar <Character>` - The column quote characer is `<Character>`; if not specified, the value of `csv_input_quote_char` from `gam.cfg` will be used
*`fields <FieldNameList>` - The column headings of a CSV file that does not contain column headings.
*`(matchfield|skipfield <FieldName> <RESearchPattern>)*` - The criteria to select rows from the CSV file; can be used multiple times; if not specified, all rows are selected
*`showcmds` - Write `timestamp,command number/number of commands,command` to stderr when each command starts; write `timestamp, command number/numberof commands,complete` to stderr when command completes
*`skiprows <Integer>` - Skip filtered rows from the CSV file/Google Sheet.
*`skiprows 0` - All rows are processed, this is the default
*`skiprows N` - The first N filtered rows are skipped
*`maxrows <Integer>` - Limit the number of filtered rows processed from the CSV file/Google Sheet after any skipped rows.
*`maxrows 0` - All rows are processed, this is the default
*`maxrows N` - N filtered rows are processed
### Use CSV file values in command line
You can make substitutions in `<GAMArgumentList>` with values from the CSV file.
- Reference the field xxx with `~xxx` if the argument contains no other text
- Reference the field xxx with `~~xxx~~` if the argument contains other text
- An argument containing exactly `~xxx` is replaced by the value of field xxx
- An argument containing instances of `~~xxx~~` has `~~xxx~~` replaced by the value of field xxx
- An argument containing instances of `~~xxx~!~pattern~!~replacement~~` has `~~xxx~!~pattern~!~replacement~~` replaced by re.sub(pattern, replacement, value of field xxx) See: https://docs.python.org/3/library/re.html
If an argument is specifying a file path and it starts with a `~`, e.g., `targetfolder "~/Documents/GamWork"`, GAM will flag it as an error:
```
ERROR: Header "/Documents/GamWork/" not found in CSV headers of "Owner,id,title".
```
Put a space in front of the `~`: `targetfolder " ~/Documents/GamWork"` to avoid the error.
### Example
* You need to update the work addresses of a set of users
* You want a note field that shows their email address as name AT domain.com
* You have a CSV file Users.csv with columns: primaryEmail,Street,City,State,ZIP
```
gam csv Users.csv gam update user "~primaryEmail" address type work unstructured "~~Street~~, ~~City~~, ~~State~~ ~~ZIP~~" primary note text_plain "~~primaryEmail~!~^(.+)@(.+)$~!~\1 AT \2~~"
```
* You want to do the above using a Google Sheet
```
gam csv gsheet <user> <fileID> "<sheetName>" gam update user "~primaryEmail" address type work unstructured "~~Street~~, ~~City~~, ~~State~~ ~~ZIP~~" primary note text_plain "~~primaryEmail~!~^(.+)@(.+)$~!~\1 AT \2~~"
```
## CSV files with redirection and select
You should use the `multiprocess` option on any redirected files: `csv`, `stdout`, `stderr`.
You want to process users with phone numbers in the area code 510; the number can be in the format `(510) ddd-dddd` or `510-ddd-dddd` or `510 ddd-dddd`.
- [Saving filters in gam.cfg](#saving-filters-in-gamcfg)
There are seven values in `gam.cfg` that can be used to filter the output from `gam print` commands.
*`csv_output_header_filter` - A list of `<RegularExpressions>` used to select specific column headers to include
*`csv_output_header_drop_filter` - A list of `<RegularExpressions>` used to select specific column headers to exclude
*`csv_output_header_force` - A list of <Strings> used to specify the exact column headers to include
*`csv_output_header_order` - A list of <Strings> used to specify the column header order; any headers in the file but not in the list will appear after the headers in the list.
*`csv_output_row_filter` - A list or JSON dictionary used to include specific rows based on column values
*`csv_output_row_drop_filter` - A list or JSON dictionary used to exclude specific rows based on column values
*`csv_output_row_limit` - A limit on the number of rows written
The original implementation required that row filters be expressed in JSON notation; these are almost
impossible to enter correctly in Windows; on Mac OS or Linux, it's easy. You can now enter the row filters as lists
You want a list of groups not created by an administrator.
```
gam config csv_output_row_filter "'adminCreated:boolean:false'" print groups fields admincreated
```
You want a list of users with phone numbers in the area code 510; the number can be in the format `(510) ddd-dddd` or `510-ddd-dddd` or `510 ddd-dddd`.
If you define a value for `csv_output_header_filter`, `csv_output_header_drop_filter`, `csv_output_header_force`, `csv_output_header_order`, `csv_output_row_filter`, `csv_output_row_drop_filter` or `csv_output_row_limit` in the `[DEFAULT]` section of `gam.cfg`,
it will apply to every `gam print` command which is probably not desirable. You can store them in `gam.cfg` in named sections.
## Python variables that control CSV file reading/writing:
```
Dialect.delimiter
A one-character string used to separate fields.
It defaults to ','.
Dialect.doublequote
Controls how instances of quotechar appearing inside a field should themselves be quoted.
When True, the character is doubled. When False, the escapechar is used as a prefix to the quotechar.
It defaults to True.
Dialect.escapechar
A one-character string used by the writer to escape the delimiter if quoting is set to QUOTE_NONE and the quotechar if doublequote is False.
On reading, the escapechar removes any special meaning from the following character.
It defaults to None, which disables escaping.
Dialect.lineterminator
The string used to terminate lines produced by the writer.
It defaults to '\r\n'.
The reader is hard-coded to recognise either '\r' or '\n' as end-of-line, and ignores lineterminator.
Dialect.quotechar
A one-character string used to quote fields containing special characters, such as the delimiter or quotechar, or which contain new-line characters.
It defaults to '"'.
Dialect.quoting
Controls when quotes should be generated by the writer and recognised by the reader. It can take on any of the QUOTE_* constants (see section Module Contents).
It defaults to QUOTE_MINIMAL.
```
## GAM variables that control CSV file reading/writing:
Option `noselfowner` suppresses the display of ACLs that reference the calendar itself as its owner.
Add additional columns of data from the command line to the output
*`addcsvdata <FieldName> <String>`
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.
### Old format commands
These commands are backwards compatible with Legacy GAM.
This is dense reading; a simpler approach is to define a test event in Google Calendar with
the recurrence rule that you want, then use `gam info event` to get the recurrence rule and use it in subsequent commands.
```
RRULE:FREQ=DAILY - Daily
RRULE:FREQ=DAILY;COUNT=30 - Daily for 30 days
RRULE:FREQ=WEEKLY - Weekly on the same day of the week as the starting day; e.g., every Wednesday
RRULE:FREQ=WEEKLY;COUNT=13 - Weekly on the same day of the week as the starting day; e.g., every Wednesday, for 13 weeks
RRULE:FREQ=MONTHLY - Monthly on the same day of the month as the starting day; e.g., every 15th of the month
RRULE:FREQ=MONTHLY;BYDAY=4TH - Monthly on the fourth instance of the starting day; e.g., every 4th Thursday
```
## Event colors
The event color grid presented in calendar.google.com and `<EventColorIndex>` are related like this:
```
11:tomato 4:flamingo
6:tangerine 5:banana
2:sage 10:basil
7:peacock 9:blueberry
1:lavender 3:grape
8:graphite
```
## Event selection
These are the possible values for `<EventEntity>`; you either specify event IDs or properties used to select events.
If none of the following options are selected, all events are selected.
*`id|eventid <EventId>` - A single event ID
*`event|events <EventIdList> | <FileSelector> | <CSVFileSelector> | <CSVkmdSelector> | <CSVSubkeySelector> | <CSVDataSelector>)` - A collection of event IDs: [Collections of Items](Collections-of-Items)
*`<EventSelectProperty>* <EventMatchProperty>*` - Properties used to select events
The Google Calendar API processes `<EventSelectProperty>*`; you may specify none or multiple properties.
*`after|starttime|timemin <Time>` - Lower bound (exclusive) for an event's end time to filter by. If timeMax is set, timeMin must be smaller than timeMax.
*`before|endtime|timemax <Time>` - Upper bound (exclusive) for an event's start time to filter by. If timeMin is set, timeMax must be greater than timeMin.
*`eventtypes <EventTypeList>` - Select events based on their type.
*`query <QueryCalendar>` - Free text search terms to find events that match these terms in any field, except for extended properties
*`privateextendedproperty <String>` - A required private property; `<String>` must be of the form `propertyName=value`
*`sharedextendedproperty <String>` - A required shared property; `<String>` must be of the form `propertyName=value`
*`showdeletedevents` - Whether to include deleted events (with status equals "cancelled") in the result
*`showhiddeninvitations` - Whether to include hidden invitations in the result
*`singleevents` - Whether to expand recurring events into instances and only return single one-off events and instances of recurring events, but not the underlying recurring events themselves
*`updatedmin <Time>` - Lower bound for an event's last modification time (as a RFC3339 timestamp) to filter by. When specified, entries deleted since this time will always be included regardless of showdeletedevents
GAM processes `<EventMatchProperty>*`; you may specify none or multiple properties.
*`matchfield attendees <EmailAddressEntity>` - All of the attendees in `<EmailAddressEntity>` must be present
*`matchfield attendeesonlydomainlist <DomainNameList>` - All attendee's email addresses must be in a domain in `<DomainNameList>`
* For example, this lets you look for events with all attendees in your internal domains. You should include `resource.calendar.google.com`
in `<DomainNameList>` if the events use resources.
*`matchfield attendeesdomainlist <DomainNameList>` - Some attendee's email address must be in a domain in `<DomainNameList>`
* For example, this lets you look for events with attendees in specific external domains
*`matchfield attendeesnotdomainlist <DomainNameList>` - Some attendee's email address must be in a domain not in `<DomainNameList>`
* For example, this lets you look for events with attendees not in your internal domains. You should include `resource.calendar.google.com`
in `<DomainNameList>` if the events use resources.
*`matchfield attendeespattern <RESearchPattern>` - Some attendee's email address must match `<RESearchPattern>`
*`matchfield attendeesstatus [<AttendeeAttendance>] [<AttendeeStatus>] <EmailAddressEntity>` - All of the attendees in `<EmailAddressEntity>` must be present
and must have the specified values.
*`<AttendeeAttendance>` - Default is `required`
*`<AttendanceStatus>` - Default is`needsaction`
*`matchfield creatoremail <RESearchPattern>` - The creator email address must match `<RESearchPattern>`
*`matchfield creatorname <RESearchPattern>` - The creator name must match `<RESearchPattern>`
*`matchfield description <RESearchPattern>` - The description (summary) must match `<RESearchPattern>`
*`matchfield location <RESearchPattern>` - The location must match `<RESearchPattern>`
*`matchfield organizeremail <RESearchPattern>` - The organizer email address must match `<RESearchPattern>`
*`matchfield organizername <RESearchPattern>` - The orgainzer name must match `<RESearchPattern>`
*`matchfield status <RESearchPattern>` - The summary must match `<RESearchPattern>`. The API documented values are:
*`confirmed`
*`tentative`
*`cancelled`
*`matchfield summary <RESearchPattern>` - The summary must match `<RESearchPattern>`
*`matchfield transparency <RESearchPattern>` - The summary must match `<RESearchPattern>`. The API documented values are:
*`opaque` - Busy. The API does not seem to return this value; use `"(^$)|opaque"` to match no value or `opaque`.
*`transparent` - Free/Available
*`matchfield visibility <RESearchPattern>` - The summary must match `<RESearchPattern>`. The API documented values are:
*`default` - The API does not seem to return this value; use `"(^$)|default"` to match no value or `default`.
*`public` - The API does not seem to return this value if it is the default; use `"(^$)|public"` to match no value or `public`.
*`private` - The API does not seem to return this value if it is the default; use `"(^$)|private"` to match no value or `private`.
If `<EventEntity>` is not specified, all events in `<CalendarEntity>` are selected. This is not typically used.
No events are deleted unless you specify the `doit` option; omit `doit` to verify that you properly selected the events to delete.
When events are deleted from a calendar, they are moved to the calendar's trash and are only permanently deleted (purged) after 30 days.
Following a suggestion here (https://stackoverflow.com/questions/41043053/how-to-empty-calendar-trash-via-google-services) you can permanently delete
calendar events with `purge events`. This is achieved by creating a temporary calendar, deleting the events, moving the deleted events to the temporary calendar
A user signed in to Google Calendar can empty the calendar trash but there is no direct API support for this operation.
To empty the calendar trash a temporary calendar is created, the deleted events are moved to the temporary calendar and then the temporary calendar is deleted.
In `<EventEntity>`, any `<EventSelectProperty>` options must precede all other options.
By default, only the base event of a recurring event is displayed. Use the `<EventSelectProperty>`
option `singleevents` to display all instances of a recurring event.
`<EventDisplayProperty> orderby starttime` is only valid with `<EventSelectProperty> singleevents`.
`showdayofweek` displays columns `start.dayOfWeek` and `end.dayOfWeek` when event start and end times are displayed.
Add additional columns of data from the command line to the output after the calendarId.
*`addcsvdata <FieldName> <String>`
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, Gam displays event details, use `countsonly` to display only the number of events. `formatjson` does not apply in this case.
When `countsonly` is specified, the `eventrowfilter` option causes
GAM to apply `config csv_output_row_filter` to the event details rather than the event counts.
This will be useful when `<EventSelectProperty>` and `<EventMatchProperty>` do not have the
capabilty to select the events of interest; e.g., you want to filter based on the event `created` property.
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.
### Special character processing
When outputting events with `formatjson` with the goal of adding the events to another calendar,
use these options at the beginning of the command:
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 Rooms and Chats to which your Bot belongs](#display-rooms-and-chats-to-which-your-bot-belongs)
- [Display Members of a Room or Chat](#display-members-of-a-room-or-chat)
- [Create a Chat Message](#create-a-chat-message)
- [Update a Chat Message](#update-a-chat-message)
- [Delete a Chat Message](#delete-a-chat-message)
- [Display a Chat Message](#display-a-chat-message)
## Introduction
To use these commands you must update your service account authorization.
```
gam user user@domain.com update serviceaccount
[*] 4) Chat API - Memberships (supports readonly)
[*] 5) Chat API - Memberships Admin (supports readonly)
[*] 6) Chat API - Messages (supports readonly)
[*] 7) Chat API - Spaces (supports readonly)
[*] 8) Chat API - Spaces Admin (supports readonly)
[*] 9) Chat API - Spaces Delete
[*] 10) Chat API - Spaces Delete Admin
```
Added `use_chat_admin_access` Boolean variable to `gam.cfg`.
```
* When False, GAM uses user access when making all Chat API calls. For calls that support admin access,
this can be overridden with the asadmin command line option.
* When True, GAM uses admin access for Chat API calls that support admin access; other calls will use user access.
* Default: False
```
Google requires that you have a Chat Bot configured in order to use the Chat API; set up a Chat Bot as described in the next section.
## Set up a Chat Bot
GAM is capable of acting as a Chat Bot and sending messages to Chat Rooms or direct messages to users.
Even if you're not going to use GAM as a Chat Bot, you have to configure a Chat Bot as it is required by the Chat API in [Users - Chat](Users-Chat).
* Run the command `gam setup chat`; it will point you to a URL to configure your Chat Bot.
* Uncheck "Build this Chat app as a Workspace add-on."
* Enter an App name and Description of your choosing.
* For the Avatar URL you can use `https://dummyimage.com/384x256/4d4d4d/0011ff.png&text=+GAM` or a public URL to an image of your own choosing.
* In Functionality, uncheck both "Receive 1:1 messages" and "Join spaces and group conversations"
* In Connection settings, choose "Cloud Pub/Sub" and enter `projects/<ProjectID>/topics/no-topic` for the Topic Name. Replace `<ProjectID>` with your GAM project ID. GAM doesn't yet listen to pub/sub so this option is not used.
* In Visibility, uncheck "Make this Chat app available to specific people and groups in Domain Workspace".
## Display Rooms and Chats to which your Bot belongs
Display the spaces to which your Chat Bot can send messages.
A space can be a direct message to a user, a chat group or a chat room.
At first you'll have no spaces listed. Try [finding your bot and chatting it](https://support.google.com/chat/answer/7655820) and then your space will be listed.
### Display information about a specific chat space
```
gam info chatspace space <ChatSpace>
[fields <ChatSpaceFieldNameList>]
[formatjson]
```
By default, Gam displays the information as an indented list of keys and values.
*`formatjson` - Display the fields in JSON format.
### Display information about all chat spaces
```
gam show chatspaces
[fields <ChatSpaceFieldNameList>]
[formatjson]
```
By default, Gam displays the information as an indented list of keys and values.
*`formatjson` - Display the fields in JSON format.
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.
----
## Display Members of a Room or Chat
### Display information about a specific chat member
```
gam info chatmember member <ChatMember>
[fields <ChatMemberFieldNameList>]
[formatjson]
```
By default, Gam displays the information as an indented list of keys and values.
* `formatjson` - Display the fields in JSON format.
### Display information about all chat members in a chat space
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.
By default, only `JOINED` members are displayed; use `showinvited` to also display `INVITED` members.
Use `filter <String>` to filter memberships by a member's role and membertype.
* To filter by role, set role to ROLE_MEMBER or ROLE_MANAGER.
* To filter by type, set member.type to HUMAN or BOT.
* To filter by both role and type, use the AND operator.
* To filter by either role or type, use the OR operator.
For example, the following queries are valid:
```
role = "ROLE_MANAGER" OR role = "ROLE_MEMBER"
member.type = "HUMAN" AND role = "ROLE_MANAGER"
```
The following queries are invalid:
```
member.type = "HUMAN" AND member.type = "BOT"
role = "ROLE_MANAGER" AND role = "ROLE_MEMBER"
```
## Create a Chat Message
Create a chat message in a space. Messages are limited to 4,096 characters and will be trimmed to that length.
Chat supports [simple formatting](https://developers.google.com/chat/reference/message-formats/basic#using_formatted_text_in_messages) allowing you to bold, underline, italics and strikethrough your text.
Use these options to select Chrome devices; if none are chosen, all Chrome devices in the account are selected.
-`ou <OrgUnitItem>` - Select devices directly in the OU `<OrgUnitItem>`
-`ou_and_children <OrgUnitItem>` - Select devices in the OU `<OrgUnitItem>` and its sub OUs
-`ous <OrgUnitList>` - Select devices directly in the OUs `<OrgUnitList>`
-`ous_and_children <OrgUnitList>` - Select devices in the OUs `<OrgUnitList>` and their sub OUs
-`minauedate <Date>` - Devices that have already expired and devices with auto expiration date equal to or later than the minimum date
-`maxauedate <Date>` - Devices that have already expired and devices with auto expiration date equal to or earlier than the maximum date
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.
Batches of devices are processed to minimize the number of API calls; `batch_size` controls the number of deviceIds handled in each batch
`batch_size` defaults to the value from `gam.cfg`, its maximum value is 600.
Google performs error checking of the browser deviceIDs, if any deviceID in a batch is invalid, none of the browsers in the batch are moved.
### Example: Move Chrome browsers from one OU to another
```
gam move browsers ou /Students/2021 browserou /Students/2020
```
## Delete Chrome browsers
Deletes a browser; the browser will be removed from Google's admin console and no longer sync policy or reporting. However, existing policies will still be applied until the device registration and dm tokens are removed.
Use these options to select Chrome browsers; if none are chosen, all Chrome browsers in the account are selected:
*`ou|org|orgunit|browserou <OrgUnitPath>` - Limit browsers to those in the specified OU; this option can be used in conjunction with query
*`(query <QueryBrowser>)|(queries <QueryBrowserList>)` - Limit browsers to those that match a query
*`select <BrowserEntity>` - Select a specific set of browsers to display
Select the fields to be displayed:
*`annotated` - Display these fields: deviceId,annotatedAssetId,annotatedLocation,annotatedNotes,annotatedUser
*`basic` - Display all fields except: browsers, lastDeviceUsers, lastStatusReportTime, machinePloicies; this is the default
*`allfields/full` - Display all fields
*`<BrowserFieldName>* [fields <BrowserFieldNameList>]` - Display a selected list of fields
* Note that `ou, org and orgunit` are both command line options and field names; use `fields` to include them in the selected list of fields
*`rawfields "<BrowserFieldNameList>"` - Display a selected list of fields
By default, Gam displays the information as an indented list of keys and values:
-`formatjson` - Display the fields in JSON format.
Use the `querytime<String> <Time>` option to allow times, usually relative, to be substituted into the `query <QueryBrowser>` and `queries <QueryBrowserList>` options.
The `querytime<String> <Time>` value replaces the string `#querytime<String>#` in any queries.
The characters following `querytime` can be any combination of lowercase letters and numbers.
Use these options to select Chrome browsers; if none are chosen, all Chrome browsers in the account are selected:
*`ou|org|orgunit|browserou <OrgUnitPath>` - Limit browsers to those in the specified OU; this option can be used in conjunction with query
*`(query <QueryBrowser>)|(queries <QueryBrowserList>)` - Limit browsers to those that match a query
*`select <BrowserEntity>` - Select a specific set of browsers to display
Use the `querytime<String> <Time>` option to allow times, usually relative, to be substituted into the `query <QueryBrowser>` and `queries <QueryBrowserList>` options.
The `querytime<String> <Time>` value replaces the string `#querytime<String>#` in any queries.
The characters following `querytime` can be any combination of lowercase letters and numbers.
For example, query for Chrome browsers last synced more than a year ago:
The first column will always be deviceId; the remaining field names will be sorted if `allfields`, `basic`, `full` or `sortheders` is specified;
otherwise, the remaining field names will appear in the order specified.
Select the fields to be displayed:
*`annotated` - Display these fields: deviceId,annotatedAssetId,annotatedLocation,annotatedNotes,annotatedUser
*`basic` - Display all fields except: browsers, lastDeviceUsers, lastStatusReportTime, machinePloicies; this is the default
*`allfields/full` - Display all fields
*`<BrowserFieldName>* [fields <BrowserFieldNameList>]` - Display a selected list of fields
* Note that `ou, org and orgunit` are both command line options and field names; use `fields` to include them in the selected list of fields
*`rawfields "<BrowserFieldNameList>"` - Display a selected list of fields
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.
### Examples
Print information about Chrome browsers synced more than 30 days ago:
arch The CPU architecture for the Chrome browser device. (e.g. x86_64)
asset_id The annotated asset ID for the Chrome browser device.
browser_version A reported Chrome browser installed on the Chrome browser device (e.g. 73)
enrollment_token The enrollment token used to register the Chrome browser device.
last_activity The last time the Chrome browser device has shown activity (policy fetch or reporting).
location The annotated location for the Chrome browser device.
machine_name The machine name for the Chrome browser device.
machine_user The last reported user of the Chrome browser device.
note The annotated note for the Chrome browser device.
num_extensions The number of extensions reported by the Chrome browser device.
num_policies The number of policies reported by the Chrome browser device.
os The combine OS platform and major OS version for the Chrome browser device (e.g. "Windows 10")
os_platform The OS platform for the Chrome browser device. (e.g. Windows)
os_version The OS version for the chrome browser device. (e.g. 10.0.16299.904)
register The registration time for the Chrome browser device.
report The last report time for the Chrome browser device
sync The last policy sync time for the Chrome browser device.
user The annotated user for the Chrome browser device.
```
For fields that accept time (register, report, sync, last_activity) the time format is YYYY-MM-DDThh:mm:ss (e.g. 2020-01-01T12:00:00). You may also specify open or closed ranges for the time:
```
datetime exactly on the given date or time, e.g., 2011-03-23 2011-04-26T14:23:05
datetime..datetime within (inclusive) the given interval of date or time, e.g., 2011-03-23..2011-04-26
datetime.. on or after the given date or time; e.g., 2011-04-26T14:23:05..
..datetime on or before the given date or time; e.g., ..2011-04-26T14:23:05
```
To search within a specific field only (for example, to search for a specific user), you can enter an operator followed by an argument -- for example, `user:jsmith`. You can use single words or quoted lists of words as an argument when running an operator query.
To run an operator query, follow these guidelines for each field:
### User
Enter user: as the operator. For example, to match the name Joe, but not Joey, enter the following:
`gam print browsers query "user:joe"`
To match the name Tom Sawyer or A. Tom Sawyer, but not Tom A. Sawyer, enter with quotation marks:
`gam print browsers query "user:'tom sawyer'"`
### Location
Enter location: as the operator. For example, to match Seattle, enter the following:
`gam print browsers query "location:seattle"`
Notes
Enter note: as the operator. For example, to match loaned from John, enter the following with quotation marks:
`gam print browsers query "note:'loaned from john'"`
### Register
This field is not displayed on the Chrome OS settings page. However, you can search for devices that were registered on a given date, or within a given time range.
Enter register: as the operator, and enter a date and time (or time range) as the argument. For example, to search for all devices registered on April 15, 2020, enter the following:
`gam print browsers query "register:2020-04-15"`
For additional examples using dates, times, and ranges, see "Format for date searches" below.
### Last Sync
Enter sync: as the operator and a date or time range as the argument. For example, to search for all devices that were last synced with policy settings on April 15, 2020, enter the following:
`gam print browsers query "sync:2020-04-15"`
For additional examples using dates, times, and ranges, see "Format for date searches" below.
### Format for date searches
*`YYYY-MM-DD` - A single date
*`YYYY-MM-DD..YYYY-MM-DD` - A date range
*`..YYYY-MM-DD` - All dates on or before a date
*`YYYY-MM-DD..` - All dates on or after a date
### Asset ID
Enter asset_id: as the operator. For example, to match the partial Asset ID 1234, enter the following:
`gam print browsers query "asset_id:1234"`
## Manage Chrome browser enrollment tokens
Create a browser enrollment token. The Google API that supports this call always returns an error.
Use these options to select Chrome browsers; if none are chosen, all Chrome browsers in the account are selected:
*`ou|org|orgunit|browserou <OrgUnitPath>` - Limit browsers to those in the specified OU; this option can be used in conjunction with query
*`(query <QueryBrowserToken>)|(queries <QueryBrowserTokenList>)` - Limit browsers to those that match a query
Use the `querytime<String> <Time>` option to allow times, usually relative, to be substituted into the `query <QueryBrowserToken>` and `queries <QueryBrowserTokenList>` options.
The `querytime<String> <Time>` value replaces the string `#querytime<String>#` in any queries.
The characters following `querytime` can be any combination of lowercase letters and numbers.
Select the fields to be displayed:
*`allfields` - Display all fields; this is the default
*`<BrowserTokenFieldName>* [fields <BrowserTokenFieldNameList>]` - Displaya selected list of fields
By default, Gam displays the information as an indented list of keys and values:
-`formatjson` - Display the fields in JSON format.
Use these options to select Chrome browsers; if none are chosen, all Chrome browsers in the account are selected:
*`ou|org|orgunit|browserou <OrgUnitPath>` - Limit browsers to those in the specified OU; this option can be used in conjunction with query
*`(query <QueryBrowserToken>)|(queries <QueryBrowserTokenList>)` - Limit browser s to those that match a query
Use the `querytime<String> <Time>` option to allow times, usually relative, to be substituted into the `query <QueryBrowserToken>` and `queries <QueryBrowserTokenList>` options.
The `querytime<String> <Time>` value replaces the string `#querytime<String>#` in any queries.
The characters following `querytime` can be any combination of lowercase letters and numbers.
The first column will always be deviceId; the remaining field names will be sorted if `allfields`, `basic`, `full` or `sortheders` is specified;
otherwise, the remaining field names will appear in the order specified.
Select the fields to be displayed:
*`allfields` - Display all fields; this is the default
*`<BrowserTokenFieldName>* [fields <BrowserTokenFieldNameList>]` - Displaya selected list of fields
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.
Use these options to select Chrome devices; if none are chosen, all Chrome devices in the account are selected.
-`ou <OrgUnitItem>` - Select devices directly in the OU `<OrgUnitItem>`
-`ou_and_children <OrgUnitItem>` - Select devices in the OU `<OrgUnitItem>` and its sub OUs
-`ous <OrgUnitList>` - Select devices directly in the OUs `<OrgUnitList>`
-`ous_and_children <OrgUnitList>` - Select devices in the OUs `<OrgUnitList>` and their sub OUs
-`filter <String>` - The minimum `last_active_date` for the devices
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.
## Display Chrome devices with a specific installed application
Use these options to select Chrome devices; if none are chosen, all Chrome devices in the account are selected.
-`ou <OrgUnitItem>` - Select devices directly in the OU `<OrgUnitItem>`
-`ou_and_children <OrgUnitItem>` - Select devices in the OU `<OrgUnitItem>` and its sub OUs
-`ous <OrgUnitList>` - Select devices directly in the OUs `<OrgUnitList>`
-`ous_and_children <OrgUnitList>` - Select devices in the OUs `<OrgUnitList>` and their sub OUs
-`start <Date>` - The minimum `last_active_date` for the devices
-`end <Date>` - The maximum `last_active_date` for the devices
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.
* [Chrome Management API - Count Devices that Need Attention](https://developers.google.com/chrome/management/reference/rest/v1/customers.reports/countChromeDevicesThatNeedAttention)
## Notes
To use these features you must add the `Chrome Management API` to your project and authorize
the appropriate scope: `Chrome Management API - read only`.
Use these options to select Chrome devices; if none are chosen, all Chrome devices in the account are selected.
-`ou <OrgUnitItem>` - Select devices directly in the OU `<OrgUnitItem>`
-`ou_and_children <OrgUnitItem>` - Select devices in the OU `<OrgUnitItem>` and its sub OUs
-`ous <OrgUnitList>` - Select devices directly in the OUs `<OrgUnitList>`
-`ous_and_children <OrgUnitList>` - Select devices in the OUs `<OrgUnitList>` and their sub OUs
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.
Use these options to select Chrome profiles; if none are chosen, all Chrome profiles in the account are selected:
* `filter <String>` - Limit profiles to those that match a query
The first two columns will always `name,profileId`; the remaining field names will be sorted if `sortheaders` is specified;
otherwise, the remaining field names will appear in the order specified.
Select the fields to be displayed:
* `<ChromeProfileFieldName>* [fields <ChromeProfileFieldNameList>]` - Display a selected list of fields
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.
## Profile Query Searchable Fields
These are the fields that can be used in a filter:
```
affiliationState
browserChannel
browserVersion
displayName
extensionCount
firstEnrollmentTime
identityProvider
lastActivityTime
lastPolicySyncTime
lastStatusReportTime
osPlatformType
osVersion
ouId
policyCount
profileId
userEmail
```
Any of the above fields can be used to specify a filter, and filtering by multiple fields is supported with AND operator.
String type fields and enum type fields support '=' and '!=' operators. Wildcard '*' can be used with a string type field filter.
The integer type and the timestamp type fields support '=', '!=', '<', '>', '<=' and '>=' operators.
Timestamps expect an RFC-3339 formatted string (e.g. 2012-04-21T11:30:00-04:00).
In addition, string literal filtering is also supported, for example, 'ABC' as a filter maps to a filter that checks if any of the filterable string type fields contains 'ABC'.
Organization unit number can be used as a filtering criteria here by specifying 'ouId = <String>', please note that only single OU ID matching is supported.
### Examples
For Windows PowerShell, replace `\"` with ``` `" ```.
Print information about Chrome profiles synced more than 30 days ago:
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.
### Examples
For Windows PowerShell, replace `\"` with ``` `" ```.
Clear cache and cookies for two specific Chrome profiles:
Use these options to select Chrome devices; if none are chosen, all Chrome devices in the account are selected.
-`ou <OrgUnitItem>` - Select devices directly in the OU `<OrgUnitItem>`
-`ou_and_children <OrgUnitItem>` - Select devices in the OU `<OrgUnitItem>` and its sub OUs
-`ous <OrgUnitList>` - Select devices directly in the OUs `<OrgUnitList>`
-`ous_and_children <OrgUnitList>` - Select devices in the OUs `<OrgUnitList>` and their sub OUs
-`start <Date>` - The minimum `last_active_date` for the devices
-`end <Date>` - The maximum `last_active_date` for the devices
By default, the versions are displayed from oldest to most recent; use the `recentfirst` option to reverse this order.
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.
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.
## Display Chrome channels
```
gam show chromehistory channels
[platform <ChromePlatformType>]
[formatjson]
```
By default, channels for all platforms are displayed; use `platform <ChromePlatformType>]`
to select a specific platform.
By default, Gam displays the information as an indented list of keys and values.
*`formatjson` - Display the fields in JSON format.
By default, channels for all platforms are displayed; use `platform <ChromePlatformType>]`
to select a specific platform.
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.
By default, versions for all platforms and channels are displayed; use `platform <ChromePlatformType>]`
and/or `channel <ChromeChannelType>` to select a specific platform and/or channel.
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.
By default, versions for all platforms, channels and versions are displayed; use `platform <ChromePlatformType>]`
and/or `channel <ChromeChannelType>` and/or `version <String>` to select a specific platform and/or channel and/or version.
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.
* [Google Classroom API - Courses Students](https://developers.google.com/classroom/reference/rest/v1/courses.students)
* [Google Classroom API - Courses Teachers](https://developers.google.com/classroom/reference/rest/v1/courses.teachers)
* [Google Classroom API - Announcements](https://developers.google.com/classroom/reference/rest/v1/courses.announcements/list)
* [Google Classroom API - Topics](https://developers.google.com/classroom/reference/rest/v1/courses.topics/list)
* [Google Classroom API - Course Work](https://developers.google.com/classroom/reference/rest/v1/courses.courseWork/list)
* [Google Classroom API - Course Work Materials](https://developers.google.com/classroom/reference/rest/v1/courses.courseWorkMaterials/list)
* [Google Classroom API - Course Work Student Submissions](https://developers.google.com/classroom/reference/rest/v1/courses.courseWork.studentSubmissions/list)
## Notes
In this document, `course materials` refers to stand-alone materials, not the materials associated with
`course announcements` or `course work`. Google added support for stand-alone materials in early 2021.
To use the course materials features you must authorize the appropriate scope: `Classroom API - Course Work/Materials`.
```
gam oauth create
gam user user@domain.com check|update serviceaccount
As course aliases and topics can contain spaces, some care must be used when entering `<CourseAliasList>` and `<CourseTopicList>`.
Suppose you have a course with the alias `Math Class`. To get information about it you enter the command: `gam info course "d:Math Class"`
The shell strips the `"` leaving a single argument `d:Math Class`; gam correctly processes the argument as it is expecting a single course.
Suppose you enter the command: `gam info courses "d:Math Class"`
The shell strips the `"` leaving a single argument `d:Math Class`; as gam is expecting a list, it splits the argument on space leaving two items and then tries to process `d:Math` and `Class`, not what you want.
You must enter: `gam info courses "'d:Math Class'"`
The shell strips the `"` leaving a single argument `'d:Math Class'`; as gam is expecting a list, it splits the argument on space while honoring the `'` leaving one item `d:Math Class` and correctly processes the item.
For multiple aliases you must enter: `gam info courses "'d:Math Class','d:Science Class'"`
See: [Lists and Collections](Lists-and-Collections)
## Updating course owner
When updating a course owner, the Classroom API generates an error if the new owner is not a co-teacher
or is the current owner.
If `<UserItem>` is not a co-teacher, GAM adds `<UserItem>` as a co-teacher of the course,
pauses 10 seconds, and then updates them to be the owner.
`copyfrom <CourseID>` allows copying of course announcements, work, topics and members from one course to another.
* Accouncements - By default, no course announcements are copied
*`announcementstates <CourseAnnouncementStateList>` - Copy class announcements with the specified states
*`individualstudentannouncements copy` - Copy individual student announcements; this is the default. You will get an error if a student is not a member of the course
*`individualstudentannouncements maptoall` - Map individual student announcements to all student announcements
* Materials - By default, no course materials are copied
*`materialstates <CourseMaterialsStateList>` - Copy class materials with the specified states
*`individualstudentmaterials copy` - Copy individual student materials; this is the default. You will get an error if a student is not a member of the course
*`individualstudentmaterials maptoall` - Map individual student materials to all student materials
* Work - By default, no course work is copied
*`workstates <CourseWorkStateList>` - Copy class work with the specified states
*`individualstudentcoursework copy` - Copy individual student coursework; this is the default. You will get an error if the student is not a member of the course
By default, the `print courses` command displays information about all courses.
To get information about a specific set of courses, use the following option; it can be repeated to select multiple courses.
* `(course|class <CourseEntity>)*` - Display courses with the IDs specified in `<CourseEntity>`.
To get information about courses based on its owner's emailaddress, use the `owneremailmatchpattern <REMatchPattern>` option.
* `foo@bar.com` - Display courses with a specific owner emailaddress.
* `.*test.*` - Display courses with an owner emailaddress that matches a pattern.
* `Unknown user` - Display courses where the owner emailaddress has been deleted.
To get information about courses based on their having a particular participant, use the following options. Both options can be specified.
* `teacher <UserItem>` - Display courses with the specified teacher.
* `student <UserItem>` - Display courses with the specified student.
To get information about courses based on their state, use the following option. This option can be combined with the `teacher` and `student` options.
By default, all course states are selected.
* `states <CourseStateList>` - Display courses with any of the specified states.
To get information about courses created/updated within a particular time frame, use the following options.
* `timefilter creationtime|updatetime` - select which event to filter
* `start|starttime <Date>|<Time>` - specify the start of the time frame; if not specified, the time frame will be open ended at the start
* `end|endtime <Date>|<Time>` - specify the end of the time frame; if not specified, the time frame will be open ended at the end
For the filter to apply, `timefilter` and at least one of `start|starttime` and `end|endtime` must be specified.
By default, all basic course fields are displayed; use the following options to modify the output.
* `owneremail` - Display course owner email; requires an additional API call per course.
* `alias|aliases` - Display course aliases; all aliases are in the single column `Aliases` separated by a delimiter; requires an additional API call per course.
* `delimiter <Character>` - Delimiter between aliases with `print` command.
* `aliasesincolumn` - Display course aliases; the `Aliases` column contains the number of aliases and `Aliases.0`, `Aliases.1`, ... contain the individual aliases; requires an additional API call per course.
* `show all|students|teachers` - Show class participants profile information; requires an additional API call per course.
* `countsonly` - Eliminates the student/teacher profile information and outputs only the student/teacher counts.
* `fields <CourseFieldNameList>` - Select specific basic fields to display.
* `skipfields <CourseFieldNameList>` - Select specific basic fields to eliminate from display; typically used with `coursematerialsets`.
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.
By default, the `print course-announcements` command displays course announcement information for all courses.
To get course announcements for a specific set of courses, use the following option; it can be repeated to select multiple courses.
* `(course|class <CourseEntity>)*` - Display courses with the IDs specified in `<CourseEntity>`.
To get course announcements for courses based on their having a particular participant, use the following options. Both options can be specified.
* `teacher <UserItem>` - Display courses with the specified teacher.
* `student <UserItem>` - Display courses with the specified student.
To get course announcements for courses based on their state, use the following option. This option can be combined with the `teacher` and `student` options.
By default, all course states are selected.
* `states <CourseStateList>` - Display courses with any of the specified states.
By default, all published course announcements for a course are displayed; use the following options to select specific course announcements.
* `courseannouncementids <CourseAnnouncementIDEntity>` - Display course announcements with the IDs specified in `<CourseAnnouncementIDEntity>`.
* `announcementstates <CourseAnnouncementStateList>` - Display course announcements with any of the specified states.
To get information about course announcements created/updated/scheduled within a particular time frame, use the following options.
* `timefilter creationtime|updatetime|scheduledtime` - select which event to filter
* `start|starttime <Date>|<Time>` - specify the start of the time frame; if not specified, the time frame will be open ended at the start
* `end|endtime <Date>|<Time>` - specify the end of the time frame; if not specified, the time frame will be open ended at the end
For the filter to apply, `timefilter` and at least one of `start|starttime` and `end|endtime` must be specified.
By default, all course announcement fields are displayed; use the following options to modify the output.
* `creatoremail` - Display course announcement creator email; requires an additional API call per course announcement.
* `fields <CourseAnnouncementFieldNameList>` - Select specific fields to display.
Use the `countsonly` option to display the number of announcements in a course but not their details.
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.
By default, the `print course-materials` command displays course materials information for all courses.
To get course materials information for a specific set of courses, use the following option; it can be repeated to select multiple courses.
* `(course|class <CourseEntity>)*` - Display courses with the IDs specified in `<CourseEntity>`.
To get course materials information for courses based on their having a particular participant, use the following options. Both options can be specified.
* `teacher <UserItem>` - Display courses with the specified teacher.
* `student <UserItem>` - Display courses with the specified student.
To get course materials information for courses based on their state, use the following option. This option can be combined with the `teacher` and `student` options.
By default, all course states are selected.
* `states <CourseStateList>` - Display courses with any of the specified states.
To get information about course materials created/updated/scheduled within a particular time frame, use the following options.
* `timefilter creationtime|updatetime|scheduledtime` - select which event to filter
* `start|starttime <Date>|<Time>` - specify the start of the time frame; if not specified, the time frame will be open ended at the start
* `end|endtime <Date>|<Time>` - specify the end of the time frame; if not specified, the time frame will be open ended at the end
For the filter to apply, `timefilter` and at least one of `start|starttime` and `end|endtime` must be specified.
By default, all published course materials for a course are displayed; use the following options to select specific course materials.
* `materialsids <CourseMaterialsIDEntity>` - Display course materials with the IDs specified in `<CourseMaterialsIDEntity>`.
* `materialsstates <CourseMaterialsStateList>` - Display course materials with any of the specified states.
By default, all course materials fields are displayed; use the following options to modify the output.
* `showcreatoremails` - Display course materials creator email; requires an additional API call per course materials.
* `showtopicnames` - Display topic names; requires and additional API call per course.
* `fields <CourseMaterialsFieldNameList>` - Select specific fields to display.
With `print course-materials`, the materials selected for display are all output on one row/line as a repeating item with the other course fields.
When `oneitemperrow` is specified, each material is output on a separate row/line with the other course fields.
This simplifies processing the materials in the CSV file with subsequent Gam commands.
Use the `countsonly` option to display the number of course materials in a course but not their details.
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.
By default, the `print course-topics` command displays course topic information for all courses.
To get course topics for a specific set of courses, use the following option; it can be repeated to select multiple courses.
* `(course|class <CourseEntity>)*` - Display courses with the IDs specified in `<CourseEntity>`.
To get course topics for courses based on their having a particular participant, use the following options. Both options can be specified.
* `teacher <UserItem>` - Display courses with the specified teacher.
* `student <UserItem>` - Display courses with the specified student.
To get course topics for courses based on their state, use the following option. This option can be combined with the `teacher` and `student` options.
By default, all course states are selected.
* `states <CourseStateList>` - Display courses with any of the specified states.
By default, all published course topics for a course are displayed; use the following options to select specific course topics.
* `coursetopicids <CourseTopicIDEntity>` - Display course topics with the IDs specified in `<CourseTopicIDEntity>`.
* `topicstates <CourseTopicStateList>` - Display course topics with any of the specified states.
To get information about course topics updated within a particular time frame, use the following options.
* `timefilter updatetime` - select which event to filter
* `start|starttime <Date>|<Time>` - specify the start of the time frame; if not specified, the time frame will be open ended at the start
* `end|endtime <Date>|<Time>` - specify the end of the time frame; if not specified, the time frame will be open ended at the end
For the filter to apply, `timefilter` and at least one of `start|starttime` and `end|endtime` must be specified.
Use the `countsonly` option to display the number of topics in a course but not their details.
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.
By default, the `print course-work` command displays course work information for all courses.
To get course work information for a specific set of courses, use the following option; it can be repeated to select multiple courses.
* `(course|class <CourseEntity>)*` - Display courses with the IDs specified in `<CourseEntity>`.
To get course work information for courses based on their having a particular participant, use the following options. Both options can be specified.
* `teacher <UserItem>` - Display courses with the specified teacher.
* `student <UserItem>` - Display courses with the specified student.
To get course work information for courses based on their state, use the following option. This option can be combined with the `teacher` and `student` options.
By default, all course states are selected.
* `states <CourseStateList>` - Display courses with any of the specified states.
To get information about course work created/updated/scheduled within a particular time frame, use the following options.
* `timefilter creationtime|updatetime|scheduledtime` - select which event to filter
* `start|starttime <Date>|<Time>` - specify the start of the time frame; if not specified, the time frame will be open ended at the start
* `end|endtime <Date>|<Time>` - specify the end of the time frame; if not specified, the time frame will be open ended at the end
For the filter to apply, `timefilter` and at least one of `start|starttime` and `end|endtime` must be specified.
By default, all published course work for a course is displayed; use the following options to select specific course work.
* `workids <CourseWorkIDEntity>` - Display course work with the IDs specified in `<CourseWorkIDEntity>`.
* `workstates <CourseWorkStateList>` - Display course work with any of the specified states.
By default, all course work fields are displayed; use the following options to modify the output.
* `showcreatoremails` - Display course work creator email; requires an additional API call per course work.
* `showtopicnames` - Display topic names; requires and additional API call per course.
* `fields <CourseWorkFieldNameList>` - Select specific fields to display.
By default, when course work is assigned to individual students, the student IDs are displayed in multiple indexed columns.
Use options `showstudentsaslist [<Boolean>]` and `delimiter <Character>` to display the student IDs is a single column as a delimited list.
With `print course-work`, any materials are all output on one row/line as a repeating item with the other course fields.
When `oneitemperrow` is specified, each material is output on a separate row/line with the other course fields.
This simplifies processing the materials in the CSV file with subsequent Gam commands.
Use the `countsonly` option to display the number of course works in a course but not their details.
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.
By default, the `print course-submissions` command displays course submission information for all course work for all courses.
To get course submission information for a specific set of courses, use the following option; it can be repeated to select multiple courses.
* `(course|class <CourseEntity>)*` - Display courses with the IDs specified in `<CourseEntity>`.
To get course submission information for courses based on their having a particular participant, use the following options. Both options can be specified.
* `teacher <UserItem>` - Display courses with the specified teacher.
* `student <UserItem>` - Display courses with the specified student.
To get course submission information for courses based on their state, use the following option. This option can be combined with the `teacher` and `student` options.
By default, all course states are selected.
* `states <CourseStateList>` - Display courses with any of the specified states.
By default, all course work for a course is displayed; use the following options to select specific course work.
* `workids <CourseWorkIDEntity>` - Display course work with the IDs specified in `<CourseWorkIDEntity>`.
* `workstates <CourseWorkStateList>` - Display course work with any of the specified states.
By default, all course submissions for a course work is displayed; use the following options to select specific course submissions.
* `submissionids <CourseSubmissionIDEntity>` - Display course submissions with the IDs specified in `<CourseSubmissionIDEntity>`.
* `submissionstates <CourseSubmissionStateList>` - Display course submissions with any of the specified states.
* `notlate` - Display course submissions not marked late.
To get information about course submissions created/updated within a particular time frame, use the following options.
* `timefilter creationtime|updatetime` - select which event to filter
* `start|starttime <Date>|<Time>` - specify the start of the time frame; if not specified, the time frame will be open ended at the start
* `end|endtime <Date>|<Time>` - specify the end of the time frame; if not specified, the time frame will be open ended at the end
For the filter to apply, `timefilter` and at least one of `start|starttime` and `end|endtime` must be specified.
By default, all course submission fields are displayed; use the following options to modify the output.
* `fields <CourseSubmissionFieldNameList>` - Select specific fields to display.
By default, only the numeric userId is displayed; use the `showuserprofile` option to get the user email address and name.
You can only get profile information if the scope `https://www.googleapis.com/auth/classroom.profile.emails` is enabled
for service account access; verify with `gam <UserTypeEntity> update serviceaccount`.
Use the `countsonly` option to display the number of submissions in a course but not their details.
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.
The Classroom API does not return the student email address, use the `showstudentemails` option to get the student email address. This requires an additional API call per student.
### Selected students, new style
```
gam <UserTypeEntity> show guardian|guardians invitations [states <GuardianInvitationStateList>] [invitedguardian <EmailAddress>]
Use these options to control what information is displayed:
*`accepted` - Display accepted guardians; this is the default
*`invitations` - Display invitations
*`states <GuardianInvitationStateList>` - Filter the invitations by state
*`all` - Display accepted guardians and pending invitations
*`states <GuardianInvitationStateList>` - Filter the invitations by state
By default, Gam displays informations for all guardians; you can limit the display with the following option:
*`invitedguardian <EmailAddress>` - Display guardians with `<EmailAddress>`.
The Classroom API does not return the student email address, use the `showstudentemails` option to get the student email address. This requires an additional API call per student.
By default, Gam displays the information as an indented list of keys and values.
*`formatjson` - Display the fields in JSON format.
Use these options to control what information is displayed:
*`accepted` - Display accepted guardians; this is the default
*`invitations` - Display invitations
*`states <GuardianInvitationStateList>` - Filter the invitations by state
*`all` - Display accepted guardians and pending invitations
*`states <GuardianInvitationStateList>` - Filter the invitations by state
By default, Gam displays informations for all guardians; you can limit the display with the following options.
*`invitedguardian <EmailAddress>` - Display guardians with `<EmailAddress>`.
The Classroom API does not return the student email address, use the `showstudentemails` option to get the student email address. This requires an additional API call per student.
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.
If `role` is not specified, `student` will be used.
You can only invite a co-teacher to be an owner of a course.
By default, classroom invitations are issued by the owner of the course, the `adminaccess` option causes the invitations to be issued by the admin named in `oauth2.txt`.
By default, when an invitation is created, GAM outputs details of the invitation as indented keywords and values.
* `csv|csvformat [todrive <ToDriveAttribute>*] [formatjson [quotechar <Character>]]` - Output the details in CSV format.
### Example
Suppose you have a CSV file CourseStudent.csv with two columns: Course,Student.
This command will invite all students to their courses serially by student.
Select invitations to delete by role. By default, invitations for all roles will be deleted; you can limit the deletions to invitations of a specific role.
## Display classroom invitations by course
```
gam show classroominvitations (course|class <CourseEntity>)*|([teacher <UserItem>] [student <UserItem>] [states <CourseStateList>])
By default, classroom invitations for all courses are displayed.
To get classroom invitations for a specific set of courses, use the following option; it can be repeated to select multiple courses.
* `(course|class <CourseEntity>)*` - Display classroom invitations from the courses with the IDs specified in `<CourseEntity>`.
To get classroom invitations for courses based on their having a particular participant, use the following options. Both options can be specified.
* `teacher <UserItem>` - Display courses with the specified teacher.
* `student <UserItem>` - Display courses with the specified student.
To get classroom invitations for courses based on their state, use the following option. This option can be combined with the `teacher` and `student` options.
By default, all course states are selected.
* `states <CourseStateList>` - Display courses with any of the specified states.
By default, for `show`, Gam displays the information as an indented list of keys and values.
* `formatjson` - Display the fields in JSON format.
By default, for `print`, 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.
As course aliases can contain spaces, some care must be used when entering `<CourseAliasList>`, `<CourseID>`, `<CourseIDList>` and `<CourseEntity>`.
Suppose you have a course with the alias `Math Class`. To get information about it you enter the command: `gam info course "d:Math Class"`
The shell strips the `"` leaving a single argument `d:Math Class`; gam correctly processes the argument as it is expecting a single course.
Suppose you enter the command: `gam info courses "d:Math Class"`
The shell strips the `"` leaving a single argument `d:Math Class`; as gam is expecting a list, it splits the argument on space leaving two items and then tries to process `d:Math` and `Class`, not what you want.
You must enter: `gam info courses "'d:Math Class'"`
The shell strips the `"` leaving a single argument `'d:Math Class'`; as gam is expecting a list, it splits the argument on space while honoring the `'` leaving one item `d:Math Class` and correctly processes the item.
For multiple aliases you must enter: `gam info courses "'d:Math Class','d:Science Class'"`
See: [Lists and Collections](Lists-and-Collections)
## Manage membership for courses
These commands can process multiple courses and `add` and `delete` can process multiple students/teachers.
By default, the `print course-participants` command displays participant information about all courses.
To get participant information for a specific set of courses, use the following option; it can be repeated to select multiple courses.
* `(course|class <CourseID>)*` - Display courses with the specified `<CourseID>`.
To get participant information for courses based on their having a particular participant, use the following options. Both options can be specified.
* `teacher <UserItem>` - Display courses with the specified teacher.
* `student <UserItem>` - Display courses with the specified student.
To get participant information for courses based on their state, use the following option. This option can be combined with the `teacher` and `student` options.
By default, all course states are selected.
* `states <CourseStateList>` - Display courses with any of the specified states.
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.
As course aliases can contain spaces, some care must be used when entering `<CourseAliasList>`, `<CourseID>`, `<CourseIDList>` and `<CourseEntity>`.
Suppose you have a course with the alias `Math Class`. To get information about it you enter the command: `gam info course "d:Math Class"`
The shell strips the `"` leaving a single argument `d:Math Class`; gam correctly processes the argument as it is expecting a single course.
Suppose you enter the command: `gam info courses "d:Math Class"`
The shell strips the `"` leaving a single argument `d:Math Class`; as gam is expecting a list, it splits the argument on space leaving two items and then tries to process `d:Math` and `Class`, not what you want.
You must enter: `gam info courses "'d:Math Class'"`
The shell strips the `"` leaving a single argument `'d:Math Class'`; as gam is expecting a list, it splits the argument on space while honoring the `'` leaving one item `d:Math Class` and correctly processes the item.
For multiple aliases you must enter: `gam info courses "'d:Math Class','d:Science Class'"`
## Special quoting for lists of titles
As student group titles can contain spaces, some care must be used when entering `selevct <StringList>`.
Suppose you want to create a student group `Advanced Students`. `gam create course-studentgroups course <CourseID> title "Advanced Students"`
The shell strips the `"` leaving a single argument `Advanced Math`; gam correctly processes the argument as it is expecting a single title.
Suppose you enter the command: `gam create course-studentgroups course <CourseID> select "Advanced Students"`
The shell strips the `"` leaving a single argument `Advanced Students`; as gam is expecting a list, it splits the argument on space leaving two items and then tries to process `Advanced` and `Students`, not what you want.
You must enter: `gam create course-studentgroups course <CourseID> select "'Advanced Students'"`
The shell strips the `"` leaving a single argument `'Advanced Students'`; as gam is expecting a list, it splits the argument on space while honoring the `'` leaving one item `Advanced Students` and correctly processes the item.
For multiple titles you can enter either of the following:
When creating student groups, the API does not check for duplicate titles; you can have multiple student grpups
with the same title; they will have unique `<StudentGroupID>s`.
The `update|delete course-studentgroups` commands manage a specific course.
By default, the `create|clear course-studentgroups` commands manage student group information about all courses.
To manage student group information for a specific set of courses, use the following option; it can be repeated to select multiple courses.
* `(course|class <CourseID>)*` - Display courses with the specified `<CourseID>`.
To manage student group information for courses based on their having a particular participant, use the following options. Both options can be specified.
* `teacher <UserItem>` - Display courses with the specified teacher.
* `student <UserItem>` - Display courses with the specified student.
To manage student group information for courses based on their state, use the following option. This option can be combined with the `teacher` and `student` options.
By default, all course states are selected.
* `states <CourseStateList>` - Display courses with any of the specified states.
By default, when a student group is created, you will get output like this:
By default, the `print course-studentgroups` command displays student group information about all courses.
To display student group information for a specific set of courses, use the following option; it can be repeated to select multiple courses.
* `(course|class <CourseID>)*` - Display courses with the specified `<CourseID>`.
To display student group information for courses based on their having a particular participant, use the following options. Both options can be specified.
* `teacher <UserItem>` - Display courses with the specified teacher.
* `student <UserItem>` - Display courses with the specified student.
To display student group information for courses based on their state, use the following option. This option can be combined with the `teacher` and `student` options.
By default, all course states are selected.
* `states <CourseStateList>` - Display courses with any of the specified states.
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.
By default, the `print course-studentgroup-members` command displays student group member information about all courses.
To display student group member information for a specific set of courses, use the following option; it can be repeated to select multiple courses.
* `(course|class <CourseID>)*` - Display courses with the specified `<CourseID>`.
To display student group member information for courses based on their having a particular participant, use the following options. Both options can be specified.
* `teacher <UserItem>` - Display courses with the specified teacher.
* `student <UserItem>` - Display courses with the specified student.
To display student group member information for courses based on their state, use the following option. This option can be combined with the `teacher` and `student` options.
By default, all course states are selected.
* `states <CourseStateList>` - Display courses with any of the specified states.
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.
The filters will contain `"`, you must quote `<String>` as follows:
* Linux and MacOS
* Surround `<String>` with single quotes `'`
* Embedded `"` in `<String>` are entered as is
* Windows Command Prompt
* Surround `<String>` with double quotes `"`
* Embedded `"` in `<String>` are entered as `\"`
* Windows PowerShell
* Surround `<String>` with single quotes `'`
* Embedded `"` in `<String>` are entered as `\"`
When retrieving lists of customers from Cloud Channel API, how many should be retrieved in each API call.
*`maxresults <Number>` - How many customers to retrieve in each API call; default is 50, the maximum.
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.
If `name accounts/<ResellerID>/customers/<ChannelCustomerID>` is specified, `resellerId <ResellerID>` and `customerid <ChannelCustomerID>`
are ignored.
If `resellerId <ResellerID>` is omitted, the `reseller_id` value from `gam.cfg` is used.
If `customerid <ChannelCustomerID>` is omitted, the `channel_customer_id` value from `gam.cfg` is used.
When retrieving lists of customer entitlements from Cloud Channel API, how many should be retrieved in each API call.
*`maxresults <Number>` - How many customer entitlements to retrieve in each API call; default is 100, the maximum.
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.
If `resellerId <ResellerID>` is omitted, the `reseller_id` value from `gam.cfg` is used.
Cloud Channel API documentation for `filter <String>`:
```
The expression to filter results by name (name of the Offer), sku.name (name of the SKU), or sku.product.name (name of the Product).
* Example 1: sku.product.name=products/p1 AND sku.name!=products/p1/skus/s1
* Example 2: name=accounts/a1/offers/o1
```
When retrieving lists of offers from Cloud Channel API, how many should be retrieved in each API call.
*`maxresults <Number>` - How many offers to retrieve in each API call; default is 1000, the maximum.
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.
If `resellerId <ResellerID>` is omitted, the `reseller_id` value from `gam.cfg` is used.
When retrieving lists of products from Cloud Channel API, how many should be retrieved in each API call.
*`maxresults <Number>` - How many products to retrieve in each API call; default is 1000, the maximum.
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.
If `resellerId <ResellerID>` is omitted, the `reseller_id` value from `gam.cfg` is used.
If `productid <ProductID>` is omitted, SKUs for all products are displayed.
When retrieving lists of SKUs from Cloud Channel API, how many should be retrieved in each API call.
*`maxresults <Number>` - How many SKUs to retrieve in each API call; default is 1000, the maximum.
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.
Adds a new device to the Google company-owned inventory. Once a user is assigned and enrolled on the device the device will be considered company-owned for management purposes.
The device will also register as company-owned with Google services like [Context-Aware Access (CAA)](https://support.google.com/a/answer/9275380).
*`all` - Company and personal devices; this is the default
*`company|nopersonaldevices` - Company devices
*`personal|nocompanydevices` - Personal devices
By default, Gam makes additional API calls to display the device users for the devices;
use `nodeviceuser` to suppress making the additional calls.
By default, when device users are displayed, they are all displayed on one row;
use `oneuserperrow` to have each of a device's users displayed on a separate row with all of the other device fields.
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.
By default, Gam displays device users for all devices;
*`select <DeviceID>` - Display users for a specific device
*`(query <QueryDevice>)|(queries <QueryDeviceList>)` - Display users that match queries.
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.
The `cimember <UserItem>` option of `gam print|show cigroup-members` requires a Google Workspace Enterprise Standard, Enterprise Plus, and Enterprise for Education;
When `<UserTypeEntity>` specifies a group or groups:
*`usersonly` - Only the user members from the specified groups are added
*`groupsonly` - Only the group members from the specified groups are added
By default, when adding members from organization units, all users, whether suspended or not, are included.
*`notsuspended` - Do not include suspended users, this is common
*`suspended` - Only include suspended users, this is not common but allows creating groups that allow easy identification of suspended users
By default, when adding members from groups, all users, whether suspended/archived or not, are included.
*`notsuspended` - Do not include suspended users, this is common
*`suspended` - Only include suspended users, this is not common but allows creating groups that allow easy identification of suspended users
*`notarchived` - Do not include archived users
*`archived` - Only include archived users, this is not common but allows creating groups that allow easy identification of archived users
*`notsuspended notarchived` - Do not include suspended and archived users
*`suspended archived` - Include only suspended or archived users
*`notsuspended archived` - Only include archived users, this is not common but allows creating groups that allow easy identification of archived users
*`suspended notarchived` - Only include suspended users, this is not common but allows creating groups that allow easy identification of suspended users
If `preview` is specified, the changes will be previewed but not executed.
If `actioncsv` is specified, a CSV file with columns `group,email,role,action,message` is generated
that shows the actions performed when updating the group.
### `actioncsv` Example
Using `actioncsv` produces a CSV file showing the actions taken.
`<GroupRole>` is ignored, deletions take place regardless of role.
When `<UserTypeEntity>` specifies a group or groups:
*`usersonly` - Only the user members from the specified groups are deleted
*`groupsonly` - Only the group members from the specified groups are deleted
By default, when deleting members from organization units, all users, whether suspended or not, are included.
*`notsuspended` - Do not include suspended users, this is common
*`suspended` - Only include suspended users, this is not common but allows creating groups that allow easy identification of suspended users
By default, when deleting members from groups, all users, whether suspended/archived or not, are included.
*`notsuspended` - Do not include suspended users, this is common
*`suspended` - Only include suspended users, this is not common but allows creating groups that allow easy identification of suspended users
*`notarchived` - Do not include archived users
*`archived` - Only include archived users, this is not common but allows creating groups that allow easy identification of archived users
*`notsuspended notarchived` - Do not include suspended and archived users
*`suspended archived` - Include only suspended or archived users
*`notsuspended archived` - Only include archived users, this is not common but allows creating groups that allow easy identification of archived users
*`suspended notarchived` - Only include suspended users, this is not common but allows creating groups that allow easy identification of suspended users
If `preview` is specified, the changes will be previewed but not executed.
If `actioncsv` is specified, a CSV file with columns `group,email,role,action,message` is generated
that shows the actions performed when updating the group.
### `actioncsv` Example
Using `actioncsv` produces a CSV file showing the actions taken.
If `ignorerole` is specified, GAM removes members regardless of role and adds new members with role MEMBER.
This is a special purpose option, use with caution and ensure that `<UserTypeEntity>` specifies the full desired membership list of all roles.
If neither `<GroupRole>` nor `ignorerole` is specified, `member` is assumed.
When `<UserTypeEntity>` specifies a group or groups:
*`usersonly` - Only the user members from the specified groups are added/deleted
*`groupsonly` - Only the group members from the specified groups are added/deleted
By default, when synchronizing members from organization units, all users, whether suspended or not, are included.
*`notsuspended` - Do not include suspended users, this is common
*`suspended` - Only include suspended users, this is not common but allows creating groups that allow easy identification of suspended users
By default, when synchronizing members from groups, all users, whether suspended/archived or not, are included.
*`notsuspended` - Do not include suspended users, this is common
*`suspended` - Only include suspended users, this is not common but allows creating groups that allow easy identification of suspended users
*`notarchived` - Do not include archived users
*`archived` - Only include archived users, this is not common but allows creating groups that allow easy identification of archived users
*`notsuspended notarchived` - Do not include suspended and archived users
*`suspended archived` - Include only suspended or archived users
*`notsuspended archived` - Only include archived users, this is not common but allows creating groups that allow easy identification of archived users
*`suspended notarchived` - Only include suspended users, this is not common but allows creating groups that allow easy identification of suspended users
Default:
* members in `<UserTypeEntity>` that are not in the current membership will be added
* members in the current membership that are not in `<UserTypeEntity>` will deleted
When the `addonly` option is specified:
* members in `<UserTypeEntity>` that are not in the current membership will be added
* members in the current membership that are not in `<UserTypeEntity>` will not be deleted
When the `removeonly` option is specified:
* members in `<UserTypeEntity>` that are not in the current membership will not be added
* members in the current membership that are not in `<UserTypeEntity>` will be deleted
If `preview` is specified, the changes will be previewed but not executed.
If `actioncsv` is specified, a CSV file with columns `group,email,role,action,message` is generated
that shows the actions performed when updating the group.
By default, all types of members (cbcmbrowser, chromeosdevice, customer, group, serviceaccount, user) in the group are displayed; this option modifies that behavior:
By default, members that are groups are displayed as a single entry of type GROUP; this option recursively expands group members to display their user members.
*`recursive` - Recursively expand group members
When `recursive` is specified, the default is to only display type user members; this option modifies those behaviors:
Members that have met the above qualifications to be displayed can be further qualifed by their email address.
*`memberemaildisplaypattern <REMatchPattern>` - Members with email addresses that match `<REMatchPattern>` will be displayed; others will not be displayed
*`memberemailskippattern <REMatchPattern>` - Members with email addresses that match `<REMatchPattern>` will not be displayed; others will be displayed
By default, the ID, role, email address, type, createTime, updateTime and expireTime of each member is displayed along with the group email address;
these options specify which fields to display:
* `<CIGroupMembersFieldName>*` - Individual field names
* `fields <CIGroupMembersFieldNameList>` - A comma separated list of field names
* `full` - Fields displayed: group, type, id, role, email, createTime, updateTime, expireTime; this is the default
By default, the group email address is always shown, you can suppress it with the `nogroupemail` option.
The `recursive` option adds two columns, level and subgroup, to the output:
* `level` - At what level of the expansion does the user appear; level 0 is the top level
* `subgroup` - The group that contained the user
Displaying membership of multiple groups or recursive expansion may result in multiple instances of the same user being displayed; these multiple instances can be reduced to one entry.
* `noduplicates` - Reduce multiple instances of the same user to the first instance
The `includederivedmembership` option is an alternative to `recursive`; it causes the API to expand type GROUP
members to display their constituent members. The role displayed for a user is the highest role it
has in any constituent group, it is not necessarily its role in the top group.
The options `recursive noduplicates` and `includederivedmembership types user` return the same list of users.
The `includederivedmembership` option makes less API calls but doesn't show level and subgroup information.
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.
## Display group membership in hierarchical format
By default, all types of members (cbcmbrowser, chromeosdevice, customer, group, serviceaccount, user) in the group are displayed; this option modifies that behavior:
Members that have met the above qualifications to be displayed can be further qualifed by their email address.
* `memberemaildisplaypattern <REMatchPattern>` - Members with email addresses that match `<REMatchPattern>` will be displayed; others will not be displayed
* `memberemailskippattern <REMatchPattern>` - Members with email addresses that match `<REMatchPattern>` will not be displayed; others will be displayed
By default, members of type GROUP are recursively expanded to show their constituent members. (Members of
type CUSTOMER are not expanded.) The `depth <Number>` argument controls the depth to which nested groups are displayed.
* `depth -1` - all groups in the selected group and below are displayed; this is the default.
* `depth 0` - the groups within a selected group are displayed, no descendants are displayed.
* `depth N` - the groups within the selected group and those groups N levels below the selected group are displayed.
The `includederivedmembership` option causes the API to expand type GROUP
members to display their constituent members. The role displayed for a user is the highest role it
has in any constituent group, it is not necessarily its role in the top group.
The options `types user` and `includederivedmembership types user` return the same list of users.
The `includederivedmembership` option makes less API calls but doesn't show hierarchy.
The `cimember <UserItem>` option of `gam print cigroups` requires a Google Workspace Enterprise Standard, Enterprise Plus, and Enterprise for Education;
The `copyfrom <GroupItem>` allows copying of group attributes from one group to another.
The following attributes are not copied: name, description, email, admincreated, aliases, noneditablealiases.
Any `<GroupAttribute>` specified will override the copied attributes.
You can update a non-dynamic group to a non-dynamic security group with the `makesecuritygroup` option. To update a dynamic group to a security group, use the `makedynamicsecuritygroup` option instead.
* Warning: A Security Group cannot be changed back to a Google Group.
You can update a group to restrict its membership with the `memberrestrictions <QueryMemberRestrictions>`option.
By default, all direct members, managers and owners in the group are displayed; these options modify that behavior:
*`members` - Display members
*`managers` - Display managers
*`owners` - Display owners
*`nousers` or `quick` - Do not display any members, managers or owners
*`membertree` - Display all roles; expand all groups
By default, when displaying members from a group, all types of members (customer, group, serviceaccount, user) in the group are displayed; this option modifies that behavior:
By default, when listing group members, GAM does not take the domain of the member into account.
*`internal internaldomains <DomainNameList>` - Display members whose domain is in `<DomainNameList>`
*`external internaldomains <DomainNameList>` - Display members whose domain is not in `<DomainNameList>`
*`internal external internaldomains <DomainNameList>` - Display all members, indicate their category: internal or external
*`internaldomains <DomainNameList>` - Defaults to value of `domain` in `gam.cfg`
Members without an email address, e.g. `customer`, `chrome-os-device` and `cbcm-browser` are considered internal.
Members that have met the above qualifications to be displayed can be further qualifed by their email address.
*`memberemaildisplaypattern <REMatchPattern>` - Members with email addresses that match `<REMatchPattern>` will be displayed; others will not be displayed
*`memberemailskippattern <REMatchPattern>` - Members with email addresses that match `<REMatchPattern>` will not be displayed; others will be displayed
By default, all group aliases are displayed, these options modify that behavior:
*`noaliases` or `quick` - Do not display group aliases
By default, GAM makes an additional API call to get the `SecuritySettings` for the group.
*`nosecuritysettings` - Do not make API and display `SecuritySettings`
*`allfields` - All Cloud Identity Group fields
*`<CIGroupFieldName>*` - Individual fields to display
*`fields <CIGroupFieldNameList>` - A comma separated list of fields to display
By default, Gam displays the information as an indented list of keys and values.
*`formatjson` - Display the output in JSON notation
Some text fields may contain carriage returns or line feeds, displaying fields containing these characters will make processing the CSV file with a script hard; this option converts those characters to a text form.
The default value is `csv_output_convert_cr_nl` from `gam.cfg`
*`convertcrnl` - Convert carriage return to \r and line feed to \n
When lists of items are displayed, the delimiter between items defaults to the `csv_output_column_delimiter` value in gam.cfg; you can specify a different delimiter:
*`delimiter <Character>` - Use `<Character>` as the list item delimiter, `<Character>` must be a single character after processing any escape character
By default, no members, managers or owners in the group are displayed; these options modify that behavior:
*`members` - Display list of members
*`memberscount` - Display count of members but not individual members
*`managers` - Display list of managers
*`managerscount` - Display count of managers but not individual managers
*`owners` - Display list of owners
*`ownerscount` - Display count of owners but not individual owners
*`countsonly` - Change any `members`, `managers` or `owners` options to `memberscount`, `managerscount` or `ownerscount`
*`totalcount` - Display sum of counts of members, managers, owners.
By default, when displaying members from a group, all types of members (customer, group, serviceaccount, user) in the group are displayed; this option modifies that behavior:
By default, when listing group members, GAM does not take the domain of the member into account.
*`internal internaldomains <DomainNameList>` - Display members whose domain is in `<DomainNameList>`
*`external internaldomains <DomainNameList>` - Display members whose domain is not in `<DomainNameList>`
*`internal external internaldomains <DomainNameList>` - Display all members, indicate their category: internal or external
*`internaldomains <DomainNameList>` - Defaults to value of `domain` in `gam.cfg`
Members without an email address, e.g. `customer`, `chrome-os-device` and `cbcm-browser` are considered internal.
Members that have met the above qualifications to be displayed can be further qualifed by their email address.
*`memberemaildisplaypattern <REMatchPattern>` - Members with email addresses that match `<REMatchPattern>` will be displayed; others will not be displayed
*`memberemailskippattern <REMatchPattern>` - Members with email addresses that match `<REMatchPattern>` will not be displayed; others will be displayed
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.
* `filter <String>` - Display filtered policies, See https://cloud.google.com/identity/docs/reference/rest/v1beta1/policies/list
* `group <REMatchPattern>` - Only display policies whose group email address matches the `<REMatchPattern>`
* `ou|org|orgunit <REMatchPattern>` - Only display policies whose OU path matches the `<REMatchPattern>`
By default, policy warnings are displayed, use the `nowarnings` option to suppress their display.
By default, additional API calls are made for `settings/workspace_marketplace.apps_allowlist`
to get the application name for the application ID. Use option `noappnames` to suppress these calls.
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.
- [Python Regular Expressions](Python-Regular-Expressions) Search function
- [Definitions](#definitions)
- [Organization Unit Quoting](#organization-unit-quoting)
- [Query Quoting](#query-quoting)
- [Query Notes](#query-notes)
- [CrOS Type Entity](#cros-type-entity)
- [All ChromeOS devices](#all-chromeos-devices)
- [A list of ChromeOS deviceIds](#a-list-of-chromeos-deviceids)
- [A list of ChromeOS device serial numbers](#a-list-of-chromeos-device-serial-numbers)
- [ChromeOS devices directly in the Organization Unit `<OrgUnitItem>`](#chromeos-devices-directly-in-the-organization-unit-orgunititem)
- [ChromeOS devices in the Organization Unit `<OrgUnitItem>` and all of its sub Organization Units](#chromeos-devices-in-the-organization-unit-orgunititem-and-all-of-its-sub-organization-units)
- [ChromeOS devices directly in the Organization Units `<OrgUnitList>`](#chromeos-devices-directly-in-the-organization-units-orgunitlist)
- [ChromeOS devices in the Organization Units `<OrgUnitList>` and all of their sub Organization Units](#chromeos-devices-in-the-organization-units-orgunitlist-and-all-of-their-sub-organization-units)
- [ChromeOS devices directly in the Organization Unit `<OrgUnitItem>` that also match a query](#chromeos-devices-directly-in-the-organization-unit-orgunititem-that-also-match-a-query)
- [ChromeOS devices in the Organization Unit `<OrgUnitItem>` and all of its sub Organization Units that also match a query](#chromeos-devices-in-the-organization-unit-orgunititem-and-all-of-its-sub-organization-units-that-also-match-a-query)
- [ChromeOS devices directly in the Organization Units `<OrgUnitList>` that also match a query](#chromeos-devices-directly-in-the-organization-units-orgunitlist-that-also-match-a-query)
- [ChromeOS devices in the Organization Units `<OrgUnitList>` and all of their sub Organization Units that also match a query](#chromeos-devices-in-the-organization-units-orgunitlist-and-all-of-their-sub-organization-units-that-also-match-a-query)
- [ChromeOS devices directly in the Organization Unit `<OrgUnitItem>` that also match any query in a list of queries](#chromeos-devices-directly-in-the-organization-unit-orgunititem-that-also-match-any-query-in-a-list-of-queries)
- [ChromeOS devices in the Organization Unit `<OrgUnitItem>` and all of its sub Organization Units that also match any query in a list of queries](#chromeos-devices-in-the-organization-unit-orgunititem-and-all-of-its-sub-organization-units-that-also-match-any-query-in-a-list-of-queries)
- [ChromeOS devices directly in the Organization Units `<OrgUnitList>` that also match any query in a list of queries](#chromeos-devices-directly-in-the-organization-units-orgunitlist-that-also-match-any-query-in-a-list-of-queries)
- [ChromeOS devices in the Organization Units `<OrgUnitList>` and all of their sub Organization Units that also match any query in a list of queries](#chromeos-devices-in-the-organization-units-orgunitlist-and-all-of-their-sub-organization-units-that-also-match-any-query-in-a-list-of-queries)
- [ChromeOS devices that match a query](#chromeos-devices-that-match-a-query)
- [ChromeOS devices that match any query in a list of queries](#chromeos-devices-that-match-any-query-in-a-list-of-queries)
- [ChromeOS deviceIds in a flat file/Google Doc/Google Cloud Storage Object](#chromeos-deviceids-in-a-flat-filegoogle-docgoogle-cloud-storage-object)
- [ChromeOS serial numbers in a flat file/Google Doc/Google Cloud Storage Object](#chromeos-serial-numbers-in-a-flat-filegoogle-docgoogle-cloud-storage-object)
- [Selected ChromeOS deviceIds in a CSV file/Google Sheet/Google Doc/Google Cloud Storage Object](#selected-chromeos-deviceids-in-a-csv-filegoogle-sheetgoogle-docgoogle-cloud-storage-object)
- [Selected ChromeOS serial numbers in a CSV file/Google Sheet/Google Doc/Google Cloud Storage Object](#selected-chromeos-serial-numbers-in-a-csv-filegoogle-sheetgoogle-docgoogle-cloud-storage-object)
- [ChromeOS devices from OUs in a flat file/Google Doc/Google Cloud Storage Object](#chromeos-devices-from-ous-in-a-flat-filegoogle-docgoogle-cloud-storage-object)
- [ChromeOS deviceIds from OUs in a CSV file/Google Sheet/Google Doc/Google Cloud Storage Object](#chromeos-deviceids-from-ous-in-a-csv-filegoogle-sheetgoogle-docgoogle-cloud-storage-object)
- [ChromeOS devices directly in or from OUs in a CSV file/Google Sheet/Google Doc/Google Cloud Storage Object](#chromeos-devices-directly-in-or-from-ous-in-a-csv-filegoogle-sheetgoogle-docgoogle-cloud-storage-object)
- [ChromeOS deviceIds from data fields identified in a `csvkmd` argument](#chromeos-deviceids-from-data-fields-identified-in-a-csvkmd-argument)
- [Examples using CSV files](#examples-using-csv-files)
- [Examples using multiple queries or Org Units](#examples-using-multiple-queries-or-org-units)
## Definitions
* [Basic Items](Basic-Items)
* [List Items](List-Items)
* [Command data from Google Docs/Sheets/Storage](Command-Data-From-Google-Docs-Sheets-Storage)
## ChromeOS devices that match any query in a list of queries
*`crosqueries <QueryCrOSList>`
## ChromeOS deviceIds in a flat file/Google Doc/Google Cloud Storage Object
```
crosfile
((<FileName> [charset <Charset>])|
(gdoc <UserGoogleDoc>)|
(gcsdoc <StorageBucketObjectName>))
[delimiter <Character>]
```
*`<FileName>` - A flat file containing a single ChromeOS deviceId per row
*`charset <Charset>` - The character aset of the file if it isn't UTF-8
*`gdoc <UserGoogleDoc>` - A Google Doc containing a single ChromeOS deviceId per row
*`gcsdoc <StorageBucketObjectName>` - A Google Cloud Storage Bucket Object containing a single ChromeOS deviceId per row
*`delimiter <Character>` - There are multiple deviceIds per row separated by `<Character>`; if not specified, there is single deviceId per row
## ChromeOS serial numbers in a flat file/Google Doc/Google Cloud Storage Object
```
crosfile_sn
((<FileName> [charset <Charset>])|
(gdoc <UserGoogleDoc>)|
(gcsdoc <StorageBucketObjectName>))
[delimiter <Character>]
```
*`<FileName>` - A flat file containing a single ChromeOS serial number per row
*`charset <Charset>` - The character aset of the file if it isn't UTF-8
*`gdoc <UserGoogleDoc>` - A Google Doc containing a single ChromeOS serial number per row
*`gcsdoc <StorageBucketObjectName>` - A Google Cloud Storage Bucket Object containing a single ChromeOS serial number per row
*`delimiter <Character>` - There are multiple serial numbers per row separated by `<Character>`; if not specified, there is single serial number per row
## Selected ChromeOS deviceIds in a CSV file/Google Sheet/Google Doc/Google Cloud Storage Object
*`<FileName>(:<FieldName>)+` - A CSV file and the one or more columns that contain ChromeOS deviceIds
*`charset <Charset>` - The character aset of the file if it isn't UTF-8
*`gsheet(:<FieldName>)+ <UserGoogleSheet>` - A Google Sheet and the one or more columns that contain ChromeOS deviceIds
*`gdoc(:<FieldName>)+ <UserGoogleDoc>` - A Google Doc and the one or more columns that contain ChromeOS deviceIds
*`gcscsv(:<FieldName>)+ <StorageBucketObjectName>` - A Google Cloud Storage Bucket Object and the one or more columns that contain ChromeOS deviceIds
*`gcsdoc(:<FieldName>)+ <StorageBucketObjectName>` - A Google Cloud Storage Bucket Object and the one or more columns that contain ChromeOS deviceIds
*`warnifnodata` - Issue message 'No CSV file data found' and exit with return code 60 if there is no data selected from the file
*`columndelimiter <Character>` - Columns are separated by `<Character>`; if not specified, the value of `csv_input_column_delimiter` from `gam.cfg` will be used
*`noescapechar <Boolean>` - Should `\` be ignored as an escape character; if not specified, the value of `csv_input_no_escape_char` from `gam.cfg` will be used
*`quotechar <Character>` - The column quote characer is `<Character>`; if not specified, the value of `csv_input_quote_char` from `gam.cfg` will be used
*`endcsv` - Use this option to signal the end of the csvfile parameters in the case that the next argument on the command line is `fields` but is specifying the output field list for the command not column headings
*`fields <FieldNameList>` - The column headings of a CSV file that does not contain column headings
*`(matchfield|skipfield <FieldName> <RESearchPattern>)*` - The criteria to select rows from the CSV file; can be used multiple times; if not specified, all rows are selected
*`delimiter <Character>` - There are multiple deviceIds per column separated by `<Character>`; if not specified, there is single deviceId per column
## Selected ChromeOS serial numbers in a CSV file/Google Sheet/Google Doc/Google Cloud Storage Object
*`<FileName>(:<FieldName>)+` - A CSV file and the one or more columns that contain ChromeOS serial numbers
*`charset <Charset>` - The character aset of the file if it isn't UTF-8
*`gsheet(:<FieldName>)+ <UserGoogleSheet>` - A Google Sheet and the one or more columns that contain ChromeOS serial numbers
*`gdoc(:<FieldName>)+ <UserGoogleDoc>` - A Google Doc and the one or more columns that contain ChromeOS serial numbers
*`gcscsv(:<FieldName>)+ <StorageBucketObjectName>` - A Google Cloud Storage Bucket Object and the one or more columns that contain ChromeOS serial numbers
*`gcsdoc(:<FieldName>)+ <StorageBucketObjectName>` - A Google Cloud Storage Bucket Object and the one or more columns that contain ChromeOS serial numbers
*`warnifnodata` - Issue message 'No CSV file data found' and exit with return code 60 if there is no data selected from the file
*`columndelimiter <Character>` - Columns are separated by `<Character>`; if not specified, the value of `csv_input_column_delimiter` from `gam.cfg` will be used
*`noescapechar <Boolean>` - Should `\` be ignored as an escape character; if not specified, the value of `csv_input_no_escape_char` from `gam.cfg` will be used
*`quotechar <Character>` - The column quote characer is `<Character>`; if not specified, the value of `csv_input_quote_char` from `gam.cfg` will be used
*`endcsv` - Use this option to signal the end of the csvfile parameters in the case that the next argument on the command line is `fields` but is specifying the output field list for the command not column headings
*`fields <FieldNameList>` - The column headings of a CSV file that does not contain column headings
*`(matchfield|skipfield <FieldName> <RESearchPattern>)*` - The criteria to select rows from the CSV file; can be used multiple times; if not specified, all rows are selected
*`delimiter <Character>` - There are multiple serial numbers per column separated by `<Character>`; if not specified, there is single deviceId per column
## ChromeOS devices from OUs in a flat file/Google Doc/Google Cloud Storage Object
```
datafile
cros|cros_sn|cros_ous|cros_ous_and_children
((<FileName> [charset <Charset>])|
(gdoc <UserGoogleDoc>)|
(gcsdoc <StorageBucketObjectName>))
[delimiter <Character>]
```
*`cros|cros_sn|cros_ous|cros_ous_and_children` - The type of item in the file
*`<FileName>` - A flat file containing a single item per row
*`charset <Charset>` - The character aset of the file if it isn't UTF-8
*`gdoc <UserGoogleDoc>` - A Google Doc containing a single item per row
*`gcsdoc <StorageBucketObjectName>` - A Google Cloud Storage Bucket Object containing a item per row
*`delimiter <Character>` - There are multiple items per row separated by `<Character>`; if not specified, there is single item per row
## ChromeOS deviceIds from OUs in a CSV file/Google Sheet/Google Doc/Google Cloud Storage Object
*`cros|cros_ous|cros_ous_and_children` - The type of item in the file
*`<FileName>(:<FieldName>)+` - A CSV file and the one or more columns that contain ChromeOS deviceIds
*`charset <Charset>` - The character aset of the file if it isn't UTF-8
*`gsheet(:<FieldName>)+ <UserGoogleSheet>` - A Google Sheet and the one or more columns that contain ChromeOS deviceIds
*`gdoc(:<FieldName>)+ <UserGoogleDoc>` - A Google Doc and the one or more columns that contain ChromeOS deviceIds
*`gcscsv(:<FieldName>)+ <StorageBucketObjectName>` - A Google Cloud Storage Bucket Object and the one or more columns that contain ChromeOS deviceIds
*`gcsdoc(:<FieldName>)+ <StorageBucketObjectName>` - A Google Cloud Storage Bucket Object and the one or more columns that contain ChromeOS deviceIds
*`warnifnodata` - Issue message 'No CSV file data found' and exit with return code 60 if there is no data selected from the file
*`columndelimiter <Character>` - Columns are separated by `<Character>`; if not specified, the value of `csv_input_column_delimiter` from `gam.cfg` will be used
*`noescapechar <Boolean>` - Should `\` be ignored as an escape character; if not specified, the value of `csv_input_no_escape_char` from `gam.cfg` will be used
*`quotechar <Character>` - The column quote characer is `<Character>`; if not specified, the value of `csv_input_quote_char` from `gam.cfg` will be used
*`endcsv` - Use this option to signal the end of the csvfile parameters in the case that the next argument on the command line is `fields` but is specifying the output field list for the command not column headings
*`fields <FieldNameList>` - The column headings of a CSV file that does not contain column headings
*`(matchfield|skipfield <FieldName> <RESearchPattern>)*` - The criteria to select rows from the CSV file; can be used multiple times; if not specified, all rows are selected
*`delimiter <Character>` - There are multiple deviceIds per column separated by `<Character>`; if not specified, there is single deviceId per column
## ChromeOS devices directly in or from OUs in a CSV file/Google Sheet/Google Doc/Google Cloud Storage Object
*`cros|cros_sn|cros_ous|cros_ous_and_children` - The type of item in the file
*`<FileName>` - A CSV file containing rows with columns of the type of item specified
*`charset <Charset>` - The character aset of the file if it isn't UTF-8
*`gsheet <UserGoogleSheet>` - A Google Sheet containing rows with columns of the type of item specified
*`gdoc <UserGoogleDoc>` - A Google Doc containing rows with columns of the type of item specified
*`warnifnodata` - Issue message 'No CSV file data found' and exit with return code 60 if there is no data selected from the file
*`columndelimiter <Character>` - Columns are separated by `<Character>`; if not specified, the value of `csv_input_column_delimiter` from `gam.cfg` will be used
*`noescapechar <Boolean>` - Should `\` be ignored as an escape character; if not specified, the value of `csv_input_no_escape_char` from `gam.cfg` will be used
*`quotechar <Character>` - The column quote characer is `<Character>`; if not specified, the value of `csv_input_quote_char` from `gam.cfg` will be used
*`endcsv` - Use this option to signal the end of the csvfile parameters in the case that the next argument on the command line is `fields` but is specifying the output field list for the command not column headings
*`fields <FieldNameList>` - The column headings of a CSV file that does not contain column headings
*`keyfield <FieldName>` - The column containing key values
*`[keypattern <RESearchPattern>] [keyvalue <RESubstitution>]` - Allows transforming the value(s) in the `keyfield` column. If only `keyvalue <RESubstitution>` is specified, all instances of `<FieldName>` in `keyvalue <RESubstitution>` will be replaced by the item value. If `keypattern <RESearchPattern>` is specified, the item value is matched against `<RESearchPattern>` and the matched segments are substituted into `keyvalue <RESubstitution>`
*`delimiter <Character>` - There are multiple values per keyfield column separated by `<Character>`; if not specified, there is single value per keyfield column
*`subkeyfield <FieldName>` - The column containing subkey values
*`[keypattern <RESearchPattern>] [keyvalue <RESubstitution>]` - Allows transforming the value(s) in the `subkeyfield` column. If only `keyvalue <RESubstitution>` is specified, all instances of `<FieldName>` in `keyvalue <RESubstitution>` will be replaced by the item value. If `keypattern <RESearchPattern>` is specified, the item value is matched against `<RESearchPattern>` and the matched segments are substituted into `keyvalue <RESubstitution>`
*`delimiter <Character>` - There are multiple values per subkeyfield column separated by `<Character>`; if not specified, there is single value per subkeyfield column
*`(matchfield|skipfield <FieldName> <RESearchPattern>)*` - The criteria to select rows from the CSV file; can be used multiple times; if not specified, all rows are selected
*`datafield <FieldName>(:<FieldName)*` - The column(s) containing data values
*`delimiter <Character>` - There are multiple values per datafield column separated by `<Character>`; if not specified, there is single value per datafield column
## ChromeOS deviceIds from data fields identified in a `csvkmd` argument
*`croscsvdata <FieldName>(:<FieldName>*)` - Data fields identified in a `csvkmd` argument
## Examples using CSV files
You want to print information about ChromeOS devices at your school from Org Units based on graduation year.
Example 1
CSV File OrgUnit.csv, exactly the data you want, `keypattern` and `keyvalue` are not required.
```
OrgUnit
/Students/2020
/Students/2021
...
```
For each row, the value from the OrgUnit column is used as the Org Unit name.
CSV File GradYear.csv, you have to convert GradYear to Org Unit name `/Students/LastTwoDigitsOfGradYear`, `keypattern` and `keyvalue` are required.
```
GradYear
2020
2021
...
```
For each row, the value from the GradYear column is matched against the `keypattern` and the matched segments are substituted into the `keyvalue` argument and that value is used as the Org Unit name.
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
