Todrive

Todrive

• Introduction
• Definitions
• Config file options
• Command line options
• Redirect CSV
• Limited Service Account Access
• No Service Account Access

• Authorization

Introduction

Gam print commands allow the results to be uploaded to Google Drive instead of being saved locally. By default, Gam titles the uploaded file: "Domain Name - Data Type"; Data Type describes the data being uploaded, e.g. Groups, Orgs, Users. It is uploaded to the root folder of the admin user named in oauth2.txt.

You can modify the default todrive behavior with options in gam.cfg or on the command line.

Definitions

<Locale> ::=
        ''|    #Not defined
        ar_eg| #Arabic, Egypt
        az_az| #Azerbaijani, Azerbaijan
        be_by| #Belarusian, Belarus
        bg_bg| #Bulgarian, Bulgaria
        bn_in| #Bengali, India
        ca_es| #Catalan, Spain
        cs_cz| #Czech, Czech Republic
        cy_gb| #Welsh, United Kingdom
        da_dk| #Danish, Denmark
        de_ch| #German, Switzerland
        de_de| #German, Germany
        el_gr| #Greek, Greece
        en_au| #English, Australia
        en_ca| #English, Canada
        en_gb| #English, United Kingdom
        en_ie| #English, Ireland
        en_us| #English, U.S.A.
        es_ar| #Spanish, Argentina
        es_bo| #Spanish, Bolivia
        es_cl| #Spanish, Chile
        es_co| #Spanish, Colombia
        es_ec| #Spanish, Ecuador
        es_es| #Spanish, Spain
        es_mx| #Spanish, Mexico
        es_py| #Spanish, Paraguay
        es_uy| #Spanish, Uruguay
        es_ve| #Spanish, Venezuela
        fi_fi| #Finnish, Finland
        fil_ph| #Filipino, Philippines
        fr_ca| #French, Canada
        fr_fr| #French, France
        gu_in| #Gujarati, India
        hi_in| #Hindi, India
        hr_hr| #Croatian, Croatia
        hu_hu| #Hungarian, Hungary
        hy_am| #Armenian, Armenia
        in_id| #Indonesian, Indonesia
        it_it| #Italian, Italy
        iw_il| #Hebrew, Israel
        ja_jp| #Japanese, Japan
        ka_ge| #Georgian, Georgia
        kk_kz| #Kazakh, Kazakhstan
        kn_in| #Kannada, India
        ko_kr| #Korean, Korea
        lt_lt| #Lithuanian, Lithuania
        lv_lv| #Latvian, Latvia
        ml_in| #Malayalam, India
        mn_mn| #Mongolian, Mongolia
        mr_in| #Marathi, India
        my_mn| #Burmese, Myanmar
        nl_nl| #Dutch, Netherlands
        nn_no| #Nynorsk, Norway
        no_no| #Bokmal, Norway
        pa_in| #Punjabi, India
        pl_pl| #Polish, Poland
        pt_br| #Portuguese, Brazil
        pt_pt| #Portuguese, Portugal
        ro_ro| #Romanian, Romania
        ru_ru| #Russian, Russia
        sk_sk| #Slovak, Slovakia
        sl_si| #Slovenian, Slovenia
        sr_rs| #Serbian, Serbia
        sv_se| #Swedish, Sweden
        ta_in| #Tamil, India
        te_in| #Telugu, India
        th_th| #Thai, Thailand
        tr_tr| #Turkish, Turkey
        uk_ua| #Ukrainian, Ukraine
        vi_vn| #Vietnamese, Vietnam
        zh_cn| #Simplified Chinese, China
        zh_hk| #Traditional Chinese, Hong Kong SAR China
        zh_tw  #Traditional Chinese, Taiwan
<SheetEntity> ::= <String>|id:<Number>
<TimeZone> ::= <String>
        See: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

Config file options

You can specify most todrive options in gam.cfg.

todrive_clientaccess
        Enable/disable use of client access rather than service account access when uploading files with todrive
        Default: False
todrive_conversion
        Enable/disable conversion of CSV files to Google Sheets when todrive is specified
        Default: True
todrive_localcopy
        Enable/disable saving a local copy of CSV files when todrive is specified
        Default: False
tdlocale
        The Spreadsheet settings Locale value.
        See <Locale>
        Default: ''
todrive_nobrowser
        Enable/disable opening a browser when todrive is specified
        Default: False
todrive_noemail
        Enable/disable sending an email when todrive is specified
        Default: True
todrive_parent
        Parent folder for CSV files when todrive is specified;
        can be id:<DriveFolderID> or <DriveFolderName>
        Default: root
todrive_timestamp
        Enable/disable adding a timestamp to the title of CSV files when todrive is specified
        Default: False
tdtimezone
        The Spreadsheet settings Timezone value.
        See: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
        Default: ''
todrive_user
        Email address of user to receive CSV files when todrive is specified
        Default: '' which becomes admin user in oauth2.txt

Command line options

Anywhere you can specify todrive, there are additional subarguments following the todrive argument that let you title the file, add a description, specify the sheet name, direct the uploaded file to a particular user and location and add a timestamp to the file title.

<ToDriveAttribute> ::=
        (tddescription <String>)|
        (tdlocalcopy [<Boolean>])|
        (tdlocale <Locale>)|
        (tdnobrowser [<Boolean>])|
        (tdnoemail [<Boolean>])|
        (tdparent (id:<DriveFolderID>)|<DriveFolderName>)|(tdfileid <DriveFileID>)
        (tdsheet <SheetEntity>)|
        (tdtimestamp [<Boolean>] [tddaysoffset <Number>] [tdhoursoffset <Number])|
        (tdtimezone <TimeZone>)|
        (tdtitle <String>)|
        (tdcellwrap clip|overflow|wrap)|
        (tdupdatesheet [<Boolean>])|
        (tduser <EmailAddress>)

