Table of Contents
| Table of Contents | ||
|---|---|---|
|
Overview
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. |
|
| 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. |
|
| Grouping Member | Any person who is a member of a grouping, regardless of whether the membership comes from the basis or the include group. |
|
| Application Account | A special username that is used 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, an application account can access whatever Grouper resources and perform whatever operations it has been granted permissions for. |
Anatomy of a Grouping
| Info |
|---|
Typically you would not need to create the underlying components described below. When we receive a grouping request, we will implement them all for you. We expect that most applications would only need to deal with a grouping's include or exclude group. |
...
| 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: | |||||||
| 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 be empty, it can have one or more groups as members, or it can implement a complex group expression. A basis is typically built from the UH Group Store. Examples: Simple basis: This basis group has zero or more groups as members, e.g. it has this one member group: 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 | |||||||
| 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 | |||||||
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. |
Grouper web services
- All UH Grouping operations are performed using Grouper web services. You will need to become familiar with it:
Application account
- If you will be using WS to read from or write to your grouping, make sure your Grouper application account has been granted the following privileges:
- View and Read privileges on the grouping itself
- Update privileges on the grouping's include and exclude subgroups. This means your application account is also considered an owner for the grouping.
Checking if a person is a member of a grouping
- Determine the full path to the group that represents the grouping itself
- e.g. hawaii.edu:custom:uhm:manoa-math-club
- Use this Grouper web service to check that the group has the UH Number of the person as a member:
- https://spaces.internet2.edu/display/Grouper/Has+Member
- e.g. to check that UH Number 11111111 is a member of hawaii.edu:custom:uhm:manoa-math-club
- HTTP request (we'll be using the RESTful XML interface throughout our examples)
- GET https://grouper.hawaii.edu/grouper-ws/servicesRest/xml/v2_1_005/groups/hawaii.edu%3Acustom%3Auhm%3Amanoa-math-club/members/11111111
- Note how we had to URL-encode the colons in the group path.
HTTP response contains this XML (skipped some attributes to keep this example uncluttered)
Code Block xml xml <WsHasMemberLiteResult> <wsGroup> <extension>manoa-math-club</extension> <typeOfGroup>group</typeOfGroup> <displayExtension>manoa-math-club</displayExtension> <description>UH Manoa Math Enthusiasts</description> <displayName>hawaii.edu:custom:uhm:manoa-math-club</displayName> <name>hawaii.edu:custom:uhm:manoa-math-club</name> <uuid>506f934c821459aee4</uuid> </wsGroup> <resultMetadata> <resultCode>IS_NOT_MEMBER</resultCode> <resultMessage> (some long message useful for Grouper debugging) </resultMessage> <success>T</success> </resultMetadata> <responseMetadata> <resultWarnings></resultWarnings> <millis>216</millis> <serverVersion>2.1.5</serverVersion> </responseMetadata> <wsSubject> <resultCode>SUCCESS</resultCode> <success>T</success> <id>11111111</id> <name>John M Doe</name> <sourceId>UH core LDAP</sourceId> </wsSubject> </WsHasMemberLiteResult>
- HTTP request (we'll be using the RESTful XML interface throughout our examples)
Adding or deleting people from the include or exclude groups
It is recommended that everyone use https://www.hawaii.edu/uhgroupings to manage every aspect of a grouping.
...