Users Group Membership

Users - Group Membership

• Definitions
• Collections of Users
• Add users to groups
• Delete users from groups
• Delete external user from groups
• Update users group roles and delivery settings
• Synchronize users group membership
• Display users group membership
  • Display group details as an indented list
  • Display group details in CSV format
  • Display group counts as an indented list
  • Display group counts in CSV format
  • Display group addresses in CSV format

Definitions

<DeliverySetting> ::=
        allmail|
        abridged|daily|
        digest|
        disabled|
        none|nomail
<DomainName> ::= <String>(.<String>)+
<EmailAddress> ::= <String>@<DomainName>
<UniqueID> ::= uid:<String>
<GroupItem> ::= <EmailAddress>|<UniqueID>|<String>
<GroupList> ::= "<GroupItem>(,<GroupItem>)*"
<GroupEntity> ::= <GroupList> | <FileSelector> | <CSVkmdSelector> | <CSVDataSelector>
<GroupRole> ::= owner|manager|member
<GroupRoleList> ::= "<GroupRole>(,<GroupRole>)*"

Add users to groups

Add each user in <UserTypeEntity> to all of the groups specified by ([<GroupRole>] <GroupEntity>)+. If <GroupRole> is not specified, member is assumed.

gam <UserTypeEntity> add group|groups ([<GroupRole>] [[delivery] <DeliverySetting>] <GroupEntity>)+

Basic Example

$ gam user [email protected] add groups owner [email protected] manager [email protected] member [email protected],[email protected]
User: [email protected], Add to 4 Groups
  Group: [email protected], Owner: [email protected], Added (1/4)
  Group: [email protected], Manager: [email protected], Added (2/4)
  Group: [email protected], Member: [email protected], Added (3/4)
  Group: [email protected], Member: [email protected], Added (4/4)

Advanced Example

Use a CSV file to specify users, groups and roles.

# Desired state
$ more UserGroupRole.csv
User,Group,Role,Status,Delivery
[email protected],[email protected],OWNER,ACTIVE,DIGEST
[email protected],[email protected],MANAGER,ACTIVE,DAILY
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],MANAGER,ACTIVE,ALL_MAIL
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],OWNER,ACTIVE,NONE

# Current state
$ gam csvkmd users UserGroupRole.csv keyfield User print groups
User,Group,Role,Status,Delivery

# Add users to groups
$ gam redirect stdout - multiprocess csv UserGroupRole.csv gam user ~User add group ~Role ~Delivery ~Group
Using 5 processes...
User: [email protected], Add to 1 Group
  Group: [email protected], Owner: [email protected], Added
User: [email protected], Add to 1 Group
  Group: [email protected], Member: [email protected], Added
User: [email protected], Add to 1 Group
  Group: [email protected], Member: [email protected], Added
User: [email protected], Add to 1 Group
  Group: [email protected], Member: [email protected], Added
User: [email protected], Add to 1 Group
  Group: [email protected], Manager: [email protected], Added
User: [email protected], Add to 1 Group
  Group: [email protected], Member: [email protected], Added
User: [email protected], Add to 1 Group
  Group: [email protected], Manager: [email protected], Added
User: [email protected], Add to 1 Group
  Group: [email protected], Owner: [email protected], Added

# Final state
$ gam csvkmd users UserGroupRole.csv keyfield User print groups
User,Group,Role,Status,Delivery
[email protected],[email protected],OWNER,ACTIVE,DIGEST
[email protected],[email protected],MANAGER,ACTIVE,DAILY
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],MANAGER,ACTIVE,ALL_MAIL
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],OWNER,ACTIVE,NONE

Delete users from groups

Delete each user in <UserTypeEntity> from all of the groups specified by <GroupEntity>. If <GroupEntity> is not specified, the user will be deleted from all groups of which it is a member.

gam <UserTypeEntity> delete|del group|groups [<GroupEntity>]

Basic Example

$ gam user [email protected] delete groups
User: [email protected], Delete from 4 Groups
  Group: [email protected], Member: [email protected], Deleted (1/4)
  Group: [email protected], Member: [email protected], Deleted (2/4)
  Group: [email protected], Member: [email protected], Deleted (3/4)
  Group: [email protected], Member: [email protected], Deleted (4/4)

Advanced Example

Use a CSV file to specify users and groups.

