Customizing Choice Lists

From ServiceNow Wiki
Home > Administer > Managing Data > Field Administration > Customizing Choice Lists
Jump to: navigation, search
Note
Note: This article applies to Fuji. For more current information, see Choice List Field Type at http://docs.servicenow.com

The ServiceNow Wiki is no longer being updated. Please refer to http://docs.servicenow.com for the latest product documentation.


Fields
Related Topics
Workflow Stage Fields
Get the Book
Knowledge.gif Field Administration

1 Overview

A choice list is a type of field that lets the user select from a pre-defined set of choices. Administrators can define the available choices and customize the behavior and appearance of choice lists.

The State field choice list for incidents

2 Choice List Security

The personalize_choices security role can be used to let non-administrators modify the options for Choice elements on all tables. If more granular control is desired, you can also create a custom ACL (security rule) governing the personalize_choices operation either for a particular field or for all fields (.*) on a particular table. However, access to the personalize_choices operation on a particular field does not confer the ability to add new choices for that field. To be able to create new choices for a particular field, two ACLs are required:

  • An ACL that grants personalize_choices access for that field.
  • An ACL that grants create access to the Choice table (sys_choice).

For example, to give the hris_admin role the ability to personalize only the Category field for Human Resources KB articles, you need:

  • An ACL granting personalize_choices access to the hris_admin role on the Category field of the Knowledge (kb_knowledge) table.
  • An ACL granting create access to the hris_admin role on the Choice (sys_choice) table.

There are predefined ACLs granting both types of access to the personalize_choices security role, for all fields on all tables. The personalize_choices security role also has read, write, and delete access to the sys_choices table. However, this additional access is not required when making just the Personalize Choices functionality available on a granular basis.

3 Choice List Definition

The Choice [sys_choice] table stores the values that appear in choice lists. To view the values in the Choice table, right-click the field label and select Configure > Show Choice List (Personalize > Show Choice List in versions prior to Fuji).

Warning
Warning: Do not add new choices to the list that you see when you select Show Choice List. To add new choices to a choice list field, use the Configure Choices option (Personalize Choices in versions prior to Fuji). See Defining Options for Choice Lists for instructions.

The Choice Set [sys_choice_set] table contains a record for every field that uses a choice list (starting with the Dublin release). The choice set record is associated with an application file, which allows update sets and team development to track and transfer all choices for a field in a single update record.

Choice list values allow a maximum character length of 40.

3.1 Defining Options for Choice Lists

To define a static list of available options:

  1. Navigate to a form on which the field appears.
  2. If the choice list is dependent on another field, enter the choice value on which these options depend.
    For example, on the incident table, the Subcategory is dependent on the Category. To customize which subcategory choices are available for the hardware category, select Hardware in the Category field.
  3. Right-click the field label and select Configure Choices (Personalize Choices in versions prior to Fuji).
  4. Use the slushbucket to rearrange the order, add, or remove items or to create new items.
  5. Click Save.


To dynamically add items to a choice list, use the addOption method. See GlideForm (g_form).

Note
Note: Some business rules may be affected by changes to choice list options (for example, default Incident states).


3.2 Reusing Choice Lists

After defining a set of choice list values, you can reuse those values for another field in a different table.

  1. Right-click on an existing choice field (Field A) and select Configure Choices (Personalize Choices in versions prior to Fuji).
  2. Add the desired choice list values.
  3. To reuse the choice list values for another field (Field B) in a different table, right-click on the label for Field B and select Configure Dictionary (Personalize Dictionary in versions prior to Fuji).
  4. In the Choice table field, select the table in which Field A resides.
  5. In the Choice field field, select Field A.

    Choice_List_Sharing.png‎

  6. Click Update.
    The choice list values defined on Field A are displayed on Field B. When you add or remove choice list values on Field A, those changes are also reflected on Field B.

3.3 Removing the -- None -- Option

To remove the -- None -- option:

  1. Navigate to a form on which the field appears.
  2. Right-click the field label and select Configure Dictionary (Personalize Dictionary in versions prior to Fuji).
  3. Change the Choice field value to Dropdown without -- None -- (must specify a default value).
    ChoiceWithoutNone.png
  4. Ensure that the Default field is populated to determine which choice is displayed by default.
    ChoiceDefault.png
