Sharing Jobs Using SAS Visual Analytics

One of the great features of SAS Viya jobs is the ability to define user input forms to let end users without programming experience run programs and customize reports. JSON-based step prompt forms make it even easier for non-programmers to create user interfaces for jobs, as it is possible to use to the custom step Designer within SAS Studio to create interactive forms with no knowledge of HTML, JSON, or XML code required.

However, JSON-based step prompt forms can currently only be used in SAS Visual Analytics and SAS for Microsoft 365, meaning that you can’t easily share a job submit URL with end users to let them run the job. In this article, I’ll discuss how to incorporate a JSON-based step prompt form in a SAS Visual Analytics report to allow end users to access job results.

Start with a Working Program

Like all job development, it’s a good idea to begin with a program that you know works. In this post, I’ll use a simple program that allows a user to select a make of car from SASHELP.CARS and generate a report of the five most expense cars and a graph of the MSRP by car type. The code looks like this:

%let selectMake=Honda;

proc sql;
	create table work.cars as 
	select Make, Model, Type, MSRP from sashelp.cars
	   where Make = "&selectMake"
	   order by MSRP desc;
quit;

title "Top Five Most Expensive: &selectMake";
proc print data=work.cars(obs=5);
run;
title;

title "MSRP by Type: &selectMake";
proc sgplot data=work.cars;
	vbar type / response=MSRP stat=mean;
run;
title;

To turn this code into a job definition, I only need to swap out the %LET statement for a %GLOBAL statement, creating the macro variable selectMake.

%global selectMake;
proc sql;
…

Create a Step Prompt Form

As of SAS Viya 2023.06, it is possible to define prompt forms using JSON syntax. Unlike HTML and XML forms which require you to write the code yourself, JSON- based forms can be created using the point-and-click custom step designer. All I need to do is create a new custom step:

Then I can select the controls I want from the control library on the left side and arrange them in the canvas.

In this case, I want to create a drop-down list that automatically populates with the values of the Make columns from SASHELP.CARS. I’ve created three prompts:

An input table selector to specify the SASHELP.CARS input table. I’ve made this read-only and hidden, so the end user will not see it.
A column selector to specify the Make column from SASHELP.CARS. I’ve also made this read-only and hidden, so the end user won’t see it. The input table selector and column selector will be used to dynamically populate the drop-down list.
A drop-down list that dynamically populates with the Make values from SASHELP.CARS. I also need to make sure that the ID value associated with the drop-down selector matches the macro variable used in the job definition.

Behind the scenes, this tool generates JSON code that defines the interface I’ve created. The Prompt UI tab contains JSON syntax:

To use this interface in my job, all I need to do is copy it and paste it in the Step Prompt (JSON) tab in the job definition.

However, I won’t be able to preview this job from within SAS Studio. To test it and to share it with end users, I’ll need to use SAS Visual Analytics.

Add a Job to a SAS Visual Analytics Report

There are a variety of ways that you can incorporate jobs in a SAS Visual Analytics report. For example, both jobs with HTML and XML-based forms can be added using either the web content object or the data-driven content object. However, to add a job a that uses a JSON-based prompt, you must use the job content object.

The job content object allows you to select a job definition to use in the report. Once you select a job definition, the input form associated with it will be displayed:

I can use this form to select the parameters I want to use to run the job, and then click OK to run it. The results of the job will be displayed directly in the object:

To re-submit the job using different parameters, you can click on the Object menu and select Set job parameters. You can also view the log of the submitted job.

Share the Job with End Users

One common use of jobs is to allow end users who are not programmers to control parameters, run programs, and create reports without having to modify the underlying code. Once the job content object has been added to a Visual Analytics report, the report can be shared with end users, and anyone with access to the report can set the parameters, run the job, and generate the reports that need, without having to touch a single line of code.

To share a SAS Visual Analytics report, you can use the Share report option to send it to a specified user or group, or you can use the Copy link option to generate a link to share.

Conclusion

SAS Viya jobs provide a great way to automate code execution and to simplify reporting for end users who are not programmers. By creating JSON-based step prompts, developers don’t have to worry about XML or HTML syntax, and they can still easily distribute the job to end users by using the job content object in SAS Visual Analytics. Stay tuned for a future article, where I’ll dive deeper into some of the other ways to integrate jobs and SAS Visual Analytics!

Tips

Make sure that job definitions are stored in a location that report viewers have access to.
You can convert an XML-based task prompt to a JSON-based step prompt. However, be aware that the conversion may not always result in one-to-one equivalence.
You need to save a report before you can share it with others.
You can hide controls from the user by setting the visible value to false in the JSON form definition. You can also make controls read-only by setting the readonly value to true.

Other Resources

Find more articles from SAS Global Enablement and Learning here.