How to install and configure HappySignals Service Portal IT Experience to ServiceNow

The installation process in brief:

1. Requesting the portal Experience application from ServiceNow Store
2. Installing the application to ServiceNow instance
3. Configuring the application
4. Activating two-way integration
5. Adding the measurement widget(s) to desired portal pages
6. (Optional) Setting up translations for survey elements
7. Testing the survey
8. All done!

Before you start

There are a couple of things to note before starting the installation process. 

1. make sure you have administrator access to the ServiceNow instance where you are installing the application
2. make sure you have access to the HappySignals cloud services
3. make sure you have received the following information from HappySignals: 
   1. End-point URLs to your HappySignals cloud environments.
      Generally, the end-point URL looks something like: https://[your company name].happysignals.com
   2. Shared secrets for all your HappySignals cloud environments, which are used to make sure generated feedbacks come from your environments.
   3. API-keys for all your HappySignals cloud environments, which are used to make sure pull feedback data back to your ServiceNow.
4. make sure you have requested the Portal Experience application from the ServiceNow store. For details on how to do this, see our article on "How to proceed when you want to download our Application from ServiceNow Store?"

Installing the application

Installation of the application is very straightforward and requires only a few steps to be complete:

1. In the ServiceNow application navigator, find the "System Applications" module. In the "System Applications" module expand the "All Available Applications" section and click on the "All" menu item.
2. In the "All applications" page, type "HappySignals" to the search bar. In the application list below find the Service Portal IT Experience application and click the "Install"-button. Confirm the installation in the modal that pops up. 
3. Wait for the install to complete.

Once the installation is complete reload the page and search "HappySignal Service Portal Experience" in the application navigator and confirm the application menu is there.

Configuring the application

After the application is installed and updated you can proceed to the configurations. First, switch your application scope to the "HappySignals Service Portal Experience".

Open the "General Properties" module under the HappySignals Service Portal Experience application.

In general properties, first configure the three environment specific details first:

1. "Endpoint", HappySignals cloud environment URL
2. "Shared Secret", shared secret to make sure the responses come from your environment
3. "Vendor API key", API that is used to access the HappySignals API.
   
   

Once you've set the environment specific details, you are ready to continue with the other configurations.

See the full list of properties to check and their descriptions below.

First property section:

User data configuration:

Configurations in this section define what information about the person who provides the feedback is passed on to HappySignals.

You can use field names from the "Users" table in the configurations to map data dynamically. Or you can use static values that will be the same for all feedbacks by wrapping a configuration value with quotation marks ("). 

Name	Description	Default value
Employment started	Information about the user's employment start date.	sys_created_on
Company	Information about the user's company.	company
Title	Information about the user's job role or title.	title
Location	Information about the user's town, city, office building or similar.	location
Country	Information about the user's country. The country information should be the full country name in English.	location.country
Region	Information about the user's region, department or similar.
Use user preferences for language selection	If enabled, looks for user's language selection in user preferences.	false
Language	A field containing information about the user's language. Used when user preference selection is not enabled or static value has been defined.	preferred_language

Widget Display Settings:

Settings in this section affect when the HappySignals widgets won't appear for the portal end users.

Activating the two-way integration

Now that all base configurations have been done, it's time to activate the two-way integration to get the feedback data back to ServiceNow.

To activate the integration, open the "Integration Job" under the HappySignals Service Portal Experience application and set the job as active.

By default the job runs once a day, but if you need more realtime integration, you can change the run interval in the job settings.

Adding the widget(s) to desired portal pages

To get started with gathering experience about the Service Portal you need to add the HappySignals widget(s) to desired portal pages.

Open your Service Portal and navigate to the page where you want to add the widget.

Move your cursor over a piece of content within the page and press CONTROL + RIGHT MOUSE CLICK to bring up the Service Portal context menu. 

In the context menu select the "Page in Designer" to open up the Service Portal page designer. 

With the page designer, drag a new "Container" to the page content. 

Then select the container in the page content and edit its settings by clicking the small pen icon  in the top-right corner of the page. 

In the container settings change the width to "Fluid" and click "Save".

Drag a 12 column layout to the newly added container.

With the new container and layout setup, it's time to add the HappySignals widgets to it.

Search with a keyword "HappySignals" and two widgets will appear in the list.

 

HappySignals Survey Pop-Up

First drag the HappySignals Survey Pop-Up to the newly add newly added 12 column layout. A blue placeholder image should show up in the page content.

Select the newly added widget and click on the small pen icon to edit the widget instance options.

Once ready with the options click "Save".

HappySignals Call To Action

The HappySignal Call To Action widget is small non-interruptive element that place on your portal page. The user can click the Call To Action to bring up the Survey Pop-Up at will. 

To add the Call to Action element to the page, drag it to the 12 column with the Survey Pop-Up widget. A blue placeholder image should show up in the page content.

Select the newly added Call to Action widget and click on the small pen icon to edit the widget instance options.

Option	Description	Default Value
Text	Text that appears on the call to action once it expands.	How do you like this portal?
Position	Select the position where the call to action appears on the page.	bottom-left
Theme	Select theme for the call to action.	light
(Custom theme) Background Colour	Set the background color for the call to action. Only applies if custom theme is selected.	#FFF
(Custom theme) Background Hover Colour	Set the background hover color for the call to action. Only applies if custom theme is selected.	#fefefe
(Custom theme) Text and Logo Colour	Select the colour of the logo and text. Only applies if custom theme is selected.	black
Automatic Expand Probability (%)	Percentage probability that the call to action will expand on any given page load.	50
Automatic Expand Delay (s)	How long will the call  to action remain minimized before expanding.	5

Once ready with the options click "Save".

(Optional) Setting up translations for survey elements

If you offer your service portal in multiple different languages you can setup translations for the HappySignals portal elements. Translation for the elements can be setup using ServiceNow built-in System UI Messages functionalities. 

To setup your translation navigate to "System UI -> Messages" and start by creating a new message record to the table.

In message record form you will need to fill in three fields described below:

If you want to translate the Call to Action widget text, the key for your translated messages is the text that you have added in the widget instance options. Note that different widget instances of the call to action can have different texts and thus use different translation keys.

To add multiple translations, simply create additional Message records with the same key but select another value in the language field.

Testing the survey

With the configurations done, you are ready to test the survey.

Open the page in Service Portal. Depending on your configurations you can either use the call-to-action to bring up the feedback survey or reload the page until the survey comes up on its own.

With the feedback survey visible, click on one of the rating buttons which opens the HappySignals survey form on a new tab.

If no errors appear and you are able to submit feedback, then everything is working as should be to capture feedbacks.

To test the two-way integration open the "Integration Job" under the HappySignals Service Portal Experience application menu. Execute the job manually to fetch latest feedback from HappySignals cloud service. Once the job has run, go to "HappySignals Feedbacks" and confirm that the feedback you just provided is available on the table.

That's it, you have now installed and configured HappySignals Portal Experience to your ServiceNow.