• tddaysoffset and tdhoursoffset - Values that subtract time from the timestamp, they default to 0. A possible use for these values is as documentation to reflect the end of the time period that the uploaded report covers.
• tddescription - The description for the uploaded file, if not specified, the command line that created the file is used.
• tdfileid - An existing/writable file for the uploaded file; it takes precedence over tdparent.
• tdlocalcopy - Should a local copy of the CSV file be saved in addition to the file uploaded to Google Drive; if not specified, the todrive_localcopy value from gam.cfg is used.
• tdlocale <Locale> - The Spreadsheet settings Locale value.
• tdnobrowser - If False, a browser is opened to view the file uploaded to Google Drive; if not specified, the todrive_nobrowser value from gam.cfg is used.
• tdnoemail - If False, an email is sent to tduser informing them of name and URL of the uploaded file; if not specified, the todrive_noemail value from gam.cfg is used.
• tdparent - An existing/writable parent folder for the uploaded file; if not specified, the todrive_parent value from gam.cfg is used; that value defaults to the root folder.
• tdsheet <String> - The sheet name in the uploaded file if it is uploaded as a Google Sheet, if not specified, the tdtitle is used.
  • When used with tdfileid but not tdupdatesheet, an existing sheet of the same name will be replaced and assigned a new sheet ID. All other sheets will be deleted.
  • When used with tdfileid and tdupdatesheet, an existing sheet of the same name will be updated and retain its sheet ID. All other sheets are unaffected.
• tdsheet id:<Number> - The sheet ID in an existing spreadsheet file.
  • Only used with tdfileid and tdupdatesheet.
  • An existing sheet will be updated and retain its sheet ID. All other sheets are unaffected.
• tdtimestamp - Should a timestamp (of the time the file is uploaded to Google) be added to the title of the uploaded file; if not specified, the todrive_timestamp value from gam.cfg is used, that value defaults to False.
• tdtimezone <TimeZone> - The Spreadsheet settings Timezone value. See: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
• tdtitle - The title for the uploaded file, if not specified, the Gam default title is used.
• tdcellwrap clip|overflow|wrap - The Spreadsheet cell wrapping strategy.
• tdupdatesheet - In conjunction with tdfileid and tdsheet or tdsheetid, an existing sheet in an existing/writeable file is updated.
• tduser - The user to receive the uploaded file; if not specified, the todrive_user value from gam.cfg is used; that value defaults to the user named in oauth2.txt.

Redirect CSV

You can specify todrive options in conjunction with redirect csv.

redirect csv <FileName> [multiprocess] [append] [noheader] [charset <Charset>]
             [columndelimiter <Character>] [quotechar <Character>]
             [todrive <ToDriveAttribute>*]

If you are doing redirect csv <FileName> multiprocess, it is more efficient to specify todrive <ToDriveAttribute>* as part of the redirect as verification of the todrive settings, which can invole several API calls, is done once rather than in each of the subprocesses.

Examples

Generate a list of user IDs and names, title the file "User IDs and Names", upload it to the "GAM Reports" folder of usermgr@domain.com, add a timestamp to the title.

gam print users fields id,name todrive tdtitle "User IDs and Names" tdtimestamp true tduser usermgr@domain.com tdparent "GAM Reports"

Generate a list of CrOS devices and update an existing sheet in a Google spreadsheet. The sheet ID is preserved so other appplications can access the data using the file ID and sheet ID. By setting 'tdtimestamp true`, the file name will the updated to reflect the time of execution, but the file ID will not change.

gam redirect csv - todrive tdtitle "CrOS" tdtimestamp true tdfileid 12345-mizZ6Q2vP1rcHQH3tAZQt_NVB2EOxmS2SU3yM tdsheet id:0 tdupdatesheet true print cros fields deviceId,notes,orgUnitPath,serialNumber,osversion

For a collection of users, generate a list of files shared with anyone; combine the output for all users into a single file.

gam redirect csv - multiprocess todrive tdtitle AnyoneShares-All csv Users.csv gam user ~primaryEmail print filelist fields id,name,permissions pm type anyone em

For a collection of users, generate a list of files shared with anyone; generate a separate file for each user. The two forms of the command are equivalent.

gam csv Users.csv gam redirect csv - todrive tdtitle "AnyoneShares-~~primaryEmail~~" user ~primaryEmail print filelist fields id,name,permissions pm type anyone em

gam csv Users.csv gam user ~primaryEmail print filelist fields id,name,permissions pm type anyone em todrive tdtitle "AnyoneShares-~~primaryEmail~~" 

Limited Service Account Access

If you want to limit a user's service account access but still allow `todrive', issue the following command and authorize the additional service account APIs:

gam user user@domain.com update serviceaccount`

Authorize these APIs:

Drive API - todrive
Gmail API - Send Messages - including todrive
Sheets API - todrive

No Service Account Access

By default, todrive uses service account access to upload files, set sheet names and send email notifications.

If it is not possible to allow the user any service account access (this is not common), perform the following command so that the user can upload files with todrive using client access.

gam config todrive_clientaccess true save

Issue the following command and authorize the additional client access APIs:

gam oauth create

Authorize these APIs:
Drive API - todrive_clientaccess
Gmail API - todrive_clientaccess
Sheets API - todrive_clientaccess

When todrive_clientaccess is true, todrive_user\tduser is ignored, all actions are performed as the user specified in oauth2.txt.