DynamicRefQuals (Client-callable Script Include)

DynamicRefQuals.js

var DynamicRefQuals= Class.create();
DynamicRefQuals.prototype = Object.extendsObject(AbstractAjaxProcessor, {

	//Client-callable
	/*
		To quickly and easily create a dynamic reference qualifier script, simply add a custom method to this Script Include.
		Here are the guidelines for modifying this Script Include:
		1. In the "@author" JSDoc tag of the method your implement, please put your user ID (For example: "twoodruff").
		2. See how the getGroupMembersByID and getGroupMembersByName methods are documented, and try to document your method in the same fashion.
		3. Unless you've got permission from the author, please do not modify anyone else's methods.
		4. Make your refqual method as generalized as possible, so that others can re-use it.
		For example, rather than name your method "getMembersOfOps()" and statically coding the sys_id of some group in the body of the method, you could name your method "getMembersOfGroup(groupID)" and accept one string argument (groupID) with the sys_id (or maybe name?) of the group to get the members of!
	*/
	
	/**
	 * Get a comma-separated list of the members of the group in question.
	 * @author twoodruff <tim@snprotips.com>
	 * @param {string} groupID - The sys_id of the group to retrieve the members of.
	 * @param {string} [userField=sys_id] - The field from the sys_user table to return
	 *  (typically you'll want this to be sys_id)
	 * @param {boolean} [activeUsersOnly=true] - Whether to only get users which are active in the system.
	 * This makes the query more efficient, and will return far fewer results.
	 * @returns {Array} - An array of the members of the group in question, by the value specified
	 *  in the userFieldToReturn argument. For example, if "sys_id" is specified, this will be an array
	 *  of the sys_ids of the users who are members of the specified group.
	 * @example
	 * //Gets the sys_ids for every user that is a member of the group with sys_id "group_sys_id", even if they're not active
	 * new DynamicRefQuals().getGroupMembersByID('group_sys_id', 'sys_id', false);
	 * @example
	 * //Gets the user_names of every ACTIVE user that is a member of the group with sys_id "group_sys_id".
	 * new DynamicRefQuals().getGroupMembersByID('group_sys_id', 'user_name');
	 * @example
	 * //Gets the sys_ids for every ACTIVE user that is a member of the group with sys_id "group_sys_id"
	 * new DynamicRefQuals().getGroupMembersByID('group_sys_id');
	 */
	getGroupMembersByID: function(groupID, userField, activeUsersOnly) {
		userField = (!userField) ? ('sys_id') : (userField);
		activeUsersOnly = (typeof activeUsersOnly == 'undefined') ? (true) : (activeUsersOnly);
		
		return this._getGroupMembers(groupID, 'sys_id', userField, activeUsersOnly);
		
	},
	
	/**
	 * Get a comma-separated list of the members of the group in question.
	 * @author twoodruff <tim@snprotips.com>
	 * @param {string} groupName - The value of the "name" field on the group (sys_user_group) table.
	 * @param {string} [userField=sys_id] - The field from the sys_user table to return
	 *  (typically you'll want this to be sys_id)
	 * @param {boolean} [activeUsersOnly=true] - Whether to only get users which are active in the system.
	 * This makes the query more efficient, and will return far fewer results.
	 * @returns {Array} - An array of the members of the group in question, by the value specified
	 *  in the userFieldToReturn argument. For example, if "sys_id" is specified, this will be an array
	 *  of the sys_ids of the users who are members of the specified group.
	 * @example
	 * //Gets the sys_ids for every user that is a member of the group "group_name", even if they're not active
	 * new DynamicRefQuals().getGroupMembersByName('group_name', 'sys_id', false);
	 * @example
	 * //Gets the user_names of every ACTIVE user that is a member of the group "group_name".
	 * new DynamicRefQuals().getGroupMembersByName('group_name', 'user_name');
	 * @example
	 * //Gets the sys_ids for every ACTIVE user that is a member of the group "group_name"
	 * new DynamicRefQuals().getGroupMembersByName('group_name');
	 */
	getGroupMembersByName: function(groupName, userField, activeUsersOnly) {
		userField = (!userField) ? ('sys_id') : (userField);
		activeUsersOnly = (typeof activeUsersOnly == 'undefined') ? (true) : (activeUsersOnly);
		
		return this._getGroupMembers(groupName, 'name', userField, activeUsersOnly);
	},
	
	/****PLACE ALL PRIVATE HELPER FUNCTIONS BELOW THIS LINE****/
	/****BEGIN ALL HELPER FUNCTION NAMES WITH AN UNDERSCORE****/
	
	/**
	 * Flexible private helper function to get group members
	 * @author twoodruff <tim@snprotips.com>
	 * @param {string} groupFieldVal - The value of the field on the group (sys_user_group) table.
	 * If groupFieldName is not specified, then this will be the sys_id of the group you want to get
	 *  the members of. If it IS specified, it'll be the value of the field indicated in that argument.
	 * @param {string} [groupFieldName=sys_id] - The field on the group (sys_user_group) table to search
	 *  for the value specified in the groupFieldVal argument.
	 * @param {string} [userFieldToReturn=sys_id] - The field from the sys_user table to return
	 *  (typically you'll want this to be sys_id)
	 * @param {boolean} [activeUsersOnly=true] - Whether to only get users which are active in the system.
	 * This makes the query more efficient, and will return far fewer results.
	 * @returns {Array} - An array of the members of the group in question, by the value specified
	 *  in the userFieldToReturn argument. For example, if "sys_id" is specified, this will be an array
	 *  of the sys_ids of the users who are members of the specified group.
	 * @private
	 */
	_getGroupMembers: function(groupFieldVal, groupFieldName, userFieldToReturn, activeUsersOnly) {
		var queryField;
		var groupUsers = [];
		var grGroupMember = new GlideRecord('sys_user_grmember');
		
		//Set default values
		groupFieldName = (!groupFieldName) ? 'sys_id' : groupFieldName.toLowerCase();
		userFieldToReturn = (!userFieldToReturn) ? 'sys_id' : userFieldToReturn.toLowerCase();
		activeUsersOnly = (typeof activeUsersOnly == 'undefined') ? true : activeUsersOnly;
		
		//Determine what the left side of the query statement should look like
		queryField = (groupFieldName == 'sys_id') ? ('group') : ('group.' + groupFieldName);
		
		/*Normally I'd put the conditional block above the addQuery line for aesthetic reasons,
			but	query param order matters, and this is slightly more efficient.*/
		grGroupMember.addQuery(queryField, groupFieldVal);
		if (activeUsersOnly) {
			grGroupMember.addQuery('user.active', 'true');
		}
		grGroupMember.query();
		
		//Push each user into the array by the value specified in userFieldToReturn
		while (grGroupMember.next()) {
			if (userFieldToReturn == 'sys_id') {
				groupUsers.push(grGroupMember.getValue('user'));
			} else {
				groupUsers.push(grGroupMember.user[userFieldToReturn].toString());
			}
		}
		
		return groupUsers;
	},
	
	type: 'DynamicRefQuals'
});