Offline report does not mean static report!
Starting with version 2021.1.5, SAS Visual Analytics provides an export functionality for "offline" usage of the report. In this article, I will explain:
- What is a SAS Report Package
- How to export a SAS Report Package
- How to use the generated package in your application
- Design considerations for the reports
What is a SAS Report Package?
In cloud environments like Microsoft Azure, Google Cloud Platform and Amazon Web Services, it is important to consider the consumption related costs. Being cost effective can be a challenge and this is where SAS Report Packages can help. A SAS Report Package provides the interactivity provided by SAS Reports but in cost effective way. Of course, not all the reports and all the use cases are good candidates for "offline" usage. If you are using SAS Visual Analytics to explore data or to perform statistical analysis then SAS Report Packages may not be the best solution for your users. If your report is used as a dashboard to present KPIs with summarized data, you can most likely benefit from the SAS Report Packages.
A SAS Report Package is a zip file which contains information about the report, report pages and report objects. It also contains a data subset, metadata about the report, and some web related files. The structure of the SAS Report Package is similar to 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.
The benefit of the report package is that you can extract the content to a web server and directly render the report. There is no need to change the content of the files nor to specify connection information or other settings. The steps to display a report are:
- Export SAS Report Package from SAS Visual Analytics
- Extract content of the package to a web server
- Display the report
You might wonder if you need a specific web server or some specific configurations. There is usually no need to customize the web server. You can use Apache, NGINX, NodeJS or any web server of your choice. The only requirement is to have access to the SAS VA SDK component which is hosted on https://unpkg.com/. There is no need to configure your SAS Viya environment like you would do for SAS VA SDK components. When you export the package, the report becomes standalone.
How to export a SAS Report Package?
SAS Report Packages can be exported directly from the SAS Visual Analytics user interface or from the command-line using sas-viya CLI. When exporting the package, from either SAS Visual Analytics UI or the command-line interface, you have to select just one report. Then from that selected report, you can select the entire report, individual pages, or individual objects.
You get then the choice to export specific objects or pages in the report.
Clicking on the Export button downloads the file to your machine. You can also select the option to save it in the SAS Content repository for persistence on the SAS Viya environment.
Using the interactive option is nice when you perform the steps as a one-time exercise. If you want to automate the process, the sas-viya CLI comes in. The following command creates a package for the report based on its ID and stores it in a specific location:
sas-viya reports build-package --id report_ID --output-file report --output-location /home/myname
From there, it is easy to save the package in a GIT repository and to automate the deployment of the SAS Report Package using Jenkins for example.
When exporting the report package, it is recommended to only select the relevant objects to keep the package size to a minimum but also to decrease the time needed to create it. It is a good practice to link into the packageStatusReport.txt included in the zip file to detect warnings and limitations for specific objects. The file is only generated when attention is needed.
How to use the generated package in your application?
As I indicated earlier, deploying the report is as easy as extracting the content of the SAS Report Package into a folder accessible by a web server. For example, you can extract it in the /var/www/html folder for an Apache HTTP server. This is extremely handy as you can render the report in a matter of minutes. There is one little trick that you might perform if you really want the report to look the same when deployed in your HTTP server and in SAS Visual Analytics. You should make sure that the fonts used by the report are available on the HTTP server. This can be achieved by downloading the fonts and making them available on the HTTP server. You can then define the fonts in the index.html contained in the package adding these instructions in the style tag:
<style>
@font-face {
font-family: 'MyFont';
src: url('/fonts/MyFont.woff2') format('woff2'),
url('/fonts/MyFont.woff') format('woff');
}
</style>
If you know a bit of CSS or JavaScript, you can also modify how the objects appear on your web page. This is where you can truly benefit from the power of the SAS Report Package and the VA SDK. For example, I will be using the Warranty Analysis sample report that is available on most SAS environments under /Products/SAS Visual Analytics/Samples.
The report contains many objects on multiple pages but as I want to build a simple portal, I want only to display the four Key Value objects and still be able to see the data for every year.
I have exported the five objects as depicted here:
After extracting the contents of the package in the HTTP server, the index.html renders all the objects on top of each other and each object takes more place than required.
If you open the index.html and comment out all the css instructions except the one for the body, the report should look prettier.
But it is not yet what I want to achieve. For example, I would like to have all the Key Value objects on one line rather than stacked vertically. To achieve this, I will use the Bootstrap library. To use Bootstrap grid layout, I just need to add the following line in the head section.
And the resulting page looks like this:
As you can see in the demo below, the selecting a year automatically adapts the Key Value objects.
If you want to integrate the report objects in another html page outside of the folder where the package has been extracted, you should make sure the packageUri reflects that structure. For example, if you have extracted the package into a folder named test and you created an HTML page in the parent folder that makes use of the report objects, your sas-report-object tag will look like this:
Design considerations for the reports
As you probably noticed while exporting the report objects, I've chosen specific object types. There is a good reason for that. Even though you can select a vast majority of the SAS Visual Analytics objects, you should be aware that not all the objects behave the same way. The report objects are classified in the documentation with different levels:
| Full support | Objects with no known limitations. |
| Basic | Objects that use only basic queries. Most interactivity is supported, but data limits apply. |
| Advanced | Objects that require advanced queries. Some limitations apply. |
| No interactivity | Objects that are rendered in the initial view, but that do not support interactions. |
| No support | Objects that cannot be rendered in an offline report. |
The level for each object can be found in the documentation.
One important point to keep in mind is the amount of data needed for the object to work properly. As the objects are not able to query the data directly into the CAS server, the data are limited to what is stored in the report package. It is really important to validate that all the actions in the "offline" report are returning data. This is required for the best user experience.
Here are a few warnings from the report package’s status report and how to fix them:
| Message | Property | Default Value |
|---|---|---|
| data limit exceeded | interactiveDataLimitMultiplier | 2 |
| query limit exceeded | offlineDataQueryLimit | 20,000 |
| size limit exceeded | offlineDataSizeLimitBytes | 10,000,000 |
You should adapt the values with care as a change will impact the performance of the environment.
Conclusion
SAS Report Packages are powerful when it comes to scalability and potential cloud usage cost reduction. One can easily export packages from the SAS Visual Analytics user interface for testing purpose and then use the sas-viya CLI to automate the process. Automating the process is a crucial part of the deployment as the data are stored in the SAS Report Package. It is important to plan refresh (extraction) of the report package based on the data refresh rate. If you are displaying summarized data for the last five years, data might just be refreshed once a year. If you are displaying the number of calls received in a call center on a daily basis, the report package should most probably be recreated and deployed every day.
With basic web development knowledge, you can adapt the layout of the index.html that is generated and included in the package.
Thanks to the SAS Report Package and the SAS VA SDK, you can easily integrate SAS report objects elements in custom web pages and bring the data and insights where the users need them.
Find more articles from SAS Global Enablement and Learning here.
