How-to display results from a SAS Viya Job in the same page?
When executing SAS Viya Jobs with a prompt, the input form disappears as soon as you click the submit. This behavior may sometimes not be what you want for your end-users. In this post, I will describe how you can build HTML prompts for a job and display the result of the job execution on the same page. As a side gift, you will also see that building cascading prompts in HTML is an easy task.
SAS Viya Jobs
Before we deep dive into the actual code, I would like to explain what SAS Viya Jobs are. If you are familiar with SAS Stored Processes in SAS 9, the SAS Viya Jobs are the next generation of stored procedures for SAS Viya. It provides the same kind of functionalities as SAS 9 Stored Processes, but designed for the SAS Viya platform and cloud consumption. Behind the scenes, SAS Viya Jobs are using SAS Compute Servers and Compute Contexts started on-demand or made reusable to improve performance. For more information about implementing reusable SAS Compute Servers, please refer to this article.
When building SAS Viya Jobs, you can design it to prompt the consumers to provide input to the SAS code. You have different options to code your prompts:
- XML
- JSON (new in SAS Viya LTS 2023.10)
- HTML
XML and JSON can be used to define metadata for your prompt. SAS will then generate the prompts which are rendered to the end-user. The look an feel of the prompts will be similar to SAS Studio's Tasks and Steps. This is most probably the best option if you are fine with the predefined layout and visuals provided by SAS.
On the other side, HTML is the best choice if you want to customize the user experience and use specific UI elements and colors. This is the option we will use in this article as it will provide the needed functionalities to build a custom web form and to display the result on the same page.
Interactive web forms
When building HTML forms, you often want to select data which are then used to filter another prompt. This functionality, often called cascading prompts, can be created easily in SAS Viya Jobs using JavaScript. Your first thought might be: “I don’t know JavaScript how should I proceed?” Don’t worry, SAS provides a JavaScript bundle to help you in the development of the HTML form. You only need to add the following script tags in the head section of your HTML page:
<script src="/SASJobExecution/resources/sap/ui/thirdparty/jquery.js"></script>
<script src="/SASJobExecution/resources/dynamic.min.js"></script>
These two scripts will be in charge for loading the needed JavaScript functions to build interactivity. As you can see, they are using relative paths which means that they are hosted in your SAS Viya environment and you don't need to load the content yourself.
After adding these two scripts, you should initialize the function when the HTML page loads. This can be done with the following code:
<body onload="SASDynamic.init()">
The setup is now complete and you will be able to define prompts and dependencies. For example, you can retrieve the list of car brands from the SASHELP.CARS table using the following drop-down box:
<label for="cars">Choose a brand:</label>
<select name="make" id="make" data-colname="make" data-library="SASHELP" data-table="CARS">
</select>
- data-library specifies the name of the input library. Note that the library should be predefined, such as a global CAS library, for the Compute Context of the Computer Server.
- data-table references the name of the input table.
- data-colname provides the name of the source column.
When rendered in a browser with some styling attributes (or JavaScript), the following dropdown will be displayed:
Select any image to see a larger version.
Mobile users: To view the images, select the "Full" version at the bottom of the page.
If you want to define other drop-down boxes which are dependent on the car brand and type, this can be done using HTML code similar to this:
<label for="model">Choose a model:</label>
<select name="model" id="model" data-colname="model" data-library="SASHELP" data-table="CARS" data-uses="make, type"></select>
If you compare this code with the previous, you will notice that we defined another property on the select element: data-uses. It can be used to defined which fields in the form should be used to filter the list of models.
If you want more information about defining dynamic HTML prompts, please refer to the documentation.
Creating the job
Now that you have a better understanding about interactive HTML forms for the SAS Viya Jobs, it is time to build the job.
In SAS Studio, click on New and select Definition under Job. In the Program pane, type the following code:
proc print data=sashelp.cars;
where model = "&model";
run;
As you can see, the job will print the observations from SASHELP.CARS which have the value of model macro variable as model. The code is simple but it serves the purpose of the article. It shows how you can pass parameters from the form to the SAS code. The macro variable name should match the name of the input field in your HTML form.
In our case, the form is defined like this:
Displaying the form results into this:
At the top of the HTML code for the form, you see that we have three hidden input fields. The _program provides the name of the program to be executed which is retrieved from the URL of the job. The two _action fields are defining that the job should execute and display a wait message while executing the code.
After the closing form tag, we should add the following code:
<iframe id="results"></iframe>
This iframe tag will host the results from the job execution. In our case, it will display the results of the execution of the proc print defined for the job.
In order to display nicely on the screen, I've defined a style tag in the HTML and a title for the web page. The complete code looks like this:
In SAS Studio, you can add the code clicking the right pane to Associate a Form.
In the HTML Form pane, you can type the code about or retrieve it from this location.
Turning into a single page application
If you save the job at this point and retrieve the URL to execute it, you will notice that the job will execute but the form will disappear to display the results.
This is not what you would expect as I mentioned above that the result will be displayed in the iframe.
To display the result in the iframe, you need to add some JavaScript in the page. At the bottom of the HTML page just before the closing body tag, add the following code:
This code is executed when the submit button of the form is pressed. We are using jQuery to attach an event listener to the form element.
In the code, we retrieve the form fields and transform them into url parameters which are then passed to the url for the SAS Job Execution.
Finally, the last line defines the src property for the HTML element which has an idea of results. In our case, the element is the iframe.
There is one line of the code which I've not covered so far. The event.preventDefault() code prevents the normal processing of the HTML form. Usually, when you press the submit button of an HTML form, the input fields are cleared out and the form executes the action defined into it. In our case, this would lead to calling the job with the parameters and clear the form, but it will force the complete page to be refreshed with the results. Adding the event.preventDefault(), we explicitly tell the browser not to execute the form as it should but take the subsequent actions instead, which ultimately in our case means: set the src attribute for the iFrame. As a result, the job will execute and display the result in the iFrame as you can see in this demo.
Conclusion
Building interactive HTML forms for a SAS Viya Job is a simple task. With basic HTML coding experience and the SAS provided scripts, you can create dependent prompts which are using SAS data. If you want to improve the layout of the HTML page, you can write your own CSS styles or rely on other libraries like BootStrap. The benefit of preventing the default behavior of the submit button is to build a single page application which gives the opportunity to the end user to execute code using different input values and staying in the same page.
If you are interested in knowing more about the SAS Viya Jobs, please refer to the following articles:
Find more articles from SAS Global Enablement and Learning here.
