Users Group Membership

Users - Group Membership

• Definitions
• Collections of Users
• Add users to groups
• Delete users from groups
• Update users group roles and delivery settings
• Synchronize users group membership
• Display users group membership

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 testuser1@domain.com add groups owner testgroup1@domain.com manager testgroup2@domain.com member testgroup3@domain.com,testgroup4@domain.com
User: testuser1@domain.com, Add to 4 Groups
  Group: testgroup1@domain.com, Owner: testuser1@domain.com, Added (1/4)
  Group: testgroup2@domain.com, Manager: testuser1@domain.com, Added (2/4)
  Group: testgroup3@domain.com, Member: testuser1@domain.com, Added (3/4)
  Group: testgroup4@domain.com, Member: testuser1@domain.com, 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
testuser1@domain.com,testgroup1@domain.com,OWNER,ACTIVE,DIGEST
testuser1@domain.com,testgroup2@domain.com,MANAGER,ACTIVE,DAILY
testuser1@domain.com,testgroup3@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser1@domain.com,testgroup4@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser2@domain.com,testgroup1@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser2@domain.com,testgroup2@domain.com,MANAGER,ACTIVE,ALL_MAIL
testuser3@domain.com,testgroup1@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser3@domain.com,testgroup2@domain.com,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: testuser1@domain.com, Add to 1 Group
  Group: testgroup1@domain.com, Owner: testuser1@domain.com, Added
User: testuser1@domain.com, Add to 1 Group
  Group: testgroup4@domain.com, Member: testuser1@domain.com, Added
User: testuser2@domain.com, Add to 1 Group
  Group: testgroup1@domain.com, Member: testuser2@domain.com, Added
User: testuser1@domain.com, Add to 1 Group
  Group: testgroup3@domain.com, Member: testuser1@domain.com, Added
User: testuser1@domain.com, Add to 1 Group
  Group: testgroup2@domain.com, Manager: testuser1@domain.com, Added
User: testuser3@domain.com, Add to 1 Group
  Group: testgroup1@domain.com, Member: testuser3@domain.com, Added
User: testuser2@domain.com, Add to 1 Group
  Group: testgroup2@domain.com, Manager: testuser2@domain.com, Added
User: testuser3@domain.com, Add to 1 Group
  Group: testgroup2@domain.com, Owner: testuser3@domain.com, Added

# Final state
$ gam csvkmd users UserGroupRole.csv keyfield User print groups
User,Group,Role,Status,Delivery
testuser1@domain.com,testgroup1@domain.com,OWNER,ACTIVE,DIGEST
testuser1@domain.com,testgroup2@domain.com,MANAGER,ACTIVE,DAILY
testuser1@domain.com,testgroup3@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser1@domain.com,testgroup4@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser2@domain.com,testgroup1@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser2@domain.com,testgroup2@domain.com,MANAGER,ACTIVE,ALL_MAIL
testuser3@domain.com,testgroup1@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser3@domain.com,testgroup2@domain.com,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 testuser1@domain.com delete groups
User: testuser1@domain.com, Delete from 4 Groups
  Group: testgroup1@domain.com, Member: testuser1@domain.com, Deleted (1/4)
  Group: testgroup2@domain.com, Member: testuser1@domain.com, Deleted (2/4)
  Group: testgroup3@domain.com, Member: testuser1@domain.com, Deleted (3/4)
  Group: testgroup4@domain.com, Member: testuser1@domain.com, 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
testuser1@domain.com,testgroup1@domain.com,OWNER,ACTIVE,DIGEST
testuser1@domain.com,testgroup2@domain.com,MANAGER,ACTIVE,DAILY
testuser1@domain.com,testgroup3@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser1@domain.com,testgroup4@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser2@domain.com,testgroup1@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser2@domain.com,testgroup2@domain.com,MANAGER,ACTIVE,ALL_MAIL
testuser3@domain.com,testgroup1@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser3@domain.com,testgroup2@domain.com,OWNER,ACTIVE,NONE