Note
Note: If the field is dependent on another field, the -- None -- option remains available.


3.4 Changing the -- None -- Display Value

To change the default display label of the -- None -- option:

  1. Navigate to a form on which the field appears.
  2. Right-click the field label and select Show Choice List.
  3. Click New.
  4. Define the new label (see table).
    NewChoiceListDisplay.png
  5. Click Submit.
    ChoiceListAfter.png
Field Value
Table Enter the table name of the field you are changing.
Element Enter the name of the field you are changing.
Language Enter ISO language code for the label.
Sequence Leave empty. This field determines the order.
Inactive Leave cleared.
Label Enter the desired label, as you want it to appear in the choice list.

You can use JavaScript, including calls to script includes, to define the label. For example, the label in the following example changes the -- None -- value of the Time-zone choice list in a user record to use the time-zone value of the instance. Image:def_null_label_choice.png

Value Enter NULL_OVERRIDE. Note: You must enter NULL_OVERRIDE as the value, or the new label will appear in addition to the -- None -- option.
Dependent Value Leave blank.
Hint leave blank.
Note
Note: To change the -- None -- display value in catalog variables, see Select Box.


3.5 Deleting All Choice List Options

You can delete all choices for a choice field from the Choice Set record (starting with the Dublin release). You may want to use this method when you are developing a new application and the business requirements change. If you are updating a choice list that is already in use, consider deactivating the options you no longer use to avoid conflicts with existing data or scripts that may rely on the previous options.

To delete all choices:

  1. In the navigation filter, enter sys_choice_set.list.
  2. Open the choice set record for the field.
    For example, to locate the choice set for the incident subcategory, filter by Table is incident and Element is subcategory.
  3. Click Delete.
    All choices for the field are deleted.

4 Creating Choice Lists for Other Field Types

You can create a choice list for a field with another type (for example, an Integer field). You may use this configuration to standardize data entry and limit available options for a field, while still maintaining the original field type.

To create a choice list for a field with another type:

  1. Navigate to System Definition > Dictionary.
  2. Open the dictionary entry for the field.
  3. Change the Choice value to Dropdown with --- None --- or Dropdown without --- None --- (must specify a default value).
  4. Right-click the form header and select Save.
  5. Click Create Choice List.
    • The Choices related list appears on the dictionary entry form.
    • If records on the table contains data for the field, a choice list value for each unique field value is created. For example, if three records exist on the table and each record has a unique value in the field, then three choices are created.
    • If no data exists in the field, a choice list value of -- New choice -- is created (starting with the Dublin release).

5 Choice List Appearance

5.1 Changing the Number of Choices Displayed

By default, choice lists are limited to display up to 15 choices. When a user types in the field, the list is dynamically filtered to show up to 15 matching choices. If more choices are available, only the first 15 are displayed.

To change the maximum number of choices displayed, navigate to System Properties > System and change the value for the Maximum number of items to show for a dynamic drop-down choice list (glide.xmlhttp.max_choices) property.

5.2 Displaying Invalid Choice List Values

By default, inactive or invalid choice list values appear in blue text instead of black. In the following example, the Network category has been deactivated, so it appears in blue for records that still contain the inactive value.

An example with a deactivated Network category

To turn off the color indicator for invalid choices, navigate to System Properties > UI Properties and clear the checkbox for the Display missing choice list entries property.

5.3 Adjusting Choice List Width

By default, all choice lists use a width of 160 pixels. To change the width for all choice list on the instance, navigate to System Properties > UI Properties and change the value for the "Default choice list width (pixels)" property (glide.ui.choicelist.defaultwidth).


To change the value for a particular list (for example, a list with much longer option names than other choice lists):

  1. Navigate to a form on which the field appears.
  2. Right-click on the field label and select Configure Styles (Personalize Styles in versions prior to Fuji).
  3. Click New.
  4. In the Style field, enter width:auto.
    Leave the Value field empty so that the field style applies to all the choices for the field.
  5. Click Submit.
    When the field is displayed, the width adjusts to the size of the content.

6 Determining Values Associated with Choices for Scripting

When you write a script that references a choice list, you need to know the value associated with each choice. For example, to check whether the incident_state field is active, you could not use the condition current.incident_state == "active" because the value associated with the choice labelled Active is the integer 2. Instead, you would use the condition current.incident_state == 2.

