Groups

Groups#

Create group#

To create a new group, use api.group.create(), providing a required string parameter of groupname.

from plone import api
group = api.group.create(groupname='staff')

When you create groups, title, description, roles and groups are optional.

from plone import api

group = api.group.create(
    groupname='board_members',
    title='Board members',
    description='Just a description',
    roles=['Reader', ],
    groups=['Site Administrators', ],
)

Get group#

To get a group by its name, use api.group.get().

from plone import api
group = api.group.get(groupname='staff')

Editing a group#

Groups can be edited by using the method api.portal.get_tool(), providing the portal tool portal_groups as the name argument. In this example, the title, description and roles are updated for the group staff.

from plone import api
portal_groups = api.portal.get_tool(name='portal_groups')
portal_groups.editGroup(
    'staff',
    roles=['Editor', 'Reader'],
    title='Staff',
    description='Just a description',
)

Get all groups#

You can also get all groups by using api.group.get_groups().

from plone import api
groups = api.group.get_groups()

Get user's groups#

Groups may be filtered by member. By passing the username parameter, api.group.get_groups() will return only the groups the user belongs to.

from plone import api
groups = api.group.get_groups(username='jane')

You can also pass the user directly to api.group.get_groups():

from plone import api
user = api.user.get(username='jane')
groups = api.group.get_groups(user=user)

Get group members#

Use the api.user.get_users() method to get all the users that are members of a group.

from plone import api
members = api.user.get_users(groupname='staff')

Delete group#

To delete a group, use api.group.delete() and pass in either the groupname or the group object you want to delete.

from plone import api
api.group.create(groupname='unwanted')
api.group.delete(groupname='unwanted')

unwanted = api.group.create(groupname='unwanted')
api.group.delete(group=unwanted)

Adding user to group#

To add a user to a group, use the api.group.add_user() method. This method accepts either the groupname or the group object for the target group and the username or the user object you want to add to the group.

from plone import api

api.user.create(email='bob@plone.org', username='bob')
api.group.add_user(groupname='staff', username='bob')

Removing user from group#

To remove a user from a group, use the api.group.remove_user() method. This also accepts either the groupname or the group object for the target group and either the username or the user object you want to remove from the group.

from plone import api
api.group.remove_user(groupname='staff', username='bob')

Get group roles#

To find the roles assigned to a group, use the api.group.get_roles() method. By default it returns site-wide roles.

from plone import api
roles = api.group.get_roles(groupname='staff')

If you pass in a content object, it will return the local roles of the group in that particular context.

from plone import api
portal = api.portal.get()
folder = api.content.create(
    container=portal,
    type='Folder',
    id='folder_four',
    title='Folder Four',
)
roles = api.group.get_roles(groupname='staff', obj=portal['folder_four'])

If you pass in a content object and inherit=False, it will return only the local roles of the group on that particular object and ignore global roles.

api.group.grant_roles(
    groupname='staff', roles=['Contributor'], obj=portal['folder_four'])

roles = api.group.get_roles(
    groupname='staff', obj=portal['folder_four'], inherit=False)

Grant roles to group#

To grant roles to a group, use the api.group.grant_roles() method. By default, roles are granted site-wide.

from plone import api
api.group.grant_roles(
    groupname='staff',
    roles=['Reviewer, SiteAdministrator'],
)

If you pass in a content object, roles will be assigned in that particular context.

from plone import api
portal = api.portal.get()
folder = api.content.create(
    container=portal, type='Folder', id='folder_five', title='Folder Five')
api.group.grant_roles(
    groupname='staff', roles=['Contributor'], obj=portal['folder_five'])

Revoke roles from group#

To revoke roles already granted to a group, use the api.group.revoke_roles() method.

from plone import api
api.group.revoke_roles(
    groupname='staff', roles=['Reviewer, SiteAdministrator'])

If you pass in a content object, it will revoke roles granted in that particular context.

from plone import api
api.group.revoke_roles(
    groupname='staff', roles=['Contributor'], obj=portal['folder_five'])