This is supported in San Diego and Tokyo releases.
Before you begin: make sure your application is in sn_wfo_work_sched scope.
Work Scheduler Extension Points
|
|
Extension Point Name and Description |
|
1. |
sn_wfo_work_sched.WorkItemRecommendationManager.getRecommendedUsers For a given record, returns a list of agents that can be recommended to work on the work item based on the recommendation criteria. |
|
2. |
sn_wfo_work_sched.WorkItemRecommendationManager.getUIElements Returns the item that matches a search query for a specific UI element. The objects returned by this method map to a related list for the work item table. These list entries can then be edited using a Typeahead-multi control. |
|
3. |
sn_wfo_work_sched.WorkItemRecommendationManager.getOptionsForUIElements Returns options for possible values that you can set on the related list for the selected work item. |
|
4. |
sn_wfo_work_sched.WorkItemRecommendationManager.processValuesFromUIElements Updates the related records on the database based on the given parameters. |
|
5. |
sn_wfo_work_sched.WorkItemRecommendationManager.isWorkConfigSupported Determines whether the extension point is supported by the selected work configuration and returns a true or false value. |
1. sn_wfo_work_sched.WorkItemRecommendationManager.getRecommendedUsers
{
/**
* For a particular record given, this method will return a list of agents that can be recommended.
* @param {string} table
* @param {string} sys_id
* @param {Object} parameters
* @returns {Array<string>} sys_id of agents that can be recommended for a particular work item based
* on each recommendation criteria
*/
getRecommendedUsers: function( /*string*/ table, /*string*/ sys_id, /*object*/ parameters) {
/* @TODO: Implementation*/
return [];
},
}Implementation Details
Returns an array of valid sys_ids from sys_user records that is set based on the criteria customized by the user.
- This method should always return agents that are part of one of the teams that the current user manages.
- If additional logic is included, users must ensure that only the corresponding sys_ids of agents who meet custom criteria are returned as part of the array.
- If there are no agents that match the given, custom criteria, then an empty array must be returned by this method.
Examples
Example 1: Image that displays the output when the getRecommendedAgent API gets called.
Example 2: An example that shows skill recommendation returning valid sys_ids of agents that have a matching skill based on the table and sys_id.
["42acb036b3120010ed7fc9c316a8dcef",
"caacb036b3120010ed7fc9c316a8dcf0",
"02acf036b3120010ed7fc9c316a8dc0c",
"4eacf036b3120010ed7fc9c316a8dc0c"];Example 3: An example of a custom method that returns empty array state because there are no agents that match the custom criteria defined by the Administrator.
[];2. sn_wfo_work_sched.WorkItemRecommendationManager.getUIElements
/**
* Returns an array with the metadata that will be used as properties for the now-typeahead-multi component that renders below the form-detail view. Usually this metadata definition corresponds to related lists that can be easily associated with the current, selected record.
* to a record, such as skills, CIs, etc.
* @param {string} table
* @param {string} sys_id
* @param {Object} parameters
* @returns {Array<Object>} metadata for UI elements to be rendered in Form-detail view
* @example
* [{
* type: 'typeahead_multi',
* name: "mandatory_skills",
* label: gs.getMessage('Mandatory skills'),
* placeholderText: 'Type to select skills',
* helperText: '',
* readOnly: false,
* required: false,
* disabled: false,
* autoFocus: false,
* items: [],
* selectedItems: []
* }]
* @see https://developer.servicenow.com/dev.do#!/reference/now-experience/sandiego/now-components/now-typeahead-multi/overview
*/
getUIElements: function( /*string*/ table, /*string*/ sys_id, /*object*/ parameters) {
return [];
}Implementation Details
Implement a related list as a now-typeahead-multi component.
Note:
- If users do not want to add new related lists, this method will return an empty array.
- If users wish to add related lists for a given work item, they must implement queries to read these related records and build an array that corresponds to the related list and the current set of values corresponding to the selected work item in the sidebar.
- The SkillRecommendation extension point implementation is available by default. This implementation adds two now-typeahead-multi components to any task or interaction-based record.
- The SkillRecommendation extension point implementation has two objects—one for mandatory skills and the other one for optional skills.
- The SkillRecommendation extension point will pre-fill each of the typeahead values. In the related lists with the current values associated with the current work item, the values are pre-filled with an array on all available skills associated with the selected work item. The getOptionsForUIElements is used to fill the items array with the corresponding associated records in the SkillRecommendation implementation.
Example
This method returns an object for mandatory skills and another one for optional skills. These two methods point to the same related list available on any task table (task_m2m_skill).
Example code for this method:
return [
{...},
{
"type": "typeahead_multi", // for now only this value is supported and is required.
"name": "mandatory_skill_selector", // unique name for this related list
"label": "Mandatory skills", // Label that will be visible for users
"placeholderText": "", // Optional placeholder text
"helperText": "", // Optional
"readOnly": false,
"required": false,
"disabled": false,
"hidden": false,
"autoFocus": false,
"items": [
// Should always return an array with the id and label of each related item associated with the current
// record. Empty if there are no records associated for the current implementation.
{
"id": "48c9ef0ac0a8018b1949dcbdcad95bdb-4e0ac4d6b3332300290ea943c6a8dc4e",
"label": "Application Support - Basic",
"skillId": "48c9ef0ac0a8018b1949dcbdcad95bdb",
"levelId": "4e0ac4d6b3332300290ea943c6a8dc4e"
},
{
"id": "48c9ef0ac0a8018b1949dcbdcad95bdb-e41a08d6b3332300290ea943c6a8dcdf",
"label": "Application Support - Intermediate",
"skillId": "48c9ef0ac0a8018b1949dcbdcad95bdb",
"levelId": "e41a08d6b3332300290ea943c6a8dcdf"
},
...
],
"selectedItems": [
{
"id": "48c9eedcc0a8018b3fca079c261987d6-4e0ac4d6b3332300290ea943c6a8dc4e",
"label": "Network - Basic",
"skillId": "48c9eedcc0a8018b3fca079c261987d6",
"levelId": "4e0ac4d6b3332300290ea943c6a8dc4e"
}
]
}
];3. sn_wfo_work_sched.WorkItemRecommendationManager.getOptionsForUIElements
* sys_id=abc123
* parameters={elementName: "mandatory_skill", searchTerm: "network"}
* Output:
* [
{id: "skill1-level1", label: "Network - Basic"},
{id: "skill1-level2", label: "Network - Intermediate"}
* ]
*/
getOptionsForUIElements: function( /*string*/ table, /*string*/ sys_id, /*object*/ parameters) {
return [];
}Implementation Details
How it is implemented for Skill recommendation: Here, Skill Recommendation implementation is used as example. implementation. This implementation available by default and implements the getOptionsForUIElements method. The values for each Skill Recommendation entry is a combination of the cmn_skill record ID and the cmn_skill_level record ID.
Generic implementation: If you want to implement this extension point, you must make sure that this method returns an array of objects where each object will have an ID and label that can map to a related record.
Therefore, when a user selects an option on the typeahead, they can add the same skill but with different skill levels. These values are processed when the users click Save on the form on the Work scheduler sidebar.
In addition to updating the record, the API will call the sn_wfo_work_sched.WorkItemRecommendationManager.processValuesFromUIElements method which will take the new set of values on the now-typeahead-multi method to properly update the related records. It does this either by adding, removing, or updating existing related records. For SkillRecommendation, the entries are updated in the task_m2m_skill table.
If users do not wish to implement related lists on the custom extension point implementations, this method will return an empty array.
Examples
[
{
"id": "48c9ef0ac0a8018b1949dcbdcad95bdb-4e0ac4d6b3332300290ea943c6a8dc4e",
"label": "Application Support - Basic",
"skillId": "48c9ef0ac0a8018b1949dcbdcad95bdb",
"levelId": "4e0ac4d6b3332300290ea943c6a8dc4e"
},
{
"id": "48c9ef0ac0a8018b1949dcbdcad95bdb-e41a08d6b3332300290ea943c6a8dcdf",
"label": "Application Support - Intermediate",
"skillId": "48c9ef0ac0a8018b1949dcbdcad95bdb",
"levelId": "e41a08d6b3332300290ea943c6a8dcdf"
},
{
"id": "48c9ef0ac0a8018b1949dcbdcad95bdb-6a1a48d6b3332300290ea943c6a8dc19",
"label": "Application Support - Advanced",
"skillId": "48c9ef0ac0a8018b1949dcbdcad95bdb",
"levelId": "6a1a48d6b3332300290ea943c6a8dc19"
},
{
"id": "48c9fb91c0a8018b729b0c63877f18e7-4e0ac4d6b3332300290ea943c6a8dc4e",
"label": "Desktops - Basic",
"skillId": "48c9fb91c0a8018b729b0c63877f18e7",
"levelId": "4e0ac4d6b3332300290ea943c6a8dc4e"
},
{
"id": "48c9fb91c0a8018b729b0c63877f18e7-e41a08d6b3332300290ea943c6a8dcdf",
"label": "Desktops - Intermediate",
"skillId": "48c9fb91c0a8018b729b0c63877f18e7",
"levelId": "e41a08d6b3332300290ea943c6a8dcdf"
},
{
"id": "48c9fb91c0a8018b729b0c63877f18e7-6a1a48d6b3332300290ea943c6a8dc19",
"label": "Desktops - Advanced",
"skillId": "48c9fb91c0a8018b729b0c63877f18e7",
"levelId": "6a1a48d6b3332300290ea943c6a8dc19"
},
..
] 4. sn_wfo_work_sched.WorkItemRecommendationManager.processValuesFromUIElements
/**
* Update related records on the DB based on parameters given
* @param {string} table
* @param {string} sys_id
* @param {Object} parameters
* @returns {void}
*/
processValuesFromUIElements: function( /*string*/ table, /*string*/ sys_id, /*object*/ parameters) {
}Implementation Details
This method gets called when a user clicks the Save UI Action on the sidebar form. It implements the corresponding script that will update any related record that is changed using the now-typeahead-multi component on the sidebar. If the custom extension point doesn't add any new How it is implemented for Skill recommendation: component mapping to a related item, then the body of this method can be left empty.
Examples
The sn_wfo_work_sched.WorkItemSkillsRecommendationManager.processValuesFromUIElements method will receive the following objects as parameters with data from the two typeheads: one for mandatory skills and the other for optional skills.
{
"elementData": {
"mandatory_skill_selector": [
{
"id": "48c9ef66c0a8018b1118b490a7604151-4e0ac4d6b3332300290ea943c6a8dc4e",
"label": "SAP - Basic",
"skillId": "48c9ef66c0a8018b1118b490a7604151",
"levelId": "4e0ac4d6b3332300290ea943c6a8dc4e"
},
{
"id": "48c9ef0ac0a8018b1949dcbdcad95bdb-4e0ac4d6b3332300290ea943c6a8dc4e",
"label": "Application Support - Basic",
"skillId": "48c9ef0ac0a8018b1949dcbdcad95bdb",
"levelId": "4e0ac4d6b3332300290ea943c6a8dc4e"
}
],
"optional_skill_selector": [
{
"id": "48c9eedcc0a8018b3fca079c261987d6-4e0ac4d6b3332300290ea943c6a8dc4e",
"label": "Network - Basic",
"skillId": "48c9eedcc0a8018b3fca079c261987d6",
"levelId": "4e0ac4d6b3332300290ea943c6a8dc4e"
}
]
}
}5. sn_wfo_work_sched.WorkItemRecommendationManager.isWorkConfigSupported
/**
* Returns true or false to determine if this extension point is supported or not
* by this workConfig.
* @param {Object} workConfig
* @returns {boolean}
*/
isWorkConfigSupported: function( /*object*/ workConfig) {
return true;
}Implementation Details
This method returns true if the custom extension point implementation supports the current workConfig; if not, it returns false.
For example, the SkillRecommendation extension point that's available by default only supports workConfigs, where the table either extends from tasks or interaction. Any custom table that doesn't extend these tables are not supported.
