Grouper API Subject Attributes

Grouper returns the following subject attributes:

• name (same as cn)
• description (same as cn)
• uid
• sn (the person's surname)
• givenName (the person's given name)
• displayName (the person's preferred name for display)
• cn (the person's full name, typically the given name and surname and often including a middle initial if available)
• uhOrgAffiliation
• eduPersonAffiliation
• eduPersonOrgDN
• uhScopedHomeOrg

For multi-valued attributes, if more than one value is available for a given attribute, the values will be separated with a delimiter of three vertical bars, “|||”

• E.g. eduPersonAffiliation with values “faculty” and “staff” returns “faculty|||staff”

If your code does not read the attributeValues JSON/XML tag for a subject being returned, you can stop reading here.  You probably don't have to worry about this change breaking your code.

If you do read attributeValues for a subject, you should always check the subjectAttributeNames in the XML/JSON returned by Grouper to determine the order in which the above attributes are returned.  This is usually relevant for API calls such as Get Members or Get Subjects or any API call that returns a subject.

For example, this is the response to a Get Members call where we asked for details (includeSubjectDetail=T) and we specified our own list of attributes (including a bogus one like 'foo'). The top-level subjectAttributeNames gives us the sequence of attributes that are being returned:

<WsGetMembersResults>
 ...
 <subjectAttributeNames>
  <string>name</string>
  <string>description</string>
  <string>foo</string>
  <string>uid</string>
  <string>cn</string>
  <string>sn</string>
  <string>givenName</string>
  <string>displayName</string>
 </subjectAttributeNames>
...
</WsGetMembersResults>

which should match the order of the attributes in the data for each member returned.  For example:

<WsSubject>
 ... 
 <attributeValues>
  <string>John C Doe</string>  (name)
  <string>John C Doe</string> (description)
  <string></string> (foo)
  <string>johncdoe</string> (uid)
  <string>John C Doe</string> (cn)
  <string>Doe</string> (sn)
  <string>John</string> (givenName)
  <string>Johnny Doeboy</string> (displayName)
 </attributeValues>
...
</WsSubject>

In other words, you should never hardcode the list of attributes to expect for each member.  If you do this, any newly added additional attributes being returned will probably break your code.  You should make sure that you are relying on subjectAttributeNames to determine the sequence of attributes to parse for each member.

Note that subjectAttributeNames may include attributes that you didn't explicitly request. That's why it's so important that you rely on subjectAttributeNames.

For example, in GetMembersLite and includeSubjectDetail=T in GetMembers, you will get back uid, cn, sn, givenName, and displayName for the same query.  It is not feasible to predict the sequence of attributes that will be returned because it depends on several settings: includeSubjectDetail/retrieveDetails, how we configured the Grouper server to append a default set of attributes, and whether you asked for specific attributes in your request.  You don't have to worry about this unpredictability if you simply read subjectAttributeNames.