role-hierarchy

Role Hierarchy Data Model

This is a data model for a hierarchy of roles, suitable for mongodb users or meteor.

Given a definition of a role hierarchy :

  let hierarchyObj = {
      "name": "admin",
      "subordinates": [
        {
          "name": "user-admin",
          "subordinates": [
            {
              "name": "schoolAdmin",
              "subordinates": [
                {
                  "name": "teacher",
                  "subordinates": [
                    {
                      "name": "student",
                      // a student can see the following fields
                      "visibleUserFields": {
                        "_id": 1,
                        "username": 1,
                        "profile.name": 1,
                        "roles": 1
                      }
                    }
                  ],
                  // new users created by a teacher get the student role
                  "defaultNewUserRoles": [
                    "student"
                  ],
                  // new users created by a teacher get the teacher's profile.school and profile.classId
                  "profileFilters": [
                    "school",
                    "classId"
                  ],
                  // a teacher can see everything a student can see, also email addresses
                  "visibleUserFields": {
                    "emails": 1
                  }
                }
              ],
              "profileFilters": [
                "school"
              ]
            },
            {
              "name":"footballCoach",
              "subordinates":[
                {
                  "name": "footballCaptain",
                  "subordinates" :[
                    {
                      "name":"footballPlayer"
                    }
                  ]
                }
              ]
            }
          ],
          "defaultNewUserRoles": [
            "teacher"
          ]
        }
      ],
      "defaultNewUserRoles": [
        "teacher"
      ]
    }
 
    let roleHierarchy = new RoleHierarchy(
      {
        "rolesHierarchy": hierarchyObj),
        "loggingConfig": { level: "debug" },
        treeModelConfig: { "childrenPropertyName": "subordinates" },
      }      
    );

And a user :

  let myUserObj = {
    _id: 'abc123',
    profile: {
      organizations: ['springfield school', 'springfield football team']
    },
    "roles": {
      "springfield school": [
        "schoolAdmin",
        "footballCaptain"
      ],
      "springfield football team": [
        "footballCoach"
      ]
 
    }
  };

You can find information about the user's subordinates.

let subordinatesMap = roleHierarchy.getAllUserSubordinatesAsMap(myUserObj);
/*
{
        "springfield school": ["teacher", "student", "footballPlayer"],
        "springfield football team": ["footballCaptain", "footballPlayer"]
      }
*/

Or about a role's subordinates

let subordinatesArray = roleHierarchy.getAllSubordinateRolesAsArray('schoolAdmin');
/*
["teacher", "student"]
*/

Tests

Look in the test/test.js file, it gives you a pretty good idea of how to use this library.

To run the tests, simply :

npm test

API

docs generated with jsdoc2md

RoleHierarchy

Kind: global class

• RoleHierarchy
  • new RoleHierarchy(paramsObj)
  • instance
    • .reparse(rolesHierarchy)
    • ._getOrganizationsForUser(myUserObj)
    • .findRoleInHierarchy(roleName) ⇒ object
    • .getRoleSubordinate(seniorRoleName, subordinateRoleName) ⇒ object
    • .getAllSubordinateRolesAsArray(seniorRoleName) ⇒ Array
    • .getAllUserSubordinatesAsMap(myUserObj) ⇒ Object
    • .getAllMyFieldsAsObject(myUserObj) ⇒ object
    • .isUserHasMoreSeniorRole(myUserObj, roleName, organizationName) ⇒ boolean
    • .isUserDescendantOfUser(seniorUserObj, subordinateUserObj, organizationName) ⇒ boolean
    • .getProfileCriteriaFromUser(userWithProfile, profileFilterCriteria, organizationName) ⇒ object
  • static
    • .getOrganizationsForUser(myUserObj) ⇒ Array.<String>
    • .getRolesForUser(user, organization) ⇒ Array
    • ._getRolesForUser(user, organization)

new RoleHierarchy(paramsObj)

create a new instance of RoleHierarchy

Param	Type	Description
paramsObj	Object	containing a hierarchy and a loggingConfig (optional) and a TreeModel config (optional): { hierarchy: {"name":"teacher", "subordinates": [ {"name":"student"} ]}, treeModelConfig: { "childrenPropertyName": "subordinates" }, loggingConfig: { "level": "debug"}}

roleHierarchy.reparse(rolesHierarchy)

re-create the hierarchy with a new object structure.

Kind: instance method of RoleHierarchy

Param	Type
rolesHierarchy	Object

roleHierarchy._getOrganizationsForUser(myUserObj)

Deprecated - use RoleHierarchy.getOrganizationsForUser instead.

Kind: instance method of RoleHierarchy

Param	Type
myUserObj	*

roleHierarchy.findRoleInHierarchy(roleName) ⇒ object

Find a role in the hierarchy by name

Kind: instance method of RoleHierarchy Returns: object - - the node in the tree that matches

Param	Type	Description
roleName	string	the name of the role to find

roleHierarchy.getRoleSubordinate(seniorRoleName, subordinateRoleName) ⇒ object

Return the subordinate roles of the given seniorRoleName

Kind: instance method of RoleHierarchy Returns: object - - the role of the subordinate, or false if not found.

Param	Type	Description
seniorRoleName	string	the name of the senior role
subordinateRoleName	string	the name of the subordinate role

roleHierarchy.getAllSubordinateRolesAsArray(seniorRoleName) ⇒ Array

Get the names of subordinate roles as an array

Kind: instance method of RoleHierarchy Returns: Array - - the subordinate role names if any, otherwise undefined.

Param	Type	Description
seniorRoleName	string	the name of the senior role

roleHierarchy.getAllUserSubordinatesAsMap(myUserObj) ⇒ Object

Get a map of all of the role names that the provided user can administer, grouped by organization

Kind: instance method of RoleHierarchy Returns: Object - an object of subordinate {organization:[roleName, roleName]} arrays that the provided user can administer

Param	Description
myUserObj	the user object of the provided user, with a roles property and a profile.organization or profile.organizations

roleHierarchy.getAllMyFieldsAsObject(myUserObj) ⇒ object

Get an object of all of the Meteor.user fields that the provided user can see

Kind: instance method of RoleHierarchy Returns: object - an object of the format {orgName: [{field1: 1, field2: 2}]}, the values being Meteor.user field names that the provided user can see, suitable for inclusion as a "fields" property in a mongodb Collection query.

Param	Description
myUserObj	the user object of the provided user, with a roles property

roleHierarchy.isUserHasMoreSeniorRole(myUserObj, roleName, organizationName) ⇒ boolean

returns true if the given object is more senior than the given role in the given organization.

Kind: instance method of RoleHierarchy Returns: boolean - true if the user is more senior than the given role

Param	Description
myUserObj	the user object of the provided user, with a roles property and an organization(s) property
roleName	the name of the role to query
organizationName	the name of the organization to query whether the user has the role

roleHierarchy.isUserDescendantOfUser(seniorUserObj, subordinateUserObj, organizationName) ⇒ boolean

returns true if the given senior user is higher in the hierarchy than the given subordinate user for the given organization.

Kind: instance method of RoleHierarchy Returns: boolean - true if the subordinateUser is below seniorUser in the hierarchy for at least one organization in common.

Param	Description
seniorUserObj	the senior user we're checking, with roles property and organization(s) property
subordinateUserObj	the user we want to check see if they are subordinate to the senior user, with roles property and organization(s) property
organizationName	the name of the organization whose roles to check

roleHierarchy.getProfileCriteriaFromUser(userWithProfile, profileFilterCriteria, organizationName) ⇒ object

Copy the given user's profile properties (as specified in roles hierarchy as profileFilters) as profile properties suitable for adding to a new user.

Kind: instance method of RoleHierarchy Returns: object - the query criteria, suitable for mongodb, to ensure only users with the same values for the specified fields will be returned.

Param	Type	Description
userWithProfile	object	the user object, with a profile property to copy
profileFilterCriteria	object	existing profileFilterCriteria. Note that if any properties are already specified, they may get overwritten.
organizationName	string	the organization we're dealing with.

RoleHierarchy.getOrganizationsForUser(myUserObj) ⇒ Array.<String>

Get the organizations that the user belongs to, as an array.

Kind: static method of RoleHierarchy Returns: Array.<String> - an array of the organizations that the user belongs to.

Param	Type	Description
myUserObj	Object	an object containing an organization or organizations property.

RoleHierarchy.getRolesForUser(user, organization) ⇒ Array

Retrieve users roles

Kind: static method of RoleHierarchy Returns: Array - Array of user's roles, unsorted.

Param	Type	Description
user	Object	user object
organization	String	Optional name of organization to restrict roles to. User's _GLOBAL_GROUP will also be included.

RoleHierarchy._getRolesForUser(user, organization)

Deprecated. Use RoleHierarchy.getRolesForUser instead.

Kind: static method of RoleHierarchy

Param	Type
user	*
organization	*