# Current state
$ gam csvkmd users UserGroupRole.csv keyfield User print groups
User,Group,Role,Status,Delivery
[email protected],[email protected],OWNER,ACTIVE,DIGEST
[email protected],[email protected],MANAGER,ACTIVE,DAILY
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],MANAGER,ACTIVE,ALL_MAIL
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],OWNER,ACTIVE,NONE

# Delete users from groups
$ gam csvkmd users UserGroupRole.csv keyfield User delete groups
User: [email protected], Delete from 4 Groups (1/3)
  Group: [email protected], Member: [email protected], Deleted (1/4)
  Group: [email protected], Member: [email protected], Deleted (2/4)
  Group: [email protected], Member: [email protected], Deleted (3/4)
  Group: [email protected], Member: [email protected], Deleted (4/4)
User: [email protected], Delete from 2 Groups (2/3)
  Group: [email protected], Member: [email protected], Deleted (1/2)
  Group: [email protected], Member: [email protected], Deleted (2/2)
User: [email protected], Delete from 2 Groups (3/3)
  Group: [email protected], Member: [email protected], Deleted (1/2)
  Group: [email protected], Member: [email protected], Deleted (2/2)

# Final state
$ gam csvkmd users UserGroupRole.csv keyfield User print groups
User,Group,Role,Status,Delivery

Delete external user from groups

There is a user from outside of your domain that you would like to delete from all groups.

$ gam user [email protected] delete groups
User: [email protected], Delete from 0 Groups

There is a Goggle issue that causes this to fail for a few external addresses. To solve this problem, you need the unique ID for the external address; the following steps show how to do this.

Create a test group.

$ gam create group testexternal description "Test External Email Addresses"
Group: [email protected], Created

Add the external address to that group.

$ gam update group testexternal add member [email protected]
Group: [email protected], Add 1 Member
  Group: [email protected], Member: [email protected], Added: Role: MEMBER

Print the group members of the group to get the unique ID of the external address.

$ gam print group-members group testexternal
Getting all Members, Managers, Owners for [email protected]
group,type,role,id,status,email
[email protected],USER,MEMBER,123406166545652215678,,[email protected]

Delete the external address from all groups.

$ gam user uid:123406166545652215678 delete groups
User: 123406166545652215678, Delete from 2 Groups
  Group: [email protected], Member: 123406166545652215678, Deleted (1/2)
  Group: [email protected], Member: 123406166545652215678, Deleted (2/2)

Update users group roles and delivery settings

For each user in <UserTypeEntity> update their current group role and delivery settings.

gam <UserTypeEntity> update groups ([<GroupRole>] [[delivery] <DeliverySetting>] <GroupEntity>)+

Example

# Current state
$ gam csvkmd users UserGroupRole.csv keyfield User print groups
User,Group,Role,Status,Delivery
[email protected],[email protected],OWNER,ACTIVE,DIGEST
[email protected],[email protected],MANAGER,ACTIVE,DAILY
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],MANAGER,ACTIVE,ALL_MAIL
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],OWNER,ACTIVE,NONE

# Desired changes
$ more UserGroupRoleNew.csv
User,Group,Role,Status,Delivery
[email protected],[email protected],OWNER,ACTIVE,DIGEST
[email protected],[email protected],MANAGER,ACTIVE,DAILY
[email protected],[email protected],OWNER,ACTIVE,DIGEST

# Update roles/delivery settings
$ gam redirect stdout - multiprocess csv UserGroupRoleNew.csv gam user ~User update group ~Role ~Delivery ~Group
Using 3 processes...
User: [email protected], Update to 1 Group
  Group: [email protected], Manager: [email protected], Updated
User: [email protected], Update to 1 Group
  Group: [email protected], Owner: [email protected], Updated
User: [email protected], Update to 1 Group
  Group: [email protected], Owner: [email protected], Updated

# Final state
$ gam csvkmd users UserGroupRole.csv keyfield User print groups
User,Group,Role,Status,Delivery
[email protected],[email protected],OWNER,ACTIVE,DIGEST
[email protected],[email protected],OWNER,ACTIVE,DIGEST
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],MANAGER,ACTIVE,DAILY
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],OWNER,ACTIVE,DIGEST

Synchronize users group membership

For each user in <UserTypeEntity> get their current group membership and do adds and deletes as necessary to match ([<GroupRole>] <GroupEntity>)+. If <GroupRole> is not specified, member is assumed.

