Widget Instances are a vital component of Service Portal, and although at first glance they seem simple, they can be quite powerful when utilized correctly. In simple terms, the widget instance record stores the location of the widget (which column) and the context needed for it to render. The context of the widget is comprised of the fields on the instance table as well as the “Additional options” field in JSON format. The additional options get generated based on the fields defined in the “Options Schema” on the widget, documented here. Each widget defines which instance table it will use along with which fields from that table. To set the “table” and “fields” variables on the widget, you must open the widget record in the standard ServiceNow UI form. See the example below from the “Icon Link” widget which uses the “sp_instance_link” table.
The following is the out-of-box instance tables available:
Instance (sp_instance)
Base instance table with the following fields: color, css, glyph, short_description, size, title, url
Instance of Carousel (sp_instance_carousel)
Instance primarily used by the carousel widget, has a related list of slides
Instance of Simple List (sp_instance_vlist)
Used by list widgets such as “Simple List” and “Unordered List” and contain fields specific to setting Tables and Filters
Instance with Link (sp_instance_link)
Used for creating widgets that act as hyperlinks, e.g. “Icon Link”, with fields such as URL and references to commonly used tables
Instance with Menu (sp_instance_menu)
This is the instance used by the Header Menu (referenced from the Portal), but can also be used for any widget displaying a menu. It has a “Menu Items” related list.
Instance with Table (sp_instance_table)
The instances behind the Data Table and Count widgets, with fields for setting the Table and Filter
You can also create your own Widget Instance table by extending “sp_instance” and referencing the new table and fields in a widget. If the table referenced on the widget is changed, it will NOT automatically update the existing instances, so you will need to remove the old instances and generate the new instances via the Service Portal Designer.
Once completed, you will now see your custom instance fields when you view the widget Instance Options (CTRL + Click > Instance Options).
Founder of 
Thanks for the article. I found it very informative. It leaves me with one question.
Can instances be used when adding a widget to a catalog item using the macro variable type?
Wes, no, the catalog item will reference the widget directly with no instance. If you must use an instance, I suppose yo could manually create one and pull it in via GlideRecord.
Hello Nathan,
I would like to find out if we do create our own widget instance then is it possible to add our own library of icons/glyphs if we want to? if so would you be able to point me towards the right direction please? I did try to replicate a column named glyph with “Glyph Icon (bootstrap)” type, but I don’t see that option under type.
Thanks
Tej
The glyph field type does not support custom fonts. You would need to implement your own solution for this.
your post was really interesting about understanding instances. I’ll make a note of this article for sure. Keep it up!
Hi Nathan,
Can we link an html form of a widget to the fields of a table directly without using insert(); in server side. Like if my form has two fields name and age and i want to store this in my table having column as name,age. So on ng-submit=c.server.update();do we need to link each data with each column of table in server side,or is there any way to directly store it into the table and get the response of success???
Valuable article for service portal.It’s impressive and also helped too.I would definitely be interested in something like this, I must say your webpage is really cool I just love the content, it’s outstanding!