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

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:

Grouper web services

• All UH Grouping operations are performed using Grouper web services.  You will need to become familiar with it:
  
  • Grouper API

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)

      <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>

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. 

If you must write code to manipulate the membership of the grouping's include and exclude groups, here is how you do it:

• Special considerations before modifying an include or exclude group:
  • Who is performing the addition or deletion from the include and exclude groups?  If it as a grouping owner, you may proceed.
  • Is your application opting in or out on behalf of a grouping member?  If so, you should check whether the owner allowed that.
• Determine the full path to the grouping's include and exclude groups. Simply append :include or :exclude to the grouping path, e.g.
  
  • hawaii.edu:custom:uhm:manoa-math-club:include
  • hawaii.edu:custom:uhm:manoa-math-club:exclude
• Use these Grouper web service to add or delete members from the include or exclude groups.
  • https://spaces.internet2.edu/display/Grouper/Add+Member
  • https://spaces.internet2.edu/display/Grouper/Delete+Member
• REQUIRED: set this Grouper attribute to the current date and time, but truncate the seconds portion:
  
  • • The attribute name is uh-settings:attributes:for-groups:last-modified:yyyymmddThhmm
    • The attribute name in the web service call is referred to as wsAttributeDefNameName. See example below.
  • Use the YYYYMMDDTHHMM format for the attribute value, e.g.
    
    • 20140315T1915 (March 15, 2014 7:15:59 PM, note how we truncated the seconds, even if this should have been rounded to 7:16 PM)
  • Please make sure your clock is synchronized with a time server.
  • Use this Grouper web service to assign the attribute:
    • https://spaces.internet2.edu/display/Grouper/Assign+Attributes

    • Example:

  • A future version of Grouper will support RabbitMQ messaging, and we should then do away with this timestamp requirement.