Menu

Grouper - intro

Grouper is a system for creating and maintaining institutional groups in a central repository. Such groups may be used for many different purposes e.g. for mailing lists, or for determining which set of people are allowed to access specific web applications, or for sharing resources. The goal is to create a group once, but use it as often as necessary in as wide a range of systems as possible.

In order to use Grouper effectively you must first understand some key concepts:

Group

A group represents a collection of 'items' or entities which are themselves considered to be members of the group.

Entity

An entity is an abstraction for any 'item' which may be a member of a group. An entity has a 'type' e.g. person or group. To specify that group B is a member of group A is to specify that all members of group B are also members of group A. In the future, other entity types may be available to define computers or applications.

Membership

A specific relationship between an entity and a group.

Folder

A folder is a name space or container in which groups exist. Folders are hierarchical and may contain subfolders or groups. Folders can be used to collect together related groups and provide a means of controlling access to groups. Some examples of folders are:

• uob>faculties>artf:fren = University of Bristol> Faculties> Arts Faculty> Department of French
• uob>personal>[username] = University of Bristol> Personal groups> [name]

In this web application, groups and folders are distinguished by the addition of square brackets [] around group names.

Privileges

Grouper provides fine control over who can create folders and groups, who can change the membership of a group, and who can grant privileges for specific folders or groups to others. In fact, privileges are granted to entities. By granting a privilege to an entity which is a group, all members of that group are granted the privilege (for as long as they are a member of the group).

EveryEntity is a special internal entity. Any privilege granted to EveryEntity is, in effect, granted to all entities.

GrouperSysAdmin is also a special internal entity which has implicit admin privileges for folders and groups.

A SysAdmin group, if defined, conveys implicit GrouperSysAdmin privileges to its members. Members of this group, by default, act as themselves with privileges limited to those assigned to them. This UI allows SysAdmin group members to opt to Act as admin.

Folder privileges

Create

Entity may create groups, attributes, and subfolders in this folder

Admin

Entity may create groups, attributes, and subfolders in this folder, delete this folder, or assign any privilege to any entity

Attribute read

Entity may see the attributes for this folder

Attribute update

Entity may modify the attributes of this folder

Group privileges

Member

Entity is a member of this group

Optin

Entity may elect to join this group

Optout

Entity may elect to leave this group

View

Entity may see that this group exists

Read

Entity may see the membership list for this group

Update

Entity may modify the membership of this group

Admin

Entity may modify the membership of this group, delete the group or assign privileges for the group

Attribute read

Entity may see the attributes for this group

Attribute update

Entity may modify the attributes of this group

Grouper end-to-end scenarios

Find a folder or a group by navigation

(requires VIEW privilege or greater)

1. Click "Explore" in the "My Tools" segment of the left menu
2. Click any folder name in the "Browse or list groups" panel to show the contents of that folder. Continue clicking through folder names to move through the folder hierarchy.
   • If your current location is not "Root", you can click the Root folder label to go to the top folder
   • If you cannot see a folder or group, you may lack permission to view any of its contents, or the folder could be in a different location. Try searching for a specific group contained in that folder, or contact your administrator.
   • Note that clicking a folder name may advance you
3. Click any group name in the "Browse or list groups" panel to see the Group Summary screen for that group

Find an entity or a group by searching

(requires VIEW privilege or greater)

1. Click "Search" in the "My Tools" segment of the left menu
2. In the "Search people or groups" panel, type a search term
3. Click the "Search" button, or press the Return key, to submit. A search results screen will appear.
4. In the results list, click an entity name or a group path to view the Entity Details screen for your selection.
   • If you have selected a group, you can click "View Group Summary" near the bottom of the summary panel to go to the Group Summary screen, which includes additional options for working with information related to that group. (The options shown will be based upon your privilege level for the group.)
   • If you cannot see an entity or group, you may lack permission to view it. Try modifying your search, or contact your administrator.

Read a group's membership list

(requires READ privilege or greater)

1. Find the Group Summary screen for the group by navigating or searching.
2. Click "Manage members" near the bottom of the summary panel. The Members screen will appear.
   • You may choose to view indirect, direct, or all members of the list by selecting the appropriate radio button at the top of the "Membership list" panel and then clicking the "Change display" button

Add a member (entity or group) to a group

(requires UPDATE privilege or greater)

1. Go to the group's membership list page
2. Click "Add member" at the bottom of the "Membership list" panel. The "Assign privileges / Add members" screen will appear.
3. In the field in the "Search people or groups" panel, type the search criteria for the member you want to add, then click the "Search" button. Your search results will appear.
   • Note that in the privileges portions of the results panel, the MEMBER privilege is selected by default. You may use the neighboring checkboxes to assign additional privileges to the entities you select.
4. Select each member you want to add by clicking the checkbox next to the member listing, then click the "Assign privileges" button at the bottom of the panel.

Remove a member from a group

(requires UPDATE privilege or greater)

