Embedded Insights with SAS Visual Analytics SDK

2 Likes

The latest release of SAS Visual Analytics 8.4 is out with a lot of new features and product enhancements. But this one in particular, the SAS Visual Analytics SDK is my most favorite. With SAS Visual Analytics (VA) SDK, organizations can leverage the openness of SAS platform and SAS Visual Analytics and build customized and personalized web applications, thereby providing a deep linking for embedded insights generated by SAS Visual Analytics into their own web applications and custom portals.

So, what is SAS Visual Analytics SDK?

SDK stands for “Software Development Kit”, which is a great way to think about it — a kit. Think about putting together a model car or plane. When constructing this model, a whole kit of items is needed, including the kit pieces themselves, the tools needed to put them together, assembly instructions, and so forth. An SDK or devkit functions in much the same way, providing a set of tools, libraries, relevant documentation, code samples, processes, and or guides that allow developers to create software applications on a specific platform.

The SAS Visual Analytics SDK is a collection of JavaScript libraries that web developers can use to embed SAS Visual Analytics insights within their software applications and customized web pages. Using the power of SAS Viya server as the backbone, the SDK will give businesses and developers the flexibility to build and customize an organization's user experience that meet their specific design/brand requirements and provide a wide range of SAS Viya insight capabilities that can be embedded into and delivered as part of their applications.

Ways to Integrate

SAS Visual Analytics SDK allows you to embed an entire VA report or individual report objects within your customized application or portal web page. The content you embed will be fully interactive and any interactions defined on those objects will remain functional, even when embedding individual objects including filter and brush interactions.

The ultimate goal of VA SDK is to bring embedded insights to the market. The intention is that objects are still designed in Visual Analytics, with options and interactions defined there in Visual Analytics. The VA SDK allows us flexibility to display our content into other third party or customer proprietary portals in a light weight manner.

This functionality is delivered as the va-report-components JavaScript library. With this library we could:

-: embed entire report or page with the <sas-report>custom HTML element tag

-: embed a single object with the <sas-report-object> element tag

-: customize your own HTML content based on data and actions that are driven from SAS Visual Analytics

For the official documentation on the various ways you can integrate refer to: developer.sas.com

Getting Started

In order to get started with using the VA SDK, you will need the following

VA SDK libraries: either downloaded or pointing to a mirrored Content Delivery Network (CDN) location
Access to a VA 8.4 on Viya 3.4 deployment with additional configurations for Cross-Origin Resource Sharing (CORS) and guest access
A Web Server that can host your portal page (html) consuming the embedded insights from VA 8.4 report\report objects

These pieces could be all on the same server or on totally different servers on different networks. Now let us look at each of these items in greater detail below.

SAS Visual Analytics SDK libraries

VA SDK libraries are published to npm (node package manager) where it can be downloaded and installed.

Since npm packages are mirrored by many Content Delivery Networks (CDN’s)you could also point to a CDN site directly instead of downloading the libraries. Refer to the Getting Started section of the developer.sas.com for installation instructions.

SAS Viya configuration for SAS Visual Analytics SDK

The following SAS Viya configuration needs to exist for VA SDK to function properly:

Enabling Guest Access

Connection to reports and objects in a report embedded into a third party portal web page can be made using the Guest access. Currently the va-report-components library only connects as the Guest user. This requires that the Viya system be setup to enable Guest, and that the Guest user have access to the appropriate report content and data. See Enabling Guest Access for more information. Future updates of SAS Visual Analytics SDK will support authentication and single sign on.

Enabling CORS

By default, your Viya deployment is not setup to allow access to REST api endpoints from different domains. This is needed in order to connect to Viya from the domain that is hosting your html page. This domain needs to be added to the allowOrigins property in Viya deployment's CORS configuration. See developer.sas.com and SAS Help Center for more information on enabling CORS.

Guest Access to reports, data and libraries

The guest user should have access to reports, and the underlying data that the report is based upon.

In my example below, I have enabled guest access on my Viya server, created a folder called "Reports for guest users" and set the permissions on the folder such that guests will get to Read and Read (convey) on all the reports in this folder. Further I moved the reports I wanted to share with my guests to this folder making sure the guests also have access to the underlying data and the CAS library that holds this data. It is very important to note here that your guest users not only needs access to the reports but also need access to the data that the report is based upon.

Permissions on "Reports for guest users" folder:

Creating a web server

Mac OS

You will also need a web server that can host your portal page (html) consuming the embedded insights from VA 8.4 report\report objects. Your Mac comes with a built in powerful web server for free. Anyone will be able to access the website stored on your mac and your website will be available any time your mac is turned on and connected to the internet. Versions of OS X prior to El Capitan, Yosemite, Mavericks, Mountain Lion and Mavericks can simply turn on “Web Sharing”, but from 10.8, 10.9, 10.10, and 10.11 onward you’ll need start the apache web server using the following command in a terminal. Enter the admin password when requested.

