Groups are sets of users that can be used in collaborations.
- List Groups
- Create a Group
- Get Information about a Group
- Update a Group
- Delete a Group
- Get a Group's Collaborations
- Add User to Group
- Get Information about a Group Membership
- Update Group Membership
- Remove User from Group
- List Group Members
- List Memberships for User
Calling client.get_groups(name=None, limit=None, offset=None, fields=None) will return a
BoxObjectCollection that allows you to iterate over the Group objects representing groups in the
enterprise.
groups = client.get_groups()
for group in groups:
print(f'Group "{group.name}" has ID "{group.id}"')Alternatively, you can set a filter on the name of the groups by passing the name parameter:
group_name = 'Example Group'
groups = client.get_groups(group_name)
for group in groups:
print(f'Group {group.id} has a name matching {group_name}')To create a new group, call
client.create_group(name, provenance=None, external_sync_identifier=None, description=None, invitability_level=None, member_viewability_level=None, fields=None) with the name of the group and any optional group properties you want to set. This method
returns a Group object representing the created group.
You can read more about the optional parameters in the Create Group API documentation.
created_group = client.create_group('Example Group')
print(f'Created group with ID {created_group.id}')To retrieve information about a group, first call client.group(group_id) to initialize a
Group object. Then, call group.get(*, fields=None, headers=None, **kwargs) to retrieve the
data about that group. This method returns a new Group object with fields populated by data form the API,
leaving the original object unmodified.
group = client.group(group_id='11111').get()
print(f'Got group {group.name}')You can optionally specify a list of fields to retrieve from the API, in order to filter out fields you don't need or
add fields that are not returned from the API by default:
group = client.group(group_id='11111').get(['name', 'description', 'provenance'])
print(f'The "{group.name}" group ({group.description}) came from {group.provenance}')To update a group, call group.update_info(data=group_update) with a dict of the group properties
to update. This method returns a new Group object with the updates applied, leaving the original
object unmodified.
group_update = {'name': 'New Group Name'}
updated_group = client.group(group_id='11111').update_info(data=group_update)
print(f'Changed the name of group {updated_group.id} to "{updated_group.name}"')To delete a group, call group.delete(). This method returns True to indicate that the deletion was
successful.
client.group(group_id='11111').delete()
print('The group was deleted!')To retrieve all collaborations for a group, call
group.get_collaborations(limit=None, offset=None, fields=None). This method returns a
BoxObjectCollection that allows you to iterate over the Collaboration objects in the
collection.
collaborations = client.group(group_id='11111').get_collaborations()
for collaboration in collaborations:
print(f'The group is collaborated on {collaboration.item.type} {collaboration.item.id}')To add a new member to the group, call
group.add_member(user, role='member', configurable_permissions=None) with the User to
add to the group. This method returns a new GroupMembership object representing the presence of
the user in the group.
You can optionally specify the user's role in the group, and for users with an admin role you can configure which
permissions they have in the group by passing a dict of group permissions to configurable_permissions.
user = client.user('1111')
membership = client.group(group_id='11111').add_member(user)
print(f'Added {membership.user.name} to the {membership.group.name} group!')To retrieve information about a group membership, first call
client.group_membership(group_membership_id) to initialize the
GroupMembership object. Then, call group_membership.get(*, fields=None, headers=None, **kwargs)
to retrieve data about the group membership from the API. This returns a new GroupMembership
object with fields populated by data from the API, leaving the original object unmodified.
membership_id = '11111'
membership = client.group_membership(membership_id).get()
print(f'User "{membership.user.name}" is a member of the {membership.group.name} group')To update a group membership, call membership.update_info(data=membership_update) with a dict of
properties to update on the membership object. This method returns a new GroupMembership object
with the changes applied, leaving the original object unmodified.
membership_id = '1234'
membership_update = {'role': 'admin'}
updated_membership = client.group_membership(membership_id).update_info(data=membership_update)
print(f'Updated {updated_membership.user.name}\'s group role to {updated_membership.role}')To remove a user from a group, delete their associated group membership by calling group_membership.delete().
This method returns True to indicate that the deletion was successful.
membership_id = '1234'
client.group_membership(membership_id).delete()
print('The membership was deleted!')To retrieve all of the memberships for a given group, call
group.get_memberships(limit=None, offset=0, fields=None). This method returns a
BoxObjectCollection that allows you to iterate over all of the GroupMembership objects in the
collection.
group_memberships = client.group(group_id='11111').get_memberships()
for membership in group_memberships:
print(f'{membership.user.name} is a {membership.role} of the {membership.group.name} group')To retrieve all of the groups a user belongs to, get a list of their associated group memberships by calling
user.get_group_memberships(limit=None, offset=0, fields=None). This method returns a
BoxObjectCollection that allows you to iterate over the GroupMembership objects in the
collection.
user_memberships = client.user(user_id='33333').get_group_memberships()
for membership in user_memberships:
print(f'User is in the {membership.group.name} group')