---
sourceDocument: Xanadu API Reference
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/xanadu/api-reference

 Release :

    - xanadu

ft:locale :

    - en-US

ft:publication_title :

    - Xanadu API Reference

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# UserSkillAnalyzer - Global

# UserSkillAnalyzer - Global {#ariaid-title1}

* Release version: Xanadu
* 
* Updated August 1, 2024
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 4 minutes to read

The UserSkillAnalyzer API provides methods to analyze user skills against skills required to complete work items.

This API requires the Skills Management plugin (com.snc.skills_management), which you can activate if you have the admin role.

See [Qualify and rank users based on skills and skill levels](https://www.servicenow.com/docs/access?context=assign-work-based-on-skills&version=xanadu&pubname=xanadu-servicenow-platform&ft:locale=en-US).

## UserSkillAnalyzer - UserSkillAnalyzer() {#ariaid-title2}

Instantiates a new UserSkillAnalyzer object.
{#USA-UserSkillAnalyzer__table_shf_4b1_whb__entry__3}

| Name | Type | Description |
|-|-|-|
| None |   |   |
[Table 1. Parameters]

{#USA-UserSkillAnalyzer__table_shf_4b1_whb}  


    var userSkillAnalyzer = new SNC.UserSkillAnalyzer();

## UserSkillAnalyzer - analyzeUserByID(String requiredSkillsJson, String userID, Boolean
isSkillLevelEnforced) {#ariaid-title3}

Analyzes user skills against the required skills and sets the number of matching
skills, skill level gap, and qualification that can be collected from an instance.
Analyzes whether an agent is qualified to work on a task by verifying if the agent has the
skills and skill levels required to complete the task. If an agent is qualified to work on a
task, the API analyzes the level gap between required skills and user's skill level which
can be further used by the application to choose the best agent based on level gap. It also
analyzes the total number of skills with and without skill levels the agent has to execute
that task.
{#USA-analyzeUserById_S_S_B__table_qps_bzr_lhb__entry__3}

| Name | Type | Description |
|-|-|-|
| requiredSkillsJson | String | List of required skills to compare with user. Each skill is listed as a JSON entry in the following format: * sys_id: String. Sys ID of skill from the Skills \[cmn_skill\] table. * is_mandatory: Boolean. Flag that indicates whether the skill is mandatory. * level: String. Sys ID from the Skill Levels \[cmn_skill_level\] table. {#USA-analyzeUserById_S_S_B__ul_q2f_xsw_33b} |
| userID | String | Sys ID from the User \[sys_user\] table. |
| isSkillLevelEnforced | Boolean | True if user must have a minimum skill level for all required mandatory skills, false otherwise. Default: false. |
[Table 2. Parameters]

{#USA-analyzeUserById_S_S_B__table_qps_bzr_lhb} {#USA-analyzeUserById_S_S_B__table_kct_qrw_33b__entry__2}

| Type | Description |
|-|-|
| String | JSON that contains all the required information about the user based on the analyzer skills map as follows: * sys_id: String. Sys ID from the User \[sys_user\] table. * is_qualified: Boolean. Flag that indicates whether the user is qualified for the required skills. * True if user has all the mandatory skills and skill level is enforced. * False if user does not have all mandatory skills or does not meet level requirements. {#USA-analyzeUserById_S_S_B__ul_ql2_rhq_g3b} * num_skills: Number. Skills matched against the required skills. * num_skills_matching_level: Number. User skills matching the required skill level. * total_skill_level_gap: Number. Skill level gap helps ranking algorithm find optimal user meeting minimum skill level requirements. Calculated based on overall gap between task skill level and user skill level. User must have required skill level for mandatory skills. * optional_skill_level_gap: Number. Provides skill level gap for optional skills only. Assists the end points in distinguishing between total skill level and optional skill level gap. {#USA-analyzeUserById_S_S_B__ul_q1n_msd_f3b} Error if inaccurate parameters or malformed JSON provided. |
[Table 3. Returns]

{#USA-analyzeUserById_S_S_B__table_kct_qrw_33b}  

    var skills = [{"sys_id":"48c9f873c0a8018b65c3814608b201e6", "is_mandatory": true, "level":"4e0ac4d6b3332300290ea943c6a8dc4e"},
    			  {"sys_id":"48c9fdddc0a8018b04bd8d7914c82c9d", "is_mandatory": false, "level":"4e0ac4d6b3332300290ea943c6a8dc4e"}];
    var userSysID = "a8f98bb0eb32010045e1a5115206fe3a";
    var userSkillAnalyzer = new SNC.UserSkillAnalyzer();
    var result = userSkillAnalyzer.analyzeUserById(JSON.stringify(skills), userSysID, true);
    gs.info('Results: ' + result);

Output:

    Calling user analyzer
    *** Script: Results: {"sys_id":"a8f98bb0eb32010045e1a5115206fe3a","is_qualified":false,"num_skills":0,"num_skills_matching_level":0,"total_skill_level_gap":0,"optional_skill_level_gap":0}

## UserSkillAnalyzer - analyzeUserBySkills(String requiredSkillsJson, String userSkillsJson,
Boolean isSkillLevelEnforced) {#ariaid-title4}

Analyzes user skills against the required skills and sets the number of matching
skills, skill-level gap, and qualification that can be collected from an instance.
{#USA-analyzeUserBySkills_S_S_B__table_crq_fzr_lhb__entry__3}

| Name | Type | Description |
|-|-|-|
| requiredSkillsJson | String | List of required skills to qualify the users against. Each skill is listed as a JSON entry in the following format: * sys_id: String. Sys ID of skill from the Skills \[cmn_skill\] table. * is_mandatory: Boolean. Flag that indicates whether the skill is mandatory. * level: String. Sys ID from the Skill Levels \[cmn_skill_level\] table. {#USA-analyzeUserBySkills_S_S_B__ul_imx_vsw_33b} |
| userSkillsJson | String | List of user skills to determine qualification for required skills. Each skill is listed as a JSON entry in the following format: * sys_id: String. Sys ID of skill from the Skills \[cmn_skill\] table. * is_mandatory: Boolean. Flag that indicates whether the skill is mandatory. * level: String. Sys ID from the Skill Levels \[cmn_skill_level\] table. {#USA-analyzeUserBySkills_S_S_B__ul_kj3_h1c_j3b} |
| isSkillLevelEnforced | Boolean | True if user must have minimum skill level for all required mandatory skills, false otherwise. Default: false. |
[Table 4. Parameters]

{#USA-analyzeUserBySkills_S_S_B__table_crq_fzr_lhb} {#USA-analyzeUserBySkills_S_S_B__table_vdx_prw_33b__entry__2}

| Type | Description |
|-|-|
| String | JSON that contains all the required information about the user based on the analyzer skills map as follows: * sys_id: String. Sys ID from the User \[sys_user\] table. * is_qualified: Boolean. Flag that indicates whether the user is qualified for the required skills. * True if user has all the mandatory skills and skill level is enforced. * False if user does not have all mandatory skills or does not meet level requirements. {#USA-analyzeUserBySkills_S_S_B__ul_ql2_rhq_g3b} * num_skills: Number. Skills matched against the required skills. * num_skills_matching_level: Number. User skills matching the required skill level. * total_skill_level_gap: Number. Skill level gap helps ranking algorithm find optimal user meeting minimum skill level requirements. Calculated based on overall gap between task skill level and user skill level. User must have required skill level for mandatory skills. * optional_skill_level_gap: Number. Provides skill level gap for optional skills only. Assists the end points in distinguishing between total skill level and optional skill level gap. {#USA-analyzeUserBySkills_S_S_B__ul_q1n_msd_f3b} Error if inaccurate parameters or malformed JSON provided. |
[Table 5. Returns]

{#USA-analyzeUserBySkills_S_S_B__table_vdx_prw_33b}  

    var skills = [{"sys_id":"48c9f873c0a8018b65c3814608b201e6", "is_mandatory": true, "level":"4e0ac4d6b3332300290ea943c6a8dc4e"},
    				{"sys_id":"48c9fdddc0a8018b04bd8d7914c82c9d", "is_mandatory": false, "level":"4e0ac4d6b3332300290ea943c6a8dc4e"}];
    var userSkills = [{"sys_id":"48c9f873c0a8018b65c3814608b201e6", "is_mandatory": true, "level":"4e0ac4d6b3332300290ea943c6a8dc4e"},
    		    {"sys_id":"k, th", "is_mandatory": false, "level":"4e0ac4d6b3332300290ea943c6a8dc4e"}];
    var userSkillAnalyzer = new SNC.UserSkillAnalyzer();
    var result = userSkillAnalyzer.analyzeUserBySkills(JSON.stringify(skills), JSON.stringify(userSkills));
    gs.info('Results: ' + result);