sudo apachectl start

Launch Safari, Chrome, or Firefox on the browser on your local machine and navigate to “http://127.0.0.1” to verify the server is running, you will see an “It Works!” message.

The default configuration files for the apache web server is under /etc/apache2/httpd.conf

And the default document root directory for the files as specified in the httpd.conf file is under

/Library/Webserver/Documents/

This location can be changed, but will require a restart of apachectl

sudo apachectl restart

The index.html file that servers the "It Works!" message resides here.

We will be creating our example VASDK.html report example page in this location.

How to find your Mac's external ipaddress:

Now you will need to know your Mac's external network address so you can access it from a remote computer on your network. There are many ways you could find this:

On your Mac, click on System Preferences->Network

You can select the connection that you are connected to and that should give you the ip address,

Alternatively - you can go to System Preferences -> Sharing and click on Remote login and that should give you the full hostname for your machine.

Alternatively you can also use the following ifconfig command line option to get the external ipaddress for yor Mac:

ifconfig | grep "inet " | grep -v 127.0.0.1

Refer to the following article: Find your IP Address on a Mac for step by step instructions with pictures.

At this point you could do a http://<youripaddress>:80 from a remote computer on your network and you should be able to see the "It Works!" message.

Windows 10

Similarly you can follow the link below to setup a IIS web server on Windows 10:

Creating web server on windows 10

VA SDK Report Example using embedded insights

Find attached a zip file that contains VASDK.html, article.css and a logo.png file.

Copy the VASDK.html as is and place it in the /Libraries/WebServer/Documents location of your Mac machine.

Copy the accompanying article.css and the logo.png file as well to the same location.

Make sure these files have Read permissions set for all users.

Read thru the VASDK.html to get familiarized with the various sections in there.

Now let us look at some of the tags in the VASDK.html

Loading the VA SDK Library

The following script tag in the html loads the VA SDK library. Notice in this case we are loading from a mirrored CDN location. In case you decide to download the library, the path will be modified accordingly. This is just an example. Please refer to the official developer page to get the latest tag for the library.

<script async src="https://unpkg.com/@sassoftware/va-report-components@0.1/dist/umd/va-report-components.js"> </script>

Embed a VA report or report object

To add a Visual Analytics report\report object to the page you will need to know two pieces of information:

Viya url: The root url of the Viya system on which you have Visual Analytics. In my example it is https://birdsgf01.unx.sas.com
Report uri: The uri of the report to embed. This value takes the form of /reports/reports/${UNIQUE_ID} and can be found in the link url of the Visual Analytics share report dialog, as shown here. Once the report link has been copied to your clipboard, use the custom tag generator in Getting Started page to generate the <sas-report> tag.

<sas-report
  authenticationType="guest"
  url="https://birdsgf01.unx.sas.com"
  reportUri="/reports/reports/c3c6befb-3981-4c9e-b011-7dc11dec5e37"
  hideNavigation
></sas-report>

Object id: It is also possible to pick out individual objects from a Visual Analytics report and add them to your page. To do this you will need to know one additional piece of information: The unique identifier of the object. Like the report uri, this can also be found in the link url of the Visual Analytics share object dialog, as shown here. Once the object link has been copied to your clipboard, use the custom tag generator in Getting Started page to generate the <sas-report-object> tag.

<sas-report-object
  authenticationType="guest"
  url="https://birdsgf01.unx.sas.com"
  reportUri="/reports/reports/698882d7-e119-45fc-a0f4-fc86f41392d1"
  objectName="ve27663"
></sas-report-object>

The example VASDK.html has a banner and a placeholder for four VA report objects. The title for every section has a link to view the pdf version of the report. In order for this to work make sure you save the pdf version of the report in the location where you save the VASDK.html

The HTML tag to add additional objects is as follows. Use this example below to modify the html to match values from your own environment. The goal of this example is to give you some basic files to get your own example going so that you can explore and play around with this functionality.

<div class="visual-container">
        <div class="object-header">
          <h2><a href="./WaterConsumptionMonitorReport.pdf">Top Water Consumers Dashboard</a></h2>
          <h3>Click on the link above to get a pdf version of the full report</h3>
        </div>
        <sas-report-object
          authenticationType="guest"
          url="https://birdsgf01.unx.sas.com"
          reportUri="/reports/reports/c4e55896-bd3b-4901-95d7-09157925e440"
          objectName="ve128"
        ></sas-report-object>
      </div>

Since my first 2 side by side objects are from the same report, when you interact with one object the interactions will take effect in the other object as well as shown below:

As you can see the SAS Visual Analytics SDK is a very powerful tool allowing users the flexibiliy to display and customize SAS Viya report content into other third party or customer proprietary portals and applications. Feel free to let us know if you have any questions or suggestions in the comments section below.

Also, refer to the SAS Visual Analytics 8.4 and the new SAS Visual Analytics SDK are now available! link for more details and documentation links.