gam <UserTypeEntity> sync group|groups ([<GroupRole>] <GroupEntity>)+

Basic Example

# Current state
$ gam user [email protected] print groups
User,Group,Role
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL

# Update membership
$ gam user [email protected] sync groups owner [email protected] manager [email protected] member [email protected],[email protected]
User: [email protected], Remove from 1 Group
  Group: [email protected], Member: [email protected], Removed
User: [email protected], Add to 1 Group
  Group: [email protected], Owner: [email protected], Added
User: [email protected], Update in 1 Group
  Group: [email protected], Manager: [email protected], Updated

# Final state
$ gam user [email protected] print groups
User,Group,Role
[email protected],[email protected],OWNER,ACTIVE,ALL_MAIL
[email protected],[email protected],MANAGER,ACTIVE,ALL_MAIL
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL

Advanced Example

# Current state
$ gam csvkmd users UserGroupRole.csv keyfield User print groups
User,Group,Role,Status,Delivery
[email protected],[email protected],OWNER,ACTIVE,ALL_MAIL
[email protected],[email protected],MANAGER,ACTIVE,ALL_MAIL
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL

# Desired state
$ more UserGroupRole.csv
User,Group,Role,Status,Delivery
[email protected],[email protected],OWNER,ACTIVE,DIGEST
[email protected],[email protected],MANAGER,ACTIVE,DAILY
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],MANAGER,ACTIVE,ALL_MAIL
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],OWNER,ACTIVE,NONE

# Update membership
$ gam csvkmd users UserGroupRole.csv keyfield User subkeyfield Role datafield Group sync groups csvdata Group
User: [email protected], Remove from 1 Group (1/3)
  Group: [email protected], Member: [email protected], Removed
User: [email protected], Update to 1 Group (2/3)
  Group: [email protected], Manager: [email protected], Updated
User: [email protected], Add to 1 Group (3/3)
  Group: [email protected], Owner: [email protected], Added

# Intermediate state
$ gam csvkmd users UserGroupRole.csv keyfield User print groups
User,Group,Role,Status,Delivery
[email protected],[email protected],OWNER,ACTIVE,ALL_MAIL
[email protected],[email protected],MANAGER,ACTIVE,ALL_MAIL
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],MANAGER,ACTIVE,ALL_MAIL
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],OWNER,ACTIVE,ALL_MAIL

# Update roles/delivery settings
$ gam redirect stdout - multiprocess csv UserGroupRole.csv gam user ~User update group ~Role ~Delivery ~Group
Using 5 processes...
User: [email protected], Update to 1 Group
  Group: [email protected], Member: [email protected], Updated
User: [email protected], Update to 1 Group
  Group: [email protected], Member: [email protected], Updated
User: [email protected], Update to 1 Group
  Group: [email protected], Member: [email protected], Updated
User: [email protected], Update to 1 Group
  Group: [email protected], Manager: [email protected], Updated
User: [email protected], Update to 1 Group
  Group: [email protected], Owner: [email protected], Updated
User: [email protected], Update to 1 Group
  Group: [email protected], Member: [email protected], Updated
User: [email protected], Update to 1 Group
  Group: [email protected], Manager: [email protected], Updated
User: [email protected], Update to 1 Group
  Group: [email protected], Owner: [email protected], Updated

# Final state
$ gam csvkmd users UserGroupRole.csv keyfield User print groups
User,Group,Role,Status,Delivery
[email protected],[email protected],OWNER,ACTIVE,DIGEST
[email protected],[email protected],MANAGER,ACTIVE,DAILY
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],MANAGER,ACTIVE,ALL_MAIL
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],OWNER,ACTIVE,NONE

Display users group membership

It takes one API call to get the list of groups to which a user belongs and one API call per group to get the user's role and delivery settings.

Display group details as an indented list

There is one row per group to which a user belongs showing role, status and delivery information.

gam <UserTypeEntity> show groups [roles <GroupRoleList>] [domain <DomainName>]

Display group details in CSV format

There is one row per user/group combination displaying role, status and delivery information.

gam <UserTypeEntity> print groups [roles <GroupRoleList>] [domain <DomainName>]
        [todrive <ToDriveAttributes>*]

By default, all groups to which a member belongs are displayed, these options allow selection of subsets of groups:

