SAS Viya SDK for JavaScript- A Tale of Two Methods (Part 2 - Direct Connection)

[#1]

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

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

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 connecting directly to SAS Viya.

Requirements

When you use the direct connection to SAS Viya, you are connecting directly to a SAS Viya deployment to deliver and display up-to-date reports and data on your custom web page or application. This means that your web page is always displaying the most up-to-date version of the content and has full interactivity. For this method, you can also use provided APIs to interact with HTML content on the web page or to create a data-driven web page.

This method, however, does require some SAS Viya configuration. Specifically, you need to enable cross-origin resource sharing (CORS), specify allowed Uris for cross-site request forgery (CSRF), and enable cross-site cookies. In addition, to view content on the web page, SAS Viya must be running, and users will either need credentials to sign in or guest access needs to be configured in your environment.

Benefits	Considerations
Up-to-date content	Requires SAS Viya configuration: CORS, CSRF, cross-site cookies
Full interactivity	SAS Viya must be running
Use APIs for broader interactivity	Users need credentials or guest access needs to be configured

Note: The authentication library and the content components library require the same Viya configuration.

 

Steps

To connect directly to SAS Viya, you (1) create a custom HTML tag using the Copy link functionality in SAS Visual Analytics and (2) insert the content into your custom web pages using standard web technologies (like HTML, CSS, and JavaScript).

Step 1: Create

In the Create step, you construct and copy a link to a report, to a page in the report, to a container, or to an individual object. This link is an embeddable web component that you can use in your web pages and applications.

To copy a link to a report, use the More button (the snowman) in the upper right corner of the report and select Copy link.

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

Links to 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.

To copy a link to a page, use the Page menu button (the snowman) on the page tab and select Copy link.

Links to report pages display all content on the page and are interactive.

To copy a link to a container, use the Object menu button (the snowman) for the container and select Copy link. The easiest way to do this is to select the container in the Objects pane (on the right).

As an alternative, on the Outline pane (on the left), you can right-click the container object and select Copy link.

Links to containers display all content in the container and are interactive.

To copy a link to an object, use the Object menu button (the snowman) for the object and select Copy link.

Links to objects are interactive and can be placed anywhere on the web page.

Pro Tip! 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 the use of 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).

The Copy Link window can be used to create different types of links for different scenarios. To create a link for your custom web page, select Interactive report and Embeddable web component. The Interactive report option enables users to interact with report content and the Embeddable web component option will create a custom HTML tag that can be used in your web page. Then, select Copy link to copy the custom HTML tag.

Note: The Copy Link window for pages, containers, and objects only has the Interactive report option. The Embeddable link option is selected by default and is not shown.

Step 2: Insert

In the Insert step, you use the link in your web page or application. Your web page needs to access the report components library from the SAS Viya SDK for JavaScript, reference the link copied from SAS Visual Analytics, 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 the 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 needed to perform these actions).

Reference

Next, your custom web page needs to reference the link copied from SAS Visual Analytics. 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).

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 the direct connection to SAS Viya and each custom element.

<sas-report url=ʹhttps://server.demo.sas.comʹ reportUri=ʹ/reports/reports/report-IDʹ authenticationType=ʹcredentialsʹ></sas-report>

General Attributes

For the direct connection to SAS Viya, the url attribute specifies the URL of the SAS Viya server that hosts the report. The URL is a full context root, including the protocol, an optional port, and the host. The reportUri attribute specifies the URI (uniform resource identifier) for the report, which is unique for every report. The authenticationType attribute specifies how requests to the SAS Viya server are authenticated.

The authenticationType attribute takes two values: credentials (which is the default) and guest. For credentials, users must use SAS Logon to establish an authenticated session with SAS Viya. This is the same screen users see when vising SAS Visual Analytics directly on the SAS Viya server. This is useful because it enables the SAS Viya SDK for JavaScript to take advantage of SAS Logon configurations, like single sign-on. If the user is already authenticated when they access the web page, the server connection is already established. If the user is not authenticated, a button will appear on the web page to initiate logon. Clicking this button will launch the SAS Logon page in a new window, which closes when the logon has succeeded.

For guest, users are automatically signed into the SAS Viya server as the guest user. For this option, guest access needs to be configured in your deployment.

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 section. 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 url=ʹhttps://server.demo.sas.comʹ reportUri=ʹ/reports/reports/report-IDʹ authenticationType=ʹcredentialsʹ pageName=ʹpage-nameʹ></sas-report-page>

<sas-report-page url=ʹhttps://server.demo.sas.comʹ reportUri=ʹ/reports/reports/report-IDʹ authenticationType=ʹcredentialsʹ 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 url=ʹhttps://server.demo.sas.comʹ reportUri=ʹ/reports/reports/report-IDʹ authenticationType=ʹcredentialsʹ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 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 url=ʹhttps://server.demo.sas.comʹ reportUri=ʹ/reports/reports/report-IDʹ authenticationType=ʹcredentialsʹ 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.

Guest Access

If you would like your users to bypass the sign-in screen when viewing the embedded content in the web page, you can select the Guest access option when copying the link. This will change the authenticationType attribute to guest and users will be automatically signed in to the SAS server as the guest user. This option is not available if guest access is not configured for your deployment.

For more information about how to configure guest access in your deployment, see “How To: Guest Access” in the SAS Viya Administration: Security documentation.

Summary

Using the direct connection is a great way to display up-to-date SAS Visual Analytics content with full interactivity in your custom web pages and applications. Using this method, however, requires viewers of the web page to either have credentials in SAS Viya or guest access to be configured for your deployment. If neither of these conditions apply, you will need to use SAS report packages.

In the next part of this series, we discuss the requirements, the steps, and the details of using the report components library with SAS report packages.

References

Documentation: SAS Visual Analytics SDK

Documentation and Examples: va-report-components

Documentation: SAS Viya Administration: Security