Widget Options Schema & Instance Options

One of the very powerful features of the Service Portal is the “Widget Options Schema” which enables developers to create a set of dynamic options on the widget. This allows for the widget to pull dynamic data from the instance without needing to modify the actual form of the instance.

You can define the options schema by either:

  • In the portal, hold [CTRL] + right click on the widget, and select “Widget Options Schema”
  • In the Widget Editor, click the hamburger menu and select “Edit options schema”

 

In the options schema modal, you can create the options by clicking the “+” button and setting the field name, label, and field type.

screenshot-2016-09-30-09-14-13

The following types are currently supported:

  • String
  • Boolean
  • Integer
  • Reference
  • Choice
  • Field_name
  • Field_list

Once the schema has been defined, you can set the values to be used on the instance by holding down [CTRL] and right clicking the widget in the portal and selecting “Instance Options”.

screenshot-2016-09-30-12-03-34

Once the Instance Options have been set, you can now access the option values using the “options” object in the widget, which is automatically made available in the Server Script, Client Controller, and HTML. See the following examples:

Client Controller:

Server Script:

HTML:

A good example of this could be as simple as a Title Widget where now the widget can be used all throughout your portal, but the title is different each time it is used since the title is being pulled from the instance.

This allows your widgets to be very configurable and reusable. I highly suggest you start using it with your portals and custom widgets today.

22 comments

  1. Hi Nathan
    Thanks a lot for this. A little question, do you know a way, how to use options in the CSS section?
    Best Regards
    Tolga

    1. Tolga, as of today you cannot. I have requested this feature, but for now all you can do is place

    2. Hi Tolga,
      The way that I’ve been working around this is by using the ng-style directive like this:
      ng-style=” {‘background-color’ : ‘{{options.color}}’} “

  2. Hello Nathan,
    How can we customize the image in the Instance of Carousel?
    For me its loading all the images in the sp_carousel_slide.

    Thanks
    Saranya

    1. I have tested this, and cannot reproduce. The carousel only displays slides linked to the individual instance, have you verified that all the slides are associated with the correct instances? If you are testing the carousel with the “widget preview” in the editor, then there will not be an instance and as such you might see all of them.

  3. Hi Nathan,

    I have created a widget on which I have created three options and I am using three instances of that widget for passing dynamic URL for the same table each time it is clicked.

    All the logic works fine but the only challenge I am facing is with setting the view to SP that I have created on that table, it is instead loading the data on default view

    Any chance or guidance how to change the view, I can see the view parameter in the widget but it is not editable as I am using oob widget.

    Thanks
    Ishan

  4. Hi,

    I have a custom widget used for selecting on the index page with three links (from a instance with link type instance). I have created three options as i have three links on the instance of the widget, which the user will be navigated based on selection.

    I am able to re-direct user to the next page with proper data based on selection from the instance, i want to set the data with the “SP” view that i have created on the table but instead it is loading with “default” view.

    How can i pass the view via the instance or widget ?
    — Can i pass in the filter that i have for three individual selections ? or how ?

    Thanks,
    Ishan

  5. Hi Nathan,

    I have created 2 different Portals. I want to configure my Widget only for 1 portal but its reflected in other portal also. How can I prevent it.

    Foe example, for ‘Request Fields’ widget of ‘sq_request’ page, I want that ‘Price’ should be displayed only for 1st portal but does not display in 2nd portal. How can I achieve this without using the URL of the portal, as later URL can be changed for Portal.

    1. Server side you can use “data.portalID = $sp.getPortalRecord().getUniqueValue();” which will return the sys_id of the portal. Use that to check which portal you’re on and then hide or show as needed.

  6. This is awesome thanks Nathan.

    Would be great if they had a place in the options schema for a default value. I notice servicenow docs mention setting default option in the server script.

    I tried using thier example but for each instance of a widget I create, when I edit the Instance Options, the defaults do not get populated. Do you know if it is possible?

    Thanks.

  7. Nathan, I’m having some trouble with the widget options schema. I’ve cloned the Data Table widget, which has a ton of options documented in the client and server scripts. But when I go to edit the options, only 4 show up (Title, Glyph, Bootstrap Color and Order). And when I added the Filter option to the schema, it showed up twice when I went to edit the options. How can I get the entire list of options to show up when I go to edit the options? Thanks!

    1. Seems like you may be experience a defect in the product. What version of ServiceNow are you using? When displaying the Instance Options it’s pulling the fields from both the Instance fields defined on the widget as well as the fields in the Option Schema. So you may need to look in both places to see all the fields. I also know the system can get confused if you create Option Schema fields named the same as the fields on the Instance table.

  8. Hi ,
    How to use Reference type in option schema .
    Can we bind the list of incident in option schema using type reference, so that we could get something like :
    data.incList=options.incidentList;
    ?

  9. Hi Nathan,

    Could you provide insights on how to use the “Choice” type of Options?
    I created an Option of the Type “Choice”. Added a bunch of Options. The Choice name is “my_options”
    So when I do c.options ; I see only 1 Value that I added as DEFAULT in the output.

    Please let me know if you need more info to help me with my query.

  10. Hello,

    Is it possible to create a dynamic filter in a ‘Data Table from Instance’ or ‘simple list’ widget? The idea is to let the users adjust their own filters like in the service now instance but instead for the widget they are looking at.

    Has anybody done something similar?

  11. is there a way to use the Data Table from URL definition widget, to display a specific table vs. having to chose it? the other data table options do not provide the “new” option that this one does.

    1. You can to create a new widget and embed the base Data Table widget, and then pass in any needed options.

  12. Hi Nathan,

    Is it possible to display the “sc-recent-popular” widget on the portal carousel. The idea is to display all popular catalog items in a carousel for easy access of the user. Could you please help me here?

Leave a Reply

Your email address will not be published. Required fields are marked *