SAS Viya SDK for JavaScript- A Tale of Two Methods (Part 3 - Report Packages)

[#1]

This is the third part of a three-part series that describes the connection options for the SAS Viya SDK for JavaScript.

• Overview
• Direct Connection
• Report Packages (this article!)

Recall that the report components library of the SAS Viya SDK for JavaScript can be used in two fundamentally different ways: online using a direct connection to SAS Viya or offline using SAS report packages. In this article, we discuss the requirements, the steps, and the details of using SAS report packages.

Requirements

When you use SAS report packages, you display content that has been exported from SAS Visual Analytics and hosted on your own web server. This enables you to display content without being connected to SAS Viya, which means that no authentication is required. This enables your webpage traffic to scale independently from your SAS Viya deployment, which means you can support large end-user audiences and better leverage your commodity web server infrastructure by reserving SAS Viya for your data scientists, business analysts, and other internal users. For this method, you also don’t need to do any specific configuration in SAS Viya to enable access from your hosted page. Offline access, however, does not mean static! This method still enables object-specific interaction between report objects. Some objects and some advanced object functionalities, however, are not supported. This method also faces some data limitations, is locale specific, and cannot display external content (like background maps, web content, and external images). In addition, the exported content in the SAS report packages must be updated when the data updates and there may be some security implications. For example, the data used to display the content (and for all interactions) is saved in CSV files that also need to be hosted on your web server, which means this data can be easily accessed. You will need to ensure that the web server hosting this content has the appropriate security and authorization constraints in place based on the sensitivity of your data.

Benefits	Considerations
No authentication	Some objects/functionalities not supported
Deliver at scale: support large end-user audiences, better leverage infrastructure	Data limitations
No configuration	Locale specific
Interactions between objects	Cannot display external content
	Content updates required
	Some security implications

Steps

To use SAS report packages, you (1) export a snapshot of your SAS Visual Analytics content, (2) host the content on your web server, and (3) embed the exported content into your custom web pages using standard web technologies (like HTML, CSS, and JavaScript).

Step 1: Export

In the Export step, you export the SAS report package from the SAS Visual Analytics report and deploy the package to the web server where the web page is hosted. You can export the entire report, pages within the report, containers and their associated content, or individual objects. To interactively export a report package in SAS Visual Analytics, use the More button (the snowman) in the upper right corner of the report and select Export > Report package.

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

In the Export Report Package window, you can choose the contents to export (the entire report, specific pages of the report, containers and their associated objects, or individual objects) and the persistence of the report package. When you are finished specifying options, select Export to create the report package.

Note: The time it takes to perform the export depends on the number of objects selected, the complexity of the report, and the amount of data needed for the export.

Exported reports display all pages in the report and can be easily navigated using page tabs or page links. In fact, the navigation experience is very similar to viewing the report within SAS Viya. Exported pages display all content on the page and are interactive. If an exported page links to another page (whether basic, hidden, or pop-up), both the source page and the target page must be included in the SAS report package for the linked page to display properly. Exported containers display all content in the container and are interactive. Exported objects are interactive and can be placed anywhere on the web page.

Note: To enable interactivity between individual objects within the web page, you need to use the reportContextKey attribute for the custom HTML elements. A shared report context enables report actions, like filtering and linked selections, and report parameters between objects. In contrast, unique report contexts enable multiple instances of the same report object to be shown at one time (for example, one with filtering applied and one without filtering applied for easy comparison).

In addition, you can choose to save the exported file to SAS content where it will persist indefinitely and can be downloaded from SAS Drive. You must, however, manage the life cycle of this file. The exported content is stored in a compressed file named report-name.sasreportpkg.zip and includes samples of exported content (including code snippets), images, style sheets, and data. The package includes all the data that is needed to render the selected objects, as well as the data that is needed to support any actions and links. It’s a best practice to only export a subset of the most relevant and important objects and pages as there are limitations on objects and functionality. For more information about the objects and features supported, see “SAS Report Package Reference” in the SAS Visual Analytics: Reference documentation. After the exported file is created, you deploy the package to the web server where the web page is hosted by unzipping the file. It’s a best practice to co-locate the report package content in a reportAssets folder with other assets for your web page. It is, however, possible to put the report package content anywhere that is accessible through a URL.

Note: Administrators can manage access to the export package capability using the /SASVisualAnalyticsCommon_capabilities/exportPackage authorization rule in SAS Environment Manager. This authorization rule defaults to granting permission to all authenticated users, but administrators can modify the rule to lock down access to specific users or groups. In addition, administrators can use the sas.reportpackages.export set of configuration properties in SAS Environment Manager to control time limits and data limits for exporting report packages. However, it is recommended to modify this setting cautiously and consider the available resources before you make changes as these can affect the overall performance and stability of the system.

When designing a report that you want to export as a report package, there are some considerations that apply. As a best practice, you should use basic objects, use basic functionality, and limit the size of the data used in the report. For more information, see “Exporting Report Packages” in the SAS Visual Analytics: Designing Reports documentation.

Step 2: Validate

In the Validate step, you view the package contents and verify that the exported content can be displayed on the web. The package contents can include the following files:

• packageIndex.html- This file is included to give you detailed information about all the exported report content and code snippets. This can help you incorporate the content into your own web page.
• index.html- This file demonstrates the mechanics of how to use the report components library to render the report content. It contains the necessary script tags to access the library, the custom HTML elements needed to display the exported content, and the style information needed to correctly size the content.
• packageStatusReport.txt- This file provides information about any issues. It contains details about the nature of the problems, explanations of objects that could not be exported or have limitations on interactivity, and possible reasons for those limitations. If no issues are encountered, this file is not created.
• metadataSupplement.xml- This file contains details about the data source used in the report and information about columns (like the types, labels, and formats).

In addition, the package can include three folders:

• css- This folder contains style sheets with specific style information. These CSS files can be referenced in your web page.
• data- This folder contains CSV files. These files contain all the data that is needed to render the selected objects, as well as the data that is needed to support any actions or links. If you are exporting only a few objects with limited data, the data folder may not be created. Instead, the data is embedded in the xml file.
• images- This folder contains any images used in the exported content. If your exported content contains no images, the images folder will not be created.

Step 3: Insert

In the Insert step, you add the exported content to your web page or application. Your web page needs to access the report components library from the SAS Viya SDK for JavaScript, reference the custom HTML elements from the report package, and specify appropriate styles to display the content as desired.

Access

First, your custom web page needs to access the report components library from the SAS Viya SDK for JavaScript. This can be accomplished by adding the following script tag to the head section of your web page:

<script src="https://cdn.developer.sas.com/packages/va-report-components/latest/dist/umd/va-report-components.js" async="">

The script tag accesses the va-report-components library (from the SAS Viya SDK for JavaScript) from the SAS Developer CDN (content delivery network). This method does not require installation or hosting of the library code and assets.

Note: When the library is used in production, consider pinning it to an explicit version. In the URL above, you would replace latest with major.minor.patch semantic version.

Note: Alternatively, because the va-report-components library is published to NPM, it can be installed by running a npm install command, deploying the contents of the folder to your page, and loading the deployed content using a script tag. See the "SAS Visual Analytics SDK: Getting Started" page for more information about this method (including the commands to perform these actions).

 

Reference

Next, your custom web page needs to reference the custom HTML elements from the report package. This can be done by adding the custom HTML tag to the body section of your web page. Three custom HTML elements are available: sas-report (which renders the entire report), sas-report-page (which renders a report page), and sas-report-object (which renders a report object, including containers that contain other objects).

Note: These are the same custom HTML elements used for the direct connection.

Each custom HTML element has several required attributes, which depend on the method used and the specific element. In this article, we will discuss the attributes for SAS report packages and each custom element.

<sas-report packageUri=ʹreportAssets/ʹ></sas-report>

General Attributes

For SAS report packages, the packageURI attribute points to the location of the package contents using either an absolute URL or a relative URL.

Report Element Attributes

The sas-report element has some optional attributes: hideNavigation and restrictViewportGestures. The hideNavigation attribute indicates whether page tabs should be displayed (true) or hidden (false). By default, this attribute is set to ‘auto’ which displays tabs only for reports with more than one page. The restrictViewportGestures attribute specifies how zooming will be handled for the report and objects within the report. By default, the scroll-wheel can be used for page scrolling on the web page and for zooming objects in the report (false). Specify this value as true if you want a modifier key to be used in addition to the scroll wheel. This is highly recommended when embedding elements in a layout that causes overflow as it can greatly improve your viewer experience.

Report Page Element Attributes

<sas-report-page packageUri='reportAssets/' pageName='page-name'></sas-report-page>

<sas-report-page packageUri='reportAssets/' pageIndex=0></sas-report-page>

In addition, the sas-report-page element requires either the pageName attribute (which specifies the internal name of the page) or the pageIndex attribute (which specifies the index of the page, where 0 is the first page). Optional attributes include restrictViewportGestures and reportContextKey.

Report Object Element Attributes

<sas-report-object packageUri='reportAssets/' objectName='object-name'><;/sas-report-object>

The sas-report-object element requires the objectName property (which specifies the internal name of the object). Optional attributes include restrictViewportGestures, reportContextKey, and hideLoadImage. The hideLoadImage attribute displays a placeholder static image of the report while it is loading (false) or hides the placeholder and displays a loading indicator (true).

Specify

Finally, your custom web page needs to specify appropriate styles to display the SAS Visual Analytics content as desired. This can be achieved by adding a style tag in the head section or by adding the style attribute to the custom HTML tag. By default, the SAS Visual Analytics content will be displayed in a small space, but styles can be used to adjust the height and width of the elements as desired.

sas-report,
sas-report-page,
sas-report-object {
width: 75vw;
height: 75vh;
}

For example, you can use external CSS in a file or internal CSS in the head section to specify the height and width for all the custom HTML elements. In this example, the width is set to 75% of the viewport width (vw) and 75% of the viewport height (vh).

<sas-report-object packageUri='reportAssets/' objectName='object-name' style='width:75%; height:75%;'></sas-report-object>

Alternatively, you can use inline CSS in the style attribute for the custom HTML element to apply styles for only that element. In this example, the width is set to 75% of the screen and the height is also set to 75% of the screen.

In addition, two custom CSS properties are available for the sas-report custom HTML element: --sas-report-background-color and --sas-report-padding. These custom properties can be specified using external CSS, internal CSS, or inline CSS. The --sas-report-background-color style can be used to control the background color of the area surrounding the report content, including the report controls area, the area behind the tab bar, the inactive page tabs, and the padding. By default, the color is chosen based on the report theme used to create the report in SAS Visual Analytics, but you can specify an RGB value (rgb(255, 127, 80), a Hex value (#FF7F50), or a color name (coral). The --sas-report-padding style can be used to specify the padding between the report content and the boundary of the custom element. By default this value is 0.

Scheduling Exports

Because a SAS report package stores a snapshot of the report at the time of the export, an interactive export is only recommended for testing and learning about supported export features. If your data updates regularly or you want to use the report package in a production environment, you might want to automate the creation of the report package by scheduling the export using the SAS Viya platform command-line interface (CLI). The CLI enables you to interact directly with the SAS Viya platform REST services and can be used to work with the platform programmatically. The CLI contains many plug-ins that can be used to manage authorization, users, services, licenses, and SAS Viya content (like folders, models, and reports). The reports plug-in has a build-package command that generates report packages.

To export an entire report, use the command seen here:

sas-viya reports build-package --id report-ID --output-file package-name --output-location directory

The report-ID can be found in the Content page of SAS Environment Manager by navigating to the report and viewing the URI (/reports/report/report-ID). The package-name specifies the name of the zipped file that is created, and the directory specifies the location where the file will be stored.

To export a page within the report, use the reports list-elements command to determine the internal names of the elements of the report (like the page-name) and use the reports build-packages command to export the package.

sas-viya reports list-elements --id report-ID

sas-viya reports build-package --id report-ID --report-elements ʺpage-nameʺ

The page-name is the name of the page to export.

To export objects in a report, use the reports list-elements command to determine the internal names of the elements of the report (like the object-name) and use the reports build-packages command to export the package.

sas-viya reports list-elements --id report-ID

sas-viya reports build-package --id report-ID --report-elements ʺobject1-name, object2-nameʺ --output-file package-name --output-location directory

The output-file and output-location commands can be used to specify the names and locations of the exported reports, pages, or objects.

Once you’ve constructed the CLI calls, you can script them to generate report packages based on any schedule or alert you choose. For more information about working with the command-line interface, see “Tools” in the SAS Viya Administration documentation.

Summary

As you can see, the SAS Viya SDK for JavaScript offers many alternatives for embedding SAS Visual Analytics content into your custom web pages or applications. Recall that the method you choose (direct connection or SAS report packages) will depend on your organizational policies, the features and functionality you want to include in your web page, and the types of configurations you want to (or are able to) make in your environment.

References

Documentation: SAS Visual Analytics SDK

Documentation and Examples: va-report-components

Documentation: SAS Visual Analytics: Designing Reports

Documentation: SAS Visual Analytics: Reference

Documentation: SAS Viya Administration