Versions Compared

Old Version 21

changes.mady.by.user Emily Eisbruch (internet2.edu)

Saved on

compared with

New Version Current

changes.mady.by.user ben.rappleyea.2@at.internet2.edu

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Include Page
spaceKeyGrouper
pageTitleNavigation

The Attribute Framework

The attribute framework is used for attaching metadata to various objects in the registry.  One example is here. 

Table of Contents
For information about the Attribute Framework UI, see this page

Features

  • Attributes can be assigned to groups, memberships (immediate or effective), members (i.e. subjects), folders, other attributes, and attribute assignments (one level deep)
  • Attribute assignments have an optional "action" qualifier.  This is a free form string which is configured per attribute definition
  • Attributes could have free-form values, multi-valued, multi-assigned, limits as to where they can be applied, validation on values (TODO on validation), etc
  • Attributes can have enabled/disabled dates.  This is in progress.

Security on Attributes

  • have a definition (attributeDef), and a name (attributeName or aka attributeDefName).  
  • There is a one-to-many relationship between attributeDef and attributeName.  
  • The definition has all the configuration, and the name is assigned to the object


    Gliffy Diagram
    nameattributeDefToNameOneToMany
    pagePin5


     
  • Attributes can be assigned to groups, memberships (immediate or effective), members (i.e. subjects), folders, other attributes, and attribute assignments (one level deep)

    Gliffy Diagram
    nameattributeAssignTo
    pagePin2

     
  • Attribute assignments that are permissions have an optional "action" qualifier for permission type attributes.  This is a free form string which is configured per attribute definition

    Gliffy Diagram
    nameattributePermissionAction
    pagePin1

     
  • Attributes could have free-form values, multi-valued, multi-assigned, limits as to where they can be applied, validation on values (TODO on validation), etc

    Gliffy Diagram
    nameattributeAssignAndValueTypes
    pagePin1

     
  • Attributes can have enabled/disabled dates.

Security on Attributes

  • Attributes have security, coupled with other objects' security.  Each attribute has the following lists:
    • ATTR_VIEW: can see that the attribute exists
    • ATTR_READ: can see the attribute assignment
    • ATTR_UPDATE: can assign or unassign the attribute
    • ATTR_ADMIN: can rename the attribute or assign security
    • ATTR_OPTIN: can assign the attribute to one's self
    • ATTR_OPTOUT: can unassign the attribute to one's self
    • ATTR_DEF_ATTR_READ (v2.2+): can see attributes assigned to this attribute definition (note you need READ on the assigned attributes definition too)
    • ATTR_DEF_ATTR_UPDATE (v2.2+): can assign attributes to this attribute definition (note you need UPDATE on the assigned attributes definition too)
  • In order to perform operations on attributes, more security is needed on the underlying objects.  For example, to assign an attribute to a group, you need ATTR_UPDATE on the attribute and GROUP_ATTR_UPDATE on the group.  In order to assign an attribute to a membership, you need ATTR_UPDATE on the attribute, and UPDATE on the group.
  • To make attributes easier to use, you can set these settings in the grouper.properties to make attributes "public".  This means that if you have the appropriate security on the underlying object, you can add / edit / delete attributes from the object
  • Attribute assignments can be delegatable. 
  • Attributes have security, coupled with other objects' security.  Each attribute has the following lists:
    • ATTR_VIEW: can see that the attribute exists
    • ATTR_READ: can see the attribute assignment
    • ATTR_UPDATE: can assign or unassign the attribute
    • ATTR_ADMIN: can rename the attribute or assign security
    • ATTR_OPTIN: can assign the attribute to one's self
    • ATTR_OPTOUT: can unassign the attribute to one's self
  • In order to perform operations on attributes, more security is needed on the underlying objects.  For example, to assign an attribute to a group, you need ATTR_UPDATE on the attribute and GROUP_ATTR_UPDATE on the group.  In order to assign an attribute to a membership, you need ATTR_UPDATE on the attribute, and UPDATE on the group.
  • To make attributes easier to use, you can set these settings in the grouper.properties to make attributes "public".  This means that if you have the appropriate security on the underlying object, you can add / edit / delete attributes from the object
  • Attribute assignments can be delegatable.  You can identify as assignment as true for delegatable, false for not delegatable, or "grant" which means the user can delegate it, and set the delegate flag.
Code Block

attributeDefs.create.grant.all.attrRead          = true|false
attributeDefs.create.grant.all.attrUpdate        = true|false

...

  1. To be able to read an attribute assigned to an effective membership, you need attrRead (or attrAdmin) on the attribute and read (or admin) on the group.
  2. To be able to update an attribute assigned to an effective membership, you need attrUpdate (or attrAdmin) on the attribute and update (or admin) on the group.

