Making a Viya Service API Call from a JES Input Form
This is the second installment of a series of two articles that discuss embedding an HTML input form directly in a Job Execution Web Application Service (JES) Job Definition. If you haven’t seen it yet, I recommend reading the first one before continuing.
As I mentioned in my previous article, one of the best parts of using the JES framework is that it allows developers to create code that leverage foundation SAS, CAS actions, and Viya APIs! Using these technologies along with the JES Web Application's ability to pass user input to a job using an HTML input form, developers can harness the full power of the Viya platform to create applications that can meet any of their customers' needs. In this article, I will demonstrate how to create a JES job which takes user input and uses it in a REST API call to a SAS Viya Service!
The example below shows the output from the job which will be discussed in this article. Notice how the user has selected the search term "Retail" from the drop down prompt. This value is then used as a parameter in a API request to the Viya Reports service. The request retrieves and prints a list of Visual Analytics reports that contain the word "Retail" in their title:
In this article we'll break down each piece of this JES job definition to understand how user input is captured and used in the API request.
Job Framework Overview:
If you look at the example from my previous article, you can see that the job is divided into three SAS Macros: %first_macro, %create_request and %create_report. Each one of these macro plays an important role in creating the user interface which contains both the HTML input form and the output from the JES job. Each of these macros is discussed below:
%first_request Macro
This is the job's first macro. It generates the output by executing a data step with several put statements that contain HTML code:
%macro first_request;
/* This is the first request. Create an HTML page with Frames. */
data _null_;
file _webout;
thissrv = "&_URL";
thispgm = "&_program";
put '<html>';
put '<table>';
put '<tr>';
put '<td width="20%">';
put '<iframe name="frame1" scrolling="no" width="100%" height="600" src="'
thissrv +(-1) '?_program=' thispgm +(-1)
'&reqtype=create_selection&_debug=0">';
put '</iframe>';
put '</td>';
put '<td width="80%">';
put '<iframe name="frame2" width="100%" height="600" >';
put '</iframe>';
put '</td></tr>';
put '</table>';
put '</html>';
run;
%mend first_request;
By looking closer at the HTML code we can see that this macro contains a simple table with two columns. The first (or left) column is set to be 20% of the browser's width. By inspecting the contents of this first column we can see that it will surface an iframe. The iframe calls the currently running JES job with the parameter '&reqtype=create_selection'. Hence it will display the output from the %create_selection macro. The second (or right) column is set to be is set to be the remaining 80% of the browser's width. Similar to the first column we can see that it will also surface an iframe. However this iframe calls the current JES job with the parameter '&reqtype=create_report' (aka: the output from the %create_selection macro).
%create_selection
This is the macro which will be displayed in the first (or left) column of the main HTML table. The macro dynamically generates the HTML which prompts the user for input. Similar to the %first_request macro, this macro generate the HTML via a data step with put statements. The result is a simple HTML input form with a drop-down list. Using this drop-down the user can make a selection and press submit. Their selection is then captured in a macro variable named "reportSearch".
data _null_;
file _webout;
thissrv = "&_URL";
thispgm = "&_program";
put '<html>';
put '<h3>Reports API Example</h3>';
put '<FORM ACTION="' thissrv +(-1) '" method=get target="frame2">';
put '<input type="hidden" name="_program" value="'
thispgm +(-1) '">';
put '<input type="hidden" name=reqtype value="report">';
put '<input type="hidden" name=_ODSDEST value="html">';
put '<b>Report Name Contains: </b>';
put '<select name="reportSearch">';
put '<OPTION VALUE="Retail">Retail';
put '<OPTION VALUE="Water">Water';
put '<OPTION VALUE="Warranty">Warranty';
put '</select>';
put '<br><br>';
put '<input type="submit" value="Submit">';
put '</form>';
put '</html>';
run;%create_report
We can now move on to the final macro which will make the REST API call to the SAS Viya Reports Service and display any returned output. As I mentioned at the start of this post, one of the biggest advantages of creating applications using the JES framework is the ability to leverage foundation SAS, CAS actions, and Viya APIs.
With this in mind, we can begin to think about the API request we want to make. First we want to use the 'reportSearch' value that the user selected in the %create_selection macro. Fortunately, this is very easy as the parameter's value is stored in the macro variable '&reportSearch'. Hence, this macro variable can been used in the url statement of a PROC HTTP request.
For the API call itself, we will be calling the Viya reports service to retrieve a collection of reports. We will also be using a filter in the REST API call to ensure the list returned to the client will only have reports which contain the string from the '&reportSearch' macro in their names. The PROC HTTP code to make this API call is below:
* Base URI for the service call;
%let BASE_URI=%sysfunc(getoption(servicesbaseurl));
* FILEREFs for the response and the response headers;
filename resp temp;
filename resp_hdr temp;
proc http url="&BASE_URI/reports/reports/?filter=contains(name,'&reportSearch')"
method='get'
oauth_bearer=sas_services
out=resp
headerout=resp_hdr
headerout_overwrite;
run; quit;
The code above returns a JSON file containing a list of reports that match the search criteria. All that is needed now is to read this json file into SAS using the JSON libname engine and display the list using PROC PRINT! The code to do this is below:
libname resp json;
title "Visual Analytics Reports That Have the Word '&reportSearch' in Their Names";
proc print data=resp.items label noobs;
/* var name creationTimeStamp createdBy modifiedTimeStamp modifiedBy description; */
var ID Name creationTimeStamp;
label ID = "Report ID"
Name = "Report Name"
creationTimeStamp = "Created On";
run; quit;
And that's it! After breaking down this JES code into its three macros, its easy to see how it can be leveraged for a wide variety of uses! It can be used to create custom HTML prompts, run traditional SAS to generate ODS reports and even make API calls to the SAS Viya services! Armed with the SAS Viya Job Execution Web Application Service, the entire Viya platform can be accessed and leveraged by SAS developers to build applications that can meet any of their customers needs!
You can find the completed code for this example on GitHub. If you copy and paste this code into a new JES job, you will also need to add an "_output_type=html" parameter to your job. To do this right click on the job file in the left-hand pane and choose "Properties":
At the next window, expand the "Parameters" menu and choose "New Parameter":
For the parameter name input "_output_type".
For the default value, input "html".
Press "Save".
Good job! The JES job creation is now complete!
How to make this example work for you
On GitHub, you will find all the code discussed in this article. All code intended to be saved in a SAS® Job Execution Web Application job definition within a Viya 3.4 (or later) environment.
