Add rating functionality to your Visual Analytics report

1 Like

Collaboration between colleagues is important in today's business world. After the pandemic and the massive introduction of remote work, being able to share opinions is something that many companies are looking for. Giving an evaluation is one way to share your feedback. You most probably rated a product you bought on your favorite online platform or a movie that you've watched on a streaming platform. Adding this type of rating functionality is something that is sometimes requested in Visual Analytics reports. In this article, I will walk you through the steps to introduce a rating component in a Visual Analytics report and display the collected results.

What do you need?

Unfortunately, SAS Visual Analytics doesn't provide a rating component out-of-the-box. It means that we will need to create it. Luckily, SAS Visual Analytics has the Data-Driven Content object. This object can be added to any report to embed an external web page. The benefit of the Data-Driven Content (DDC) object is the data exchange capability that it provides. By data exchange, I mean that the DDC object can retrieve data used in the report and send data to the report. The DDC object can be considered as a custom object where you can define your business logic and most importantly the visualization that you want. The DDC object is often used to embed visualizations that are not available in the SAS Visual Analytics graph objects. You can, for example, embed an organization chart, a sunburst chart, or any other visualization which are available in JavaScript libraries like D3js, Google Charts, or Canvas JS to name a few. As you may have noticed, these libraries are based on the JavaScript language, and this is the technology you should use to integrate the Visual Analytics data in an external web page which will then be referenced in the DDC object within Visual Analytics.

At a high level, to integrate a Data-Driven Content object in your Visual Analytics report, you need:

A web page with some JavaScript code
A web server to host and render that page

What you will see in this article is that you can also use SAS code to process some data on the CAS server. If you want to get more information and ideas about using Data-Driven Content object in SAS Visual Analytics, please have a look to the following articles on SAS Support Communities:

What will the report look like?

If you follow along with this article, your final web page will look like this:

Select any image to see a larger version.
Mobile users: To view the images, select the "Full" version at the bottom of the page.

On the left-hand side, you have a list table which is used to select a car model. When the user selects a row in the list table the form in the Data-Driven Content (on the top right) is populated with the Make and Model information. The user selects a rating level and saves the evaluation. To save the evaluation, a SAS Viya Job is called and saves the evaluation in table which contains all the ratings. The rating table is then used to populate the bar chart which displays the Maker's rating in the bottom right.

Designing the report

Now that you have seen the report, I hope you are willing to know how it is implemented. Here are the steps:

Load the SASHELP.CARS data into CAS.
Create a new report based on CARS table.
Add a List Table object to the report.
Add Make, Model and Invoice variables to the List Table object.
Add a Data-Driven Content object to the right of the List Table object.
Add Make and Model variables to the Data-Driven Content object.
Add a Bar Chart object under the Data-Driven Content object.
Select the List Table object and define a new action to link the List table object to the Data-Driven Content object.
Validate the defined action by clicking on a row in the List Table object. The Data-Driven Content object should only display the selected car model.

When done, your report should look like this.

Please note that no data items are assigned to the Bar Chart object as it will use another CAS table which is not yet created.

Building the web page

SAS provides JavaScript code to integrate data coming from the Visual Analytics report into a web page. The code is available on GitHub. To ease the development process, and to build a nice-looking form, Bootstrap and jQuery will be used. These are two popular JavaScript libraries which can be integrated easily from a CDN location or downloaded from:

I chose to use the CDN option as it is easier to maintain. If you choose the CDN option, you should make sure that the end-users have internet access when consuming the report.

The top part of the HTML code is the following:

If you have been through the code, you may have noticed that on line 11, there is a reference to jobExecutionUtil.js. This file is not a standard file provided by SAS but it provides a helper function to execute SAS Viya Jobs: executeJob()

The code for that function is available in the Git repository and will be used in this example.

The executeJob function requires three parameters:

The URL to the SAS Environment
The data which should be passed to the job
The parameters that should be passed to the SASJobExecution web application. The parameters should contain the information about the job which should be executed.

Let's now dive into the actual code of the web page. The body of the HTML page contains a reference to a form element and a script tag. The form element is not more than:

The script tag will have different purpose:

Create dynamically the content of the form element: displayForm and ratingComponent
Handle the submission of the job which will update the CAS table.

To achieve this, a function named displayForm is used to build the form content. The function is triggered when the page receives data from the Visual Analytic report through the messagingUtil. When the form is submitted the executeJob function will be executed.

The displayForm code looks like this:

And the ratingComponent is defined like this:

And finally the code which triggers the form creation:

The HTML page is now complete. The next step will be to define the SAS Viya Job.

Hosting the web page

To use the web page, you need to host it. You have different approaches to deploy the web page:

An existing web server like Apache, Nginx, NodeJS, Flask, Django, ...
A container based on your favorite web server

In this article, I will not explain the differences and the benefits of using one or the other approach. If you want to get more information about deploying a web page for DDC in Viya 2020.1 or higher, please refer to this article: Deploy a custom web application in the cloud for Data-Driven Content object in SAS Viya 4.

As the purpose of this article is to build a simple demo, I suggest that you host a web server on your development machine. If you use Visual Studio Code to create the web page, you can for example install the Five Server extension. It will start a standalone web server on your machine with reload functionality. As this is the option I used for the development, you will find a fiveserver.config.js file in the repository. The file is passing parameters to Five Server to execute on port 3000 and sets the protocol to 3000 on localhost.

If you are running on a local machine, you should also make sure that the CORS and CSRF configurations are correct. You can therefore follow the instructions in the article: Configure Cross-Origin Resource Sharing for SAS Viya for REST API’s and web developments

Defining the SAS Viya job

SAS Viya jobs are designed to execute predefined SAS code from web interfaces. To create a job, you should use SAS Studio. In the current application, the job will receive data from the web page, manipulate the data and store them in a CAS table.

The job definition is as follows:

Now that you have the job definition, you can save it and update the reference in index.html. Around line 70, you will see the call to the Viya job. Make sure that the url constant and the parameters are properly set.

Updating the report

At this point, you have all the components to rate cars. You have created the job and the web application is hosted and reachable.

You should now update the report to integrate the web page, add the newly created data source, and populate the role assignments for the Bar Chart.

To insert the web page in the Data-Driven Content object, select the object and in the Options pane, specify the URL of the web page. If you chose the Five Server extension, your web page should be available on https://localhost:3000 . You can set that value for the parameter:

The other modifications are for the Bar Chart to display data. You should:

Add the CARSRATE table to the report
Change the rating variable aggregation to Average.
Assign the Make and rating variables to the Bar Chart
Change the X Axis options to enforce the maximum to be: 5

When done, you should see the following result:

In order to see the updated values in the report, you should adapt the refresh rate of the Bar Chart:

When done, save the report and switch to the Viewer mode.

Demo

You have now a fully functional report with a rating component. Here is the result:

(view in My Videos)

Conclusion

Using Data-Driven Content in SAS Visual Analytics offers a wide range of functionalities to report designers. With a bit of HTML and JavaScript knowledge, you can create a web page which suits your needs and allows you to interact with data from the Visual Analytics report. You can combine the functionalities of Visual Analytics with other SAS components. You have seen how SAS Viya Jobs could be used. You can also integrate the models that are deployed to MAS or SCR. You can also execute specific CAS actions using REST APIs. As you can see, there is no limit to integration with SAS data. If you want to integrate with sources of information that are external to SAS, you can also make it through REST APIs.

The code for this web page is available here.

Find more articles from SAS Global Enablement and Learning here.

Share this content:

SAS Users channel on YouTube

YouTube