Adding instance options to directly embedded Service Portal Widgets

[Mark Roethof]

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!

👍	If this post helped you in any way, I would appreciate it if you hit bookmark or mark it as helpful. Interested in more articles, blogs, videos, and Share projects on Service Portal I published? - Service Portal

Kind regards,
Mark
2020 ServiceNow Community MVP
2020 ServiceNow Developer MVP

---

LinkedIn

[Dhirendra Singh]

@Mark Roethof 

Hello, I find this post helpful. I am stuck in trying to understand how virtual agent is called in new Customer Support etc. service portals which are using polaris themes. It's being called via agent chat configuration as they are not being drag/dropped like earlier but where to find this piece of code to read? Basically i want to see if that code can read only one record from sp_agent_chat_config for same portal or more than one and if more than one can it prioritize and read highest priority and discard others? 

Use case - need custom branding on CSM portal but anyway its applied it fails till OOB CSM Chat record in sp_agent_chat_config is modified (even after duplication the oob record has to be made active false). I would not like to touch OOB record if anyway possible.

[Mark Roethof]

@Dhirendra Singh this should help you:
- 2022-07-04 - Article - Am I using Service Portal Agent Chat configuration or a Virtual Agent Service Portal widget?

Kind regards,
Mark

[Dhirendra Singh]

@Mark Roethof 

Thanks but it doesnt help as I have already tested without using any theme, header etc. still the agent loads. how?

Also OOB latest portals dont have classic widget, I have already removed all instances of same as well. Any other pointers? attached is the new icon on latest oob installed csm application csm portal.

[Mark Roethof]

So did you check Service Portal Agent Chat configuration?

Kind regards,
Mark