Sending Bigger Tables: Integrating SAS Visual Analytics with SAS Jobs via Data-Driven Content-Part 2
In this article you are going to expand on the solution provided in the previous article. Just to refresh your mind, you have used HTTP GET request to execute a SAS job that produced an HTML ODS output table containing the same data passed as input. The data was passed as a stringified JSON directly in the SASJobExecution web application URL. Even though you were able to display the HTML output in a SAS Visual Analytics report, the content needed some work, such as removing columns that didn’t exist in the input data, replace generic column names with their correct names, apply column labels, format values, etc. This is what this article is about. Besides fixing all those things, you will also see how to make the HTTP call using a POST request, which is recommended for handling bigger tables.
HelloBigWorld Example
In contrast with the example called HelloSmallWorld from the previous article, this HelloBigWorld example can handle larger tables as input because it uses HTTP POST request to upload the table onto the server.
SAS Job Code
The SAS job code is very similar to the one used before:
The basic difference compared to the initial example is that you no longer need to save the stringified JSON content passed as parameter in the SAS job URL into a file. As said before, the data has already been uploaded to the server, and it already exists as a temporary file that can be accessed through the pre-defined macro variable called _WEBIN_FILEURI. Because of that, the job code is slightly simpler.
Data-Driven Content Code
This code is also very similar to the one used in the HelloSmallWorld example. The only difference resides on the JavaScript function that calls the job:
GET request (previous example):
POST request (this example):
The callJob() function code used in this example uses the FormData object to set the job input parameters, which is passed to the job in the HTTP POST request call. Unlike the HelloSmallWorld example that uses a GET request, the parameters aren’t appended to the URL, but instead, they are sent in the HTML payload as the data element. All parameters are the same as the previous example, except for the table data that is not only stringified, but also transformed into a Blob. A blob in the payload is what triggers the file to be uploaded to the server. The ajax() call has a few additional parameters such as contentType, ProcessData, and headers. The header contains the X-CRF-TOKEN set to pre-defined variable $CSRF$, which must be specified exactly as shown and it’s important to ensure that the request is considered non-malicious, as explained in the previous article.
HelloBigWorldFormatted Example
The modification performed in the previous HelloBigWorld example didn’t really change the output generated by the job and displayed in the report. In this example you will treat the data received from SAS Visual Analytics before it is sent to the job and then leverage that information in the job itself to produce cleaner and formatted results.
Data-Driven Content Code
The difference compared with the HelloBigWorld example is minimal:
First, you will need to add a reference to the jobUtil.js module, available in GitHub. This module provides the function PrepareVADataForSASJobs(), which is responsible for making some transformations in the data received from SAS Visual Analytics and providing additional and useful information to the job, so it can better treat missing values and formats.
SAS Job Code
While the changes in the DDC code were minimal, the SAS job code needs additional steps to leverage the new information received in the JSON file. The new steps are highlighted in those three blocks of code.
The first block is responsible for retrieving enhanced column metadata that was added by the DDC via function PrepareVADataForSASJobs(). That information is stored in a dataset and will be used to create a JSON map file. This step also replaces blank spaces in column names with underscores.
The second block of code uses the dataset created in the first block and creates a JSON map file in a temporary location referenced by jmap.
The third block re-issues the JSON libname with the JSON map attribute. This allows for the JSON file to be read more intelligently and formatted.
JSON map files are explained in the JSON libname engine documentation.
The end result produced by the job before and after this new example is seen below.
Before:
After:
Deploying These Examples
All files used in this example are available for downloading from the GitHub project sas-visualanalytics-thirdpartyvisualizations, under folder called samples/IntegrationWithSASJobs.
It requires the CARS table to be loaded into memory in the Public caslib. The table is originally available in the SASHELP library.
Deployment steps:
- Download the GitHub project
- Unzip it into your Web Server document folder. These instructions assume you have unzipped the GitHub project in a folder called github in the Web Server document root folder. You will only need the content of folders github/utils and github/samples/IntegrationWithSASJobs.
- Logged into SAS Job Execution Web application, do the following:
a. Create two new jobs in a folder of your preference (e.g. /Public/Jobs/SAS Communities) and name them HelloBigWorld and HelloBigWorldFormatted (see first article for more details if needed)
b. Open the jobs for edition, copy & paste the content of files github/samples/IntegrationWithSASJobs/2.HelloBigWorld/HelloBigWorld.sas and github/samples/IntegrationWithSASJobs/2.HelloBigWorld/HelloBigWorldFormatted.sas to their respective jobs
c. Save the jobs
d. Add job parameter _action=FORM as discussed in the beginning of the first article to each of the jobs
e. For each job, create a new job form either as a separate content or attached to the job (SAS Visual Analytics 8.5 or above only), as explained in the beginning of the first article. If they are separate content, give them the same name as their jobs
f. Open the first job form for edition, copy & paste the content of file github/samples/IntegrationWithSASJobs/2.HelloBigWorld/HelloBigWorld.html (1). Repeat the process for the second job using the file github/samples/IntegrationWithSASJobs/2.HelloBigWorld/HelloBigWorldFormatted.html (1)
g. For each one of the forms, make changes to the host name (search for your.host.name and replace it accordingly) and the path of src on line 20 of HelloBigWorld, and lines 20 and 21 of HelloBigWorldFormatted (1):
h. Make changes to the job path on line 71 of HelloBigWorld and 73 of HelloBigWorldFormatted if necessary (tip: right click on the code and turn on “Show line numbers”), so they match with your environment (same as #3a) (1):
i. Save the job forms
- Logged into SAS Visual Analytics, do the following:
- Create a new empty report
- With the report opened, hit Ctrl+Alt+B to bring the SAS Visual Analytics Diagnostics window.
- With the BIRD tab selected across the top (that’s the default), replace the BIRD XML content with the content of the file github/samples/IntegrationWithSASJobs/2.HelloBigWorld/VA-DDC-Job Hello Big Worlds.xml
- Hit Load (this will close the diagnostics window)
- For each page on the report, select the DDC object at the bottom of the page, go to the Options pane on the right and fix the URL entries: replace your.host.name accordingly and make sure the path to the job is correct (same value entered in #3a)
- Save the report
Note: (1) Starting with release 2023.06, the examples that used to inherit jQuery from their parent (the SAS Visual Analytics web application) no longer work, so we have provided replacement codes. These replacement files have the same names as their original, but they end with .v4. Because of that, some references to line numbers may not exactly match on those .v4 files.
We could have exported all the content as a package, but this would require special privileges in order to import it. Sharing the examples as standalone files will give you the opportunity to better explore the SAS Job Execution Web application, familiarize yourself with the content, and understand how they are connected.
Next Steps
In the next article you will be introduced to a new way of leveraging SAS jobs from SAS Visual Analytics. You still be using the Data-Driven Content as the bridge to execute SAS jobs, but jobs will no longer be generating the visual output, like the ODS HTML table you saw in the previous examples. After processing the data, those jobs will be loading the output table in memory, so that SAS Visual Analytics or another application can consume the information and display it anyway wanted.
References
- SAS Job Execution Web Application 2.2: User’s Guide documentation
- JSON Libname Engine documentation
- Reading data with the SAS JSON libname engine documentation
- Data-Driven Content: leveraging third-party visualizations in SAS Visual Analytics (part 1 of 2) by SAS’s Renato Luppi
- Data-Driven Content: leveraging third-party visualizations in SAS Visual Analytics (part 2 of 2) by SAS’s Renato Luppi
- Using parameters with Data-Driven Content in SAS Visual Analytics by SAS’s Renato Luppi
- sas-visualanalytics-thirdpartyvisualizations GitHub project and examples
Learn More…
- Programming Considerations for Data-Driven Visualizations documentation
- Customize data visualizations in SAS Visual Analytics with #D3Thursday by SAS’ Ryan West
- Leverage a Google 3D-PieChart within VA using the Data-Driven Content Object by SAS’ Meera Venkataramani
- Custom Visualizations in SAS Visual Analytics - A Strategy for Using the Data-Driven Content Object by SAS’ Robby Powell
- Use Custom Visualizations to Extend SAS® Visual Analytics by SAS’ Robby Powell
- Reading data with the SAS JSON libname engine by SAS’s Chris Hemedinger
