Gamification in Service Portal (Knowledge18 CreatorCon)

Introduction Thanks for attending our Knowledge18 CreatorCon Session. During this session, NewRocket showcased a scoped Gamification application that is available to download free here:   NOTE It is required that your version of ServiceNow is running Jakarta or later. This scoped app is not supported on Istanbul or earlier. Components GamificationAPI (Script Include) - Contains the application logic Activities (Table) Badges (Table) Levels (Table) User Badges (Table) User Activities (Table) Gamer (Table) Gamification Points & Badges (Widget) Gamification Event Listener (Widget) Gamification Examples (Widget) Gamification (Page) Driver.js (Widget Dependency) GamificationDriver (UI Script) GamificationTourConfig (UI Script) GamificationDriver (CSS Include) Installation Install & commit the Update Set Navigate to your portal theme record (e.g. Stock) Inside the Header or Footer, embed the Gamification Event Listener widget using the folllowing code: <widget id="gamification-event-listener"></widget> Navigate to the gamification portal page (e.g. /sp?id=gamification) Click Award Points If all has been successful, you should be rewarded with 100 points Included Examples Feature Tour (using Driver.js Library) Social Q&A Configuration Includes "Gamification for Service Portal" Application Menu with the following Modules: Activities - The activities users complete to earn points Badges - Badges are earned based on accomplishments Gamers - An extension of sys_user, stores user points Levels - The levels users can obtain based on number of points To configure the Driver.js Feature Tour, edit the GamificationTourConfig UI Script. Corrections - (6/13/18) The GamificationAPI Script Include needs "Accessible from" set to "All application scopes" The documentation incorrectly lists the app prefix as "x_nero_gamificatio", however it should be "x_nero_gamificati" Additional documentation has been provided on the Gamification portal page (/sp?id=gamification). For more information on the Driver.js library, check out the docs here:

The Road to Kingston: Announcements (Part 1 of 3)

In this 3 part series, we'll take a deeper look into the new Service Portal features found in the ServiceNow Kingston release. Part 1 - Announcements Part 2 - Route Maps Part 3 - Order Guides Link to official ServiceNow Kingston Service Portal Release Notes Announcements for Service Portal One of the new features Kingston has to offer is the out-of-box support for announcements in Service Portal. No longer do you need to hack together your own implementation of a News Knowledge Base category to display within the Service Portal. The new Announcements feature gives you a extensive control over the look and feel of an announcement, as well as the content and routing for that announcement. In the rest of this article, we’ll go through the new configuration records for Announcements, as well as some of the cool configuration settings that are included. When To Use Announcements There are a number of use cases for announcements, such as informing employees of: A critical outage New employee health benefits information An upcoming planned maintenance window Feature Highlights Standard styles: Style announcements by creating custom style records where you can set the background color, foreground color, etc. Announcement window: Provide From and To date fields to determine the lifetime of an announcement Portal specific announcements: Select which portal you’d like the announcements to display on Configurable links: Add a link to an existing portal page or custom URL Configurable dismissal: Control whether users have the ability to dismiss the notification New Configuration Records The following configuration records have been added to ServiceNow to provide support for the new Announcements feature: New Tables Announcement [announcement] - Stores announcement information Announcement Style [announcement_style] - This table stores a few out-of-box styling configurations for the Announcements widget and allows users to create their own styles Announcement Consumer Type [announcement_consumer_type] - Stores the Consumer Type values of Banner and Widget Portal Announcements [m2m_announcement_portal] - Stores mapping between Announcement record and Portal record Dismissed Announcements [m2m_dismissed_announcement] - Stores mapping between User record and Announcement record New Module Announcements [Service Portal > Announcements] New Role announcement_admin - Maintain Service Portal Announcements including creating and deleting. Exploring The Announcement Form Most of the fields are self-explanatory but there are a few things worth mentioning: Type field: Contains a watchlist for Announcement Consumers. This is used to tell Service Portal where to render the announcement. Display style field: A reference to the Announcement Styles table, where you can define the look and feel of an announcement by creating or modifying existing styles. Click target field: This field is used to determine if the announcement is clickable, and if so where the user will be routed to. Options include a Service Portal Page record or a custom URL. Dismiss options field: Used to determine if a Service Portal user can dismiss the announcement. Portals related list: If there is no Portal record associated with the announcement, by default, the announcement will show on all portals. If a Portal record is provided, the announcement will only show on those Portals that have been specified. Consumer Types When it comes to displaying announcements in the Service Portal, administrators have 2 options. The first option is the Announcements banner feature and the second option is the new out-of-box Announcements widget, where you can define exactly where in a page the Announcement should be displayed. Given the nature of an announcement, this is generally what you’d like the user to see first, which is why it is included in the header for the Portal. The image below shows the 2 display options, which are references to the same Announcement record. Announcement Styles Looking to change the default blue announcement background to a color that matches your company’s color palette? This can easily be accomplished by creating a new Announcement Style record, which is where you can define the following configurations: Background color Foreground color (text color) Alignment (left aligned or center aligned text) Final Thoughts Although it’s a little frustrating that the Announcements feature cannot be modified since it’s injected behind the scenes before the header of the Service Portal, overall it’s a step in the right direction. The Announcement Styles and Portal related list on the Announcement record was a great architectural decision. What We Like Flexibility of Announcement styles Control over the display of an Announcement by the Portal related list on the Announcement record From and To fields for an easy-to-maintain announcement lifespan User dismissal options What Could Be Improved The Announcement banner is injected above the top of the page, so you have no control over the placement and limited options for styling The ability to provide an Angular template would have been a nice added feature h5,h4 { margin-top: 24px; margin-bottom: 18px; } h4 { color: #3d89cc; } .aligncenter { text-align: center; } .entry-content { border-top: 1px solid #ddd; }

