UH Groupings Developer Documentation

UH Groupings uses Grouper behind the scenes to implement the concept of a grouping. This document specifies the Grouper operations that can be performed on a grouping.

Grouping Roles and Permissions

User Type	Description	Can use hawaii.edu/uhgroupings to perform these operations:
Grouping Superuser	Any person who has been designated as a Grouper administrator.	Can do everything in UH Grouper (and therefore UH Groupings)
Grouping Owner	Any person who is responsible for a grouping. The first owner requests for the creation of a grouping. That request must specify the basis and destination (if any) of the grouping.	Can designate other people as Grouping Owners. Can add or delete people from the include and exclude groups. Can specify whether opt-in or opt-out is allowed for the grouping. Can enable or disable LISTSERV list for grouping Cannot change the basis using hawaii.edu/uhgroupings. Must request these changes or it can be done through the API described on this page.
Grouping Member	Any person who is a member of a grouping, regardless of whether the membership comes from the basis or the include group.	Can opt in or opt out of a grouping, assuming the grouping owner allowed it
Application Account	A special username that is by an application to interact with UH Grouper (and therefore, UH Groupings). Grouper permissions are granted based on the needs of the application.	N/A

Anatomy of a Grouping

All groupings must be created under hawaii.edu:custom:<org> or a subdirectory under that. We'll describe the Grouper components that make up a grouping by using a manoa-math-club grouping example. Remember that a colon delimits a folder, so we'll notate them in bold and ending with a colon:

hawaii.edu:						Top-level folder for all Grouper groups
	custom:					All groupings must be inside custom: subfolder
		uhm:				Organize grouping by <org> code. We will create it under the uhm folder
			manoa-math-club			The grouping itself. It is a composite group defined as: hawaii.edu:custom:uhm:manoa-chess-club:basis+include relative complement hawaii.edu:custom:uhm:manoa-chess-club:exclude
			manoa-math-club:			A folder holding all artifacts that implement the grouping. Every grouping has a folder with the same name as the grouping.
				basis		The basis of the grouping. It can have a single group as a member or it can be a complex group expression. Examples: Simple basis: This basis group has only one member, hawaii.edu:auto:sis:registration:MAN:MATH:140:86212:201430:enrolled Complex basis: This basis group has one member, hawaii.edu:custom:uhm:manoa-math-club:basis:100, which is a composite group that implements a complex group expression. See below.
				basis:		If the basis is a complex group expression, we will need to create intermediate groups that represent each group operation. Such groups go into this folder.
					100	A composite group that represents a complex basis that is implemented by operations on the 101, 102, etc. groups below. For example, this group is a composite group defined as hawaii.edu:custom:uhm:manoa-math-club:basis:101 relative complement hawaii.edu:custom:uhm:manoa-math-club:basis:102
					101	This could be a composite defined as hawaii.edu:auto:sis:registration:MAN:MATH:111:85029:201430:enrolled union hawaii.edu:auto:sis:registration:MAN:MATH:112:82784:201430:enrolled
					102	This could be another composite defined as hawaii.edu:menu:any-dataOrigin:aff:any-org:faculty union hawaii.edu:menu:any-dataOrigin:aff:any-org:staff
				include		The grouping's include group.
				exclude		The grouping's exclude group.
				basis+include		Every grouping has this. It is the composite group that implements the "basis union include" portion of the grouping.

Adding or deleting people from the include or exclude groups

Determine the full path to the grouping's include and exclude groups.

Use Grouper's API to add or delete members from the include or exclude groups.

Set the uh-settings:for-groups:last-modified attribute to the current date and time, but truncate the seconds, and use this format: 20140315T1915 (March 15, 2014 7:15:59pm, note we truncate even if this is closer to 7:16pm. Please make sure your clock is synchronized with some time server)

Special considerations: who is performing the addition or deletion from the include and exclude groups? Is your application opting in or out on behalf of the user? If so, you should check whether the owner allowed that.