KIM Types

Implementing Custom KIM Types

KIM uses types to add additional attributes to objects (currently, groups and roles) and to affect their behavior.

Basic Service Requirements

All custom type services must implement a sub-interface of org.kuali.rice.kim.service.support.KimTypeService based on the type of custom type being created.

Your custom type service class should extend the appropriate subclass of org.kuali.rice.kim.service.support.impl.KimTypeServiceBase and only override the methods necessary to implement your custom behavior. Use the methods in these classes as the basis for your custom code.

public class MyTypeService extends KimTypeServiceBase
 implements KimTypeService {
    // Do something


}

Method getAttributeDefinitions

This method retrieves the map of attribute definitions related to a type. The map is keyed on the sort code of the attribute definition.

Parameters:

  • kimTypeId – The ID of the KIM type

Method getUniqueAttributes

This method retrieves the list of attribute names related to a type that uniquely defines the principal. For any given principal, there should be only one assignment (for example, a role assignment or type assignment) that contains the particular set of values for these attributes.

Parameters:

  • kimTypeId – The ID of the KIM type

Method getWorkflowDocumentTypeName

This method returns the name of the workflow document type that will be used for the role qualifiers when you route objects with this type. If no special document type is needed, this method must return null.

Parameters: None

Method getWorkflowRoutingAttributes

This method returns the names of attributes that need to be passed to workflow for route processing.

Parameters:

  • routeLevel – The routing level

Method validateAttributes

This method performs validation on the attributes of an object. The default implementation ensures that the values fit within type and length constraints and, if there is a look-up table for the values, that the value exists and is active. If null is returned or the map is empty, no validation errors were detected.

Parameters:

  • kimTypeId – The ID of the KIM type

  • attributes – The attributes on the object

Method validateAttributesAgainstExisting

This method performs validation on the attributes of an object. The default implementation does not do any checking but simply returns an empty map. If null is returned or the map is empty, no validation errors were detected.

Parameters:

  • kimTypeId – The ID of the KIM type

  • newAttributes – The new attributes on the object

  • oldAttributes – The old attributes on the object

Method validateUniqueAttributes

This method performs validation on the unique attributes of an object. The default implementation ensures that the principal does not have another assignment that duplicates the new values. If null is returned or the map is empty, no validation errors were detected.

Parameters:

  • kimTypeId – The ID of the KIM type

  • newAttributes – The new attributes on the object

  • oldAttributes – The old attributes on the object

Method validateUnmodifiableAttributes

This method performs validation on the unique attributes of an object. The default implementation ensures that these values are not being changed. If null is returned or the map is empty, no validation errors were detected.

Parameters:

  • kimTypeId – The ID of the KIM type

  • newAttributes – The new attributes on the object

  • oldAttributes – The old attributes on the object

KIM Group Type Service

Classes that customize the handling of group qualifiers must implement org.kuali.rice.kim.framework.group.GroupTypeService. This document contains a brief description of the methods specific to group types. Please refer to the Implementing Custom KIM Types document for information on methods common to all custom type services. Please also refer to the API javadocs for more details on the methods described here.

Java Class Information

Your custom type service class should extend org.kuali.rice.kns.kim.group.GroupTypeServiceBase and only override the methods necessary to implement your custom behavior. Use the methods in this class as the basis for your custom code.

public class MyGroupTypeService extends KimGroupTypeServiceBase
 implements KimGroupTypeService {

    // Do something
}

Methods Specific to Group Types

There are no methods specific to group types.

KIM Permission Type Service

Classes that customize the handling of permission qualifiers and implement custom permission checks must implement org.kuali.rice.kim.api.permission.KimPermissionTypeService. This document contains a brief description of the methods specific to permission types. Please refer to the Implementing Custom KIM Types document for information on methods common to all custom type services. Please also refer to the API javadocs for more details on the methods described here.

Java Class Information

Your custom permission type service class should extend org.kuali.rice.kns.kim.permission.PermissionTypeServiceBase and only override the methods necessary to implement your custom behavior. Use the methods in this class as the basis for your custom code.

public class MyPermissionionTypeService extends KimPermissionTypeServiceBase
 implements KimPermissionTypeService {
    // Do something
}

Methods Specific to Permission Types

Method getMatchingPermissions

This method is called to find the permission assignments that are applicable for the request. The implementation of this method must not modify the parameters in any way.

Parameters:

  • requestedDetails – The details in the request

  • permissionsList – The list of permissions to check

Method performPermissionMatches

This method is called by getMatchingPermissions to find the matching permissions. You can override this method to customize the way that matches are made without replicating the rest of the getMatchingPermissions method. The implementation of this method must not modify the parameters in any way.

Parameters:

  • requestedDetails – The details in the request

  • permissionsList – The list of permissions to check

KIM Responsibility Type Service

Classes that customize the handling of responsibility qualifiers and implement custom responsibility checks must implement org.kuali.rice.kim.service.support.KimResponsibilityTypeService. This document contains a brief description of the methods specific to responsibility types. Please refer to the Implementing Custom KIM Types document for information on methods common to all custom type services. Please also refer to the API javadocs for more details on the methods described here.

Java Class Information

