Creating JES Prompts and Output Using the Viya Reports API
In my last post, I demonstrated how developers can use java script within a JES’s HTML input form to control how job output is handled. This was useful because it allows both the user prompt and JES output to be displayed on the same page. However this is really just the tip of the iceberg when it comes to all the ways developers can use the JES HTML input form to create dynamic, useful applications for report consumers.
In this post, I will build on the previous JES example by incorporating request calls to the Viya Reports API. Just like in the previous example, when the job is called, it first shows some custom HTML. Within this HTML page we will make XMLHttpRequest request to the Viya Reports API to get a list of the ten most recently created Visual Analytics reports in the Viya environment. We will use this list to populate an HTML drop down from which the user can make a selection. After the user makes their selection it will be passed to the job's SAS code and will make another request to the Viya Reports API to get the visual elements that are contained within the report. Finally, we will display a table of only the Graph type elements to the user.
A view of what the finished example looks like is below:
Pretty neat! In this post, I'll show you how to build this example! Let’s get started!
Step 1: Create the JES Job and Adding Source Code
Before we can create our HTML input form, we will need to create our JES job and add some source code to it. We'll start within the Job Execution WebApp by creating a new job. In the screenshot below, I'm creating a job in the folder "/Public/JES_Example"
Give your job a name. In my example, the job is named "JESPromptsOutputViyaAPI".
All other options can remain as their default values. Press "OK":
Now we need some SAS code for our job to execute. You can add this by right-clicking the job and selecting: "Edit" -> "Source code":
From here you can add SAS Code to the job and save it.
To start my code, I'm adding SAS code which uses PROC HTTP to make an API call to the Viya Reports API and gets a report's content elements. Notice that there is a SAS macro variable "&JESParameter" which will eventually contain a specific report uri when the code is run:
*if you are unfamiliar with how to use SAS to make requests to the Viya API, check out my previous article which goes into further explanation of how to do this.
Now that we have made our call, we can use the json libname engine to read in the response and return the visual elements from the report. For this example, we are only going to create a report which lists the visual elements that are of type "Graph". Hence, we will create a data set that only contains these elements:
Finally we want to create our output report. We will use proc report to list any graph elements that our report has in it. However, we will also need to accommodate for the event that the report has no graph elements (i.e. the report might only have a list table in it). Hence we will first check how many observations are in the 'reportElements' data set. If the observation count is greater than zero, then we will run our proc report step. If the observation count is equal to zero, we will generate a message informing the user that the report they selected has no graph elements:
Great! We've added all the needed SAS code to our job.
Step 2: Use the Viya Reports API to create an HTML prompt
As I mentioned in my previous article, one of the best parts of the Job Execution WebApp is the ability to create custom HTML containing input form(s) that can be displayed before the job's SAS code runs. However did you know you can place code in these HTML forms that can make calls to the Viya API? This can be very helpful if you want to populate your custom HTML with information about the Viya system.
For example, perhaps I wanted to create a drop down selection which allows the user to choose a from the 10 most recently created Visual Analytics reports on our Viya environment. Well it turns our that this is super easy when we are working with the Job Execution Web Application. All we need to do is make a "get" request to the Viya Reports API and get a collection of reports. We also want to ensure that we return the most recently created Visual Analytics reports, so we will use the sorting functionality provided by the Viya API platform. Finally we only want to return ten reports. So we will leverage a pagination query parameter to our request to limit the number of items the API returns.
While this might sound like a complicated API request, it's actually quite simple if you look at the request call:
GET /reports/reports?limit=10&sortBy=creationTimeStamp:descending
Now that we have the request syntax, we can place it in the custom HTML for our job. To do this, right-click the job and select: "Edit" -> "New HTML Form":
Here is where you can add any HTML that you would like to display to the user before the job is submitted. As in my previous article, I will be using code sourced from the Executing a Job Using JavaScript - Sending Small Data to the Job example in the Job Execution Web Application Service 2.2 Documentation. I will modify this code slightly by creating a drop down prompt from the response from Viya Reports API and placing it in the 'reportList' DIV tag within page's <body> tag. When the user makes a selection, it will then be passed into the job's SAS Code as a macro variable. The SAS code executes, and its output is returned and placed in the 'JobResults' DIV element within the HTML Form's <body> tag.
Let's begin by adding basic HTML page with a user selection:
Great! Now that our user form is in place, we will need to add the script which will create our HTML dropdown prompt. This will happen in two steps. First we will make the request to get the ten most recently created Visual Analytics Reports. Second we will loop though each item in the API's response json file and iteratively convert it into drop down list options. The code to do this is below:
With this code in place, now's our first chance to see our work in action! To do this, right click on your job and choose: "Display form" -> "HTML form":
We can see our script has made the call to the reports service, converted the response into a drop down selection, and inserted it into the HTML.
Looks like I have quite a few Visual Analytics reports which are still in development!
The final step is to add one final script which will take the user's selection and submit it to the job using the POST method. If you are unsure about how the following steps work, they are covered in detail in my previous article.
Note use of the value $PROGRAM$ as the value for the _program input tag. As the JES documentation points out, "When the HTML input form is displayed, the path and name of the program to execute are substituted for $PROGRAM$." This makes the HTML code we are writing more portable.
Great! You're done with the coding part of creating the example. All that's left is for us to add a job definition parameter so the HTML input form will be displayed before the job is executed. This is easily done by right-clicking the job and selecting: "Properties":
From here, select "Parameters". Click "Add a new parameter". Apply the following values:
- Name: "_action"
- Default value: "form,execute"
Press Save:
And you're done! To see your completed work, simply select your job and click the "Submit" button. From there make a selection from the HTML prompt we created, press submit, and see the results of the JES job all on the same page! Here is what my finished JES output looks like:
Notice both API calls are shown. First the call to the Viya Reports API to create the selection (highlighted in red), second selection is passed the selection to the JES job itself (highlighted in black) and finally the SAS code which makes a call to the Viya Reports API to return the report's graph elements is highlighted in green!
The example javascript and SAS code used in this example are very simple in order to demonstrate the basic principles of how each piece of the job work together. However these concepts can be used as building blocks to make the job much more exciting. More elaborate API Calls, HTML prompts, javascript code and SAS programs can be added to truly make a JES job that can meet report user's needs.
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 2.2 job definition within a Viya 3.5 environment.
On Github, you will find the following support files for this article:
- A JSON file containing the completed JES Job - JESPromptsOutputViyaAPI.json
- *A SAS Administrator can import this to the Viya content folder "/Public" within a SAS Viya 3.5 (or later) environment using these instructions
- The JES job's SAS source code to create the ODS output - JESPromptsOutputViyaAPI.sas
- The JES job's HTML code to create prompts and execute the job - JESPromptsOutputViyaAPI.html
