Grouper User Guide

1. Click the Create new group button from any page
   
2. Select Create new folder or Create new group
3. Review the Create in this folder field: 
   1. The parent folder combobox will default to whatever folder is being accessed, but can be changed to another folder.  The combobox will only show results where the user is allowed to create folders.
   2. You can also click the “search for a folder…” link to see other locations you can create a folder
4. Folder/Group Name: Enter a name for your new folder
5. Folder/Group ID: Do not change
6. Description: Enter a description for the folder or group
7. Click the Save button

Guide for New Groups

• Users are only allowed to create groups in folders they have access to.
• Generally the folder name and folder ID are the same, as the user types in the folder name, the ID will be populated with the same text unless the user chooses to have them differ. 
• Use meaningful group names that adhere to the group naming policy.

Adding Members to Groups

Add a single member 

1. From inside the group, click the Add members button
2. Type the member email address, NinerNET or name in the search field
3. The combobox will show results of searches in subject sources.  Groups are returned which the user can READ and can be added as members of other groups.
4. Members can be added with default privileges (member), or they can be given other privileges in addition or instead
5. Click the Add button

Searching Tips

1. If you have trouble finding a member or group, click the link to "search for an entity". This allows for more flexible and partial name searching.
2. You will receive “the value entered is not valid” error if the name is not entered exactly into the search bar.

Import a list of members

entityIdOrIdentifier
jsmith123
testuser123
testuser2
some:path:to:group:idPath

1. Prepare your text file for import. This should be a plain text file with the first line labeled 'entityIdOrIdentifier', followed by each member's NinerNET username on a separate line.
    
2. Navigate to group where you want to import members
3. Click the Add members button
4. Select import a list of members
5. Next to How to specify Members? select the Import a file (you can also copy/paste IDs info a text field).
6. Import file will show you the different options for imports, you can use a csv format instead of txt if preferred
7. Scroll to the bottom of the page
8. You may opt to replace existing group members OR remove users with the list you are importing
9. Review the Import results screen. Press the Submit button to return to the group

How to View / Remove Group Members

• Navigate to the group you want to review
  
• Members are listed under the Members tab
• Direct members are people who were added directly to the group
• Indirect members are members of groups that were added to the group
• You can only remove direct group members
  • Filter for: Has direct membership
  • Select the members (or groups) to remove
  • Click Remove Selected Members button

Group Member Actions

In a group members list you can view various actions for a group member.

• Navigate to the group where you want to view members
• On the Members tab, find a specific user
• Click the Actions button and select from the various actions:
  • Edit membership and privileges: If it is a direct membership you can assign start and end dates
  • Trace Membership: You can see the path that a user has to the overall group. The trace screen will explain nested groups, composite groups, and privilege inheritance (when dealing with privileges).

Composite Access Groups

When you request an app group it will automatically be created with access control groups _allow, _allow_adhoc and _deny from which memberships flow into the resulting composite group (app:appname:service:policy:groupname) from your request. It is highly recommend you use institutional data, via reference groups, in your access group policies so members can be auto-updated whenever their affiliation changes. The resultant membership of the composite group are individuals who exist in both groups. Since reference groups only contain members with a current affiliation (e.g. employee), once anyone in the ref group becomes non-current (e.g. retirement) they will automatically be removed from the composite group.

If your application policy groups will be mostly ad-hoc (i.e. they cannot be built from institutional groups) you can make a composite intersection group of the ad-hoc members against an institutional ref group. In order to have members automatically drop out of the ad-hoc if no longer part of the overall institutional group.

How to create a composite group

1. To make a composite group, first create an ad-hoc group using the instructions for How to Create a Group and Add Members to Group.
2. Create a new group, must be empty
   1. Navigate to the folder in which the group should reside
   2. Click the More Actions button
   3. Select Create New Group
   4. Group Name: Use a name that indicates it is an access group
   5. Description:  Enter a description that explains what this group will be used for
   6. Press the Save button
3. Select More Actions from inside the empty group
4. Select Edit composite, Click the Yes button
5. First Factor Group: This group is the ad-hoc group you created earlier.
6. Operation: Choose and (intersection) to allow for auto-removal
7. Second Factor Group: This group is an institutional reference group you want to cross your ad hoc group with. A common selection would be “All Employees”, or a departmental members groups. Search by group name and select the group you want to use.
8. Press the Save button

Export Members from Group

1. Navigate to the group you want to export data from
2. Click the More Actions button
3. Select Export members
4. Choose All member data or Only member IDs 
5. Press the Export button
6. Your member data will download as a .csv file

Setup Group Attestation

Grouper attestation means marking a group or folder so that owners must review the membership list periodically. This is highly recommend for manually maintained groups where deprovisioning is not automatic.

1. Navigate to the group or folder you want to set attestation on.
   Likely a final policy group, i.e. group that syncs to AD.
2. Click the More Actions button
3. Select Attestation
4. Under Attestations actions select Edit attestation settings

Attestation options

Attestation/Has attestation: Both should be yes to enable
Send email: Can be configured to email all groups admins (based on group security privileges) or a manual entered list of addresses.
Recertify days: By default the recertification period is 180 days, this is customizable. 

Project Documentation

The Grouper project wiki has documentation for the end user UI at:

https://spaces.at.internet2.edu/display/Grouper/User+Interface