The purpose of this blog is to illustrate what is an Option Schema in Service Portal and how it plays an important role in changing the behavior of a widget. This blog will help to understand how one can edit and create an Option Schema to increase the reusability of a widget.

Option Schema:
Widget option schema is one of the significant features in Service Portal which allows users to configure each widget uniquely by defining their own set of parameters or widget instance options to their widgets. Every widget has its own set of options whose values one need to specify whenever using that widget. For instance, a Homepage search widget has three options defined that are title, short description and Typeahead Search. One has to provide those values whenever using that widget.
While developing a widget, one can either edit the existing option schema for our widget or can store the widget instance options in a table extending sp_instance table.

Editing Option Schema:
For editing the existing option schema, one can navigate to Service Portal > Service Portal Configuration > Widget Editor and select the widget for which one want to configure the option schema. From the Menu Icon , one can navigate to Edit Option Schema, or from the portal itself can do CTRL + right Click and select ‘Widget Options Schema’. This option is available to only those user who have either admin or sp_admin role.


From widget editor


From Portal Page

This opens the widget option schema and one can add more widget options here by clicking on the (+) icon and simply defining the Label, Name, Type, Hint and Default Value. Additional fields may appear depending on the field type selected.

The field types that are available in widget option schema are: String, Boolean, Integer, Reference, choice, field_list, field_name, glide_list.

Creating Option Schema from a Table:
Other ServiceNow Fields are not available or supported in option schema. But for that one can create a table extending from ‘sp_instance’ which will store the widget instance options. It allows one to define complex option schema, where they can have any ServiceNow field type along with advanced customizations such as client script, UI policy, add filters to the fields etc. to the option schema.
To edit existing option schema from service portal is easy rather than creating it from table as it comes with challenges to maintain it further. Hence, one should create option schema from table only if they require handling complexity.

Storing widget instance options in a table:

  • For defining custom options schema, one has to create a custom table and extend it from sp_instance table.
  • After creating table, one can define custom fields of any type by adding columns to the table to use in the option schema.
  • Select the widget for which creating the options schema by navigate to Service Portal> widgets.
  • Update the data table field with the custom table created for storing option schema.
  • To display the custom fields in the options schema, add them to the fields slushbucket.
  • Save the form with all the changes.
  • After saving, when opening the option schema of that widget in the portal, one can see that their custom fields will appear in the option schema. Likewise, one can create more complex option schema for any widget when required including additional customizations to the field through UI Policy, client Scripts, Script Includes etc.

Using options from Widget Option Schema:
The options of option schema are accessible through server side, client side and HTML by using option’s global variable.
Option values are accessible through ‘options.optionName’.

  • Accessing widget instance options from HTML:
  • Accessing widget instance options from Server side script:
  • Accessing widget instance options from Client side script:

We are quite sure that this blog must have given a brief idea about option schema and its importance in Service Portal. We will appreciate any suggestion/feedback on the same.