Create a SAS Viya Job with a prompt using HTML Prompts

[#1]

In this article, I described how-to create prompts for the SAS Viya Jobs using Task Prompts and the Common Task Model (CTM). Another SAS Viya job prompt option is to use HTML code. The functionality described in this article uses a JavaScript file provided by SAS and has been available since SAS Viya 2021.1.2.

This article will describe how a developer can create dynamic HTML prompts for the SAS Viya Jobs. While the Common Task Model uses XML to define the prompt structure, HTML and JavaScript are used for the dynamic HTML prompts. SAS provides the JavaScript files needed to expand the HTML tags with data-* attributes.

This article describes how to implement the HTML prompts for SAS Viya Jobs. You will see that using a few lines HTML code, you can create an interface similar to the one described in the first article.

In the previous article, the generated prompts look like:

 

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 version of this prompt will look like this:

As you can see the look and feel are pretty similar. The biggest difference between the two versions is the language used to develop the user interface. The first one is developed in XML and the second uses HTML and JavaScript. For the SAS code which is executed behind the scenes there is no differences. This is the reason why I will not focus on the SAS code which can be found here. If you want more information about the SAS code, please refer to the previous article.

Create the Job

To develop the SAS Viya Job, you can use SAS Studio or the SAS Job Execution Web Application. In this article, I will use SAS Studio as this is the preferred user interface to write SAS code in SAS Viya.

In SAS Studio, click on New and select Definition under the Job section.

In the Code pane, paste the SAS code from this link. The code should look like this:

As you can read in the code, the generate macro uses

• var_origin
• var_type
• var_type_count
• var_driveTrain
• var_invoice

to generate statements that are used in the where clause to filter the data stored in SASHELP.CARS used in the print procedure. There is nothing more about the SAS code.

 

Create the prompt

With the SAS code defined, it is time to define the HTML prompt. To do so, in SAS Studio, the first step is to define the prompt type:

When defining HTML prompts, you have two options HTML form or Existing form. While Existing form can be reused by multiple jobs, the HTML form is bound to the job definition and can't be reused with other jobs. For this article, I chose not to create a reusable prompt as the code will be tied to the variables in the dataset and will only be used for SASHELP.CARS data.

Write the HTML header

At this stage, the prompt is empty and the HTML page will not render anything. The first step will be to define the standard HTML file headers.

You can define other information in the head section but these tags are the minimum set of information which should be passed the HTML page.

The next piece of code will be some script tags:

These two tags load the needed JavaScript code provided by SAS which will extend the HTML form properties with data-* attributes. The attributes will be detected when displaying the HTML page and will be interpreted to add extra functionalities. The scripts have been available since SAS Viya 2021.1.2. Before that release, it was possible to create SAS Viya Jobs with HTML forms but the developer had to create the prompting logic. The scripts are there to ease the development of the prompts using dynamic data.

For example, you can

• Retrieve libraries and tables lists using the data-library and data-table attributes
• Conditionally display form elements using data-visibility attribute
• Build dependent form elements using data-uses attribute

Before defining the HTML form, I will add some minimalistic CSS instructions to style the different form components.

Write the HTML body

Inside the body section of the HTML page, there is a form element which contains the information about the different fields and how they should appear in the page.

Let me describe the different sections highlighted on the picture.

1. The attribute of the body tag may be the most important. It tells the browser to initialize the SASDynamic function when the body loads. Without that event, the data-* attributes will be useless. That function call is what makes the form dynamic.
2. This section tells the browser what should occur when the submit button is pressed. The action will be to call SASJobExecution endpoint. When submitting the form besides sending the information that the end-user will see, the form will also send the name of program which is generated for you and the action to be executed.
3. This section is in charge of displaying the geographic filter. As you can see, the attributes id and name are defined as the macro variable name in the SAS Code. The data-* attributes are defining the library and table which are used as source and the colname defines the source column for the data to be displayed in the selection dropdown menu.
4. Here the section will be for the driveTrain and type variables from SASHELP.CARS table. As you may notice it, the data-* attributes are set the same way as in the previous section but the data-uses attribute indicates that var_origin form field should be used to filter the data in var_type form field. The same happens for var_driveTrain form field but this time there is an extra dependency on var_type field.
5. The attention point is not really on the range input but more on the div at the beginning with the data-visible attribute. The instruction tells the SASDynamic function that the field should only be displayed when the var_origin form field is equal to Asia.
6. The last script tag is adding an extra functionality to display the value of the range input field in a box.

 

Demo

After saving the job definition, here is how the interface can be used.

 

Conclusion

Using SAS Viya Jobs, end-users can execute predefined SAS Code from SAS Studio or directly from the web. The jobs can also be integrated in SAS Visual Analytics reports. Adding prompts makes the code more interactive by providing a way to pass values as parameters to the job. The developer has two options to define these prompts: HTML or XML. Depending on preferences and need for customizations, one or the other might be better. While the Task prompt offers the consistent user experience , the HTML version gives the opportunity to customize the prompts by adding extra styling. With these two options the developers have all the tools needed to build appealing user experience for SAS Viya Jobs.

The code for the two articles is available on GitHub.    

Find more articles from SAS Global Enablement and Learning here.

Share this content:

SAS Users channel on YouTube

YouTube 

[jins]

Got a question - For some reason, the drop downs are not loading up with values. What can be the reason?

[obendav]

Xavier,

Please can you share word document of pdf version of this YouTube training you provided?

Create a SAS Viya Job with a prompt using Task Prompts

[Babloo]

@XavierBizoux  I've executed the job definition per your post in SAS Studio, but I don't see any values in any of the dropdown. Am I making any mistake? Thanks in advance.

SAS Code what I used is,

%global originStmt typeStmt driveTrainStmt invoiceStmt;

%macro generate; 
	%if %symexist(var_origin) %then %let originStmt = origin in ("&var_origin") and;  
	%if %symexist(var_type) %then %do;
		%let typeList = ;
		%if %symexist(var_type_count) %then 
		%do i=1 %to &var_type_count;
			%let typeList = "&&var_type&i", &typeList ;
		%end;
		%else %let typeList = "&var_type"; 
		%let typeStmt = type in (&typeList) and; 
	%end; 
	%if %symexist(var_driveTrain) %then %let driveTrainStmt = driveTrain in ("&var_driveTrain") and;
	%if %symexist(var_invoice) %then %let invoiceStmt = invoice < &var_invoice ; 
	%else %let invoiceStmt = invoice > 0;
%mend; 

%generate; 

proc print data=sashelp.cars; 
	where &originStmt  &typeStmt &driveTrainStmt &invoiceStmt; 
run;

HTML code which I used is,

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <title>Job with Dynamic prompts</title>
</head>
<script src="/SASJobExecution/resources/sap/ui/thirdparty/jquery.js"></script>
<script src="/SASJobExecution/resources/dynamic.min.js"></script>
<style>
    details div {
        padding: 1em;
    }

    summary {
        margin-top: .5em;
        font-size: large;
        font-weight: bold;
    }

    label {
        display: block;
    }

    select {
        margin-left: 1em;
        margin-top: 1em;
        min-width: 10em;
    }

    input[type="range"] {
        margin-left: 1em;
        margin-top: 2em;
        width: 40em;
        float: left;
        vertical-align: middle;
    }

    input[type="submit"] {
        padding: 0.5em;
    }

    .displayValue {
        margin-left: 1em;
        margin-top: 1em;
        border-radius: 0.5em;
        border-color: grey;
        border-style: solid;
        float: left;
        width: 5em;
        height: .6em;
        vertical-align: middle;
        padding-top: .5em;
    }
</style>

<body onload="SASDynamic.init()">
    <form action="/SASJobExecution/" target="_tab">
        <input type="hidden" name="_program" value="$PROGRAM$">
        <input type="hidden" name="_action" value="execute">
        <input type="submit" value="Submit">
        <hr>
        <details>
            <summary>Geography</summary>
            <div>
                <label for="var_origin">Choose a geographic location:</label>
                <select name="var_origin" id="var_origin" data-colname="origin" data-library="SASHELP" data-table="CARS"></select>
            </div>
        </details>
        <details>
            <summary>Car's characteristics</summary>
            <div>
                <label for="var_type">Choose one or multiple car types:</label>
                <select name="var_type" id="var_type" data-colname="type" multiple size="10" data-library="SASHELP" data-table="CARS" data-uses="var_origin"></select>
            </div>
            <div>
                <label for="var_driveTrain">Which kind of drive train do you want:</label>
                <select name="var_driveTrain" id="var_driveTrain" data-colname="drivetrain" data-library="SASHELP" data-table="CARS" data-uses="var_origin, var_type"></select>
            </div>
        </details>
        <div data-visible="var_origin,eq,Asia">
            <details>
                <summary>Financial aspect</summary>
                <div>
                    <label for="var_invoice">What is the maximum price you want to pay?</label>
                    <div id="invoiceValue" class="displayValue"></div>
                    <input type="range" id="var_invoice" name="var_invoice" min="10000" max="150000" value="50000" step="1000" data-uses="var_origin">
                </div>
            </details>
        </div>
    </form>
    <script>
        document.getElementById("var_invoice").addEventListener("change", (e) => {
            document.getElementById("invoiceValue").innerHTML = e.target.value
        })
    </script>
</body>

</html>