Added option name <CIPolicyName> to gam print|show policies

docs/Basic-Items.md

@@ -1,4 +1,4 @@
-!# Basic Items
+# Basic Items
 - [Primitives](#primitives)
 - [Items built from primitives](#items-built-from-primitives)
 - [Named items](#named-items)
@@ -274,14 +274,15 @@
         <EmailAddress>|user:<EmailAddress>|group:<EmailAddress>|
         domain:<DomainName>|domain|default
 <CalendarItem> ::= <EmailAddress>
-<GIGroupAlias> ::= <EmailAddress>
-<GIGroupItem> ::= <EmailAddress>|<UniqueID>|groups/<String>
-<CIGroupType> ::= customer|group|other|serviceaccount|user
 <ChannelCustomerID> ::= <String>
 <ChatMember> ::= spaces/<String>/members/<String>
 <ChatMessage> ::= spaces/<String>/messages/<String>
 <ChatSpace> ::= spaces/<String> | space <String> | space spaces/<String>
 <ChatThread> ::= spaces/<String>/threads/<String>
+<GIGroupAlias> ::= <EmailAddress>
+<GIGroupItem> ::= <EmailAddress>|<UniqueID>|groups/<String>
+<CIGroupType> ::= customer|group|other|serviceaccount|user
+<CIPolicyName> ::= policies/<String>
 <ClassroomInvitationID> ::= <String>
 <ClientID> ::= <String>
 <CommandID> ::= <String>
@@ -533,6 +534,7 @@
         (tdnotify [<Boolean>])|
         (tdparent (id:<DriveFolderID>)|<DriveFolderName>)|
         (tdretaintitle [<Boolean>])|
+        (tdreturnidonly [<Boolean>])|
         (tdshare <EmailAddress> commenter|reader|writer)*|
         (tdsheet (id:<Number>)|<String>)|
         (tdsheettimestamp [<Boolean>] [tdsheettimeformat <String>])

docs/Cloud-Identity-Policies.md

@@ -1,12 +1,13 @@
 # Cloud Identity Policies
 - [API documentation](#api-documentation)
 - [Notes](#notes)
+- [Definitions](#definitions)
 - [Policies](#policies)
 - [Display Cloud Identity Policies](#display-cloud-identity-policies)
 
 ## API documentation
 * https://cloud.google.com/identity/docs/concepts/overview-policies
-* https://cloud.google.com/identity/docs/reference/rest/v1beta1/policies
+* https://cloud.google.com/identity/docs/reference/rest/v1beta1/policies/list
 
 ## Notes
 To use these commands you must update your client access authentication.
@@ -16,6 +17,11 @@ gam oauth create
 [*] 19)  Cloud Identity - Policy
 ```
 
+## Definitions
+```
+<CIPolicyName> ::= policies/<String>
+```
+
 ## Policies
 These are the supported policies GAM can show today.
 ```
@@ -300,17 +306,26 @@ workspace_marketplace.apps_allowlist
 ```
 ## Display Cloud Identity Policies
 ```
-gam show policies (query <String>) [nowarnings]
+gam show policies
+        [(filter <String>)|(name <CIPolicyName>)] [nowarnings]
         [formatjson]
 ```
+By default, all policies are displayed.
+* `filter <String>` - Display filtered policies, See https://github.com/taers232c/GAMADV-XTD3/wiki/Cloud-Identity-Policies
+* `name <CIPolicyName>` - Display a specfic policy
+
 By default, Gam displays the information as an indented list of keys and values.
 * `formatjson` - Display the fields in JSON format.
 
 ```
 gam print policies [todrive <ToDriveAttribute>*]
-        (query <String>) [nowarnings]
+        [(filter <String>)|(name <CIPolicyName>)] [nowarnings]
         [formatjson [quotechar <Character>]]
 ```
+By default, all policies are displayed:
+* `filter <String>` - Display filtered policies, See https://github.com/taers232c/GAMADV-XTD3/wiki/Cloud-Identity-Policies
+* `name <CIPolicyName>` - Display a specfic policy
+
 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,11 +10,16 @@ Add the `-s` option to the end of the above commands to suppress creating the `g
 
 See [Downloads-Installs-GAM7](https://github.com/GAM-team/GAM/wiki/Downloads-Installs) for Windows or other options, including manual installation
 
-7.00.28
+### 7.00.29
+
+Added option `name <CIPolicyName>` to `gam print|show policies` that displays
+information about a specific policy.
+
+### 7.00.28
 
 Fixed issue that caused `gam print/show policies` to fail on some group policies.
 
-7.00.27
+### 7.00.27
 
 Updated `gam <UserTypeEntity> collect orphans` and all commands that print file paths to recognize
 that a file owned by a user that has no parents is not an orphan if `sharedWithMeTime` is set.
@@ -24,12 +29,11 @@ user A's access to the folder.
 Added commands to display Cloud Identity policies.
 ```
 gam print policies [todrive <ToDriveAttribute>*]
-        (query <String>) [nowarnings]
+        (filter <String>) [nowarnings]
         [formatjson [quotechar <Character>]]
-gam show policies (query <String>) [nowarnings]
+gam show policies (filter <String>) [nowarnings]
         [formatjson]
 ```
-
 ### 7.00.26
 
 Updated `drive_dir` in `gam.cfg` to allow the value `.` that causes `redirect csv|stdout|stderr <FileName>`

docs/How-to-Upgrade-Legacy-GAM-to-GAM7.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
-GAM 7.00.26 - https://github.com/GAM-team/GAM - pyinstaller
+GAM 7.00.29 - https://github.com/GAM-team/GAM - pyinstaller
 GAM Team <google-apps-manager@googlegroups.com>
 Python 3.13.0 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
-GAM7 7.00.26 - https://github.com/GAM-team/GAM - pythonsource
+GAM7 7.00.29 - https://github.com/GAM-team/GAM - pythonsource
 GAM Team <google-apps-manager@googlegroups.com>
 Python 3.13.0 64-bit final
 Windows-10-10.0.17134 AMD64

docs/List-Items.md

@@ -1,4 +1,4 @@
-!# List Items
+# List Items
 - [Lists of basic items](#lists-of-basic-items)
 - [List quoting rules](#list-quoting-rules)
 - [Basic Items](Basic-Items)

docs/Version-and-Help.md

@@ -3,7 +3,7 @@
 Print the current version of Gam with details
 ```
 gam version
-GAM 7.00.26 - https://github.com/GAM-team/GAM - pyinstaller
+GAM 7.00.29 - https://github.com/GAM-team/GAM - pyinstaller
 GAM Team <google-apps-manager@googlegroups.com>
 Python 3.13.0 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
-GAM 7.00.26 - https://github.com/GAM-team/GAM - pyinstaller
+GAM 7.00.29 - https://github.com/GAM-team/GAM - pyinstaller
 GAM Team <google-apps-manager@googlegroups.com>
 Python 3.13.0 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
-GAM 7.00.26 - https://github.com/GAM-team/GAM - pyinstaller
+GAM 7.00.29 - https://github.com/GAM-team/GAM - pyinstaller
 GAM Team <google-apps-manager@googlegroups.com>
 Python 3.13.0 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/gam7
 Version Check:
   Current: 5.35.08
-   Latest: 7.00.26
+   Latest: 7.00.29
 echo $?
 1
 ```
@@ -72,7 +72,7 @@ echo $?
 Print the current version number without details
 ```
 gam version simple
-7.00.26
+7.00.29
 ```
 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 7.00.26 - https://github.com/GAM-team/GAM
+GAM 7.00.29 - https://github.com/GAM-team/GAM
 GAM Team <google-apps-manager@googlegroups.com>
 Python 3.13.0 64-bit final
 MacOS Sonoma 14.5 x86_64

src/GamCommands.txt

@@ -370,14 +370,15 @@ If an item contains spaces, it should be surrounded by ".
         <EmailAddress>|user:<EmailAddress>|group:<EmailAddress>|
         domain:<DomainName>|domain|default
 <CalendarItem> ::= <EmailAddress>
-<GIGroupAlias> ::= <EmailAddress>
-<GIGroupItem> ::= <EmailAddress>|<UniqueID>|groups/<String>
-<CIGroupType> ::= customer|group|other|serviceaccount|user
 <ChannelCustomerID> ::= <String>
 <ChatMember> ::= spaces/<String>/members/<String>
 <ChatMessage> ::= spaces/<String>/messages/<String>
 <ChatSpace> ::= spaces/<String> | space <String> | space spaces/<String>
 <ChatThread> ::= spaces/<String>/threads/<String>
+<GIGroupAlias> ::= <EmailAddress>
+<GIGroupItem> ::= <EmailAddress>|<UniqueID>|groups/<String>
+<CIGroupType> ::= customer|group|other|serviceaccount|user
+<CIPolicyName> ::= policies/<String>
 <ClassroomInvitationID> ::= <String>
 <ClientID> ::= <String>
 <CommandID> ::= <String>
@@ -487,6 +488,8 @@ If an item contains spaces, it should be surrounded by ".
 <Marker> ::= <String>
 <MatterItem> ::= <UniqueID>|<String>
 <MatterState> ::= open|closed|deleted
+<MeetConferenceName> ::= conferenceRecords/<String>
+<MeetSpaceName> ::= spaces/<String> | <String>
 <MessageContent> ::=
         (message|textmessage|htmlmessage <String>)|
         (file|textfile|htmlfile <FileName> [charset <Charset>])|
@@ -4070,9 +4073,10 @@ gam update deviceuserstate <DeviceUserEntity> [clientid <String>]
 # Cloud Identity Policies
 
 gam print policies [todrive <ToDriveAttribute>*]
-        (query <String>) [nowarnings]
+        [(filter <String>)|(name <CIPolicyName>)] [nowarnings]
         [formatjson [quotechar <Character>]]
-gam show policies (query <String>) [nowarnings]
+gam show policies
+        [(filter <String>)|(name <CIPolicyName>)] [nowarnings]
         [formatjson]
 
 # Inbound SSO

src/GamUpdate.txt

@@ -1,3 +1,8 @@
+7.00.29
+
+Added option `name <CIPolicyName>` to `gam print|show policies` that displays
+information about a specific policy.
+
 7.00.28
 
 Fixed issue that caused `gam print/show policies` to fail on some group policies.
@@ -12,9 +17,9 @@ user A's access to the folder.
 Added commands to display Cloud Identity policies.
 ```
 gam print policies [todrive <ToDriveAttribute>*]
-        (query <String>) [nowarnings]
+        (filter <String>) [nowarnings]
         [formatjson [quotechar <Character>]]
-gam show policies (query <String>) [nowarnings]
+gam show policies (filter <String>) [nowarnings]
         [formatjson]
 ```
 

src/gam/__init__.py

@@ -25,7 +25,7 @@ https://github.com/GAM-team/GAM/wiki
 """
 
 __author__ = 'GAM Team <google-apps-manager@googlegroups.com>'
-__version__ = '7.00.28'
+__version__ = '7.00.29'
 __license__ = 'Apache License 2.0 (http://www.apache.org/licenses/LICENSE-2.0)'
 
 #pylint: disable=wrong-import-position
@@ -35090,11 +35090,12 @@ def updateFieldsForCIGroupMatchPatterns(matchPatterns, fieldsList, csvPF=None):
 CIPOLICY_TIME_OBJECTS = {'createTime', 'updateTime'}
 
 # gam print policies [todrive <ToDriveAttribute>*]
-#	(query <String>) [nowarnings]
+#	[(filter <String>)|(name <PolicyName>)]  [nowarnings]
 #	[formatjson [quotechar <Character>]]
-# gam show policies (query <String>) [nowarnings]
+# gam show policies
+#	[(filter <String>)|(name <PolicyName>)]  [nowarnings]
 #	[formatjson]
-def doPrintCIPolicies():
+def doPrintShowCIPolicies():
 
   def _showPolicy(policy, FJQC, i=0, count=0):
     if FJQC is not None and FJQC.formatJSON:
@@ -35106,7 +35107,8 @@ def doPrintCIPolicies():
     Ind.Increment()
     policy.pop('name')
     showJSON(None, policy, timeObjects=CIPOLICY_TIME_OBJECTS)
-    printBlankLine()
+    if not pname:
+      printBlankLine()
     Ind.Decrement()
 
   def _printPolicy(policy):
@@ -35131,8 +35133,7 @@ def doPrintCIPolicies():
   cd = buildGAPIObject(API.DIRECTORY)
   csvPF = CSVPrintFile(['name']) if Act.csvFormat() else None
   FJQC = FormatJSONQuoteChar(csvPF)
-  fields = 'nextPageToken,policies(name,policyQuery(group,orgUnit,sortOrder),type,setting)'
-  ifilter = None
+  ifilter = pname = None
   add_warnings = True
   while Cmd.ArgumentsRemaining():
     myarg = getArgument()
@@ -35140,25 +35141,37 @@ def doPrintCIPolicies():
       csvPF.GetTodriveParameters()
     elif myarg == 'filter':
       ifilter = getString(Cmd.OB_STRING)
+    elif myarg == 'name':
+      pname = getString(Cmd.OB_STRING)
     elif myarg == 'nowarnings':
       add_warnings = False
     else:
       FJQC.GetFormatJSONQuoteChar(myarg, True)
-  printGettingAllAccountEntities(Ent.POLICY, ifilter)
-  pageMessage = getPageMessage()
-  throwReasons = [GAPI.INVALID, GAPI.INVALID_ARGUMENT, GAPI.PERMISSION_DENIED]
-  try:
-    policies = callGAPIpages(ci.policies(),
-                             'list',
-                             'policies',
-                             throwReasons=throwReasons,
-                             pageMessage=pageMessage,
-                             filter=ifilter,
-                             fields=fields,
-                             pageSize=100)
-  except (GAPI.invalid, GAPI.invalidArgument, GAPI.permissionDenied) as e:
-    entityActionFailedWarning([Ent.POLICY, None], str(e))
-    return
+  if ifilter and pname:
+    usageErrorExit(Msg.ARE_MUTUALLY_EXCLUSIVE.format('filter', 'name'))
+  throwReasons = [GAPI.INVALID, GAPI.INVALID_ARGUMENT, GAPI.PERMISSION_DENIED, GAPI.INTERNAL_ERROR]
+  fields = 'name,policyQuery(group,orgUnit,sortOrder),type,setting'
+  if not pname:
+    printGettingAllAccountEntities(Ent.POLICY, ifilter)
+    pageMessage = getPageMessage()
+    try:
+      policies = callGAPIpages(ci.policies(), 'list', 'policies',
+                               throwReasons=throwReasons,
+                               pageMessage=pageMessage,
+                               filter=ifilter,
+                               fields=f'nextPageToken,policies({fields})',
+                               pageSize=100)
+    except (GAPI.invalid, GAPI.invalidArgument, GAPI.permissionDenied) as e:
+      entityActionFailedExit([Ent.POLICY, None], str(e))
+  else:
+    try:
+      policies = [callGAPI(ci.policies(), 'get',
+                           bailOnInternalError=True,
+                           throwReasons=throwReasons,
+                           name=pname,
+                           fields=fields)]
+    except (GAPI.invalid, GAPI.invalidArgument, GAPI.permissionDenied, GAPI.internalError) as e:
+      entityActionFailedExit([Ent.POLICY, pname], str(e))
   # Google returns unordered results, sort them by setting type
   policies = sorted(policies, key=lambda p: p.get('setting', {}).get('type', ''))
   for policy in policies:
@@ -75199,7 +75212,7 @@ MAIN_COMMANDS_WITH_OBJECTS = {
       Cmd.ARG_CHROMEVERSIONS:	doPrintShowChromeVersions,
       Cmd.ARG_CIGROUP:		doPrintCIGroups,
       Cmd.ARG_CIGROUPMEMBERS:	doPrintCIGroupMembers,
-      Cmd.ARG_CIPOLICIES:	doPrintCIPolicies,
+      Cmd.ARG_CIPOLICIES:	doPrintShowCIPolicies,
       Cmd.ARG_CLASSROOMINVITATION:	doPrintShowClassroomInvitations,
       Cmd.ARG_CONTACT:		doPrintShowDomainContacts,
       Cmd.ARG_COURSE:		doPrintCourses,
@@ -75328,7 +75341,7 @@ MAIN_COMMANDS_WITH_OBJECTS = {
       Cmd.ARG_CHROMESCHEMA:	doPrintShowChromeSchemas,
       Cmd.ARG_CHROMEVERSIONS:	doPrintShowChromeVersions,
       Cmd.ARG_CIGROUPMEMBERS:	doShowCIGroupMembers,
-      Cmd.ARG_CIPOLICIES:	doPrintCIPolicies,
+      Cmd.ARG_CIPOLICIES:	doPrintShowCIPolicies,
       Cmd.ARG_CLASSROOMINVITATION:	doPrintShowClassroomInvitations,
       Cmd.ARG_CONTACT:		doPrintShowDomainContacts,
       Cmd.ARG_CROSTELEMETRY:	doInfoPrintShowCrOSTelemetry,

src/gam/gamlib/glapi.py

@@ -369,8 +369,8 @@ _CLIENT_SCOPES = [
   {'name': 'Cloud Identity - Policy',
    'api': CLOUDIDENTITY_POLICY,
    'subscopes': READONLY,
-   'scope': 'https://www.googleapis.com/auth/cloud-identity.policies',
    'roByDefault': True,
+   'scope': 'https://www.googleapis.com/auth/cloud-identity.policies'
   },
   {'name': 'Cloud Identity User Invitations API',
    'api': CLOUDIDENTITY_USERINVITATIONS,