# Delete users from groups
$ gam csvkmd users UserGroupRole.csv keyfield User delete groups
User: testuser1@domain.com, Delete from 4 Groups (1/3)
  Group: testgroup1@domain.com, Member: testuser1@domain.com, Deleted (1/4)
  Group: testgroup2@domain.com, Member: testuser1@domain.com, Deleted (2/4)
  Group: testgroup3@domain.com, Member: testuser1@domain.com, Deleted (3/4)
  Group: testgroup4@domain.com, Member: testuser1@domain.com, Deleted (4/4)
User: testuser2@domain.com, Delete from 2 Groups (2/3)
  Group: testgroup1@domain.com, Member: testuser2@domain.com, Deleted (1/2)
  Group: testgroup2@domain.com, Member: testuser2@domain.com, Deleted (2/2)
User: testuser3@domain.com, Delete from 2 Groups (3/3)
  Group: testgroup1@domain.com, Member: testuser3@domain.com, Deleted (1/2)
  Group: testgroup2@domain.com, Member: testuser3@domain.com, Deleted (2/2)

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

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
testuser1@domain.com,testgroup1@domain.com,OWNER,ACTIVE,DIGEST
testuser1@domain.com,testgroup2@domain.com,MANAGER,ACTIVE,DAILY
testuser1@domain.com,testgroup3@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser1@domain.com,testgroup4@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser2@domain.com,testgroup1@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser2@domain.com,testgroup2@domain.com,MANAGER,ACTIVE,ALL_MAIL
testuser3@domain.com,testgroup1@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser3@domain.com,testgroup2@domain.com,OWNER,ACTIVE,NONE

# Desired changes
$ more UserGroupRoleNew.csv
User,Group,Role,Status,Delivery
testuser1@domain.com,testgroup2@domain.com,OWNER,ACTIVE,DIGEST
testuser2@domain.com,testgroup2@domain.com,MANAGER,ACTIVE,DAILY
testuser3@domain.com,testgroup2@domain.com,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: testuser2@domain.com, Update to 1 Group
  Group: testgroup2@domain.com, Manager: testuser2@domain.com, Updated
User: testuser3@domain.com, Update to 1 Group
  Group: testgroup2@domain.com, Owner: testuser3@domain.com, Updated
User: testuser1@domain.com, Update to 1 Group
  Group: testgroup2@domain.com, Owner: testuser1@domain.com, Updated

# Final state
$ gam csvkmd users UserGroupRole.csv keyfield User print groups
User,Group,Role,Status,Delivery
testuser1@domain.com,testgroup1@domain.com,OWNER,ACTIVE,DIGEST
testuser1@domain.com,testgroup2@domain.com,OWNER,ACTIVE,DIGEST
testuser1@domain.com,testgroup3@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser1@domain.com,testgroup4@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser2@domain.com,testgroup1@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser2@domain.com,testgroup2@domain.com,MANAGER,ACTIVE,DAILY
testuser3@domain.com,testgroup1@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser3@domain.com,testgroup2@domain.com,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 testuser1@domain.com print groups
User,Group,Role
testuser1@domain.com,testgroup2@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser1@domain.com,testgroup3@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser1@domain.com,testgroup4@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser1@domain.com,testgroup5@domain.com,MEMBER,ACTIVE,ALL_MAIL

# Update membership
$ gam user testuser1@domain.com sync groups owner testgroup1@domain.com manager testgroup2@domain.com member testgroup3@domain.com,testgroup4@domain.com
User: testuser1@domain.com, Remove from 1 Group
  Group: testgroup5@domain.com, Member: testuser1@domain.com, Removed
User: testuser1@domain.com, Add to 1 Group
  Group: testgroup1@domain.com, Owner: testuser1@domain.com, Added
User: testuser1@domain.com, Update in 1 Group
  Group: testgroup2@domain.com, Manager: testuser1@domain.com, Updated

