Articles, Blogs, Videos, Podcasts, Share projects - Experiences from the field

Hi there,

When working with the Page Designer on the Service Portal, you probably used to dragging & dropping Service Portal widgets. Because this way actually Widget Instances are created, you can utilize the Instance options to configure the behavior, presentation, etc. of the Service Portal Widget concerned. Really nice!

Though what if you embed a Service Portal widget directly to a Page, a Header, a Footer? No Widget Instance is created in that case. So what about the Instance Options then?!

Widget Instance

Because one of my favorite subjects is Virtual Agent, let's take the "Virtual Agent Service Portal Widget" as an example. When you would drag & drop this on to a page through the Page Designer, a Widget Instance would be created automatically. This would allow you to configure the Instance Options. For example (as an admin-user) by performing a right-mouse click on the Widget itself on your Service Portal page. A small pop-up would appear with amongst others the option "Instance Options".

In this case, we would just like to have a different button color and add additional URL parameters.

When reloading your Service Portal page, the changes will be visible.

Embedding a Widget

In some cases, you might want to embed a Service Portal widget directly to a Page, a Header, a Footer, or even within a different Service Portal widget. A well-known case would be to add the Virtual Agent widget to the header or footer, so it's visible on all your Service Portal pages instead of just the index page.

With the below code, within the Footer Body HTML template, the Virtual Agent Service Portal widget can be embedded.

<div>
  <widget id="sn-va-sp-widget"></widget>
</div>

This will work fine, the Service Portal widget now be displayed on your page(s). Though, performing a right-mouse click on the Widget itself on your Service Portal page will not work anymore! So what about the Instance Options? Like mentioned, by embedding a Service Portal widget this way, how valid your case even is, there's no Widget Instance created.

Instance Options on Embedded Widgets

Luckily there's still a way to add Instance Options on Embedded Widgets. It takes a bit more effort, though works fine. Within the Widget element on the Body HTML template, you could add an attribute "options". Something like:

options="{}"

Within this options attribute, you can just list the options you are after. The notation is actually comparable to what you would see on the Option schema of Service Portal widgets. For the Virtual Agent Service Portal widget this looks like:

[
  {
    "hint":"The color of the floating button which opens the virtual agent service portal widget button.",
    "name":"button_color",
    "section":"Presentation",
    "default_value":"#8D8DE0",
    "label":"Floating Button Color",
    "type":"string"
  },
  {
    "hint":"The URL parameters to pass to the VA client, for example: sysparm_live_agent_queue=abc123&sysparm_conversation=xzy456",
    "name":"va_url_params",
    "section":"Behavior",
    "label":"Virtual Agent Client URL Parameters",
    "type":"string"
  }
]

In our example, we want to have a different button color, and add additional URL parameters. Seeing the above Option schema, we could change the widget element and the options attribute into:

<div>
  <widget id="sn-va-sp-widget" options='{"button_color":"#FF0000","va_url_params":"&sysparm_skip_load_history=true"}'></widget>
</div>

Result

After applying the changes to the Body HTML template of the footer and reloading your Service Portal, the changes should be visible immediately. The button color is red and the chat is opened without loading the history.

---

And that's it actually. Hope you like it. If any questions or remarks, let me know!

Kind regards,

Mar k Roethof

ServiceNow Technical Consultant @ Quint Technology

1x ServiceNow Developer MVP

1x ServiceNow Community MVP

---