draft-internet2-mace-dir-Grouper-search-00.html
Tom Barton, editor
The
Comments to: tbarton@uchicago.edu
Draft for discussion by the mace-dir-groups project group.
Grouper API Search & Browse Capabilities
Sections 1 and 2 review the group name- and namespace name-related attributes in play. In section 3 other attributes of search & browse interest are itemized, and in section 4 the search & browse capabilities to be supported are sketched.
Implementation of each of these capabilities is tentatively assigned to Grouper versions in section 4.1 below.
Recall a principle from very early in the design process for Grouper: applications with extensive or intensive search requirements should rely on a searchable group store provisioned from the Groups Registry, e.g., an LDAP directory. Grouper should focus on management functionality and not try to match other established technologies in their ability to search.
The one application category to which this principle is difficult to apply is group management. It is somewhere between undesirable and dysfunctional to oblige group management applications to rely on two stores of groups, one for updating and the other for searching. Hence, much of the search & browse capability specified here is motivated by the need to adequately support group management applications.
Character set restrictions on stem and extension strings as specified in the “Grouper Phase 1 Specifications” document on the mace-dir-groups website apply appropriately below, although note that the term “descriptor” used in that document is effectively replaced by “extension” here.
attribute name: guid
description: a globally unique identifier for the group that is never reassigned or revoked.
attribute name: stem
description: the name of the namespace in which the group is named.
attribute name: extension
description: the relative name of the group within its namespace.
attribute name: name
description: a system-maintained, read-only string representation of the logical ordered pair of (stem, extension), used to facilitate searching for groups by name.
syntax: the value of stem followed by the configured namespace delimiter followed by the value of extension. E.g., if ":" is the namespace delimiter, <stem>:<extension>.
attribute name: displayExtension
description: an alternative string for representing the extension attribute, for use in the UI.
attribute name: displayName
description: a system-maintained string representation of the logical ordered pair of (displayName of stem, displayExtension), used to facilitate searching for groups by displayed name.
syntax: the value of the displayName of the stem followed by the configured namespace delimiter followed by the value of displayExtension. Otherwise it is just the displayExtension.
Note that a group may be unambiguously referred to by specifying its ordered pair of (stem, extension), by specifying its name, or by specifying its guid. Stems and extensions (and hence names) can be changed, but guids are never changed.
Grouper maintains an internal guid that is distinct from the guid attribute exposed in the API. Both are created as part of the group creation process. They are distinguished only by the fact that one is exposed to API clients.
attribute name: stem
description: the name of the namespace to which this namespace is subordinate.
The string representation of the stem attribute is a sequence of 0 or more naming extensions separated by the configured namespace delimiter.
attribute name: extension
description: the name of this namespace within its parent namespace.
attribute name: name
description: a system-maintained, read-only string representation of the logical ordered pair of (stem, extension), used to facilitate searching for namespaces by name.
syntax: If the parent namespace stem is not null, the value of stem followed by the configured namespace delimiter followed by the value of extension. Otherwise it is just the value of extension. E.g., if ":" is the namespace delimiter, <stem>:<extension>.
attribute name: displayExtension
description: an alternative string for representing the extension attribute, for use in the UI.
attribute name: displayName
description: a system-maintained string representation of the logical ordered pair of (displayName of parent namespace, displayExtension), used to facilitate searching for namespaces by displayed name.
syntax: If the parent namespace stem is not null, it is the value of the displayName of the parent namespace followed by the configured namespace delimiter followed by the value of displayExtension. Otherwise it is just the displayExtension.
This amounts to a system of naming for namespaces the same as that for groups, except that a guid is not stamped on each namespace.
Namespace example 1: "uofc"
stem:
extension: uofc
name: uofc
displayExtension:
displayName:
Namespace example 2: "uofc:bsd"
stem: uofc
extension: bsd
name: uofc:bsd
displayExtension: Biological Sciences Division
displayName:
Group example 1: "uofc:exec_council"
stem: uofc
extension: exec_council
name: uofc:exec_council
displayExtension: Executive Council
displayName:
Group example 2: "uofc:bsd:eis_staff"
stem: uofc:bsd
extension: eis_staff
name: uofc:bsd:eis_staff
displayExtension:
displayName:
Note: The UI mediating a user's creation of a new namespace must "register" the new namespace twice. Once with Grouper 'cause Grouper will need to know about all namespaces in play, and again with the provider of the naming privilege interface, so that it knows to manage privileges over the new namespace. That's the price of separation of duties, I guess.
Each group and namespace has the 6 attributes [create|modify][Time|Subject|Source], although the semantics for Source are as yet unspecified and so the two Source related attributes won't be implemented in the initial release.
Each group has a members list and a description attribute.
The Access and Naming privilege interfaces will have methods for returning the set of privileges that a given subject has with respect to a given group or namespace. Those interfaces will also specify methods for returning lists of all groups or namespaces to which a given subject has a given privilege. Although the default implementation of those interfaces native to Grouper will support these latter methods, it is possible that alternative privilege interface providers might not have that capability. The interface specifies a way for providers to return a "can't do" indication instead of a real list.
A site may extend the set of group types, although without the aid of the API. So there may be additional attributes available for searching or browsing. In addition, the list of types associated with each group, although not exposed as an attribute in the API, is potentially available for use in filtering searches, i.e., to constrain a search to all groups of a specified type.
Following are capabilities that support searching & browsing, in addition to those that are inherent in the Access & Naming privilege interfaces as mentioned above. The types of supported searches are limited by Grouper's reliance on the SQL LIKE comparison on the backend. All searches are implicitly scoped by the subject's VIEW and READ privileges.
1. The name, extension, or displayName attributes of groups can be searched.
2. The name, extension, or displayName attributes of namespaces can be searched.
3. All groups with a given stem can be listed.
4. All namespaces with a given stem can be listed.
5. A search of the extension or displayExtension attributes of groups can be scoped to groups with a given stem.
6. A search of the extension or displayExtension attributes of namespaces can be scoped to namespaces with a given stem.
7. A search of the name, extension, or displayName attributes of groups can be scoped to groups within a namespace subordinate to a given stem.
8. A search of the name, extension, or displayName attributes of namespaces can be scoped to namespaces subordinate to a given stem.