Added option onlyusers <UserTypeEntity> to gam <UserTypeEntity> claim ownership <DriveFileEntity>`

docs/GamUpdates.md

@@ -10,6 +10,12 @@ Add the `-s` option to the end of the above commands to suppress creating the `g
 
 See [Downloads](https://github.com/taers232c/GAMADV-XTD3/wiki/Downloads) for Windows or other options, including manual installation
 
+### 6.77.05
+
+Added option `onlyusers <UserTypeEntity>` to gam <UserTypeEntity> claim ownership <DriveFileEntity>`
+that causes GAM to only claim ownership of files/folders owned by `onlyusers <UserTypeEntity>`.
+This option is multually exclusive with `skipusers <UserTypeEntity>`.
+
 ### 6.77.04
 
 Fixed bug in `gam report users ... range <Date> <Date>` where an extraneous API call

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

@@ -335,7 +335,7 @@ writes the credentials into the file oauth2.txt.
 admin@server:/Users/admin/bin/gamadv-xtd3$ rm -f /Users/admin/GAMConfig/oauth2.txt
 admin@server:/Users/admin/bin/gamadv-xtd3$ ./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.77.04 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
+GAMADV-XTD3 6.77.05 - 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
@@ -1009,7 +1009,7 @@ writes the credentials into the file oauth2.txt.
 C:\GAMADV-XTD3>del C:\GAMConfig\oauth2.txt
 C:\GAMADV-XTD3>gam version
 WARNING: Config File: C:\GAMConfig\gam.cfg, Section: DEFAULT, Item: oauth2_txt, Value: C:\GAMConfig\oauth2.txt, Not Found
-GAMADV-XTD3 6.77.04 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
+GAMADV-XTD3 6.77.05 - 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/Other-Resources.md

@@ -9,7 +9,7 @@ Thank you.
 * Gabriel Clifton - https://docs.google.com/document/d/1p32QOBTr89GaG7RfCafSbFuhlUQ9r3qBM_666E0xvQM/edit
 * Goldy Arora - https://www.goldyarora.com/license-notifier/
 * Iain Macleod - https://docs.google.com/document/d/1QxWAPdhROcx70OXLpSD9Trh3vs-nJKSMiaMZCTwOOTg/edit?pli=1#heading=h.2a2azzpy36k0
-* James Seymour - https://sites.google.com/jis.edu.bn/gam-commands/home
+* James Seymour - https://sites.google.com/view/gam--commands/
 * Kevin Melillo - https://github.com/KevinMelilloIEEE/gam-script
 * Korey Rideout - https://chatgpt.com/g/g-PTxxnVPMG-gam-assist - A helpful tool to assist with, GAM (+Advance) and GYB commands to assist with syntax for Google Workspace Administrators.
 * Paul Ogier (Taming.Tech) - GAMADV-XTD3 Course on Udemy https://taming.tech/GAMCourse

docs/Users-Drive-Ownership.md

@@ -92,7 +92,7 @@ point to control the students further access to the files.
 ```
 gam <UserTypeEntity> claim ownership <DriveFileEntity>
         [<DriveFileParentAttribute>] [includetrashed]
-        [skipids <DriveFileEntity>] [skipusers <UserTypeEntity>] [subdomains <DomainNameEntity>]
+        [skipids <DriveFileEntity>] [onlyusers|skipusers <UserTypeEntity>] [subdomains <DomainNameEntity>]
         [restricted [<Boolean>]] [writerscanshare|writerscantshare [<Boolean>]]
         [keepuser | (retainrole reader|commenter|writer|editor|none)] [noretentionmessages]
         (orderby <DriveOrderByFieldName> [ascending|descending])*
@@ -107,8 +107,11 @@ By default, files in the trash are not transferred.
 Specify order of file processing.
 * `(orderby <DriveOrderByFieldName> [ascending|descending])*`
 
-These options handle special cases where you want to prevent ownership from being transferred for selected files/folders.
+This option handles special cases where you want to prevent ownership from being transferred for selected files/folders.
 * `skipids <DriveFileEntity>` - Do not transfer ownership for files/folders with the specified IDs.
+
+These mutually exclusive  options handle special cases where you want to prevent ownership from being transferred based on the current file/folder owner.
+* `onlyusers <UserTypeEntity>` - Only transfer ownership for files/folders owned by the specified users.
 * `skipusers <UserTypeEntity>` - Do not transfer ownership for files/folders owned by the specified users.
 
 By default, only files owned by users in the same domain as the claiming user have their ownership transferred.

docs/Version-and-Help.md

@@ -3,7 +3,7 @@
 Print the current version of Gam with details
 ```
 gam version
-GAMADV-XTD3 6.77.04 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
+GAMADV-XTD3 6.77.05 - 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.77.04 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
+GAMADV-XTD3 6.77.05 - 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.77.04 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
+GAMADV-XTD3 6.77.05 - 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.77.04
+   Latest: 6.77.05
 echo $?
 1
 ```
@@ -72,7 +72,7 @@ echo $?
 Print the current version number without details
 ```
 gam version simple
-6.77.04
+6.77.05
 ```
 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.77.04 - https://github.com/taers232c/GAMADV-XTD3
+GAM 6.77.05 - 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

@@ -6696,7 +6696,7 @@ gam <UserTypeEntity> transfer ownership <DriveFileEntity> <UserItem>
         [todrive <ToDriveAttribute>*]
 gam <UserTypeEntity> claim ownership <DriveFileEntity>
         [<DriveFileParentAttribute>] [includetrashed]
-        [skipids <DriveFileEntity>] [skipusers <UserTypeEntity>] [subdomains <DomainNameEntity>]
+        [skipids <DriveFileEntity>] [onlyusers|skipusers <UserTypeEntity>] [subdomains <DomainNameEntity>]
         [restricted [<Boolean>]] [writerscanshare|writerscantshare [<Boolean>]]
         [keepuser | (retainrole commenter|reader|writer|editor|fileorganizer|none)] [noretentionmessages]
         (orderby <DriveFileOrderByFieldName> [ascending|descending])*

src/GamUpdate.txt

@@ -13,6 +13,12 @@ where `date` is the earliest date for which report data was requested.
 
 Merged GAM-Team version
 
+6.77.05
+
+Added option `onlyusers <UserTypeEntity>` to gam <UserTypeEntity> claim ownership <DriveFileEntity>`
+that causes GAM to only claim ownership of files/folders owned by `onlyusers <UserTypeEntity>`.
+This option is multually exclusive with `skipusers <UserTypeEntity>`.
+
 6.77.04
 
 Fixed bug in `gam report users ... range <Date> <Date>` where an extraneous API call
@@ -29,6 +35,17 @@ Thanks to jay, added the following Colab License SKUs:
 Thanks to Jay, updated `gam print|show admins` to properly display addresses
 of service accounts with admin role assignments.
 
+Added option `limitdatechanges <Integer>` to `gam report users|customers`.
+
+If no report is available for the specified date, can an earlier date be used?
+* `limitdatechanges -1' - Back up to earlier dates to find report data; this is the default.
+* `limitdatechanges 0 | nodatechange' - Do not report on an earlier date if no report data is available for the specified date.
+* `limitdatechanges N' - Back up to earlier dates to find report data; do not back up more than N times.
+
+By default, when `gam report user user <UserItem>` is specified and no report data is available, there is no output.
+If `csv_output_users_audit = true` in `gam.cfg`, then a row with columns `email,date` will be displayed
+where `date` is the earliest date for which report data was requested.
+
 6.77.02
 
 Cleaned up problems with some of the new Chat API asadmin commands.
@@ -69,7 +86,7 @@ gam <UserItem> info chatmember asadmin
 gam <UserItem> print|show chatmembers|asadmin
 ```
 
-* See: https://github.com/taers232c/GAMADV-XTD3/wiki/Users-Chat
+* See: https://github.com/taers232c/GAMADV-XTD3/wiki/Users-Chat#developer-preview-admin-access
 
 Added `use_chat_admin_access` Boolean variable to `gam.cfg`. 
 ```

src/gam/__init__.py

@@ -60805,7 +60805,7 @@ def transferOwnership(users):
 
 # gam <UserTypeEntity> claim ownership <DriveFileEntity>
 #	[<DriveFileParentAttribute>] [includetrashed]
-#	[skipids <DriveFileEntity>] [skipusers <UserTypeEntity>] [subdomains <DomainNameEntity>]
+#	[skipids <DriveFileEntity>] [onlyUsers|skipusers <UserTypeEntity>] [subdomains <DomainNameEntity>]
 #	[restricted [<Boolean>]] [writerscanshare|writerscantshare [<Boolean>]]
 #	[keepuser | (retainrole reader|commenter|writer|editor|none)] [noretentionmessages]
 #	(orderby <DriveFileOrderByFieldName> [ascending|descending])*
@@ -60822,7 +60822,7 @@ def claimOwnership(users):
         childEntryInfo = childEntry['info']
         if includeTrashed or not childEntryInfo['trashed']:
           owner = childEntryInfo['owners'][0]['emailAddress']
-          if not childEntryInfo['ownedByMe'] and owner not in skipusers:
+          if (not childEntryInfo['ownedByMe']) and ((not checkOwner) or (checkOnly and owner in onlyOwners) or (checkSkip and owner not in skipOwners)):
             oldOwnerPermissionIds[owner] = childEntryInfo['owners'][0]['permissionId']
             filesToClaim.setdefault(owner, {})
             if childFileId not in filesToClaim[owner]:
@@ -60850,7 +60850,7 @@ def claimOwnership(users):
         if filepath:
           fileTree[childFileId] = {'info': childEntryInfo}
         owner = childEntryInfo['owners'][0]['emailAddress']
-        if not childEntryInfo['ownedByMe'] and owner not in skipusers:
+        if (not childEntryInfo['ownedByMe']) and ((not checkOwner) or (checkOnly and owner in onlyOwners) or (checkSkip and owner not in skipOwners)):
           oldOwnerPermissionIds[owner] = childEntryInfo['owners'][0]['permissionId']
           filesToClaim.setdefault(owner, {})
           if childFileId not in filesToClaim[owner]:
@@ -60885,7 +60885,9 @@ def claimOwnership(users):
   skipFileIdEntity = initDriveFileEntity()
   OBY = OrderBy(DRIVEFILE_ORDERBY_CHOICE_MAP)
   body = {}
-  skipusers = []
+  checkOnly = checkSkip = False
+  onlyOwners = set()
+  skipOwners = set()
   subdomains = []
   filepath = includeTrashed = False
   pathDelimiter = '/'
@@ -60908,8 +60910,14 @@ def claimOwnership(users):
       showRetentionMessages = False
     elif myarg == 'skipids':
       skipFileIdEntity = getDriveFileEntity()
+    elif myarg == 'onlyusers':
+      _, userList = getEntityToModify(defaultEntityType=Cmd.ENTITY_USERS)
+      checkOnly = True
+      onlyOwners = set(userList)
     elif myarg == 'skipusers':
-      _, skipusers = getEntityToModify(defaultEntityType=Cmd.ENTITY_USERS)
+      _, userList = getEntityToModify(defaultEntityType=Cmd.ENTITY_USERS)
+      checkSkip = len(userList) > 0
+      skipOwners = set(userList)
     elif myarg == 'subdomains':
       subdomains = getEntityList(Cmd.OB_DOMAIN_NAME_ENTITY)
     elif myarg == 'includetrashed':
@@ -60936,6 +60944,9 @@ def claimOwnership(users):
       changeParents = True
     else:
       unknownArgumentExit()
+  if checkOnly and checkSkip:
+    usageErrorExit(Msg.ARE_MUTUALLY_EXCLUSIVE.format('onlyusers', 'skipusers'))
+  checkOwner = checkOnly or checkSkip
   Act.Set(Act.CLAIM_OWNERSHIP)
   if csvPF:
     if filepath:
@@ -61020,7 +61031,7 @@ def claimOwnership(users):
       filesTransferred.add(fileId)
       if fileId not in skipFileIdEntity['list'] and (includeTrashed or not fileEntryInfo['trashed']):
         owner = fileEntryInfo['owners'][0]['emailAddress']
-        if not fileEntryInfo['ownedByMe'] and owner not in skipusers:
+        if (not fileEntryInfo['ownedByMe']) and ((not checkOwner) or (checkOnly and owner in onlyOwners) or (checkSkip and owner not in skipOwners)):
           oldOwnerPermissionIds[owner] = fileEntryInfo['owners'][0]['permissionId']
           filesToClaim.setdefault(owner, {})
           if fileId not in filesToClaim[owner]: