UserCriteriaLoader - API to Evaluate User Criteria

[Alikutty A]

User criteria is a powerful feature that allows you to setup data driven access controls by evaluating the user attributes of a logged-in user. It is extensible enough by allowing you to configure additional user attributes and also provide an advanced script evaluator that could add logic beyond the configurations. They are primarily used for controlling user access on service portals, catalog items, knowledge articles, HR services, HR contents etc. With a proper API, they could be extended further or used in any of your custom implementations.

ServiceNow has an undocumented API named UserCriteriaLoader which is used at multiple scripts within the instance. It can be used to control access and dynamically evaluate a user criteria for your custom solutions. Below, I am explaining all the methods that I was able to discover while using the same for one of my implementation.

1. getAllUserCriteria - Returns an array of all user criteria's matched by the logged in user

var allCriterias = new sn_uc.UserCriteriaLoader.getAllUserCriteria(gs.getUserID());
gs.info(allCriterias);
gs.info(allCriterias.length);

2. userMatches - Validates whether the user matches any of the user criteria's listed in the array and returns a boolean value ie true or false 

var userCriterias = ['6b6df061ff2121009b20ffffffffff44','0b5b0e6453631300afffddeeff7b1201'];
var userMatches = sn_uc.UserCriteriaLoader.userMatches(gs.getUserID(), userCriterias);
gs.info(userMatches);

3. getMatchingCriteria - Checks if the user criteria's passed in an array is matched by the user ID and returns the matching ones

var userCriterias = ['6b6df061ff2121009b20ffffffffff44','0b5b0e6453631300afffddeeff7b1201'];
var matchingCriterias = sn_uc.UserCriteriaLoader.getMatchingCriteria(gs.getUserID(), userCriterias);
gs.info(matchingCriterias);

4. getUserCriteria - Returns the list of user criteria's that are matched by the user from a specific table. For eg sc_cat_item_user_criteria_mtom or Catalog Item Available For is the table used to control access for catalog items and the function will return all user criteria's from this table that are matched by the user

var getCriterias = new sn_uc.UserCriteriaLoader.getUserCriteria(gs.getUserID(),'sc_cat_item_user_criteria_mtom');
gs.info(getCriterias);

SNC.UserCriteriaLoader is another related API used in the instance but it is not supported in scoped applications.

Note: The user criterias are by default not overridden by admin users and you will have to explicitly grant them access. Script based user criterias are cached, hence the changes wont reflect unless the user has logged out of the instance.

[Joe Pruitt]

This is very useful!. Do you know if there is a plan to "officially" support this javascript API (var allCriterias = new sn_uc.UserCriteriaLoader.getAllUserCriteria(user_sys_id) Thanks!

[xease]

Hi

Can you let me know in which files were you able to find getMatchingCriteria, getAllUserCriteria methods. I did a code search across all applications in studio and only got results with userMatches function.

Thanks in advance.

[Community Alums]

This was extremely helpful, saved me a lot of time.  We had an issue where some standard change templates were being misused by end users who were using a saved URL to open the standard change, even though the user criteria of the template excludes the user opening the change record.  I used this to create a business rule to block insert of the change if the logged in user does not match the User Criteria on the applied Standard Change Template using the getMatchingCriteria function.  This ensures that users cannot erroneously open a standard change using a template that they do not have the proper matching User Criteria.  Thanks for sharing this info!

[Markus Kraus]

I don't use user criteria all that often - but when I do I always come back to this post. Thanks a lot for this!

Some additions:

The API shown in this post is made available via the plugin: com.glideapp.user_criteria.scoped.api

Before using the API in a script, a caller should first test if this plugin is installed:

new GlidePluginManager().isActive('com.glideapp.user_criteria.scoped.api')

[Ravi Chandra_K]

How did I miss this!!!

This is super helpful content ✨

Thank you!

[Sachin Dahiya]

thanks Ali. This is really helpful.

[Khanna Ji]

getAllUserCriteria  - It's a killer. It should never be used.

[johnmark]

UserCriteriaLoader.getAllUserCriteria() method is a deprecated method and we advice using userMatches() instead.

☞ Please refer to this article below, which explains on this in detailed.
https://www.servicenow.com/community/now-platform-blog/a-deep-dive-to-user-criteria/ba-p/2281285

Below are additional Knowledge articles which discusses Semaphore Exhaustion caused by the getAllUserCriteria function being called in widgets:

Semaphore Exhaustion is caused due to the getAllUserCriteria function getting called in widgets

Semaphores keep getting stuck and cause slow performance due to UserCriteriaLoader.getAllUserCriteri...

[Ramon Cordova]

Is this API still valid?
When I tested it, I was getting the "userMatches" method as undefined.

[Markus Kraus]

@Ramon Cordova

you need to use it without 'new':

correct: var userMatches = sn_uc.UserCriteriaLoader.userMatches

incorrect: var userMatches = new sn_uc.UserCriteriaLoader().userMatches