Course-work and vacation updates

docs/Classroom-Courses.md

@@ -354,7 +354,7 @@ Drive files with `shareMode` `Each student will get a copy` don't seem to be abl
 
 ## Delete courses
 Classes can only be deleted when they are in the ARCHIVED state; to delete a class, you can update its state to ARCHIVED
-and then delete it or you can specify that it be archived as part of the delete command.
+and then delete it or you can specify that it be archived as parot of the delete command.
 ```
 gam delete course <CourseID> [archived]
 gam delete courses <CourseEntity> [archived]
@@ -603,7 +603,9 @@ gam print course-work [todrive <ToDriveAttribute>*]
         (course|class <CourseEntity>)*|([teacher <UserItem>] [student <UserItem>] states <CourseStateList>])
         (workids <CourseWorkIDEntity>)|(workstates <CourseWorkStateList>)*
         (orderby <CourseWorkOrderByFieldName> [ascending|descending])*)
-        [showcreatoremails] [showtopicnames] [fields <CourseWorkFieldNameList>] [formatjson [quotechar <Character>]]
+        [showcreatoremails] [showtopicnames] [fields <CourseWorkFieldNameList>]
+        [showstudentsaslist [<Boolean>]] [delimiter <Character>]
+        [formatjson [quotechar <Character>]]
         [timefilter creationtime|updatetime|scheduledtime] [start|starttime <Date>|<Time>] [end|endtime <Date>|<Time>]
 ```
 By default, the `print course-work` command displays course work information for all courses.
@@ -625,7 +627,7 @@ To get information about course work created/updated/scheduled within a particul
 * `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 pub`lished course work for a course is displayed; use the following options to select specific course work.
+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.
 