Object types

Attribute definition (attributeDef):

...

Create an attribute definition in GHS GSH:

Code Block
addRootStem("school","school");
addStem("school", "attr", "attr");
addStem("school:attr", "students", "students");
grouperSession = GrouperSession.startRootSession();
attrStudentsStem = StemFinder.findByName(grouperSession, "school:attr:students");
studentsAttrDef = attrStudentsStem.addChildAttributeDef("students", AttributeDefType.attr);
studentsAttrDef.setAssignToGroup(true);
studentsAttrDef.store();

Create an attribute name

Code Block
attrArtsAndSciences = attrStudentsStem.addChildAttributeDefName(studentsAttrDef, "artsAndSciences", "artsAndSciences");

Assign an attribute name to an object:

Code Block
addStem("school", "math", "math");
groupBrainProject = addGroup("school:math", "brainProject", "brainProject");
groupBrainProject.getAttributeDelegate().assignAttribute(attrArtsAndSciences);

Set the security of an attribute definition

Code Block
groupStudents = addGroup("school", "students", "students");
studentsAttrDef.getPrivilegeDelegate().grantPriv(groupStudents.toSubject(), AttributeDefPrivilege.ATTR_READ, false);

...

Here   is   how   to   assign   the   same   attribute   multiple   times   (v1.6+)  \ [note,   needed   to   restart   GSH   to   clear   cache)
 Code Block

studentsAttrDef.setMultiAssignable(true);
studentsAttrDef.store();
-- RESTART GSH --
grouperSession = GrouperSession.startRootSession();
groupBrainProject = GroupFinder.findByName(grouperSession, "school:math:brainProject", true);
attrArtsAndSciences = AttributeDefNameFinder.findByName("school:attr:students:artsAndSciences", true);
groupBrainProject.getAttributeDelegate().addAttribute(attrAtrsAndSciencesattrArtsAndSciences);
groupBrainProject.getAttributeDelegate().addAttribute(attrAtrsAndSciencesattrArtsAndSciences);
groupBrainProject.getAttributeDelegate().addAttribute(attrAtrsAndSciencesattrArtsAndSciences);
groupBrainProject.getAttributeDelegate().retrieveAssignments(attrArtsAndSciences);

 Wiki MarkupHere   is   how   to   assign   a   value   (v1.6+)  \ [note,   needed   to   restart   GSH   to   clear   cache)
 Code Block

studentsAttrDef.setValueType(AttributeDefValueType.string);
studentsAttrDef.store();
groupBrainProject.getAttributeDelegate().retrieveAssignments(attrArtsAndSciences).iterator().next().getValueDelegate().assignValue("hey");

//or, assign directly from group based on name of attributeDefName

//note, you get a result that has the assignment object, and whether this was a new assignment, or already existed
//this is true for the value delegate, or the delegate on the assignment above
groupBrainProject.getAttributeValueDelegate().assignValue("school:attr:students:artsAndSciences", "hey");

 Wiki MarkupHere   is   how   to   assign   multiple   values   to   an   assignment    (v1.6+)  \ [note,   needed   to   restart   GSH   to   clear   cache).
 Code Block

studentsAttrDef.setMultiValued(true);
studentsAttrDef.store();

//again, this returns a result object that has the object
groupBrainProject.getAttributeDelegate().retrieveAssignments(attrArtsAndSciences).iterator().next().getValueDelegate().addValue("there");
groupBrainProject.getAttributeDelegate().retrieveAssignments(attrArtsAndSciences).iterator().next().getValueDelegate().retrieveValuesString();
java.util.ArrayList: [there, hey]

//you could also do this directly with the value delegate
groupBrainProject.getAttributeValueDelegate().addValue("school:attr:students:artsAndSciences", "there");
groupBrainProject.getAttributeValueDelegate().retrieveValuesString("school:attr:students:artsAndSciences");
java.util.ArrayList: [there, there]

...
Add a multi-valued attribute to a group, say mailAlternateAddress with two values "foo@memphis.edu" and "bar@memphis.edu".  Here is the API code:
 Code Block

AttributeDef attributeDef = stem.addChildAttributeDef("someName", AttributeDefType.attr); attributeDef.setAssignToGroup(true);
attributeDef.setMultiValued(true);
attributeDef.setValueType(AttributeDefValueType.string);
attributeDef.store();