1. Go to the group's membership list page
2. Select the member(s) you want to remove by clicking the checkbox next to the member listing(s).
3. Click the "Remove selected members" button

Assign someone to be able to manage a group

(requires ADMIN privilege or greater)

1. Go to the group's membership list page
2. Click "Add member" at the bottom of the "Membership list" panel.
The "Assign privileges / Add members" screen will appear.
3. In the field in the "Search people or groups" panel, type the search criteria for the member you want to add, then click the "Search" button. Your search results will appear.
4. In the privileges portions of the results panel, select the checkbox for "update" [can modify group membership] or "admin" [can modify group membership, change group name, or delete the group].
   • Choose the simplest permission that will suffice, keeping in mind that anyone with ADMIN privilege can rename or delete the group, whether intentionally or accidentally.
   • If the user can manage the group, but is not a member of the group, unselect the checkbox for "member".
5. Select each entity you want to receive the designated privilege by clicking the checkbox next to the entity listing, then click the "Assign privileges" button at the bottom of the panel.

Create a new group

(requires CREATE privilege or greater)

1. Find a parent folder for the group. This should place you on the Browse Groups Hierarchy screen
   • If you have permissions to create a group in this folder, you will see the "Manage folders" panel at the bottom of the page. If you do not see this panel, contact your administrator.
2. Click "Create Group" at the bottom of the "Manage folders" panel. The Create Group screen will appear.
   • You can mouse over the field labels to learn more about what to enter in each field
3. Fill the fields in the panel, then click "Save" to create the group.
   • If you click the "Add members" button, your new group will be saved and you can add members to the group.

Create a composite group

(requires CREATE privilege or greater) Grouper allows you to use two existing groups (called "factors") to define a third (composite) group. You may combine two groups in the following ways:

• UNION includes all members of the two original (factor) groups -- "adding"
• INTERSECTION includes entities that belong to both of two original (factor) groups -- "members-in-common"
• COMPLEMENT includes entities that belong to the primary ("left) factor group who are not also members of the secondary ("right") factor group -- "left minus right"

To create a composite group:

1. Place each of your two factor groups in the Group Workspace
   1. Find or create each factor group
      • Find a group by navigating or searching, and proceed to the Group Summary page.
      • Create a factor group using the steps above to create a group and assign members to it. After you assign new members, click "Group Summary" at the bottom of the "Assign Privileges/Add Members" page to proceed.
   2. Click "Add to Group Workspace" at the bottom of the summary panel.
   3. Confirm that both factor groups are in the Group Workspace by clicking "Group Workspace" in the "My Tools" segment of the left menu.
2. Combine the factor groups to make a new, third group (composite)
   1. Find a parent folder for the group. This should place you on the Browse Groups Hierarchy screen
      • If you have permissions to create a group in this folder, you will see the "Manage folders" panel at the bottom of the page. If you do not see this panel, contact your administrator.
   2. Click "Create Group" at the bottom of the "Manage folders" panel. The Create Group screen will appear.
      • You can mouse over the field labels to learn more about what to enter in each field
   3. Fill the fields in the panel, then click "Make composite" to begin creating a composite group. The "Create composite group" panel will appear.
   4. Use the pulldown lists to select the two factor groups and how you wish to combine them.
      • The groups appearing in the pulldown lists are those in your Group Workspace
      • Assigning "Left group" and "Right group" will only matter if you are using COMPLEMENT ("left minus right") to combine the groups.
   5. Click the "Create composite group" button at the bottom of the panel to create the new composite group.

Create a new folder

(requires CREATE privilege or greater)

1. Find a parent folder for the folder you will be creating. This should place you on the Browse Groups Hierarchy screen
   • If you have permissions to create a folder in this folder, you will see the "Manage folders" panel at the bottom of the page. If you do not see this panel, contact your administrator.
2. Click "Create Folder" at the bottom of the "Manage folders" panel. The Create Folder screen will appear.
   • You can mouse over the field labels to learn more about what to enter in each field
3. Fill the fields in the panel, then click "Save" to create the group.
   • If you click the "Add members" button, your new group will be saved and can add search for and members to the group

Assign someone to be able to create new folders or groups within a parent folder

(requires ADMIN privilege)

1. Find a parent folder for the folder you will be creating. This should place you on the Browse Groups Hierarchy screen
   • If you have permissions to assign privileges in this folder, you will see the "Manage folders" panel at the bottom of the page. If you do not see this panel, contact your administrator.
2. Click the "Show Entities with" at the bottom of the "Manage folders" panel. The "Current entities with [Create] privilege" screen will appear.
3. Click "Assign this privilege" at the bottom of the "Entity list filtered by privilege" panel. The "Assign creation privileges for [group name]" screen will appear.
4. In the field in the "Search people or groups" panel, type the search criteria for the member you want to add, then click the "Search" button. Your search results will appear.
   • Note that in the privileges portions of the results panel, the CREATE privilege is selected by default. You may also use the ADMIN, ATTRIBUTE READ, or ATTRIBUTE UPDATE checkboxes to assign privileges to the entities you select.
   • The folder privileges you grant apply to the parent folder only, and not to any subfolders contained within it (i.e. there is no hierarchical inheritance of folder privileges by default)

My Memberships*

lets you find groups of which you are a member

   -- groups where you have member privilege --

Join Groups*

lets you find groups that you are eligible to join

   -- groups where you have optin privilege --

Manage Groups*

lets you find groups where you may update membership lists or assign privileges to others

   -- groups where you have update privilege or admin privilege --

Create Groups*

lets you create new groups or (sub)folders, as permitted by location

   -- folders where you have admin privilege or create privilege --

Explore

lets you explore all groups that are visible to you

   -- groups where you have view privilege --

Search

Lets you search for any entity known to Grouper. Allows an entity-centric approach i.e. you can list all groups where the entity is a member or has an Access privilege, or folders where the entity has one of the Folder privileges.

Group workspace

As described below, Grouper provides several ways of finding groups. It is possible, from the Group Summary page, to save, for the duration of your session, a group in a list. This menu item provides quick access to the groups throughout the session and provides a way of removing groups. The list provides the means for selecting groups for Group Math, described below. Saved groups are stored in the same list as saved entities (see belolw), however, this menu item filters the list to return only groups.

Entity workspace

Grouper provides a Entity summary page which can be accessed from many points in the UI. It is possible, from this page, to save, for the duration of your session, an entity in a list. This menu item provides quick access to the entities throughout the session and also provides a means to remove them.

*

These menu items filter the group hierarchy so that you see groups and folders relevant to the task you want to perform. GrouperSystemAdmin can manage all groups and folders and is not intended to be a group member, therefore, GrouperSystemAdmin does not have access to these menu items. This is also true of SystemAdminGroup members who have opted to Act as admin.

Finding groups

Browsing

click on folders to find subfolders and groups:

Listing

with the exception of All Groups it is possible to hide folders and simply show the list of groups for a particular section. This may work well when there are relatively few groups

Searching

case-insensitive substring searching of group names below a selected folder is provided. There is an advanced search screen which gives the user more control over which attributes are searched.

Saved groups

as described above, groups can be saved in a list in the session for quick access by clicking on the appropriate menu item.

Finding entities

Browsing

click on folders to find child groups. You can also click on a group to expand its membership list and select entities from that list

Searching

the user interface allows the user to enter a query string which is used to match entities. How the query string is interpreted depends on the specific implementation(s) of the Entity API present in the Grouper installation. The reference Grouper installation will return entities where:

1. any of the entity attributes are an exact* match for the query string
2. the entity is not a person and the the query string is a substring of a entity attribute.
3. the entity is a person and:
   1. the query string is an exact match for a fisrt name
   2. the query string is two terms e.g. ben fiona, and the second term is an exact first name match, and the first term matches the start of the entity's surname.

*searches are case-insensitive

Saved entities

as described above, entities can be saved in a list in the session for quick access by clicking on the appropriate menu item. When looking for entities to assign membership or privileges to, the list of saved entities can be displayed for quick assignment to any entity in the list.

Direct vs indirect

Privileges and membership of a entity for a group (Group A) may be granted directly to the entity, or may be indirectly derived because the entity is a member of a group which has been granted a privilege for Group A, or is, itself, a member of Group A.

The Grouper UI indicates whether a membership is direct, indirect or may, in fact, have more than one source e.g. if entity A is a member of Group A and Group B and both Group A and Group B are members of Group C, then entity A has two memberships for Group C.

Group math

Grouper allows the membership of a group to be defined as the union (or), intersection (and) or complement (not) of two other groups. This special type of member is known as a Composite member. A composite member has two Factor groups.

Take two ordinary groups:

1. fionas = Fiona Windsor, Fiona Benson, Fiona Tarbuck
2. bensons= Keith Benson, Fiona Benson, Ian Benson

fionas union bensons= Fiona Windsor, Fiona Benson, Fiona Tarbuck, Keith Benson, Ian Benson

union indicates the result of adding the members of fionas and bensons.

fionas intersection bensons= Fiona Benson

intersection indicates the members-in-common of fionas and bensons.

fionas complement bensons= Fiona Windsor, Fiona Tarbuck

complement indicates the members of fionas minus the members of bensons. In this case the position, left or right, of the groups is important.

A group can have a single composite member, or any number of entities (including groups) as members, but not a combination, however, groups which have a composite member can be used anywhere other groups can be used.

Custom group types

It is possible for sites to define custom attributes for groups (Grouper administrators can see wiki for more info). A special kind of attribute, a list, is a collection of entities, similar to a group's membership list. If a group has list attributes, and you have READ or WRITE privilege for the list, the Grouper UI will let you manage the list in a similar way to a group's membership list. A custom list cannot have a direct composite member, however, it can have as members, groups which have composite members.