Skip to content

Commit

Permalink
Updated transfer calendars to manipulate calendar lists
Browse files Browse the repository at this point in the history
  • Loading branch information
taers232c committed May 19, 2024
1 parent 2b711be commit 7de9e98
Show file tree
Hide file tree
Showing 7 changed files with 114 additions and 32 deletions.
8 changes: 8 additions & 0 deletions docs/GamUpdates.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,14 @@ 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.76.05

Added options `deletefromoldowner`, `addtonewowner <CalendarAttribute>*` and `nolistmessages`
to `gam <UserTypeEntity> transfer calendars <UserItem>` that allow manipulation of the
source and target user's calendar lists.

* See: https://github.com/taers232c/GAMADV-XTD3/wiki/Users-Calendars-Access#transfer-calendar-ownership

### 6.76.04

Added the following fields to `<CrOSFieldName>`:
Expand Down
4 changes: 2 additions & 2 deletions docs/How-to-Upgrade-from-Standard-GAM.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.76.04 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
GAMADV-XTD3 6.76.05 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
Ross Scroggs <ross.scroggs@gmail.com>
Python 3.12.3 64-bit final
MacOS Sonoma 14.4.1 x86_64
Expand Down Expand Up @@ -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.76.04 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
GAMADV-XTD3 6.76.05 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
Ross Scroggs <ross.scroggs@gmail.com>
Python 3.12.3 64-bit final
Windows-10-10.0.17134 AMD64
Expand Down
31 changes: 27 additions & 4 deletions docs/Users-Calendars-Access.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,17 @@ Calendar ACL roles (as seen in Calendar GUI):
<UniqueID> ::= id:<String>
<UserItem> ::= <EmailAddress>|<UniqueID>|<String>
<CalendarAttribute> ::=
(backgroundcolor <ColorValue>)|
(color <CalendarColorName>)|
(colorindex|colorid <CalendarColorIndex>)|
(foregroundcolor <ColorValue>)|
(hidden <Boolean>)|
(notification clear|(email <CalendarEmailNotificatonEventTypeList>))|
(reminder clear|(email|pop <Number>)|(<Number> email|pop))|
(selected <Boolean>)|
(summary <String>)
<CalendarSettings> ::=
(description <String>)|
(location <String>)|
Expand Down Expand Up @@ -134,27 +145,39 @@ The `quotechar <Character>` option allows you to choose an alternate quote chara
## Transfer calendar ownership

You can transfer ownership of calendars from one user to another; only non-primary calendars owned by the source user can be transferred.
You can update calendar settings as part of the transfer. In description, location and summary, #email#, #user# and #username# will be replaced
by the original owner's full email address or just the name portion; #timestamp# will be replaced by the current date and time.
```
gam <UserTypeEntity> transfer calendars <UserItem> <UserCalendarEntity>
gam <UserTypeEntity> transfer calendars|seccals <UserItem> [<UserCalendarEntity>]
[keepuser | (retainrole <CalendarACLRole>)] [sendnotifications <Boolean>]
[noretentionmessages]
[<CalendarSettings>] [append description|location|summary] [noupdatemessages]
gam <UserTypeEntity> transfer seccals <UserItem> [keepuser] [sendnotifications <Boolean>]
[deletefromoldowner] [addtonewowner <CalendarAttribute>*] [nolistmessages]
```
If `<UserCalendarEntity>` is not specified, all of a user's owned secondary calendars will be transferrdd.

By default, the users in `<UserTypeEntity>` retain no role in the transferred calendars.
* `keepuser` - The users in `<UserTypeEntity>` retain their ownership.
* `retainrole <CalendarACLRole>` - The users in `<UserTypeEntity>` retain the specified role.
* `noretentionmessages` - Suppress the original owner role retention messages.

By default, when you add or update a calendar ACL, a notification is sent to the affected users; use `sendnotifications false` to suppress sending the notifications.

