SAS Viya API Wrappers for JS – Building dynamic prompts for SAS Viya Jobs
As we saw in the previous article in this series, the goal of the SAS Viya API Wrappers for JS is to facilitate the development of custom web applications that can, for example, use the SAS Compute Server to populate prompts. One of the use cases is to create dynamic prompts for SAS Viya jobs. In this article, I will walk you through the steps of building dynamic prompts. This first example will help you mirror the capabilities that SAS provides out-of-the-box (more information) in a custom web application.
Using SAS Viya Wrappers for JS
The SAS Viya Wrappers for JS are designed to be used as a CDN package as well as inside a NodeJS based application via npm installation. Using a CDN, you can write the application in your favorite text editor or inside SAS Studio when creating a SAS Viya job. Using the npm installation method, you need to configure NodeJS and install the required dependencies using npm. In this article, we will cover using the CDN. A later article will explain how to use the SAS Viya API Wrappers for JS within a NodeJS based application. To use the library inside your web page, you need to import it into an HTML script tag like this one:
<script type="importmap" crossorigin="anonymous">
{
"imports": {
"sas-wrappers": "https://cdn.jsdelivr.net/npm/sas-viya-api-wrappers-js/dist/sas-viya-api-wrappers-js.js"
},
"integrity": {
"https://cdn.jsdelivr.net/npm/sas-viya-api-wrappers-js/dist/sas-viya-api-wrappers-js.js": "sha256-o5E56OSVRTSJlYXb+/M2vL+Dj2Q8o59+WsrVOBKolwU="
}
}
</script>
Please note that you should update the hash key in the integrity each time the sas-viya-api-wrappers-js.js is updated. If the hash is not correct, you will see an error in the Developer Tools of your browser. For more information about the importmap type for script, please refer to this documentation. This declaration makes the library available in the web page, and it can be referenced as sas-wrappers in other HTML script tags on the same page using an import statement like this:
<script type="module">
import { ComputeSession } from 'sas-wrappers'
const computeSession = await ComputeSession.init({baseURL : 'https://server.demo.sas.com', contextName : 'SAS Job Execution compute context'})
// Remaining code
</script>
You now have a SAS Compute Server session. This session object can then be used to call the various methods provided by the library to get a list of libraries, tables, columns, and values.
The use case
In this example, the web page will display dynamic prompts in the form of HTML select tags and execute a SAS Viya job using the selected values. To improve the look and feel of the application, we will use the Bootstrap library. The resulting prompt will look like 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 HTML code
WARNING: images are based on version 1.2.4 of the library. Starting with version 1.2.5, the method signatures have changed to pass an object instead of a list of parameters.
Let's start with the HTML head section where we import the different libraries.
As you can see, we import the CSS stylesheet from Bootstrap and the sas-viya-api-wrappers-js.js from jsDelivr CDN hosting. The body element is then defined with the following class "container-fluid". Next, the top of the form element contains some layout elements and, most importantly, the two hidden elements used to invoke the SAS Viya job:
All select boxes are defined like this:
And finally, you have the Submit button. While the HTML tags define the layout of the application, the JavaScript code is responsible for handling the user interactions. At the bottom of the body element, we create a script tag with the following code:
<script type="module">
import { ComputeSession } from 'sas-wrappers'
const computeSession = await ComputeSession.init({baseURL: 'https://server.demo.sas.com', contextName: 'SAS Job Execution compute context'})
// Remaining code
</script>
In the rest of the code, we define a function to generate the HTML option elements within the HTML select elements:
This function takes two parameters:
- Target is the id of the HTML select element to populate.
- Options is the data set used to generate the HTML option elements.
From line 107 through line 111, a dummy option is created and selected by default. This forces the end user to select a value in order to move forward in the selection process. From line 112 through line 117, the HTML option elements are created and appended to the select element. Finally, the select element is enabled to allow user selection. To simplify interaction with the various HTML select elements, each is bound to a specific JavaScript variable. For example:
const librarySelect = document.getElementById('librarySelect')
Let us move on to the next part, which will fill the librarySelect element:
The first step is to call the getLibraries method from the computeSession object. This method sends a request to the SAS Compute Server session to retrieve a list of libraries defined in the server context. This method is asynchronous. This is the reason for the use of the await keyword. Once the library data is retrieved, we execute the populateDropdown function using the data and populating the options in the librarySelect element. So far, we have created the various HTML select elements, and only the librarySelect element has been populated with data. We need to define what happens when the end user changes the selected value. The following code does this.
As you can see, the first task of the function is to clear the list of options for the different elements: tableSelect, columnSelect and valueSelect. The elements are also disabled to prevent selection. Then, the getTables method is called and the currently selected value for the librarySelect element is passed to the method as a parameter. Once the method returns data, the rest of the function is executed and the populateDropdown function is executed to populate the tableSelect element with the retrieved data. If you go through the rest of the code in the script tag, you will see that onchange functions have been assigned to each element to handle the selection. Finally, we close the script tag and add another script tag to import the necessary Bootstrap JavaScript files.
The deployment
This web page can easily be copied into the HTML form of a SAS Viya job. The purpose of this article is not really to demonstrate the capabilities of SAS Viya jobs. For this reason, the code for the job is as simple as a proc print that accepts the various variables passed from the form when submitted.
proc print data=&librarySelect..&tableSelect ;
where &columnSelect = "&valueSelect" ;
run;
The macro variables are automatically generated based on the name property of the select elements. For example, the columnSelect macro variable refers to the value of the select element having columnSelect as name (line 82).
Note: This code is oversimplified and assumes that the valueSelect macro variable doesn't contain double quotes in its value. If there are risks that the value contains double quotes or other special characters, you should use the proper macro quoting functions.
The demo
About portability
The SAS Viya API Wrappers for JS has been designed to ease the build process of web pages for job prompts. One of the benefits of the library is that you can host the web page with the SAS Viya Job, but also on a standalone web server if you want to integrate it with other HTML elements on your page. Using the same HTML page as above, you can quickly adapt the form element to use fully qualified path for the SAS Job Execution web application and the path to the program to be executed. You need therefore to adapt the two elements on the HTML page:
- The form element
- The input element named:_program
The form element action property should contain the hostname like this:
<form
id="form"
action="https://server.demo.sas.com/SASJobExecution/"
class="form justify-content-center w-50 mt-3 mx-auto"
target="_self">
The input element should be adapted like this:
<input
type="hidden"
name="_program"
value="/Public/Demo/Jobs/SASViyaAPIWrappers_CDN" />
Where the value is set to the SAS Content location where the job is saved.
After changing these parameters, the HTML page will work fine when saved along with the SAS Viya Job in SAS Viya, but it will also work when hosting the HTML page on an external web server. You can even adapt the web page a bit more to display the result of the job execution on the same page as described in this article: How-to display results from a SAS Viya Job in the same page?
Conclusion
In this first example, we have seen how we can use the library to ease the development of dynamic prompts. The biggest difference with the solution that SAS provides out-of-the-box, is that we are using HTML tags and the content of the form is generated on the fly based on the data extracted from the SAS libraries available in the SAS Compute Server session. This approach while requiring more code than when using the SAS provided library also gives more flexibility to adapt the display of the form elements and their behavior. This is what you will see in the next article in the series.
The code for this article can be found here.
If you have ideas about how to improve the library code, please don't hesitate to contact me.
Articles in this series are:
SAS Viya API Wrappers for JS – Building dynamic prompts for SAS Viya Jobs (this article)
SAS Viya API Wrappers for JS – Building advanced dynamic prompts for SAS Viya Jobs
SAS Viya API Wrappers for JS – Building a Data Filtering and Display Application with React
Find more articles from SAS Global Enablement and Learning here.
