How to automatically retrieve a SAS Visual Analytics Report's URI
Are you a SAS developer who is interested in learning how to use SAS code to interact with the Viya Rest APIs? If so, you should check out the SAS Global Form paper SAS® Viya® reportImages Service: The Report Optimization Speedometer! This paper's GitHub repository includes a program that can be run in a SAS Studio 5.1 session which uses the Viya reportImages service to generate an SVG image for a specific VA report.
If you've already looked though some of the reportImages examples on developer.sas.com, you might have noticed that when making a request for the reportImages service, you must include the report's internal unique ID (or URI) in the request. Finding a VA report's URI is usually a manual process that involves navigating to the SAS Environment Manager's content menu, locating the specific VA report of interest, and manually copying and pasting the report's URI into your SAS program.
Fortunately, you can use the Viya reports service to do this step for you! All you need to do is tell the service the name of the report you're looking for and it will return the report's URI. In this article, I'll show you the SAS code that does this!
Step 1 - Sending the request
Let's imagine you have a SAS Visual Analytics report named: "Simple Roads Report" that you want to create an SVG image from. First you need to get the report's internal unique URI. According to the documentation, we can request that the reports service send us detailed information (including the URI) for any VA report by making a "GET" request to this base URL: http://example.com/reports/reports.
The documentation goes on to tell us that we can place filters at the end of our request. Using one of these filters, we can request information about just one specific report. So if we want to get information about our specific Visual Analytics report, "Simple Roads Report", our new url will be:
http://example.com/reports/reports?filter=eq(name,'Simple%20Roads%20Report')
*notice that the report name must be urlencoded. This can easily be done using the URLENCODE Function.
Since both SAS Studio 5.1 and the SAS Viya services we are calling are within the same environment, we can also use a nifty SAS trick to automatically generate the http address (or endpoint) for the reports service. At the top of our program we can place the following code:
%let BASE_URI=%sysfunc(getoption(servicesbaseurl));
This will dynamically determine the base address for the service call and we can place it in the macro variable "BASE_URI". Therefore we don't have to hard code our Viya Environment's URL into our code!
We can use PROC HTTP to build a request for detailed information about the report, 'Simple Roads Report':
%let BASE_URI=%sysfunc(getoption(servicesbaseurl));
/* Create filename for response */
filename rep_id temp;
/* Make the request */
proc http
oauth_bearer=sas_services
method="GET"
url="&BASE_URI/reports/reports?filter=eq(name,'Simple%20Roads%20Report')"
out=rep_id;
run;
Probably the most useful part of making SAS Viya services requests from SAS Studio 5.1 is the ability to use the OAUTH_BEARER= argument in PROC HTTP. This sends an OAuth access token along with the HTTP call. Using this in conjunction with the "sas_services" constant, an access token is obtained using the identity of the user that is logged into SAS Studio 5.1. In short, this uses your current login information to grant you access the SAS Viya services! *this option is only available in SAS Viya
Step 2: Reading the response
In the code above, we have used PROC HTTP to make the request. After receiving the request, the reports service will respond by sending back the detailed information for the report we have specified (in this case the 'Simple Roads Report'). We will want to capture this response and place it somewhere that the SAS engine can read. Hence, before sending the request to the reports service, we create a temporary filename named 'rep_id'. By placing this filename in the "out=" argument of PROC HTTP, the response from the API is held in the filename 'rep_id'. All that we have to do now is use SAS to read the filename's contents!
The format of the response content that is now held in the 'rep_id' is a json string. Because we are using SAS, we can now use the JSON libname engine to read this content. By simply assigning a libname to the rep_id file, the response from the reports service becomes available as SAS datasets. The internal report id for the report we requested ("Simple Roads Report") is located in the newly assigned library 'rep_id' as the dataset: 'items'. From here we can use PROC PRINT to display the information we are interested in (the report's name and unique id).
libname rep_id json;
proc print data=rep_id.items noobs label;
label name='Report Name' id='Report Internal ID';
var name id;
run;
And there you have it!
In just a few lines of code, you have programmatically retrieved the unique URI for the "Simple Roads Report." Armed with this ability to easily retrieve a Visual Analytics Report's URI, we can start using the reportImages service to create SVGs of our reports!
How to make this example work for you
This example was created in Viya 3.4. All code in this article is intended to be submitted in a SAS Studio 5 session within a Viya 3.4 environment which contains the SAS Viya services that are being called.
On GitHub, you will find all the code discussed in this article. The code has one required input parameter:
- A %let= statement in which you can place the name of a Visual Analytics report (Line 34)
- *the default value for this %let statement is "Retail Insights"