AttributeDefName attributeDefName = stem.addChildAttributeDefaddChildAttributeDefName(attributeDef, "someNamemailAlternateAddress", AttributeDefType.attr"mailAlternateAddress"); attributeDef.setAssignToGroup(true);
attributeDef.setMultiValued(true);
attributeDef.setValueType(AttributeDefValueType.string);
attributeDef.store();

AttributeDefName attributeDefName = stem.addChildAttributeDefName(attributeDef, "mailAlternateAddress", "mailAlternateAddress");

group.getAttributeValueDelegate().assignValuesString(
	attributeDefName.getName(), GrouperUtil.toSet("foo@memphis.edu", "bar@memphis.edu"), true);

Example 2
Put an attribute on a membership


group.getAttributeValueDelegate().assignValuesString(
	attributeDefName.getName(), GrouperUtil.toSet("foo@memphis.edu", "bar@memphis.edu"), true);

Example 2
Put an attribute on a membership
 Code Block
gsh 0%
gsh 1% grouperSession = GrouperSession.startRootSession();
edu.internet2.middleware.grouper.GrouperSession: 3c50fffcfb104b39adbd55d05d47355 7,'GrouperSystem','application'
gsh 2% folder = StemFinder.findByName(grouperSession, "Communities:LVC:LSC:MOU:UWM:UWMGroupAttributes",true)
stem: name='Communities:LVC:LSC:MOU:UWM:UWMGroupAttributes' displayName='Communi ties:LVC:LSC:MOU:UWM:UWMGroupAttributes' uuid='97f4c134149941fbad8906d3a1ed2340'
gsh 3% attributeDef = folder.addChildAttributeDef("attr01", AttributeDefType.attr
 Code Block

gsh 0%
gsh 1% grouperSession = GrouperSession.startRootSession();
edu.internet2.middleware.grouper.attr.GrouperSession: 3c50fffcfb104b39adbd55d05d47355 7,'GrouperSystem','application'
gsh 2% folder = StemFinder.findByName(grouperSession, "Communities:LVC:LSC:MOU:UWM:UWMGroupAttributes",true)
stem: name='Communities:LVC:LSC:MOU:UWM:UWMGroupAttributes' displayName='Communi tiesAttributeDef: AttributeDef[name=Communities:LVC:LSC:MOU:UWM:UWMGroupAttributes:attr01,uuid=f8756aac777947ff9ae386786de4a287]
gsh 4% attributeDef.setAssignToImmMembership(true);
gsh 5% attributeDef.store();
gsh 6% myAttributeName = folder.addChildAttributeDefName(attributeDef,"myAttributeName","myAttributeName");
edu.internet2.middleware.grouper.attr.AttributeDefName: AttributeDefName[name=Communities:LVC:LSC:MOU:UWM:UWMGroupAttributes':myAttributeName ,uuid='97f4c134149941fbad8906d3a1ed2340'db8d3c93b30e4e2f96d3cdd9ae1af737]
gsh 3%7% attributeDefsubject = folderSubjectFinder.addChildAttributeDeffindById("attr01scott.koranda@LIGO.ORG", AttributeDefType.attrtrue);
edu.internet2.middleware.grouper.attr.AttributeDef: AttributeDef[name=Communities:LVC:LSC:MOU:UWM:UWMGroupAttributes:attr01,uuid=f8756aac777947ff9ae386786de4a287]
gsh 4% attributeDef.setAssignToImmMembership(true);
gsh 5% attributeDef.store();
gsh 6% myAttributeName = folder.addChildAttributeDefName(attributeDef,"myAttributeName","myAttributeName");
edu.internet2.middleware.grouper.attr.AttributeDefName: AttributeDefName[name=subject: id='scott.koranda@LIGO.ORG' type='person' source='ligo' name='Scott Koranda'
gsh 8% member = MemberFinder.findBySubject(grouperSession, subject, true);
member: id='scott.koranda@LIGO.ORG' type='person' source='ligo' uuid='56246fe035bd4266bc92abb617430033'
gsh 9% group = GroupFinder.findByName(grouperSession, "Communities:LVC:LSC:MOU:UWM:UWMGroupMembers");
group: name='Communities:LVC:LSC:MOU:UWM:UWMGroupAttributes:myAttributeName ,uuid=db8d3c93b30e4e2f96d3cdd9ae1af737]
gsh 7% subject = SubjectFinder.findById("scott.koranda@LIGO.ORG":UWMGroupMembers' displayName='Communities:LVC:LSC:MOU:UWM:UWMGroupMembers' uuid='00918b49-ad44-49aa-8b13-49d8a1aa459c'
gsh 10% membership = MembershipFinder.findImmediateMembership(grouperSession, group,subject,Group.getDefaultList(), true);
subject: id='scott.koranda@LIGO.ORG' type='person' source='ligo' name='Scott Koranda'
gsh 8% member = MemberFinder.findBySubject(grouperSession, subject, true);
member: id='scott.koranda@LIGO.ORG' type='person' source='ligo' uuid='56246fe035bd4266bc92abb617430033'
gsh 9% group = GroupFinder.findByName(grouperSession, "Communities:LVC:LSC:MOU:UWM:UWMGroupMembers");
group: name='Communities:LVC:LSC:MOU:UWM:UWMGroupMembers' displayName='Communities:LVC:LSC:MOU:UWM:UWMGroupMembers' uuid='00918b49-ad44-49aa-8b13-49d8a1aa459c'
gsh 10% membership = MembershipFinder.findImmediateMembership(grouperSession, group,subject,Group.getDefaultList(), true)
edu.internet2.middleware.grouper.Membership: Membership[createTime=1270587726584,creatorUuid=e00f1b26f1c340db8845e1dfe297f01b,depth=0,listName=members,listType=list,memberUuid=56246fe035bd4266bc92abb617430033,groupId=00918b49-ad44-49aa-8b13-49d8a1aa459c,type=immediate,uuid=faefbff7e2ce4561b86c7e070fcd0ac9:a5b12a759438462a996842dca313ccfc]
gsh 11% membership.getAttributeDelegate().assignAttribute(myAttributeName);
edu.internet2.middleware.grouper.attr.assign.AttributeAssignResult: edu.internet2.middleware.grouper.attr.assign.AttributeAssignResult@488e753c
gsh 12% membership.getAttributeDelegate().retrieveAssignments(myAttributeName);
edu.internet2.middleware.grouper.attr.assign.MembershipAttributeAssign: MembershipAttributeAssign[createTimeid=1270587726584350594e5dc39431ea56c17635eab253f,creatorUuidaction=e00f1b26f1c340db8845e1dfe297f01bassign,depth=0,listName=members,listType=list,memberUuid=56246fe035bd4266bc92abb617430033,groupId=00918b49-ad44-49aa-8b13-49d8a1aa459c,type=immediate,uuid=faefbff7e2ce4561b86c7e070fcd0ac9:a5b12a759438462a996842dca313ccfc]
gsh 11% membership.getAttributeDelegate().assignAttribute(myAttributeName);
edu.internet2.middleware.grouper.attr.assign.AttributeAssignResult: edu.internet2.middleware.grouper.attr.assign.AttributeAssignResult@488e753c
gsh 12% membership.getAttributeDelegate().retrieveAssignments(myAttributeName);
edu.internet2.middleware.grouper.attr.assign.AttributeAssign: AttributeAssign[id=350594e5dc39431ea56c17635eab253f,action=assign,attributeDefName=Communities:LVC:LSC:MOU:UWM:UWMGroupAttributes:evil,membershipId=faefbff7e2ce4561b86c7e070fcd0ac9]
gsh 13%

See Also
attributeDefName=Communities:LVC:LSC:MOU:UWM:UWMGroupAttributes:evil,membershipId=faefbff7e2ce4561b86c7e070fcd0ac9]
gsh 13%

Exclude attributes from audits, changelog, and point in time
 Code Block
# comma separated names of attribute defs will not be audited or change log or point in time
# same as ${edu.internet2.middleware.grouper.cfg.GrouperConfig.retrieveConfig().propertyValueStringRequired('grouper.attribute.rootStem')}
grouper.attribute.namesOfAttributeDefsToIgnoreAuditsChangeLogPit.elConfig = $$grouper.attribute.rootStem$$:userData:grouperUserDataValueDef,$$grouper.attribute.rootStem$$:instrumentationData:instrumentationDataInstanceCountsDef,$$grouper.attribute.rootStem$$:instrumentationData:instrumentationDataInstanceDetailsDef,$$grouper.attribute.rootStem$$:instrumentationData:instrumentationDataCollectorDetailsDef

# comma separated names of attribute def names will not be audited or change log or point in time
grouper.attribute.namesOfAttributeDefNamesToIgnoreAuditsChangeLogPit.elConfig = $$grouper.attribute.rootStem$$:attestation:attestationCalculatedDaysLeft,$$grouper.attribute.rootStem$$:attestation:attestationLastEmailedDate,$$grouper.attribute.rootStem$$:loaderMetadata:grouperLoaderMetadataLastFullMillisSince1970,$$grouper.attribute.rootStem$$:loaderMetadata:grouperLoaderMetadataLastIncrementalMillisSince1970,$$grouper.attribute.rootStem$$:loaderMetadata:grouperLoaderMetadataLastSummary




See Also