Creating Images of Your Visual Analytics Reports in Just 10 Lines of Code
I've written previously on how to use the reportImages API service to create images of SAS Visual Analytics reports. The method I demonstrated on how to do this was a bit tedious, as it involved creating a job, observing the job's status, waiting for the job to complete, and then finally retrieving the location of the generated image. This left me wondering if there was a simpler way to generate images of Visual Analytics reports. Well, as it turns out there is!
As of SAS Viya version 2021.2.4, the new Visual Analytics API makes creating images of SAS Visual Analytics reports easier than ever! Not only can it be used to create an image file of an entire report tab, but it can also create images of individual report objects. In this article, I'll demonstrate how to call the Visual Analytics API from SAS Studio and use it to create an image of a Visual Analytics report – all in just 10 lines of code! An example of the process is below:
Let's get started!
Example 1: Creating Images of an Entire Report Tab
Before we can start generating the image of the report, we will need to know the following:
- What is the id (or URI) of the Visual Analytics report that we want to create an image of?
- What size (height and width) do we want our output image size to be?
- Where do we want the output image placed?
We can tell our SAS program the answers to these first 2 questions by simply entering them in a set of %let statements. In the example code below, I've declared the report URI for the example report "Retail Insights" that comes installed with SAS Viya. You can read more about the example reports in the SAS Viya Documentation. I've also declared that I want my output image's height and width to be 800px and 600px respectively.
%let reportID = 6945298b-9466-41d3-aeed-f5a7aaf4985b;
%let height=800px;
%let width=600px;
Great! We are already well on our way! Now where do we want the output image to be placed and what should its name be? We can see from the API's documentation that the image which will be created is returned as the response’s body. Because of this, we can use the FILENAME Statement: FILESRVC Access Method to save the output image to a folder in the Viya folders Content area. For this article, I'm going to place the output image in the private "My Folder" area for my user id and name it "myOutputImage.svg". This is achieved using the following line of code:
filename imgfile filesrvc folderuri='/folders/folders/@myFolder' filename="myOutputImage.svg";You may notice that I am using the value '/folders/folders/@myFolder' in the value of the ‘folderuri’ parameter. This is a dynamic pointer that will automatically point to your "My Folder" directory in the SAS Content folder directory structure. Alternatively, you could place your image in another location (such as "/Public" using the "FOLDERPATH=" option).
Alright! Now that we have answered all the needed questions for creating the image file of our Visual Analytics report, we can start writing our API call using PROC HTTP.
First, we will need to retrieve the base URI for the service call. Since we are doing our programming within SAS Studio, we can dynamically get this by submitting the following line of code. The URI is saved to the SAS macro variable "BASE_URI":
%let BASE_URI=%sysfunc(getoption(servicesbaseurl));
With these pieces in place, we can write out our API call. The code to make the call is below:
proc http method="GET"
oauth_bearer=sas_services
url="&BASE_URI/visualAnalytics/reports/&reportID/svg?size=&height,&width"
out=imgfile;
run;
We begin our PROC HTTP call by specifying that we want to perform an HTTP "GET" method. The next step is to think about authentication to the API. Since we are already logged into the SAS Viya platform and submitting SAS code using SAS Studio, we can connect to the SAS Viya services by placing the keyword sas_services in the PROC HTTP option oauth_bearer. This ensures that the access token for the current authenticated user is automatically obtained and attached to the request. Next, we specify the fully qualified URL path that identifies the endpoint for the HTTP request. The pieces of this URL path were already saved as SAS Macro Variables in our %let statements. So, we can place these macro variable references in the URL. Finally, we simply need to tell PROC HTTP where to place the response from the call. For this, we can simply place the file reference "imgfile" we created earlier.
And that's it! Let's go ahead and run our code!
Well done! We have now successfully created and saved an svg image of our Visual Analytics report tab. And we did it in just 10 lines of SAS code!
Example 2: Snapshotting a Single Report Object
Now that we know how to create an image of an entire report, we can move on to creating an image of just a single report object. Fortunately, the new Visual Analytics API makes this process as easy as the first example in this article. In fact, we only need to add a single parameter to our PROC HTTP call. The new parameter is: "reportObject". For the value of this new parameter, we will need to retrieve the name of the object we want to import. I have written a previous article on how to do this using SAS code. However, you can also manually retrieve the report object’s name by opening your Visual Analytics report and clicking the three dots in the top right of the report object you would like to create an image of. After clicking the three dots, select “Create link”.
In the example below, I'm selecting a bar-line graph in my Visual Analytics report:
After clicking "Copy link", a new window appears with a dynamically created link. The very last bit of text in this link contains the report object's name. In the example below the report's object name is: 've152':
From here we can execute a modified version of the code from the first example, but this time with our new parameter and associated parameter value. As we did with the reportID, we create a reportObjectID macro variable and place the actual name of the report object we want to export into it. You will also notice that we changed the name of the output image file to include the value saved in the reportObjectId macro variable. This will make the output image that is place in our "My Folder" unique:
%let BASE_URI=%sysfunc(getoption(servicesbaseurl));
%let reportID = <- report uri ->;
%let reportObjectId = ve152;
%let height=800px;
%let width=600px;
filename imgfile filesrvc folderuri='/folders/folders/@myFolder' filename="myOutputImage_&reportObjectId..svg";
proc http method="GET"
oauth_bearer=sas_services
url="&BASE_URI/visualAnalytics/reports/&reportID/svg?size=&height,&width&reportObject=&reportObjectId."
out=imgfile;
run;
After running this code, we get a new image in our folder:
And that's it! In just a few lines of code we have programmatically created svg images of both an entire Visual Analytics Report tab, and also an individual report object!