Creating a sticky footer in your Service Portal

While developing web layouts, at some point you've probably run into the issue with the footer floating in the middle of the page just below the content. This can easily be fixed with a little CSS magic. Service Portal does support fixed headers and footers, but this causes the footer to stick to the browser window and overlap the content, which is not what we want. We want the footer to always be at the bottom of the page. This is called a "sticky footer".   In between Helsinki and Istanbul some major changes were to made to the outer page structure that broke some earlier solutions posted on the community. My goal is to provide a solution that would work with all versions of Service Portal and it's various supported browsers. The Solution: I've chosen to implement the sticky footer using Flexbox as this provides the most amount of flexibility. One added advantage of flexbox is that it also supports variable height footers, which many other solutions do not. Installation: Go to your portals theme record. Select a footer widget, you can use the out-of-box "Sample Footer" as a test. Make sure the "Fixed footer" checkbox is unchecked. Paste the following snippet of CSS into the "CSS variables" textarea, or alternatively you can include it in a CSS Include. [crayon-5b2f2790f328f265788423/] It's been tested on Helsinki, Istanbul, and Jakarta using Chrome, Safari 9+, IE10+. For additional information on flexbox, you can check out the following resources: A quick guide to flexbox by CSS-Tricks - here. Solved by Flexbox, a website dedicated to cool flexbox techniques - here. I hope you've picked up something new and useful from this article. Would love to hear your comments and questions in the comment section below.

Full Text Searches in Service Portal

In the stock Service Portal it asks the user "How can we help" and then provides the user with a big search input. This implies that the user could enter a sentence or phrase such as "reset my password" to answer the question, however this will rarely deliver the correct results. ServiceNow provides several search operators for performing full text searches with GlideRecord using ServiceNow's Zing search engine. However the stock widgets in Service Portal are hardcoded to use “123TEXTQUERY321” which works great for single word searches but not so much for searches containing multiple words or phrases. In this example, the simple addition of the word "my" prevented the user from finding the "Reset Password" item. To improve the search results, let’s take a quick look at some of the other options available. Search Operator Description IR_AND_QUERY Display results with exact matches of all terms only (Same as 123TEXTQUERY321) IR_OR_QUERY Display results with any matches of any terms. IR_AND_OR_QUERY First display results with exact matches of all terms, then display results with any matches of any terms Of the above, I recommend using IR_AND_OR_QUERY as this will return the best results across all combinations of searches. When performing a full text search, ServiceNow also adds an additional property to the GlideRecord called "ir_query_score" which contains the relevance score calculated by the system. Administrators can control the scoring for each field in a table with the ts_weight attribute. Here is a quick example of how to search the Service Catalog and return results ordered by relevancy: [crayon-5b2f27910099a998577042/] For further reading, check out:  

How to Avoid “Unsafe” Prefix on Links

If you’ve ever tried creating a dynamic link with a non-standard protocol or prefix (e.g. file, sms, tel, ftp, local) in Service Portal, you may have noticed that it prepends the url with “unsafe” rendering it unusable. The sanitization is a security measure aimed at preventing XSS attacks via html links and is coming from Angular.js which maintains a whitelist of safe urls. To fix this you will need to override the default whitelist by passing in a regular expression to the application configuration. You can do this by creating a “js_include” in your portal theme and include the following script: [crayon-5b2f279101a66398045369/] Where you see https?|ftp|mailto, etc… that is the regular expression you will want to update to include your url prefixes.

