Typeahead Search interact with Virtual Agent Service Portal Widget callout

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

Hi there,

Out-of-the-box the Virtual Agent Service Portal widget looks pretty clean, though a bit invisible. Using the Agent Chat Configuration you might change the widget icon using CSS, though that's it. If you do want to have the widget more visible, you do need to use a custom widget. Oke, though what options for more visibility are there?

That's actually completely up to you 😀. Your imagination is your limitation!

In previous articles I already shared examples of adding a callout, having the callout appear after N seconds, enlarging the chat icon. Let's add another idea, having the

Typeahead Search interact with a callout

on your Virtual Agent Service Portal widget.

Callout

So what is my understanding of a callout? Basically a bubble, next to the chat icon, which contains some information. For example the name of your Virtual Agent and a question. The contents could also be dynamic like I shared in Virtual Agent feature bubble (2), auto display after N seconds.

In this case, the Callout we are going for:

Typeahead Search

Out-of-the-box, a Typeahead Search widget is used on the Service Portal. This Typeahead Search provides the logged-in user with results on Catalog Items, Knowledge Articles, etcetera.

Typeahead Search -> Callout

So what about having the Typehead Search interact with a callout on the Virtual Agent Service Portal widget? For example, when the logged-in user has entered three searches, having the callout appear. The callout appearing to attract the logged-in user's attention that the Virtual Agent might be of assistance.

Technically it's possible to have Service Portal widgets interact which each other, using broadcast. So what can we do, with as little as possible customizing on the out-of-the-box Service Portal widgets for Typeahead Search and Virtual Agent?

Typeahead Search

Let's jump to the Typeahead Search widget. Looking at the Service Portal index page, you would find widget "Homepage Search". This widget actually embeds widget "Typeahead Search". This is the one we are after. After reading the widget code a while, you might notice that the text entered by the logged-in user, results in Client controller function "c.getSearchSuggestions". We could add a broadcast in this function. For example by adding:

if(c.data.search_count) {
	c.data.search_count = c.data.search_count + 1
} else {
	c.data.search_count = 1;
}

if(c.data.search_count == parseInt(c.data.typeahead_count)) {
	$rootScope.$broadcast('showConversationBubble');
}

The second If condition containing the broadcast, the first If condition to count the number of searches entered by the logged-in user. I also added the use of "c.data.typeahead_count", in the Server script this will get the value of a System Property.

data.typeahead_count = gs.getProperty('va.interact-typeahead-search.count') || 3;

Because we are using $rootscope and $broadcast, we do need to add both to the function in the Client controller on line 1.

That's all for the Typeahead Search widget.

Virtual Agent

Most work needs to be done on the Virtual Agent widget. First would be cloning the out-of-the-box widget and providing an ID. For example "sn-va-sp-widget-callout-typeahead-search", this ID is needed later when adding the widget to the header or footer of your Service Portal.

First, let's add a div that will represent the callout. At the end of the Body HTML template, though within the div of class "conversation-button-container":

<div ng-if="$ctrl.enableConversationBubble && !$ctrl.disableConversationBubble" class="conversation-bubble">
  <font class="conversation_bubble_question">{{::data.conversationBubbleAgentName}}</font><br />
  <font class="conversation_bubble_answer">{{::data.conversationBubbleAgentResponse}}</font>
</div>

Also on the button add:

ng-mouseenter="$ctrl.hideConversationBubble()"

This will make the callout hide, when the logged-in user hovers over the chat icon.

Next would be expanding the Server script. To support the usage of "data.conversationBubbleAgentName" and "data.conversationBubbleAgentResponse".

Adding:

data.conversationBubbleAgentName = gs.getProperty('va.virtual-agent.name') || 'Now Support';
data.conversationBubbleAgentResponse = gs.getMessage('Hi, can I help you?');

The Virtual Agent name can be added to a new System Property "va.virtual-agent.name". Also a UI Message "Hi, can I help you?" will be used for the message on the callout.

Final part for having the Typeahead Search widget interact with the Virtual Agent widget would be actually using the broadcast. This would be done in the Client controller:

$ctrl.hideConversationBubble = function() {
	$ctrl.disableConversationBubble = true;
}

$rootScope.$on('showConversationBubble', function() {
	$ctrl.enableConversationBubble = true;
});

The script also contains hiding the callout, as mentioned in the Body HTML template, when hovering over the chat icon.

Because the added script is using $rootScope, we do need to add $rootScope to the function on line 1.

Now both widgets can interact with each other! The only thing left… applying CSS on the callout:

$box-shadow: 0px 2px 11px #ababab;

.conversation-bubble {
  margin-right: 75px;
  height: $button-height;
  border: 1px solid #d4d4d4;
  border-radius: $bottom-margin;
  display: block;
  background-color: $color-white;

  box-shadow: $box-shadow;
  -moz-box-shadow: $box-shadow;
  -o-box-shadow: $box-shadow;
  padding: 8px 12px;  
}

.conversation_bubble_question {
  font-weight: bold;
}

.conversation_bubble_answer {
  font-style: oblique;
}

Header / Footer

Last, but certainly not least… embedding the Virtual Agent widget to the header or footer of your Service Portal. In this case, we are embedding the widget to the "Stock Header". Within the Body HTML Template, at the end add code like:

<widget id="sn-va-sp-widget-callout-typeahead-search" options='{"va_url_params":"sysparm_skip_load_history=true"}'></widget>

Note: The Update Set does not contain an updated Header or Footer. You will need to add yourself, as described above.

Result

It's a bit of work, and for some, this will look complicated. I'm certainly no Service Portal expect myself, though looking at other widgets, reading the code multiple times, just giving it a try… it will make sense at some point 😀.

The result of the work above should be when a user enters three times a search text, that the callout on the Virtual Agent widget appears.

Bonus

Let's animate the callout a little bit! To draw some extra attention of the logged-in user. Instead of the CSS mentioned above, use:

.conversation-bubble {
  margin-right: 75px;
  height: $button-height;
  border: 1px solid #d4d4d4;
  border-radius: $bottom-margin;
  display: block;
  background-color: $color-white;

  box-shadow: $box-shadow;
  -moz-box-shadow: $box-shadow;
  -o-box-shadow: $box-shadow;
  padding: 8px 12px;  

  animation: shake 0.82s cubic-bezier(.36,.07,.19,.97) both;
  transform: translate3d(0, 0, 0);
  backface-visibility: hidden;
  perspective: 1000px;
}

@keyframes shake {
  10%, 90% {
    transform: translate3d(-1px, 0, 0);
  }

  20%, 80% {
    transform: translate3d(2px, 0, 0);
  }

  30%, 50%, 70% {
    transform: translate3d(-4px, 0, 0);
  }

  40%, 60% {
    transform: translate3d(4px, 0, 0);
  }
}

.conversation_bubble_question {
  font-weight: bold;
}

.conversation_bubble_answer {
  font-style: oblique;
}

Share

An Update Set with this Service Portal widget can be downloaded from Share:
- Virtual Agent Service Portal Widget: Callout interact with Typeahead Search

Note: The Update Set contains the updated out-of-the-box Typeahead Search widget. By default, this is not possible, though I've chosen to overwrite the Access Control with Access Role "maint" for this. It's up to you to decide to do the same or going for a cloned Typeahead Search widget.

---

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

Kind regards,

Mark Roethof

ServiceNow Technical Consultant @ Quint Technology
1x ServiceNow Developer MVP

1x ServiceNow Community MVP

---

LinkedIn