The Type field on the choice list dictionary entry determines the data type of the values.

To determine the value associated with a choice, right-click on the field label and select Show Choice List, then locate the choice for which you need to know the value.

Image:shown_choices.png

The -- None -- option may not have a sys_choice record associated with it. A choice list field set to -- None -- evaluates to these values, depending on the script context:

  • For client-side scripts (such as client scripts): "" (empty string)
  • For server-side scripts (such as business rules): "0" (string of the number zero)

7 Integer Values for Default Choice Lists

Queries on choice list fields use the value, not the label. Some common choice lists use integer values that do not match the string labels. For example, the Problem table uses these default values for the State field.

Value Label
1 Open
2 Known Error
3 Pending Change
4 Closed/Resolved

These integer values are also used in several default business rules. For example, a business rule on the Incident table sets the active flag to false when the State field changes to 7, which is the default value for the Closed. If you change the values of your Incident state options, this business rule may no longer behave as desired or expected.

On the Incident table, the Active, State, and Incident state fields are affected by these default business rules:

  • mark_closed (incident): if the incident_state changes to 7 (Closed), the active flag is set to false
  • incident reopen (incident): if the incident_state is less than 7 (Closed) and the active flag is false, the active flag is set to true
  • mark closed (task): if the state changes to either 3 (Closed Complete) or 4 (Closed Incomplete), the active flag is set to false
  • task closer (task): if the active flag changes from true to false and the state is neither 3 (Closed Complete) nor 4 (Closed Incomplete), the state is set to 3 (Closed Complete)
  • task reopener (task): if the active flag changes from false to true and the state is either 3 (Closed Complete) or 4 (Closed Incomplete), the state is set to 1 (Open)
Note
Note: Notice that these business rules do not change incident_state based on a change to either the active flag or the state field. Changes to incident_state drive the other two fields, not the other way around.


8 Best Practices for State Field Choice Values

When you configure choice values for the state field:

  • Use a negative value to add a new active state field.
  • Search for and study the business rules that use a state number filter on the Script and Conditions fields. You can use the Debug tool to trace the order of the business rule execution.

8.1 Incident State Modification Example

Consider the following example for incidents:

  1. Navigate to System Definition > Choice Lists.
  2. At the top of the list, construct a list filter like the following:
    • Table: incident
    • Element: incident_state
  3. Run the filter.
    Notice that the Closed state has a value of 7 and the Resolved state has a value of 6. Any state greater than or equal to 7 is assumed to be inactive.
    Therefore, you should use a positive integer greater than 7 if you want to add a new inactive-type of state. Use a negative value like -1 or -2 if you wish to add a new active-type of state field, such as Awaiting Vendor.

8.2 Change State Modification Example

Consider the following example for change requests:

  1. Navigate to System Definition > Choice Lists.
  2. At the top of the list, construct a list filter like the following:
    • Table: change_request
    • Element: phase_state
  3. Run the filter.
    Notice that the Complete state has a value of 8. Any state greater than or equal to 8 is assumed to be inactive.
    Therefore, you should use a positive integer greater than 8 if you want to add a new inactive-type of state, such as Cancelled. Use a negative value like -1 or -2 if you wish to add a new active-type of state field, such as Pending.

8.3 Change States and Business Rules

Business rules in the system make assumptions about state values. Any changes to these values or the introduction of new state values can lead to unexpected results.

This example shows you how to determine which business rules are operating on the Closed incident_state fields:

  1. Navigate to System Definition > Business Rules.
  2. Construct a filter like this one to view the scripts and conditions that pertain to the Resolved incident_state of 6 or the Closed incident_state value of 7:
    The Script field contains 7 OR the Condition field contains 7 OR the Script field contains 6 OR the Condition field contains 6 AND the Table field is incident AND the Active field is true.

See Debug Business Rule for information on how to trace the order of business rule execution. You can click Debug All, resolve an incident, and then check the trace at the bottom of form to watch the business rules execute. These two line examples show that the mark_closed business rule code is entered ==> and then exited <==.

==> 'mark_closed' on incident
<== 'mark_closed' on incident
Was this article helpful?
Yes, I found what I needed
No, I need more assistance