Using sn-record-picker in ServiceNow Service Portal: A Comprehensive Guide

[Alka_Chaudhary]

The sn-record-picker is a powerful directive in ServiceNow’s Service Portal that enables users to select records from any table in the system. Whether you're working with user records or other types of data, the sn-record-picker simplifies record selection and display for users. In this guide, we'll walk through the following:

1. Creating an sn-record-picker component.
2. Setting initial values in the picker.
3. Fetching selected values for processing.
4. Enabling multiple record selection.

1. Creating an sn-record-picker

The sn-record-picker is a powerful component for selecting records from any table in ServiceNow. It allows users to search for and pick records based on the fields specified. Here’s how to create one.

Basic Structure of sn-record-picker:

<sn-record-picker 
    field="user" 
    table="'sys_user'" 
    display-field="'name'" 
    value-field="'sys_id'" 
    search-fields="'name'" 
    page-size="100" 
    default-query="'active=true'">
</sn-record-picker>

• field: This is the AngularJS model that holds the value of the selected record. In this case, it's bound to the user field in the client script.
• table: Specifies the table from which records are selected. Here, it’s set to 'sys_user', meaning users will be selected.
• display-field: The field that will be shown to the user in the picker (e.g., 'name').
• value-field: The field whose value will be stored in the field object (e.g., 'sys_id').
• search-fields: The fields that are searchable in the picker (e.g., 'name').
• page-size: The number of results shown per page in the search results.
• default-query: This specifies a default filter for the records displayed in the picker. In this example, it’s set to 'active=true', meaning only active users will be shown.

This basic structure sets up a picker for selecting users from the sys_user table.

2. Setting Initial Values in sn-record-picker

Often, you’ll want to populate the sn-record-picker with a default or pre-selected value. This can be done by passing data from the server-side (e.g., the current user) and binding it to the picker through the $scope object.

Server-Side Script:

In the widget’s server script, use GlideScripting to retrieve the necessary data, such as the current user’s information:

(function() {
    // Get the current user's display name and sys_id
    data.user = {
        'name': gs.getUserDisplayName(),  // Get the current user's display name
        'sys_id': gs.getUserID()          // Get the current user's sys_id
    };
})();

This retrieves the current user's name and sys_id from ServiceNow and passes it to the client via the data object.

Client-Side Script:

In the client script, bind this data to the sn-record-picker:

$scope.user = {
    displayValue: c.data.user.name || '',  // Set the display value as the user's name or empty string
    value: c.data.user.sys_id || '',        // Set the sys_id as the value or empty string
    name: 'user'
};

Now, the sn-record-picker will be initialized with the current user's information, displaying their name and storing their sys_id.

HTML:

<sn-record-picker 
    field="user" 
    table="'sys_user'" 
    display-field="'name'" 
    value-field="'sys_id'" 
    search-fields="'name'" 
    page-size="100" 
    default-query="'active=true'">
</sn-record-picker>

Here, the field is set to user, which references the $scope.user object initialized in the client script. This ensures the picker is pre-populated with the current user's data.

3. Fetching Selected Values from sn-record-picker

Once a user selects a record from the sn-record-picker, you’ll often need to capture this selection and process it (e.g., store it in a database or send it to the server).

Client-Side Script:

To fetch the selected value when a user makes a change, listen for a field change event in your client script.

$scope.$on("field.change", function(evt, parms) {
    if (parms.field.name === 'user') {
        // Capture the new user value
        $scope.selectedUser = parms.newValue;
        spUtil.addInfoMessage("Selected User sys_id:", $scope.selectedUser);
    }
});

This code listens for changes to the user field and captures the newly selected user record. The sys_id of the selected user will be stored in $scope.selectedUser.

You can then pass this value back to the server for further processing or store it for use in other parts of your application.

4. Enabling Multiple Record Selection

There are situations where you may want users to select more than one record. The sn-record-picker can be configured to allow multiple selections, enabling users to pick multiple records at once.

HTML for Multiple Selection:

To allow multiple record selection, use the multiple attribute in your sn-record-picker:

<sn-record-picker 
    field="selectedUsers" 
    table="'sys_user'" 
    display-field="'name'" 
    value-field="'sys_id'" 
    search-fields="'name'" 
    page-size="100" 
    default-query="'active=true'" 
    multiple="true">
</sn-record-picker>

• multiple="true": This enables multiple record selection in the picker.

Setting Default Values for Multiple Selection:

If you want to pre-populate the picker with default values when multiple selections are enabled, you can format the displayValue to combine multiple fields, such as display-field1####display-field2.

Client-Side Script for Multiple Selection:

When multiple records are selected, the field bound to the picker will hold an array of the selected records’ sys_id values.

$scope.$on("field.change", function(evt, parms) {
    if (parms.field.name === 'selectedUsers') {
        // Capture the array of selected users
        $scope.selectedUsers = parms.newValue;
        spUtil.addInfoMessage("Selected Users sys_ids:", $scope.selectedUsers);
    }
});

In this case, $scope.selectedUsers will contain an array of sys_id values for all the selected records. You can then process this data accordingly, such as sending it to the server or using it in another widget.

Note:

If you don’t want to pre-populate the sn-record-picker, define the default value as empty in your client script to avoid errors. This ensures that the component is initialized correctly without trying to display undefined values.

The sn-record-picker is a flexible and easy-to-use component for record selection in ServiceNow's Service Portal. By understanding how to create the picker, set initial values, fetch the selected values, and enable multiple selections, you can build highly interactive and functional interfaces for your users.

Check the attached screenshot for reference on how the sn-record-picker looks and functions.

If this article is helpful to you, please mark it as helpful .👍

Thanks & Regards,

Alka

[randytangco]

@Alka_Chaudhary.  Great post.  Do you have an example on how you use this in a service portal or page?  Have you used this on a catalog item in the service portal such as ESC?

[youssef_effat]

@Alka_Chaudhary 

Thanks for the detailed explanation !!

I was wondering if i can use the sn-record-picker directive on a UI Page? if it's possible, how it could be integrated into the UI Page ??