@@ -634,6 +636,9 @@ By default, all course work fields are displayed; use the following options to m
 * `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.
+
 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.
 

docs/GamUpdates.md

@@ -10,6 +10,18 @@ Add the `-s` option to the end of the above commands to suppress creating the `g
 
 See [Downloads-Installs](https://github.com/taers232c/GAMADV-XTD3/wiki/Downloads-Installs) for Windows or other options, including manual installation
 
+### 6.80.01
+
+Added options `showstudentsaslist [<Boolean>]` and `delimiter <Character>` to `gam print course-work`.
+By default, when course work is assigned to individual students, the student IDs are displayed in multiple indexed columns.
+Use these options to display the student IDs in a single column as a delimited list.
+
+Updated `gam <UserTypeEntity> vacation [<Boolean>]` to make `<Boolean>` optional; this allows changes
+to other fields without affecting the current responder state.
+
+Updated `gam <UserTypeEntity> print|show vacation` to avoid a trap when invalid start or end dates
+have been entered in the Gmail user interface. Invalid dates are represented as `1970-01-01`.
+
 ### 6.80.00
 
 Fixed bug in `gam <UserTypeEntity> print users ... license ... formatjson` that caused a trap.

docs/Groups.md

@@ -584,7 +584,7 @@ gam print grouptree <GroupEntity> [todrive <ToDriveAttribute>*]
 ```
 By default, the group parent emails and names are displayed in multiple indexed columns.
 Use options `showparentsaslist [<Boolean>]` and `delimiter <Character>` to display
-the group parent emails and names in two columns as delimited lists .
+the group parent emails and names in two columns as delimited lists.
 
 #### Examples
 ```

docs/How-to-Upgrade-from-Standard-GAM.md

@@ -251,7 +251,7 @@ writes the credentials into the file oauth2.txt.
 admin@server:/Users/admin$ rm -f /Users/admin/GAMConfig/oauth2.txt
 admin@server:/Users/admin$ gam version
 WARNING: Config File: /Users/admin/GAMConfig/gam.cfg, Section: DEFAULT, Item: oauth2_txt, Value: /Users/admin/GAMConfig/oauth2.txt, Not Found
-GAMADV-XTD3 6.80.00 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
+GAMADV-XTD3 6.80.01 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
 Ross Scroggs <ross.scroggs@gmail.com>
 Python 3.12.4 64-bit final
 MacOS Sonoma 14.5 x86_64
@@ -923,7 +923,7 @@ writes the credentials into the file oauth2.txt.
 C:\>del C:\GAMConfig\oauth2.txt
 C:\>gam version
 WARNING: Config File: C:\GAMConfig\gam.cfg, Section: DEFAULT, Item: oauth2_txt, Value: C:\GAMConfig\oauth2.txt, Not Found
-GAMADV-XTD3 6.80.00 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
+GAMADV-XTD3 6.80.01 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
 Ross Scroggs <ross.scroggs@gmail.com>
 Python 3.12.4 64-bit final
 Windows-10-10.0.17134 AMD64

docs/Running-GAMADV-XTD3-securely-on-a-Google-Compute-Engine.md

@@ -15,24 +15,37 @@ GAMADV-XTD3 version 6.50.00 or higher is required.
 ## Setup Steps
 1. Create a [GCP project](https://cloud.google.com/resource-manager/docs/creating-managing-projects).
 
-2. Create [a service account](https://cloud.google.com/iam/docs/creating-managing-service-accounts) which will be used by GAMADV-XTD3. Continue steps 2 and 3 without granting the new service account any special access to the project and without granting users access to the service account.
+2. Create [a service account](https://cloud.google.com/iam/docs/creating-managing-service-accounts) which will be used by GAMADV-XTD3.
+   * Enter a value in Service account name
+   * Enter text in Service account description
+   * Click Create and Continue
+   * Click Continue under Grant this service account access to project
+   * Click Done under Grant users access to this service account
  
 3. Grant the service account rights to generate authentication tokens.
-   * go to [console.cloud.google.com](https://console.cloud.google.com).
-   * go to "IAM & Admin" > Service accounts
-   * click on the service account you created (not the default service account).
-   * copy the email address of your service account to the clipboard.
-   * click on the Permissions tab.
-   * click "Grant Access".
+   * Go to [console.cloud.google.com](https://console.cloud.google.com).
+   * Go to "IAM & Admin" > Service accounts
+   * Click on the service account you created (not the default service account).
+   * Copy the email address of your service account to the clipboard.
+   * Click on the Permissions tab.
+   * Click "Grant Access".
    * In the "New principals text box, paste the service account email you copied.
    * Give your service account the "Service Account Key Admin", "Service Account Token Creator" and "View Service Accounts" roles.
+   * Click Save
 
-4. [Create a Windows or Linux virtual machine](https://cloud.google.com/compute/docs/instances/create-start-instance).
+4. [Create a Windows or Linux virtual machine](https://cloud.google.com/compute/docs/access/create-enable-service-accounts-for-instances).
+   * Scroll down and start at Create a VM and attach the service account
+   * Click Go to VM instances
+   * Click Create Instance
+   * Enter a value for Name
+   * Configure Manage Tags and Labels
    * You can choose a region physically close to you though you may be limited in your choices if you want to use the free tier.
    * GAMADV-XTD3 can run on the minimal `e2-micro` [free tier VM](https://cloud.google.com/free/docs/free-cloud-features#compute) though performance may suffer. If you are performing batch operations, raising the CPU count will help performance. If you have a very large and busy Workspace instance downloading reports or Drive file lists may require more RAM.
-   * [DO NOT use the default service account](https://cloud.google.com/iam/docs/best-practices-service-accounts#single-purpose). Choose the service account you created above instead.
+   * Set Service account under Identity and AOI access
+   * Choose the service account you created above instead.
    * GAMADV-XTD3 does not use a significant amount of storage, unless you have specific storage needs the default disk size should suffice.
-   * leave other VM instance settings at their defaults unless you know what you are doing.
+   * Leave other VM instance settings at their defaults unless you know what you are doing.
+   * Click Create
 
 5. Install GAMADV-XTD3 on the VM
    * See: https://github.com/taers232c/GAMADV-XTD3/wiki/How-to-Install-Advanced-GAM

docs/Users-Gmail-Send-As-Signature-Vacation.md

@@ -210,11 +210,13 @@ gam config csv_output_row_filter "signature:boolean:false"
 
 ## Manage vacation
 ```
-gam <UserTypeEntity> vacation <Boolean> subject <String>
+gam <UserTypeEntity> vacation [<Boolean>] [subject <String>]
         [<VacationMessageContent> (replace <Tag> <UserReplacement>)*]
         [html [<Boolean>]] [contactsonly [<Boolean>]] [domainonly [<Boolean>]]
         [start|startdate <Date>|Started] [end|enddate <Date>|NotSpecified]
 ```
+The initial `<Boolean>` can be omitted to allow updates to other fields without affecting the current responder state.
+
 `<VacationMessageContent>` is the vacation message, there are four ways to specify it:
 * `message|textmessage|htmlmessage <String>` - Use `<String>` as the vacation message
 * `file|htmlfile <FileName> [charset <Charset>]` - Read the vacation message from `<FileName>`

docs/Version-and-Help.md

@@ -3,7 +3,7 @@
 Print the current version of Gam with details
 ```
 gam version
-GAMADV-XTD3 6.80.00 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
+GAMADV-XTD3 6.80.01 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
 Ross Scroggs <ross.scroggs@gmail.com>
 Python 3.12.4 64-bit final
 MacOS Sonoma 14.5 x86_64
@@ -15,7 +15,7 @@ Time: 2023-06-02T21:10:00-07:00
 Print the current version of Gam with details and time offset information
 ```
 gam version timeoffset
-GAMADV-XTD3 6.80.00 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
+GAMADV-XTD3 6.80.01 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
 Ross Scroggs <ross.scroggs@gmail.com>
 Python 3.12.4 64-bit final
 MacOS Sonoma 14.5 x86_64
@@ -27,7 +27,7 @@ Your system time differs from www.googleapis.com by less than 1 second
 Print the current version of Gam with extended details and SSL information
 ```
 gam version extended
-GAMADV-XTD3 6.80.00 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
+GAMADV-XTD3 6.80.01 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
 Ross Scroggs <ross.scroggs@gmail.com>
 Python 3.12.4 64-bit final
 MacOS Sonoma 14.5 x86_64
@@ -64,7 +64,7 @@ MacOS High Sierra 10.13.6 x86_64
 Path: /Users/Admin/bin/gamadv-xtd3
 Version Check:
   Current: 5.35.08
-   Latest: 6.80.00
+   Latest: 6.80.01
 echo $?
 1
 ```
@@ -72,7 +72,7 @@ echo $?
 Print the current version number without details
 ```
 gam version simple
-6.80.00
+6.80.01
 ```
 In Linux/MacOS you can do:
 ```
@@ -82,7 +82,7 @@ echo $VER
 Print the current version of Gam and address of this Wiki
 ```
 gam help
-GAM 6.80.00 - https://github.com/taers232c/GAMADV-XTD3
+GAM 6.80.01 - https://github.com/taers232c/GAMADV-XTD3
 Ross Scroggs <ross.scroggs@gmail.com>
 Python 3.12.4 64-bit final
 MacOS Sonoma 14.5 x86_64

src/GamCommands.txt

@@ -3148,6 +3148,7 @@ gam print course-works [todrive <ToDriveAttribute>*]
         (workids <CourseWorkIDEntity>)|((workstates <CourseWorkStateList>)*
         (orderby <CourseWorkOrderByFieldName> [ascending|descending])*)
         [showcreatoremails|creatoremail] [showtopicnames] [fields <CourseWorkFieldNameList>]
+        [showstudentsaslist [<Boolean>]] [delimiter <Character>]
         [formatjson [quotechar <Character>]]
         [timefilter creationtime|updatetime|scheduledtime] [start|starttime <Date>|<Time>] [end|endtime <Date>|<Time>]
 
@@ -7515,7 +7516,7 @@ gam <UserTypeEntity> show signature|sig [compact|format|html]
 gam <UserTypeEntity> print signature [compact]
         [primary|default] [verifyonly] [todrive <ToDriveAttribute>*]
 
-gam <UserTypeEntity> vacation <Boolean> subject <String>
+gam <UserTypeEntity> vacation [<Boolean>] [subject <String>]
         [<VacationMessageContent> (replace <Tag> <UserReplacement>)*]
         [html [<Boolean>]] [contactsonly [<Boolean>]] [domainonly [<Boolean>]]
         [start|startdate <Date>|Started] [end|enddate <Date>|NotSpecified]

src/GamUpdate.txt

@@ -2,6 +2,18 @@
 
 Merged GAM-Team version
 
+6.80.01
+
+Added options `showstudentsaslist [<Boolean>]` and `delimiter <Character>` to `gam print course-work`.
+By default, when course work is assigned to individual students, the student IDs are displayed in multiple indexed columns.
+Use these options to display the student IDs in a single column as a delimited list.
+
+Updated `gam <UserTypeEntity> vacation [<Boolean>]` to make `<Boolean>` optional; this allows changes
+to other fields without affecting the current responder state.
+
+Updated `gam <UserTypeEntity> print|show vacation` to avoid a trap when invalid start or end dates
+have been entered in the Gmail user interface. Invalid dates are represented as `1970-01-01`.
+
 6.80.00
 
 Fixed bug in `gam <UserTypeEntity> print users ... license ... formatjson` that caused a trap

src/gam/__init__.py

@@ -2344,9 +2344,12 @@ def formatLocalTimestampUTC(timestamp):
   return ISOformatTimeStamp(datetime.datetime.fromtimestamp(int(timestamp)//1000, iso8601.UTC))
 
 def formatLocalDatestamp(timestamp):
-  if not GC.Values[GC.OUTPUT_DATEFORMAT]:
-    return datetime.datetime.fromtimestamp(int(timestamp)//1000, GC.Values[GC.TIMEZONE]).strftime(YYYYMMDD_FORMAT)
-  return datetime.datetime.fromtimestamp(int(timestamp)//1000, GC.Values[GC.TIMEZONE]).strftime(GC.Values[GC.OUTPUT_DATEFORMAT])
+  try:
+    if not GC.Values[GC.OUTPUT_DATEFORMAT]:
+      return datetime.datetime.fromtimestamp(int(timestamp)//1000, GC.Values[GC.TIMEZONE]).strftime(YYYYMMDD_FORMAT)
+    return datetime.datetime.fromtimestamp(int(timestamp)//1000, GC.Values[GC.TIMEZONE]).strftime(GC.Values[GC.OUTPUT_DATEFORMAT])
+  except OverflowError:
+    return NEVER_DATE
 
 def formatMaxMessageBytes(maxMessageBytes, oneKiloBytes, oneMegaBytes):
   if maxMessageBytes < oneKiloBytes:
@@ -46935,7 +46938,8 @@ def doPrintCourseWM(entityIDType, entityStateType):
       topicId = courseWM.get('topicId')
       if topicId:
         courseWM['topicName'] = topicNames.get(topicId, topicId)
-    row = flattenJSON(courseWM, flattened={'courseId': course['id'], 'courseName': course['name']}, timeObjects=TimeObjects)
+    row = flattenJSON(courseWM, flattened={'courseId': course['id'], 'courseName': course['name']}, timeObjects=TimeObjects,
+                      simpleLists=['studentIds'] if showStudentsAsList else None, delimiter=delimiter)
     if not FJQC.formatJSON:
       csvPF.WriteRowTitles(row)
     elif csvPF.CheckRowTitles(row):
@@ -46980,6 +46984,8 @@ def doPrintCourseWM(entityIDType, entityStateType):
   OBY = OrderBy(OrderbyChoiceMap)
   creatorEmails = {}
   showCreatorEmail = showTopicNames = False
+  delimiter = GC.Values[GC.CSV_OUTPUT_FIELD_DELIMITER]
+  showStudentsAsList = False
   while Cmd.ArgumentsRemaining():
     myarg = getArgument()
     if myarg == 'todrive':
@@ -47000,6 +47006,10 @@ def doPrintCourseWM(entityIDType, entityStateType):
       showTopicNames = True
     elif getFieldsList(myarg, FieldsChoiceMap, fieldsList, initialField='id'):
       pass
+    elif myarg == 'showstudentsaslist':
+      showStudentsAsList = getBoolean()
+    elif myarg == 'delimiter':
+      delimiter = getCharacter()
     else:
       FJQC.GetFormatJSONQuoteChar(myarg, True)
   if showCreatorEmail and fieldsList:
@@ -47072,6 +47082,7 @@ def doPrintCourseMaterials():
 #	(workids <CourseWorkIDEntity>)|((workstates <CourseWorkStateList>)*
 #	(orderby <CourseWorkOrderByFieldName> [ascending|descending])*)
 #	[showcreatoremails|creatoremail] [showtopicnames] [fields <CourseWorkFieldNameList>] [formatjson [quotechar <Character>]]
+#	[showstudentsaslist [<Boolean>]] [delimiter <Character>]
 #	[timefilter creationtime|updatetime] [start|starttime <Date>|<Time>] [end|endtime <Date>|<Time>]
 def doPrintCourseWork():
   doPrintCourseWM(Ent.COURSE_WORK_ID, Ent.COURSE_WORK_STATE)
@@ -72101,13 +72112,14 @@ def _showVacation(user, i, count, result, showDisabled, sigReplyFormat):
       printKeyValueList(['Message', 'None'])
   Ind.Decrement()
 
-# gam <UserTypeEntity> vacation <Boolean> subject <String>
+# gam <UserTypeEntity> vacation [<Boolean>] [subject <String>]
 #	[<VacationMessageContent> (replace <Tag> <UserReplacement>)*]
 #	[html [<Boolean>]] [contactsonly [<Boolean>]] [domainonly [<Boolean>]]
 #	[start|startdate <Date>|Started] [end|enddate <Date>|NotSpecified]
 def setVacation(users):
-  enable = getBoolean(None)
-  body = {'enableAutoReply': enable}
+  body = {}
+  if Cmd.PeekArgumentPresent(TRUE_VALUES) or Cmd.PeekArgumentPresent(FALSE_VALUES):
+    body['enableAutoReply'] = getBoolean(None)
   responseBodyType = 'responseBodyPlainText'
   message = subject = None
   tagReplacements = _initTagReplacements()
@@ -72172,7 +72184,7 @@ def setVacation(users):
                         userId='me', body=oldBody)
       printEntity([Ent.USER, user, Ent.VACATION_ENABLED, result['enableAutoReply']], i, count)
     except (GAPI.invalidArgument, GAPI.failedPrecondition, GAPI.permissionDenied) as e:
-      entityActionFailedWarning([Ent.USER, user, Ent.VACATION_ENABLED, enable], str(e), i, count)
+      entityActionFailedWarning([Ent.USER, user, Ent.VACATION_ENABLED, oldBody['enableAutoReply']], str(e), i, count)
     except (GAPI.serviceNotAvailable, GAPI.badRequest):
       entityServiceNotApplicableWarning(Ent.USER, user, i, count)