You can update calendar settings as part of the transfer. In description, location and summary, #email#, #user# and #username# will be replaced
by the original owner's full email address or just the name portion; #timestamp# will be replaced by the current date and time.
* `<CalendarSettings>` - The value specified will replace the existing value.
* `append description|location|summary` - The specified <CalendarSettings> value will be appended to the existing value.
* `noupdatemessages` - Suppress the settings update messages.

You can manipulate the old and new owner's calendar lists.
* `deletefromoldowner` - Delete the calendar from the old owner's calendar list
* `addtonewowner <CalendarAttribute>*` - Add the calendar to the new owner's calendar list; optionally specify attributes
* `nolistmessages` - Suppress the calendar list add/delete messages.

### Example
Transfer a secondary calendar from oldowner to newowner. Remove the calendar from the old owner's calendar list and add to the new owner's calendar list.
```
gam user oldowner@domain.com transfer calendars newowner@domain.com c_aaa123zzz@group.calendar.google.com removefromoldowner addtonewowner
```

Transfer ownership of all non-primary calendars from oldowner to newowner; append a message to the calendar description noting the old owner and the time of transfer.
```
gam user oldowner@domain.com transfer calendars newowner@domain.com minaccessrole owner description "(Transferred from #user# on #timestamp#)" append description
Expand Down
12 changes: 6 additions & 6 deletions docs/Version-and-Help.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
Print the current version of Gam with details
```
gam version
GAMADV-XTD3 6.76.04 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
GAMADV-XTD3 6.76.05 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
Ross Scroggs <ross.scroggs@gmail.com>
Python 3.12.3 64-bit final
MacOS Sonoma 14.4.1 x86_64
Expand All @@ -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.76.04 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
GAMADV-XTD3 6.76.05 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
Ross Scroggs <ross.scroggs@gmail.com>
Python 3.12.3 64-bit final
MacOS Sonoma 14.4.1 x86_64
Expand All @@ -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.76.04 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
GAMADV-XTD3 6.76.05 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
Ross Scroggs <ross.scroggs@gmail.com>
Python 3.12.3 64-bit final
MacOS Sonoma 14.4.1 x86_64
Expand Down Expand Up @@ -64,15 +64,15 @@ MacOS High Sierra 10.13.6 x86_64
Path: /Users/Admin/bin/gamadv-xtd3
Version Check:
Current: 5.35.08
Latest: 6.76.04
Latest: 6.76.05
echo $?
1
```

Print the current version number without details
```
gam version simple
6.76.04
6.76.05
```
In Linux/MacOS you can do:
```
Expand All @@ -82,7 +82,7 @@ echo $VER
Print the current version of Gam and address of this Wiki
```
gam help
GAM 6.76.04 - https://github.com/taers232c/GAMADV-XTD3
GAM 6.76.05 - https://github.com/taers232c/GAMADV-XTD3
Ross Scroggs <ross.scroggs@gmail.com>
Python 3.12.3 64-bit final
MacOS Sonoma 14.4.1 x86_64
Expand Down
8 changes: 4 additions & 4 deletions src/GamCommands.txt
Original file line number Diff line number Diff line change
Expand Up @@ -5701,12 +5701,12 @@ gam <UserTypeEntity> print calendaracls <UserCalendarEntity> [todrive <ToDriveAt
[noselfowner] (addcsvdata <FieldName> <String>)*
[formatjson [quotechar <Character>]]

Transfer ownership of a selection of users calendars to another user
Transfer ownership of a selection of a users secondary calendars to another user

gam <UserTypeEntity> transfer calendars <UserItem> <UserCalendarEntity>
gam <UserTypeEntity> transfer calendars|seccals <UserItem> [<UserCalendarEntity>]
[keepuser | (retainrole <CalendarACLRole>)] [sendnotifications <Boolean>] [noretentionmessages]
<CalendarSettings>] [append description|location|summary] [noupdatemessages]
gam <UserTypeEntity> transfer seccals <UserItem> [keepuser] [sendnotifications <Boolean>]
<CalendarSettings>* [append description|location|summary] [noupdatemessages]
[deletefromoldowner] [addtonewowner <CalendarAttribute>*] [nolistmessages]

<AttendeeAttendance> ::= optional|required
<AttendeeStatus> ::= accepted|declined|needsaction|tentative
Expand Down
8 changes: 8 additions & 0 deletions src/GamUpdate.txt
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,14 @@

Merged GAM-Team version

6.76.05

Added options `deletefromoldowner`, `addtonewowner <CalendarAttribute>*` and `nolistmessages`
to `gam <UserTypeEntity> transfer calendars <UserItem>` that allow manipulation of the
old and new owners's calendar lists.

* See: https://github.com/taers232c/GAMADV-XTD3/wiki/Users-Calendars-Access#transfer-calendar-ownership

6.76.04

Added the following fields to `<CrOSFieldName>`:
Expand Down
75 changes: 59 additions & 16 deletions src/gam/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -48357,8 +48357,7 @@ def _validateUserGetCalendarIds(user, i, count, calendarEntity,
'agenda': 'agenda',
}

def _getCalendarAttributes(body):
colorRgbFormat = False
def _getCalendarAttributes(body, returnOnUnknownArgument=False):
while Cmd.ArgumentsRemaining():
myarg = getArgument()
if myarg == 'selected':
Expand All @@ -48374,10 +48373,8 @@ def _getCalendarAttributes(body):
elif myarg in {'backgroundcolor', 'backgroundcolour'}:
body['backgroundColor'] = getColor()
body.setdefault('foregroundColor', '#000000')
colorRgbFormat = True
elif myarg in {'foregroundcolor', 'foregroundcolour'}:
body['foregroundColor'] = getColor()
colorRgbFormat = True
elif myarg == 'reminder':
body.setdefault('defaultReminders', [])
if not checkArgumentPresent(Cmd.CLEAR_NONE_ARGUMENT):
Expand All @@ -48394,9 +48391,11 @@ def _getCalendarAttributes(body):
invalidChoiceExit(ntype, CALENDAR_NOTIFICATION_TYPES_MAP, True)
else:
body['notificationSettings']['notifications'] = []
elif returnOnUnknownArgument:
Cmd.Backup()
return
else:
unknownArgumentExit()
return colorRgbFormat

def _showCalendar(calendar, j, jcount, FJQC, acls=None):
if FJQC.formatJSON:
Expand Down Expand Up @@ -48453,11 +48452,12 @@ def _processCalendarList(user, calId, j, jcount, cal, function, **kwargs):
GAPI.cannotChangeOwnAcl, GAPI.cannotChangeOwnPrimarySubscription) as e:
entityActionFailedWarning([Ent.USER, user, Ent.CALENDAR, calId], str(e), j, jcount)

# gam <UserTypeEntity> add calendars <UserCalendarAddEntity> <CalendarAttribute>
# gam <UserTypeEntity> add calendars <UserCalendarAddEntity> <CalendarAttribute>*
def addCalendars(users):
calendarEntity = getUserCalendarEntity()
body = {'selected': True, 'hidden': False}
colorRgbFormat = _getCalendarAttributes(body)
_getCalendarAttributes(body)
colorRgbFormat = 'backgroundColor' in body or 'foregroundColor' in body
i, count, users = getEntityArgument(users)
for user in users:
i += 1
Expand Down Expand Up @@ -48489,11 +48489,12 @@ def _updateDeleteCalendars(users, calendarEntity, function, **kwargs):
calendarId=calId, **kwargs)
Ind.Decrement()

# gam <UserTypeEntity> update calendars <UserCalendarEntity> <CalendarAttribute>
# gam <UserTypeEntity> update calendars <UserCalendarEntity> <CalendarAttribute>+
def updateCalendars(users):
calendarEntity = getUserCalendarEntity()
body = {}
colorRgbFormat = _getCalendarAttributes(body)
_getCalendarAttributes(body)
colorRgbFormat = 'backgroundColor' in body or 'foregroundColor' in body
_updateDeleteCalendars(users, calendarEntity, 'patch', body=body, colorRgbFormat=colorRgbFormat, fields='')

# gam <UserTypeEntity> delete calendars <UserCalendarEntity>
Expand Down Expand Up @@ -48923,18 +48924,20 @@ def printShowCalendarACLs(users):

TRANSFER_CALENDAR_APPEND_FIELDS = ['description', 'location', 'summary']

# gam <UserTypeEntity> transfer calendars <UserItem> <UserCalendarEntity>
# gam <UserTypeEntity> transfer calendars|seccals <UserItem> [<UserCalendarEntity>]
# [keepuser | (retainrole <CalendarACLRole>)] [sendnotifications <Boolean>] [noretentionmessages]
# [<CalendarSettings>] [append description|location|summary] [noupdatemessages]
# gam <UserTypeEntity> transfer seccals <UserItem> [keepuser] [sendnotifications <Boolean>]
# <CalendarSettings>* [append description|location|summary] [noupdatemessages]
# [deletefromoldowner] [addtonewowner <CalendarAttribute>*] [nolistmessages]
def transferCalendars(users):
targetUser = getEmailAddress()
calendarEntity = getUserCalendarEntity(noSelectionKwargs={'minAccessRole': 'owner', 'showHidden': True})
notAllowedForbidden = Msg.FORBIDDEN if (not calendarEntity['all']) and (not calendarEntity.get('kwargs', {}).get('minAccessRole', '') == 'owner') else Msg.NOT_ALLOWED
retainRoleBody = {'role': 'none'}
sendNotifications = showUpdateMessages = showRetentionMessages = True
sendNotifications = showListMessages = showRetentionMessages = showUpdateMessages = True
updateBody = {}
appendFieldsList = []
addToNewOwner = deleteFromOldOwner = False
targetListBody = {'selected': True, 'hidden': False}
while Cmd.ArgumentsRemaining():
myarg = getArgument()
if myarg == 'keepuser':
Expand All @@ -48943,8 +48946,6 @@ def transferCalendars(users):
retainRoleBody['role'] = getChoice(CALENDAR_ACL_ROLES_MAP, mapChoice=True)
elif myarg == 'sendnotifications':
sendNotifications = getBoolean()
elif myarg == 'noretentionmessages':
showRetentionMessages = False
elif _getCalendarSetting(myarg, updateBody):
pass
elif myarg == 'append':
Expand All @@ -48953,13 +48954,25 @@ def transferCalendars(users):
appendFieldsList.append(field)
else:
invalidChoiceExit(field, TRANSFER_CALENDAR_APPEND_FIELDS, True)
elif myarg == 'nolistmessages':
showListMessages = False
elif myarg == 'noretentionmessages':
showRetentionMessages = False
elif myarg == 'noupdatemessages':
showUpdateMessages = False
elif myarg == 'deletefromoldowner':
deleteFromOldOwner = True
elif myarg == 'addtonewowner':
addToNewOwner = True
_getCalendarAttributes(targetListBody, returnOnUnknownArgument=True)
else:
unknownArgumentExit()
targetUser, targetCal = validateCalendar(targetUser)
if not targetCal:
return
colorRgbFormat = 'backgroundColor' in targetListBody or 'foregroundColor' in targetListBody
if 'summaryOverride' in targetListBody and 'summary' not in updateBody:
updateBody['summary'] = targetListBody.pop('summaryOverride')
if updateBody:
timestamp = currentISOformatTimeStamp('seconds')
appendFields = ','.join(set(appendFieldsList))
Expand Down Expand Up @@ -48992,7 +49005,7 @@ def transferCalendars(users):
calendarId=calId, body=targetRoleBody, sendNotifications=sendNotifications, fields='')
entityModifierNewValueItemValueListActionPerformed([Ent.CALENDAR, calId], Act.MODIFIER_TO, None, [Ent.USER, targetUser], j, jcount)
except (GAPI.forbidden, GAPI.requiredAccessLevel) as e:
entityActionFailedWarning([Ent.CALENDAR, calId], str(e), j, jcount)
entityActionFailedWarning([Ent.USER, user, Ent.CALENDAR, calId], str(e), j, jcount)
continue
except (GAPI.notFound, GAPI.invalid):
entityUnknownWarning(Ent.CALENDAR, calId, j, jcount)
Expand Down Expand Up @@ -49024,6 +49037,19 @@ def transferCalendars(users):
entityActionFailedWarning([Ent.CALENDAR, calId], str(e), j, jcount)
except (GAPI.serviceNotAvailable, GAPI.authError):
entityServiceNotApplicableWarning(Ent.CALENDAR, calId, j, jcount)
if addToNewOwner:
Act.Set(Act.ADD)
targetListBody['id'] = calId
try:
callGAPI(targetCal.calendarList(), 'insert',
throwReasons=[GAPI.NOT_FOUND, GAPI.DUPLICATE, GAPI.UNKNOWN_ERROR, GAPI.SERVICE_NOT_AVAILABLE,
GAPI.CANNOT_CHANGE_OWN_ACL, GAPI.CANNOT_CHANGE_OWN_PRIMARY_SUBSCRIPTION],
body=targetListBody, colorRgbFormat=colorRgbFormat, fields='')
if showListMessages:
entityModifierNewValueItemValueListActionPerformed([Ent.CALENDAR, calId], Act.MODIFIER_TO, None, [Ent.USER, targetUser], j, jcount)
except (GAPI.notFound, GAPI.duplicate, GAPI.unknownError, GAPI.serviceNotAvailable,
GAPI.cannotChangeOwnAcl, GAPI.cannotChangeOwnPrimarySubscription) as e:
entityActionFailedWarning([Ent.CALENDAR, calId], str(e), j, jcount)
Act.Set(Act.RETAIN)
if retainRoleBody['role'] == 'owner':
if showRetentionMessages:
Expand Down Expand Up @@ -49052,6 +49078,23 @@ def transferCalendars(users):
entityActionPerformed([Ent.CALENDAR, calId, Ent.CALENDAR_ACL, formatACLScopeRole(sourceRuleId, retainRoleBody['role'])], j, jcount)
except (GAPI.notFound, GAPI.invalid):
entityUnknownWarning(Ent.CALENDAR, calId, j, jcount)
if deleteFromOldOwner:
Act.Set(Act.DELETE)
try:
callGAPI(sourceCal.calendarList(), 'delete',
throwReasons=[GAPI.NOT_FOUND, GAPI.DUPLICATE, GAPI.UNKNOWN_ERROR, GAPI.SERVICE_NOT_AVAILABLE,
GAPI.CANNOT_CHANGE_OWN_ACL, GAPI.CANNOT_CHANGE_OWN_PRIMARY_SUBSCRIPTION],
calendarId=calId)
entityModifierNewValueItemValueListActionPerformed([Ent.CALENDAR, calId], Act.MODIFIER_FROM, None, [Ent.USER, user], j, jcount)
except GAPI.notFound as e:
if retainRoleBody['role'] == 'none':
if showListMessages:
entityModifierNewValueItemValueListActionPerformed([Ent.CALENDAR, calId], Act.MODIFIER_FROM, None, [Ent.USER, user], j, jcount)
else:
entityActionFailedWarning([Ent.CALENDAR, calId], str(e), j, jcount)
except (GAPI.duplicate, GAPI.unknownError, GAPI.serviceNotAvailable,
GAPI.cannotChangeOwnAcl, GAPI.cannotChangeOwnPrimarySubscription) as e:
entityActionFailedWarning([Ent.CALENDAR, calId], str(e), j, jcount)
Ind.Decrement()

def _createImportCalendarEvent(users, function):
Expand Down

0 comments on commit 7de9e98

Please sign in to comment.