Your custom permission type service class should extend org.kuali.rice.kim.service.support.impl.KimResponsibilityTypeServiceBase and only override the methods necessary to implement your custom behavior. Use the methods in this class as the basis for your custom code.

public class MyResponsibilityTypeService extends KimResponsibilityTypeServiceBase
 implements KimResponsibilityTypeService {

    // Do something
}

Methods Specific to Responsibility Types

Method getMatchingResponsibilities

This method is called to find the responsibility assignments that are applicable for the request. The implementation of this method must not modify the parameters in any way.

Parameters:

  • requestedDetails – The details in the request

  • responsibilitiesList – The list of responsibilities to check

Method performResponsibilityMatches

This method is called by getMatchingResponsibilities to find the matching responsibilities. This method can be overridden to customize the way that matches are made without replicating the rest of the getMatchingResponsibilities method. The implementation of this method must not modify the parameters in any way.

Parameters:

  • requestedDetails – The details in the request

  • responsibilitiesList – The list of responsibilities to check

KIM Role Type Service

Classes that customize the handling of role qualifiers and implement custom role membership must implement org.kuali.rice.kim.service.support.KimRoleTypeService. This document contains a brief description of the methods specific to role types. Please refer to the Implementing Custom KIM Types document for information on methods common to all custom type services. Please also refer to the KIM API documentation for more details on the methods described here.

Java Class Information

Your custom type service class should extend one of the following classes (all in the package org.kuali.rice.kim.service.support.impl):

  • KimDerivedRoleTypeServiceBase – Roles with derived membership

  • PrincipalDerivedRoleTypeServiceImpl – Derived roles with only principals as members

  • KimRoleTypeServiceBase – Basic role implementation

Only override the methods necessary to implement your custom behavior. Use the methods in these classes as the basis for your custom code.

public class MyRoleTypeService extends KimPrincipalDerivedRoleTypeServiceImpl
 implements KimRoleTypeService {
    // Do something


}

Methods Specific to Role Types

Method convertQualificationAttributesToRequired

This method converts qualifier attributes based on the needs of the role. For example, a role that is based on campus might convert the organization-based attributes “chart=BL,org=PSY” into the attribute “campus=BLOOMINGTON”. The implementation of this method must not modify the parameter in any way.

Parameters:

  • qualificationAttributes – The qualifier attributes to convert

Method convertQualificationForMemberRoles

This method converts qualifier attributes for use by roles that are a member of the role. The implementation of this method must not modify the parameters in any way.

Parameters:

  • namespaceCode – The name space code for this role

  • roleName – The name for this role

  • memberRoleNamespaceCode – The name space code for the member role

  • memberRoleName – The name for the member role

  • qualification – The qualifiers applied to the role assignment

Method doesRoleQualifierMatchQualification

This method returns true if the qualifications applied to a role assignment match the qualifiers applied to a role, false if they don’t match. The implementation of this method must not modify the parameters in any way.

Parameters:

  • qualification – The qualifiers applied to the role assignment

  • roleQualifier – The qualifiers applied to the role

Method doRoleQualifiersMatchQualification

This method finds the subset of member roles where the qualifications applied to a role assignment match the qualifiers applied to a role. The implementation of this method must not modify the parameters in any way.

Parameters:

  • qualification – The qualifiers applied to the role assignment

  • roleMemberList – The role members to check

Method getRoleMembersFromApplicationRole

This method returns the list of role members based on an application role. The implementation of this method must not modify the parameters in any way.

Parameters:

  • namespaceCode – The name space code for the application role

  • roleName – The name for the application role

  • qualification – The qualifiers applied to the search

Method hasApplicationRole

This method returns true if the given principal has this application role, false if not. The implementation of this method must not modify the parameters in any way.

Parameters:

  • principalId – The ID of the principal

  • groupIds – The complete list of groups in which the principal belongs

  • namespaceCode – The name space code for the application role

  • roleName – The name for the application role

  • qualification – The qualifiers applied to the search

Method isApplicationRoleType

This method returns true if the role as an application role, false if not. This means that the application defines the members of the role, not KIM.

Parameters: None

Method principalInactivated

The Role Service calls this method when a principal is inactivated. This allows an application role to perform any necessary clean up.

Parameters:

  • principalId – The ID of the principal

  • namespaceCode – The name space code for the application role

  • roleName – The name for the application role

Method sortRoleMembers

This method sorts a list of roles being returned by RoleService.getRoleMembers. The list passed as a parameter may be modified and returned rather than generating a new list. If the order of the members is not meaningful, the parameter may simply be returned.

Parameters:

  • roleMembers – The list of role members to sort

Method shouldCacheRoleMembershipResults

RoleManagementService caches information about role membership, based on the assumption that most roles are fairly stable in terms of membership. Returning true from this method allows RoleManagementService to cache the results of membership calls (specifically principalHasRole and getRoleMembers). Returning false prevents caching. Roles with highly volatile membership sets should return false from this method, so that all membership changes are taken into consideration during permission and responsibility calls.

Parameters:

  • namespaceCode – The namespace code of the role which is being tested for allowing of membership information caching.

  • roleName – The name of the role which is being tested for allowing of membership information caching.