# Final state
$ gam user testuser1@domain.com print groups
User,Group,Role
testuser1@domain.com,testgroup1@domain.com,OWNER,ACTIVE,ALL_MAIL
testuser1@domain.com,testgroup2@domain.com,MANAGER,ACTIVE,ALL_MAIL
testuser1@domain.com,testgroup3@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser1@domain.com,testgroup4@domain.com,MEMBER,ACTIVE,ALL_MAIL

Advanced Example

# Current state
$ gam csvkmd users UserGroupRole.csv keyfield User print groups
User,Group,Role,Status,Delivery
testuser1@domain.com,testgroup1@domain.com,OWNER,ACTIVE,ALL_MAIL
testuser1@domain.com,testgroup2@domain.com,MANAGER,ACTIVE,ALL_MAIL
testuser1@domain.com,testgroup3@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser1@domain.com,testgroup4@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser1@domain.com,testgroup5@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser2@domain.com,testgroup1@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser2@domain.com,testgroup2@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser3@domain.com,testgroup1@domain.com,MEMBER,ACTIVE,ALL_MAIL

# Desired state
$ more UserGroupRole.csv
User,Group,Role,Status,Delivery
testuser1@domain.com,testgroup1@domain.com,OWNER,ACTIVE,DIGEST
testuser1@domain.com,testgroup2@domain.com,MANAGER,ACTIVE,DAILY
testuser1@domain.com,testgroup3@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser1@domain.com,testgroup4@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser2@domain.com,testgroup1@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser2@domain.com,testgroup2@domain.com,MANAGER,ACTIVE,ALL_MAIL
testuser3@domain.com,testgroup1@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser3@domain.com,testgroup2@domain.com,OWNER,ACTIVE,NONE

# Update membership
$ gam csvkmd users UserGroupRole.csv keyfield User subkeyfield Role datafield Group sync groups csvdata Group
User: testuser1@domain.com, Remove from 1 Group (1/3)
  Group: testgroup5@domain.com, Member: testuser1@domain.com, Removed
User: testuser2@domain.com, Update to 1 Group (2/3)
  Group: testgroup2@domain.com, Manager: testuser2@domain.com, Updated
User: testuser3@domain.com, Add to 1 Group (3/3)
  Group: testgroup2@domain.com, Owner: testuser3@domain.com, Added

# Intermediate state
$ gam csvkmd users UserGroupRole.csv keyfield User print groups
User,Group,Role,Status,Delivery
testuser1@domain.com,testgroup1@domain.com,OWNER,ACTIVE,ALL_MAIL
testuser1@domain.com,testgroup2@domain.com,MANAGER,ACTIVE,ALL_MAIL
testuser1@domain.com,testgroup3@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser1@domain.com,testgroup4@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser2@domain.com,testgroup1@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser2@domain.com,testgroup2@domain.com,MANAGER,ACTIVE,ALL_MAIL
testuser3@domain.com,testgroup1@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser3@domain.com,testgroup2@domain.com,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: testuser2@domain.com, Update to 1 Group
  Group: testgroup1@domain.com, Member: testuser2@domain.com, Updated
User: testuser1@domain.com, Update to 1 Group
  Group: testgroup4@domain.com, Member: testuser1@domain.com, Updated
User: testuser1@domain.com, Update to 1 Group
  Group: testgroup3@domain.com, Member: testuser1@domain.com, Updated
User: testuser1@domain.com, Update to 1 Group
  Group: testgroup2@domain.com, Manager: testuser1@domain.com, Updated
User: testuser1@domain.com, Update to 1 Group
  Group: testgroup1@domain.com, Owner: testuser1@domain.com, Updated
User: testuser3@domain.com, Update to 1 Group
  Group: testgroup1@domain.com, Member: testuser3@domain.com, Updated
User: testuser2@domain.com, Update to 1 Group
  Group: testgroup2@domain.com, Manager: testuser2@domain.com, Updated
User: testuser3@domain.com, Update to 1 Group
  Group: testgroup2@domain.com, Owner: testuser3@domain.com, Updated

