VA Report Example: Using D3js in your Report

6 Likes

Have you ever wished to create graphs in your SAS Visual Analytics reports that are not part of the default SAS Visual Analytics objects but can still interact with the other report objects?

Have you ever been jealous of open source javascript graph frameworks?

In the SAS Visual Analytics 7.x versions, you probably used one of the following techniques or a mixture of creating:

A custom graph in SAS Visual Analytics's Custom Graph Builder
A stored process to extract data and display the data using SAS
A stored process which generates an html file which calls an open source javascript framework
A web page and reference it as an external URL

What if SAS Visual Analytics offers you that functionality out of the box?

It does! Starting with the SAS Visual Analytics 8.2 release on SAS Viya you can use other open sourced graphics with the Data-Driven Content objects.

This blog entry explains how you can integrate SAS Visual Analytics 8.2+ report and a D3.js graph which makes use of the VA report data. D3.js has been chosen because it is a popular javascript library that specializes in data visualizations. Other javascript frameworks/libraries such as jQuery, Processing.js, etc. can also be integrated in your VA report. The integration is seamless and you will probably think that the graph is part of the default objects provided by SAS Visual Analytics.

With a basic understanding of javascript and html, adding a Data-Driven Content object is an easy task. The objective of this blog is not to explain how to code in javascript and html but to focus on how to use these pieces to integrate with a VA report. I have created all the files you need to be able to view this report in your own VA 8.2+ environment. I have attached a file that contains what is needed: the xml of the report, sample data, javascript files and an html page. The javascript files and the html page can be found with other samples on SAS repository on Github. You also need an environment with SAS Visual Analytics 8.2 or later licensed and installed.

The high level steps include: loading the sample data into CAS, then importing the xml of the report in SAS Visual Analytics and saving the html page and the javascript files on a web server. For the purpose of this example, the xml and javascript files are hosted on my personal server which should always be available to the VA environment. If you want to host the files on your own VA environment, you can store the files under the html directory under /var/www/ on the machine that hosts your HTTP Apache web service. You should copy the 2 directories and the html page contained in the zip file under the same directory.

To import the data and the report, you should:

First we will import the data. From SAS Drive, use the side menu and select Explore and Visualize Data
Choose to create a New report
From the Data pane, select Import > Local File and navigate to the sample data provided in the csv file. There is no need to change options. If you want to change the name of the Target table, it can be done but it requires to update the data source name in the xml of the report. Click on Import Item.
Click on OK to close the panel. You should now see the available data items listed in the Data pane.
Now we will open/replace my provided VA report into this current report. Press the Ctrl + Alt + b keys simultaneously on your keyboard. This will open the current report BIRD (Business Intelligence Report Definition). When the SAS Visual Analytics Diagnostics appear, you will see the xml that defines this report.
Replace the xml of the report with the one I provided in the package. This is a quick and easy way to import a report if you do not have administrative access in your environment.
Click on Load
You should now see the report with the Data-Driven Content object.

If you uncheck or check some values in the List control, the graph adapts automatically.

What are the important points when designing such a report?

The Options of the Data-Driven Content object should point to the URL of your html file. (In the attached code example: d3_radialStackedBar.html). If you don't have access to a web server, you can use the following address: https://sassoftware.github.io/sas-visualanalytics-thirdpartyvisualizations/samples/d3_radialStackedB...
The Roles should contain all the variables that are used in your graph. In this example, the data set is small so all the variables can be selected. If the dataset contains many variables, it might be a good idea to limit the variables to improve the performance.

What you should have in mind when designing the html?

The html should contain the following code to link the html page and the data used in the Visual Analytics report:

if (window.addEventListener) {
       // For standards-compliant web browsers
       window.addEventListener("message", onMessage, false);
   } else {
       window.attachEvent("onmessage", onMessage);
   }
// Retrieve data and begin processing
   function onMessage(event) {
       if (event && event.data)
       {
           //process event.data
       }
   }

To ease your developments, SAS provides functions to use in your html page. The functions are explained here.

D3.js object might require different layout for the JSON data than the one provided by Data-Driven Content object. This means that some manipulation of the JSON object is required before usage in the D3.js objects.
The html page is embedded into the Data-Driven Content object in the report. This means that you might have to resize the graph to have a nicer layout.
Developer Tools of the browser (for Chrome, Firefox and Internet Explorer) are your best friend. It allows to debug the code but also see the data object sent by SAS.

Where can you find information?

About Data-Driven Content object: SAS Help Center
About D3.js: https://d3js.org/
About the specific D3.js graph (radial stacked bar): https://gist.github.com/mbostock/6fead6d1378d6df5ae77bb6a719afcb2
SAS Communities: Data-Driven Content: leveraging third-party visualizations in SAS Visual Analytics and #D3Thursday article series

pritesh_sas · ‎11-05-2020

Works like a charm. Thank you sharing