• roles <GroupRoleList> - Limit display to those groups for which the user has a specific role
• domain <DomainName> - Limit display to groups in the domain <DomainName>

Display group counts as an indented list

There is one row per user displaying the number of groups, by role, to which a user belongs.

gam <UserTypeEntity> show groups [roles <GroupRoleList>] [domain <DomainName>]
        countsonly

Display group counts in CSV format

There is one row per user displaying the number of groups, by role, to which a user belongs.

gam <UserTypeEntity> print groups [roles <GroupRoleList>] [domain <DomainName>]
        countsonly [todrive <ToDriveAttributes>*]

By default, all groups to which a member belongs are displayed, these options allow selection of subsets of groups:

• roles <GroupRoleList> - Limit display to those groups for which the user has a specific role
• domain <DomainName> - Limit display to groups in the domain <DomainName>

Display group addresses in CSV format

There is one row per user showing the number and list of groups to which a user directly belongs.

gam <UserTypeEntity> print groupslist [domain <DomainName>] [todrive <ToDriveAttribute>*]
        [delimiter <Character>] [quotechar <Character>]

By default, all groups to which a member belongs are displayed, these options allow selection of subsets of groups:

• domain <DomainName> - Limit display to groups in the domain <DomainName>

By default, the entries in lists of groups are separated by the csv_output_field_delimiter' from gam.cfg`.

• delimiter <Character> - Separate list items with <Character>

By default, when writing CSV files, Gam uses a quote character of double quote ". The quote character is used to enclose columns that contain the quote character itself, the column delimiter (comma by default) and new-line characters. Any quote characters within the column are doubled. The quotechar <Character> option allows you to choose an alternate quote character, single quote for instance, that makes for readable/processable output. quotechar defaults to gam.cfg/csv_output_quote_char. When uploading CSV files to Google, double quote " should be used.

Examples

$ gam user [email protected] show groups
User: [email protected], Show 4 Groups
  Group: [email protected], Role: OWNER, Status: ACTIVE, Delivery: DIGEST (1/4)
  Group: [email protected], Role: MANAGER, Status: ACTIVE, Delivery: DAILY (2/4)
  Group: [email protected], Role: MEMBER, Status: ACTIVE, Delivery: ALL_MAIL (3/4)
  Group: [email protected], Role: MEMBER, Status: ACTIVE, Delivery: ALL_MAIL (4/4)

$ gam user [email protected] print groups
User,Group,Role,Status,Delivery
[email protected],[email protected],OWNER,ACTIVE,DIGEST
[email protected],[email protected],MANAGER,ACTIVE,DAILY
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL
[email protected],[email protected],MEMBER,ACTIVE,ALL_MAIL

$ gam csvkmd users UserGroupRole.csv keyfield User show groups role owner
User: [email protected], Show maximum of 4 Groups (1/3)
  Group: [email protected], Role: OWNER, Status: ACTIVE, Delivery: DIGEST (1/4)
User: [email protected], Show maximum of 2 Groups (2/3)
User: [email protected], Show maximum of 2 Groups (3/3)
  Group: [email protected], Role: OWNER, Status: ACTIVE, Delivery: NONE (2/2)

$ gam csvkmd users UserGroupRole.csv keyfield User print groups role owner
User,Group,Role,Status,Delivery
[email protected],[email protected],OWNER,ACTIVE,DIGEST
[email protected],[email protected],OWNER,ACTIVE,NONE

$ gam users testuser1,testuser2 show groups domain domain.net
User: [email protected], Show maximum of 2 Groups (1/2)
  Group: [email protected], Role: MEMBER (1/2)
  Group: [email protected], Role: MEMBER (2/2)
User: [email protected], Show maximum of 0 Groups (2/2)

$ gam users testuser1,testuser2 print groups domain domain.net
User,Group,Role
[email protected],[email protected],MEMBER
[email protected],[email protected],MEMBER

$ gam users testuser1,testuser2 print groupslist
Getting all Groups for [email protected] (1/2)
Getting all Groups for [email protected] (2/2)
User,Groups,GroupsList
[email protected],6,[email protected] [email protected] [email protected] [email protected] [email protected] [email protected]
[email protected],0,

$ gam config csv_output_row_filter "Groups:count=0" users testuser1,testuser2 print groupslist
Getting all Groups for [email protected] (1/2)
Getting all Groups for [email protected] (2/2)
User,Groups,GroupsList
[email protected],0,