# Final state
$ gam csvkmd users UserGroupRole.csv keyfield User print groups
User,Group,Role,Status,Delivery
testuser1@domain.com,testgroup1@domain.com,OWNER,ACTIVE,DIGEST
testuser1@domain.com,testgroup2@domain.com,MANAGER,ACTIVE,DAILY
testuser1@domain.com,testgroup3@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser1@domain.com,testgroup4@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser2@domain.com,testgroup1@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser2@domain.com,testgroup2@domain.com,MANAGER,ACTIVE,ALL_MAIL
testuser3@domain.com,testgroup1@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser3@domain.com,testgroup2@domain.com,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 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>]

If countsonly is specified, GAM displays the number of groups, by role, to which a user belongs rather than listing the group details.

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 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.

Examples

$ gam user testuser1@domain.com show groups
User: testuser1@domain.com, Show 4 Groups
  Group: testgroup1@domain.com, Role: OWNER, Status: ACTIVE, Delivery: DIGEST (1/4)
  Group: testgroup2@domain.com, Role: MANAGER, Status: ACTIVE, Delivery: DAILY (2/4)
  Group: testgroup3@domain.com, Role: MEMBER, Status: ACTIVE, Delivery: ALL_MAIL (3/4)
  Group: testgroup4@domain.com, Role: MEMBER, Status: ACTIVE, Delivery: ALL_MAIL (4/4)

$ gam user testuser1@domain.com print groups
User,Group,Role,Status,Delivery
testuser1@domain.com,testgroup1@domain.com,OWNER,ACTIVE,DIGEST
testuser1@domain.com,testgroup2@domain.com,MANAGER,ACTIVE,DAILY
testuser1@domain.com,testgroup3@domain.com,MEMBER,ACTIVE,ALL_MAIL
testuser1@domain.com,testgroup4@domain.com,MEMBER,ACTIVE,ALL_MAIL

$ gam csvkmd users UserGroupRole.csv keyfield User show groups role owner
User: testuser1@domain.com, Show maximum of 4 Groups (1/3)
  Group: testgroup1@domain.com, Role: OWNER, Status: ACTIVE, Delivery: DIGEST (1/4)
User: testuser2@domain.com, Show maximum of 2 Groups (2/3)
User: testuser3@domain.com, Show maximum of 2 Groups (3/3)
  Group: testgroup2@domain.com, Role: OWNER, Status: ACTIVE, Delivery: NONE (2/2)

$ gam csvkmd users UserGroupRole.csv keyfield User print groups role owner
User,Group,Role,Status,Delivery
testuser1@domain.com,testgroup1@domain.com,OWNER,ACTIVE,DIGEST
testuser3@domain.com,testgroup2@domain.com,OWNER,ACTIVE,NONE

$ gam users testuser1,testuser2 show groups domain domain.net
User: testuser1@domain.com, Show maximum of 2 Groups (1/2)
  Group: testgroup@domain.net, Role: MEMBER (1/2)
  Group: testnet@domain.net, Role: MEMBER (2/2)
User: testuser2@domain.com, Show maximum of 0 Groups (2/2)

$ gam users testuser1,testuser2 print groups domain domain.net
User,Group,Role
testuser1@domain.com,testgroup@domain.net,MEMBER
testuser1@domain.com,testnet@domain.net,MEMBER

$ gam users testuser1,testuser2 print groupslist
Getting all Groups for testuser1@domain.com (1/2)
Getting all Groups for testuser2@domain.com (2/2)
User,Groups,GroupsList
testuser1@domain.com,6,classroom_teachers@domain.com testfromgroup@domain.com testgroup1@domain.com testgroup2@domain.com testgroup4@domain.com testgroup@domain.com
testuser2@domain.com,0,

$ gam config csv_output_row_filter "Groups:count=0" users testuser1,testuser2 print groupslist
Getting all Groups for testuser1@domain.com (1/2)
Getting all Groups for testuser2@domain.com (2/2)
User,Groups,GroupsList
testuser2@domain.com,0,