CSS Utility Classes in Service Portal

Included with Service Portal are a variety of different CSS utility classes loosely based on some of Bootstraps utility classes. For many of the classes below, you will see a format similar to: "m-t-lg", this stands for "margin top large". As I'm sure you can guess, there is also a classes for bottom, left, right, small (sm), medium (md), etc. and all the various combinations thereof.  This allows you to easily add consistent margins, padding, colors, etc. without creating custom styles within the widget. Here is a list we've compiled of some of the most common utility classes: Padding: wrapper, wrapper-xs, wrapper-sm, wrapper-md, wrapper-lg, wrapper-xl Horizontal Padding: padder, padder-xs, padder-md, padder-lg, padder-xl Vertical Padding: padder-v, padder-v-md, padder-v-lg, padder-v-xl Top Padding: padder-t, padding-top-s, padding-top-m, padding-top-lg, padder-t-lg, padder-t-xl Right Padding: pad-right Bottom Padding: padder-b-none, padder-b, padder-b-md, padder-b-lg, padder-b-xl Left Padding: N/A Top Margin: m-t, m-t-none, m-t-xxs, m-t-xs, m-t-sm, m-t-lg, m-t-xl, m-t-n-xs, m-t-n-lg Right Margin: m-r, m-r-none, m-r-xs, m-r-sm, m-r-lg, m-r-n Bottom Margin: m-b, m-b-none, m-b-xs, m-b-sm, m-b-lg, m-b-xl, m-b-n Left Margin: m-l, m-l-none, m-l-xs, m-l-sm, m-l-lg, m-l-n Text Color: text-muted, text-primary, text-success, text-info, text-warning, text-danger Background Color: bg-primary, bg-success, bg-info, bg-warning, bg-danger Float Elements pull-left - Floats an element to the left pull-right - Floats an element to the right Clearing Floats clearfix - Clears floats Display & Margin center-block - Sets an element to display:block with margin-right:auto and margin-left:auto Visibility show - Forces an element to be shown (display:block) hidden - Forces an element to be hidden (display:none) invisible - Forces an element to be invisible (visibility:hidden). Will take up space on page even though it is invisible sr-only - Hides an element to all devices except screen readers sr-only-focusable - Combine with "sr-only" to show the element again when it is focused (e.g. by a keyboard-only user) text-hide - Helps replace an element's text content with a background image close - Indicates a close icon caret - Indicates dropdown functionality (will reverse automatically in dropup menus) Hide visible-xs, visible-sm, visible-md, visible-lg Show hidden-xs, hidden-sm, hidden-md, hidden-lg For more details on CSS in Service Portal, you can check out the unofficial documentation on Github:

Create custom action buttons in Service Portal

A common feature request for Service Portal is to be able to add custom buttons to the sc_request or ticket page similar to the way you could add UI actions to a form. This functionality is not available out-of-box, but here is a quick example on how you could create a custom widget to display some buttons to mimic the UI Actions on a form. In this example, we will create a "Resolve Incident" button to place on the incident "ticket" page. HTML: [crayon-5b2f27910270f104335895/] Client Script: [crayon-5b2f279102718921606189/] Server Script: [crayon-5b2f27910271d701876017/] The resulting widget should look something like this: This is far from the complete solution, but will hopefully provide a good example to work off of.

Understanding Instances

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).

Embedding widgets in Service Catalog

In Service Catalog you have the ability to embed a UI Macro as a variable in your catalog items or record producers. UI Macros are based on Jelly and as such they will not render in Service Portal. To work around this, you can now embed a widget for your UI Macro variables when displaying your catalog in Service Portal. In this example, we're going to create three variables, and make the third variable a widget that will display the sum of the other variables. Create a catalog item with the following variables: Single Line Text: "value1" Single Line Text: "value2" Macro: "results" On the "results" variable record, you will see a "Default Value" tab, with a reference to the Widget. Create and select a new widget called "Embedded Results", and use the following values: HTML: [crayon-5b2f2791047a6546894009/] Client Script: [crayon-5b2f2791047af428481893/] Now when you view this catalog item in the portal, the embedded widget will display the results of the two variables: Note, that the "field.change" event fires when the field loses focus, so you will have to tab or click out of the field to see the results.