Product documentation Docs
    • English
    • Deutsch
    • 日本語
    • 한국어
    • Français
  • More Sites
    • Now Community
    • Developer Site
    • Knowledge Base
    • Product Information
    • ServiceNow.com
    • Training
    • Customer Success Center
    • ServiceNow Support Videos
  • Log in

Product documentation

  • Home
How search works:
  • Punctuation and capital letters are ignored
  • Special characters like underscores (_) are removed
  • Known synonyms are applied
  • The most relevant topics (based on weighting and matching to search terms) are listed first in search results
Topics are ranked in search results by how closely they match your search terms
  • A match on the entire phrase you typed
  • A match on part of the phrase you typed
  • A match on ALL of the terms in the phrase you typed
  • A match on ANY of the terms in the phrase you typed

Note: Matches in titles are always highly ranked.

  • Release version
    Table of Contents
    • Now Platform capabilities
Table of Contents
Choose your release version
    Home New York Now Platform Capabilities Now Platform capabilities Service Portal Service Portal widgets Widget developer guide Widget option schema

    Widget option schema

    • Save as PDF Selected topic Topic & subtopics All topics in contents
    • Unsubscribe Log in to subscribe to topics and get notified when content changes.
    • Share this page

    Widget option schema

    Widget instances allow users to uniquely configure each widget they add to a page. Use the option schema to define the parameters for your widget.

    Storing instance options

    When developing a widget, you can edit the option schema to create parameters for your widget, or you can create a table to store instance options. If you edit the existing option schema, any instance options defined are stored in JSON format in the Additional options, JSON format field in the sp_instance table. The following field types are available:

    • String
    • Boolean
    • Integer
    • Reference
    • Choice
    • Field_list (depends on table)
    • Field_name (depends on table)
    • Glide_list

    To use other field types not supported in the option schema, create an extension table to store your custom widget option schema. Using a table enables you to:

    • Add any ServiceNow field type, including fields with advanced customization, to the option schema.
    • Define a complex option schema.
    • Search and filter instance options.
    Note: While storing options in a table enables you to define more complex options, this method is more difficult to maintain than editing the option schema. To avoid creating unnecessary tables and adding additional server calls to your widget, edit the existing option schema when possible. Store options in a table only when complex or searchable options are required.

    Using options in a widget

    Access options in the widget from both the client script and the server script using the options global variable. You can access to any option value in your widget client script or server script using options.optionName.

    Client script
    function() {
      /* widget controller */
      var c = this;
        console.log(c.options.text_color) //Outputs the text_color option for this instance
    }
    Server script
    (function() {
         $sp.log(options.text_color) //Logs the value of the text_color option to the browser console.
    })();

    Defining default options

    Before an option value is set on an instance, it appears as an undefined value when you access that option variable. Use the widget server script to specify default values for your options.

    (function() {
      options.text_color=options.text_color||"blue";
      options.maximum_entry_count=options.maximum_entry_count||5;
    })

    Edit the widget option schema

    Widget instances allow users to uniquely configure each widget they add to a page. Edit the option schema to define basic parameters for your widget.

    Before you begin

    Role required: admin or sp_admin

    Procedure

    1. Navigate to Service Portal > Service Portal Configuration > Widget Editor.
    2. Select the widget you want to configure the option schema for.
    3. Click the menu icon (Menu icon) and select Edit option schema.
      This option only appears for users that have the right to edit the widget.
    4. Click + to add a widget option.
    5. Define a label, name, type, hint and form section. More fields appear depending on the type you select.

      Adding flexible widget options allows you to create more reusable widgets. You can add default values to help users understand each widget option. If you do not select a form section, the default is set to Other options.

      Widget options schema form with fields completed as follows: label=time zone, name=zone, type=string, hint=blank, default value=America/Denver
    6. Click Save.
      The option schema you defined is stored in JSON format in the Option schema field in the sp_widget table. Based on this option schema, each instance of the widget can use individually defined instance options.
    7. Test the option schema by adding the widget to a page in the Service Portal Designer.
      1. Navigate to Service Portal > Service Portal Configuration > Service Portal Designer.
      2. Add the widget to a page and click the edit icon on the widget instance to view the instance options.
      3. Configure the widget instance options.
      4. View the configuration by navigating to the instance record in the sp_instance table.
        The instance options are stored in JSON format in the Additional options, JSON format field.

    Store instance options in a table

    Create a table to store widget instance options instead of editing the existing option schema. When using a table as your widget option schema, you can define custom fields using any ServiceNow field type, add filters to fields, and search or query instance options.

    Before you begin

    Role required: admin or sp_admin

    About this task

    To define a custom option schema, add fields to an sp_instance extension table, then set your widget to use the extension table as a data source. Using an extension table enables you to:

    • Add any ServiceNow field type, including fields with advanced customization, to the option schema.
    • Define complex widget options.
    • Search and filter instance options.
    Note: While storing options in a table enables you to define more complex options, this method is more difficult to maintain than editing the option schema. To avoid creating unnecessary tables and adding additional server calls to your widget, edit the existing option schema when possible. Store options in a table only when complex or searchable options are required.

    Procedure

    1. Create a table that extends an sp_instance table to store your custom option schema.
      1. Navigate to System Definition > Tables.
      2. Click New.
      3. Define a label and name.
      4. In the Extends table field, select an sp_instance table that provides the necessary fields.
        Instance table Description
        Instance [sp_instance] Includes base instance fields.
        Instance with Table [sp_instance_table] Includes sp_instance fields and fields to display table data such as Table and Filter.
      5. Save the form.
    2. Define custom fields in the extension table.
      You can define any field type to use in your option schema by adding new columns in the Columns list.
    3. Update your widget to use the extension table as a data source.
      1. Navigate to Service Portal > Widgets.
      2. Open the widget you would like to create custom options for.
      3. In the Data table field, select your sp_instance extension table.
        Card List Instance extension table selected in the Data table field.
    4. Configure the extension table form to display the desired fields. Fields configured on the form are available as instance options.
      1. Navigate to the extension table form: <yourInstance>/<your_extenstion_table>.do.
      2. Right-click the header menu and select Configure > Form Layout.
      3. Add the fields to the form.
      4. Click Save.
    5. Configure the widget to display the desired fields as instance options.
      1. Navigate to Service Portal > Widgets.
      2. Open the widget that has the extension table set as the data source.
      3. Use the Fields slushbucket to select fields to display as instance options.
        My Custom Field moved to the Selected column.
      4. Save the form.

    What to do next

    Test the option schema by adding the widget to a page in the Service Portal Designer. Click the edit icon on the widget instance to view the instance options. After configuring the widget instance options, view the configuration by navigating to the instance record in the sp_instance extension table.

    Tags:

    Feedback
    On this page

    Previous topic

    Next topic

    • Contact Us
    • Careers
    • Terms of Use
    • Privacy Statement
    • Sitemap
    • © ServiceNow. All rights reserved.

    Release version
    Choose your release version

      Widget option schema

      • Save as PDF Selected topic Topic & subtopics All topics in contents
      • Unsubscribe Log in to subscribe to topics and get notified when content changes.
      • Share this page

      Widget option schema

      Widget instances allow users to uniquely configure each widget they add to a page. Use the option schema to define the parameters for your widget.

      Storing instance options

      When developing a widget, you can edit the option schema to create parameters for your widget, or you can create a table to store instance options. If you edit the existing option schema, any instance options defined are stored in JSON format in the Additional options, JSON format field in the sp_instance table. The following field types are available:

      • String
      • Boolean
      • Integer
      • Reference
      • Choice
      • Field_list (depends on table)
      • Field_name (depends on table)
      • Glide_list

      To use other field types not supported in the option schema, create an extension table to store your custom widget option schema. Using a table enables you to:

      • Add any ServiceNow field type, including fields with advanced customization, to the option schema.
      • Define a complex option schema.
      • Search and filter instance options.
      Note: While storing options in a table enables you to define more complex options, this method is more difficult to maintain than editing the option schema. To avoid creating unnecessary tables and adding additional server calls to your widget, edit the existing option schema when possible. Store options in a table only when complex or searchable options are required.

      Using options in a widget

      Access options in the widget from both the client script and the server script using the options global variable. You can access to any option value in your widget client script or server script using options.optionName.

      Client script
      function() {
        /* widget controller */
        var c = this;
          console.log(c.options.text_color) //Outputs the text_color option for this instance
      }
      Server script
      (function() {
           $sp.log(options.text_color) //Logs the value of the text_color option to the browser console.
      })();

      Defining default options

      Before an option value is set on an instance, it appears as an undefined value when you access that option variable. Use the widget server script to specify default values for your options.

      (function() {
        options.text_color=options.text_color||"blue";
        options.maximum_entry_count=options.maximum_entry_count||5;
      })

      Edit the widget option schema

      Widget instances allow users to uniquely configure each widget they add to a page. Edit the option schema to define basic parameters for your widget.

      Before you begin

      Role required: admin or sp_admin

      Procedure

      1. Navigate to Service Portal > Service Portal Configuration > Widget Editor.
      2. Select the widget you want to configure the option schema for.
      3. Click the menu icon (Menu icon) and select Edit option schema.
        This option only appears for users that have the right to edit the widget.
      4. Click + to add a widget option.
      5. Define a label, name, type, hint and form section. More fields appear depending on the type you select.

        Adding flexible widget options allows you to create more reusable widgets. You can add default values to help users understand each widget option. If you do not select a form section, the default is set to Other options.

        Widget options schema form with fields completed as follows: label=time zone, name=zone, type=string, hint=blank, default value=America/Denver
      6. Click Save.
        The option schema you defined is stored in JSON format in the Option schema field in the sp_widget table. Based on this option schema, each instance of the widget can use individually defined instance options.
      7. Test the option schema by adding the widget to a page in the Service Portal Designer.
        1. Navigate to Service Portal > Service Portal Configuration > Service Portal Designer.
        2. Add the widget to a page and click the edit icon on the widget instance to view the instance options.
        3. Configure the widget instance options.
        4. View the configuration by navigating to the instance record in the sp_instance table.
          The instance options are stored in JSON format in the Additional options, JSON format field.

      Store instance options in a table

      Create a table to store widget instance options instead of editing the existing option schema. When using a table as your widget option schema, you can define custom fields using any ServiceNow field type, add filters to fields, and search or query instance options.

      Before you begin

      Role required: admin or sp_admin

      About this task

      To define a custom option schema, add fields to an sp_instance extension table, then set your widget to use the extension table as a data source. Using an extension table enables you to:

      • Add any ServiceNow field type, including fields with advanced customization, to the option schema.
      • Define complex widget options.
      • Search and filter instance options.
      Note: While storing options in a table enables you to define more complex options, this method is more difficult to maintain than editing the option schema. To avoid creating unnecessary tables and adding additional server calls to your widget, edit the existing option schema when possible. Store options in a table only when complex or searchable options are required.

      Procedure

      1. Create a table that extends an sp_instance table to store your custom option schema.
        1. Navigate to System Definition > Tables.
        2. Click New.
        3. Define a label and name.
        4. In the Extends table field, select an sp_instance table that provides the necessary fields.
          Instance table Description
          Instance [sp_instance] Includes base instance fields.
          Instance with Table [sp_instance_table] Includes sp_instance fields and fields to display table data such as Table and Filter.
        5. Save the form.
      2. Define custom fields in the extension table.
        You can define any field type to use in your option schema by adding new columns in the Columns list.
      3. Update your widget to use the extension table as a data source.
        1. Navigate to Service Portal > Widgets.
        2. Open the widget you would like to create custom options for.
        3. In the Data table field, select your sp_instance extension table.
          Card List Instance extension table selected in the Data table field.
      4. Configure the extension table form to display the desired fields. Fields configured on the form are available as instance options.
        1. Navigate to the extension table form: <yourInstance>/<your_extenstion_table>.do.
        2. Right-click the header menu and select Configure > Form Layout.
        3. Add the fields to the form.
        4. Click Save.
      5. Configure the widget to display the desired fields as instance options.
        1. Navigate to Service Portal > Widgets.
        2. Open the widget that has the extension table set as the data source.
        3. Use the Fields slushbucket to select fields to display as instance options.
          My Custom Field moved to the Selected column.
        4. Save the form.

      What to do next

      Test the option schema by adding the widget to a page in the Service Portal Designer. Click the edit icon on the widget instance to view the instance options. After configuring the widget instance options, view the configuration by navigating to the instance record in the sp_instance extension table.

      Tags:

      Feedback

          Share this page

          Got it! Feel free to add a comment
          To share your product suggestions, visit the Idea Portal.
          Please let us know how to improve this content

          Check any that apply

          To share your product suggestions, visit the Idea Portal.
          Confirm

          We were unable to find "Coaching" in Jakarta. Would you like to search instead?

          No Yes
          • Contact Us
          • Careers
          • Terms of Use
          • Privacy Statement
          • Sitemap
          • © ServiceNow. All rights reserved.

          Subscribe Subscribed Unsubscribe Last updated: Tags: January February March April May June July August September October November December No Results Found Versions Search preferences successfully updated My release version successfully updated My release version successfully deleted An error has occurred. Please try again later. You have been unsubscribed from all topics. You are now subscribed to and will receive notifications if any changes are made to this page. You have been unsubscribed from this content Thank you for your feedback. Form temporarily unavailable. Please try again or contact  docfeedback@servicenow.com  to submit your comments. The topic you requested does not exist in the release. You were redirected to a related topic instead. The available release versions for this topic are listed There is no specific version for this documentation. Explore products Click to go to the page. Release notes and upgrades Click to open the dropdown menu. Delete Remove No selected version Reset This field is required You are already subscribed to this topic Attach screenshot The file you uploaded exceeds the allowed file size of 20MB. Please try again with a smaller file. Please complete the reCAPTCHA step to attach a screenshot
          Log in to personalize your search results and subscribe to topics
          No, thanks Login