WARNING: If you are reading this on GitHub, DON’T! Read it on ReadTheDocs:
references and proper formatting.

Groups

Create group

To create a new portal group, use api.group.create().

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

When creating 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=['Readers', ],
    groups=['Site Administrators', ]
)

Get group

To get a group by it’s 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 group_tool. In this example the title, description and roles are updated for the group ‘Staff’.

from plone import api
group_tool = api.portal.get_tool(name='portal_groups')
group_tool.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

If you set the user parameter, then api.group.get_groups() will return groups that the user is member of.

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

Get group members

Remember to use the api.user.get_users() method to get all users that are members of a certain 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

The api.group.add_user() method accepts either the groupname or the group object of 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

The api.group.remove_user() method accepts either the groupname or the group object of 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

The api.group.get_roles() method is used to getting group’s roles. 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 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'])

Grant roles to group

The api.group.grant_roles() allows us to grant a list of roles site-wide to the group.

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

If you pass in a content object, it will grant these roles 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

The api.group.revoke_roles() allows us to revoke a list of roles from the group.

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

If you pass in a content object, it will grant these roles in that particular context.

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

Project Versions

Table Of Contents

Previous topic

Users

Next topic

List of all API methods with descriptions

This Page