Group API Data Structures and Operations

Group Data Structures

Group objects

Group {
  uri    handle
  string id
  string displayName
  string description
}

GroupLookup {
  uri    handle
  string id
}

GroupList {
  bool fullList
  int  listSize
  List<Group> groups
}

SubjectList {
  bool fullList
  int  listSize
  List<Subject> subjects
}

id: Globally unique ID, does not need to be human readable, does not change. May be any format (eg: UUID, ePPN). Permitted characters as per RFC 2141. Max length 1024.
uuid: Globally unique ID in URI format of fifergroup://grouper.school.edu/folder/folder2/groupName. May change, though changing should be avoided.
displayName: Human readable name. Should be unique within a GMS, but not required. May change. May include folder structure. Max length 1024. Permitted characters TBD.
description: Human readable description. Free form. Max length 1024. Permitted characters TBD.

It is the responsibility of the server to ensure that id and handle cannot refer to different entities if they have the same value.

Availability

Mandatory.

Renaming Considerations

When a group is renamed, future retrievals of the old name (id) may result in an indication that the group has moved and the id of the new name. To access a new group at the old name, the request must be qualified.

Group Operations

hasMember()

boolean hasMember(GroupLookup group, Subject subject, enum immediacy=any)

Input

group: GroupLookup object
subject: Subject object
immediacy: Constraint on search for subject as an immediate, nonimmediate, or any member of group

Output

true if subject is an immediate or nonimmediate member (as specified) of group, false otherwise

Availability

Mandatory.

getMembers()

SubjectList getMembers(GroupLookup group, enum immediacy=any)

Input

group: GroupLookup object
immediacy: Constraint on search for subject as an immediate, nonimmediate, or any member of group

Output

List of Subject objects

Availability

Mandatory.

getGroupsForMember()

GroupList getGroupsForMember(Subject subject, enum immediacy=any)

Input

subject: Subject object
immediacy: Constraint on search for subject as an immediate, nonimmediate, or any member of the relevant groups

Output

List of Group objects

Availability

Mandatory.

addMember()

boolean addMember(GroupLookup group, Subject subject, bool addOnly=false)

Input

group: GroupLookup object
subject: Subject object
addOnly: If true, addMember() fails if subject is already a member of groupID.

Output

true if subject is successfully added or if addOnly is false and subject is already a member of groupID, false otherwise.

Availability

Optional. Data store may be read-only.

removeMember()

boolean removeMember(GroupLookup group, Subject subject, boolean removeOnly=false)

Input

group: GroupLookup object
subject: Subject object
removeOnly: If true, removeMember() fails if subject is not a member of groupID.

Output

true if subject is successfully removed or if removeOnly is false and subject is not a member of groupID, false otherwise.

Availability

Optional. Data store may be read-only.

saveGroup()

Group saveGroup(Group group)

Input

group: Group object. If group:id and group:uuid are blank, a new group is being requested.

Output

Group object holding group id/uuid (possibly newly assigned).

Availability

Optional. Data store may be read-only.

deleteGroup()

urn deleteGroup(GroupLookup group, boolean deleteOnly=false)

Input

group: GroupLookup object
deleteOnly: If true, deleteGroup() fails if group does not exist.

Output

true if group is successfully deleted or if deleteOnly is false and group does not exist, false otherwise.

Availability

Optional. Data store may be read-only.

findGroups()

List<Group> findGroups(List<GroupLookup> groupLookups, urn folder, enum folderDepth=one|sub,
                       List<enum> fieldNames=urn|displayName|description, String fieldSearchString,
                       String wildcard, boolean splitStringOnWhitespace, boolean caseSensitive)

Input

groupLookups: list of group lookups to find. max 100.
folder: (optional): if results should be constrained in a certain folder
folderDepth: (required if folder set): "one" for results directly in the folder, "sub" for results in the folder or subfolders
fieldNames: (optional): if searching by a substring of a field, can be urn|displayName|description. Note, if multiple are set, then the search string could be in any of the fields.
fieldSearchString: (required if fieldName set): this is the search string to find groups. Can contain caller-specified wildcards.
wildcard: (optional, can only be set if fieldName is set): if not set, there is no wildcard in the search. If set, can be one or more chars, and this found in the fieldSearchString will be treated as a wildcard. Note there is no way to escape this wildcard, so client should pick something not otherwise being searched
splitStringOnWhitespace: (required if fieldName set): if true, then any whitespace in the fieldSearchString will cause the search to be split on whitespace, and and'ed together.
caseSensitive: (required if fieldName set): if true then the search string should be checked as is, if false then should be case-sensitive

Note, either or multiple of the groupLookups or folder or fieldNames needs to be set

For example, if the folder URN is: urn:group:school/apps/confluence
and the folderDepth is: sub
and the search string is: *english* *dept*
and the wildcard is: *
and the fieldNames are: urn and displayName
and caseSensitive is: false
and splitStringOnWhitespace is: true

Then the query run will get all groups the caller is allowed to see in the school/apps/confluence folder or subfolders, that have "english" and "dept" somewhere in the urn or displayName case insensitive.

Output

List of Group objects

Availability

Mandatory

Questions

TODO

Folder object and operations: find, save, delete
Common group permissions: Admin the group (add/remove members), public (self-subscribe), readable (eg by a portal but not by the public)