The Visual Analytics Alphabet Series – A is also for APIs!

[#1]

This is the next part of a multi-part series that discusses some of the distinctive features of SAS Visual Analytics.

• A is for Aggregated Data
• A is also for APIs (this article!)

Today, is again brought to you by the letter A… which is also for APIs.

I know I already did A (see A is for Aggregated Data), but the Visual Analytics API is a cool, relatively new feature in VA that is worth the repeat! I find myself using the APIs constantly to automate tasks and save development time.

Did you know that the idea of APIs goes back to the early days of computing when developers started using reusable subroutines to avoid rewriting the same logic over and over? Now if only I can figure out a way to apply this to cooking!

SAS Viya provides a whole host of APIs that are designed specifically for enterprise developers to build on the work of model builders and data scientists. Many applications in SAS Viya (including SAS Visual Analytics) have their own specific APIs for creating and accessing various SAS resources. For example, there is a Files API that enables you retrieve a list of file resources in a specific folder, update those files, and delete them if necessary. For a list of SAS Viya APIs, usage notes, and examples, see Rest APIs. In this article, we will focus on the SAS Visual Analytics API.

The SAS Visual Analytics API provides a programmatic way for performing basic tasks with a Visual Analytics report, like creating and modifying reports (adding pages, objects, and setting parameter values), transforming reports (like changing data sources or themes), exporting content (like PDFs, data, images, or report packages), and deleting reports.

One of my favorite ways to use the SAS Visual Analytics API is to perform some task (like creating a PDF of a report) for many different values (different companies, different users, or different movies).

Recall that we have a data source that has information about HORROR_MOVIES, like a description of each movie, the tagline, release date, original language, genre, the collection, a popularity score, budget, revenue, and runtime. For more details about the data and the data preparation steps undertaken, please see The Visual Analytics Alphabet Series – The Data.

Screamers Collection
I’ve already created a report that shows details about different horror movies within a collection. In this example, we can see that the Screamers Collection has two movies: Screamers (1995) and Screamers: The Hunting (2009). A bar chart on the right shows the budget of the movie in dollars (white bar) and the revenue earned from the movie (red bar). Some movies (like Screamers: The Hunting) contain no information about budget or revenue in our data, so bars do not appear for those movies. At the bottom of the page is a list table that shows details for each movie in the collection, like the Release Year, the movie runtime, the IMDb Rating, the number of user ratings, and the popularity score.

Pro Tip! The IMDb rating is a calculated data item that uses a Unicode character to display the star. For more information about how to use Unicode characters in VA reports, see Leveraging Unicode in SAS Visual Analytics Reports.

This report also has a data source filter applied that returns only details about one collection (whichever collection is specified for the Collection Name Parameter).

Data Filter

I can easily export a PDF of the report by clicking the More button in the upper right corner and selecting Export > PDF.

Export PDF

In this example, however, there are hundreds of horror movie collections. It would take me all day, maybe all week to create a PDF for each collection. Then, what if I get new data next month or tomorrow?

Instead of exporting the PDFs individually, let’s see if the Visual Analytics APIs can help.

For this example, we will need to use two endpoints of the Visual Analytics API: updateReport to change the value of the Collection Name Parameter for each collection and getExportedReportPdf to create the PDF for that collection.

Each endpoint contains details about the endpoint, samples, a list of parameters, and typical responses.

Documentation for getExportedReportPdf

In the Request Samples area, multiple code formats are provided so you can call the API from any tool you want.

Request Samples

Because I am a SAS coder at heart, I prefer to call the API endpoint using PROC HTTP in SAS Studio. This is great because I can also read the CAS table (HORROR_MOVIES), subset it for the collections I’m interested in, and create a macro program that creates the PDF file for each collection.

In SAS Studio, I’ll start by defining several macro variables:

• caslib – the name of the CAS library where the HORROR_MOVIES dataset is stored
• lib – the name of the library that will enable me to see the CAS library in SAS Studio
• ds – the name of the dataset (HORROR_MOVIES)
• viyaHost – the SAS Viya Host URL (which will be used in PROC HTTP)
• collection_parm – the name of the parameter used in the Visual Analytics report (Collection Name Parameter)
• uri – the URI of the Visual Analytics report
• targetPath – the SAS Content path for the folder where I want to store my PDF files

Defining Macro Variables

Pro Tip! You can determine the URI of SAS Viya resources in SAS Environment Manager. Using the Content pane, navigate to the report and select it. Then, in the Details pane on the right, expand More > URI to find the path for that object.

Next, I create a CAS session that points to my CAS library and create two SAS library references to CAS libraries, so I can easily work with the data in my code.

Creating CAS Session

Now, I want to subset my data to include details about movies that are in a collection (collection_name ne ‘NA’), originally created in English (original_language = ‘en’), and were first released within an 18-year span (year(collection_release) between 1983 and 2001). This gives me a smaller number of collections to work with.

Subset CAS Table
Note: I use the years 1983 to 2001 because those are the years I was born and graduated high school, respectively.

Then, I’ll create a macro variable (collections) that contains a list of all those collection_names separated by a pipe character (|) and a macro variable (num_cols) that contains the number of collections. I’ll later use these macro variables to run the macro program that will create a PDF for each collection in the list.

Create collections and num_cols Macro Variable

Next, I’ll create a helper macro program to grab the entity tag (ETag) for the most recent version of the report. The ETag changes each time the report is updated and any calls to the API must include the latest ETag value. This ensures that any update requests (like changing the value of a parameter) are only applied if the client’s version of the report is current, which helps manage concurrent access.

Notice, I’m using PROC HTTP to call the Visual Analytics API to retrieve this information.

• The METHOD= option specifies the method (get, put, post) and will differ based on the endpoint used.
• The OAUTH_BEARER = sas_services option sends an OAuth access token from SAS Viya along with the HTTP call; this option enables your SAS Viya login credentials to be used for the call.
• The URL= option specifies the SAS Viya Host and URL for the specific API call.
• The HEADEROUT= option specifies the text file where the response headers are written.
• The HEADERS statement specifies the request headers for the request. These are specified on the Rest APIs Developer page.

get_etag Macro Program

For more information about retrieving the eTag, see the headersForGetReport endpoint.

Pro Tip! To ensure the code runs without errors, it’s a best practice to close the report before running the code and scheduling the code to run when others are unlikely to be accessing or modifying the report (so there are no competing accesses).

Then, I’ll create a macro program (pdfs) that uses the collection name as input to create the individual PDF files for each collection. The first part of the macro program creates a new macro variable (targetFileName) that specifies the name of the PDF file. Then, it calls the get_etag macro to get the ETag of the most recent version of the Visual Analytics report.

pdfs Macro Program - Defining target file and getting eTag

Then, a DATA step is used to create a temporary file (parm) that contains the operations request object, which specifies the operation to be performed on the report (in this example, setParameterValue). The setParameterValue operation specifies the name of the parameter used in the report (in this example, the collection_parm macro variable which equals Collection Name Parameter) and the value of the parameter (in this example, the collection macro variable which equals the name of the collection).

This temporary file is used in the PROC HTTP step to update the report by changing the parameter value. This PROC HTTP step contains a few additional options:

• The IN= option specifies the file with the operation details.
• The OUT= option specifies where the output (the response for the API call) is written. This is useful for troubleshooting if your API call produces an error.
• The HEADERS statement contains the If-Match header that verifies that the ETag we retrieved is the ETag of the most recent version of the Visual Analytics report. Remember, this is necessary for this API call because we are issuing a PUT request that will update the report.

pdfs Macro Program - Changing the value of a parameter

Then, PROC HTTP is used to export a PDF of the report. Notice the URL contains a list of query parameters:

• reportObjects specifies the labels of the report objects to export, like individual objects or complete pages. This can be a list of multiple objects (separated by commas) and can be enclosed in quotes if the object label contains spaces or special characters. If the internal identifier of the object is known, this value can be used instead.
• includeAppendix specifies if an appendix should be included (true) or not (false).
• includeCoverPage specifies if the cover page should be included (true) or not (false).
• paperSize specifies the paper size for the PDF file. If set, this value overrides any size that is saved with the report.

pdfs Macro Program - Exporting a PDF of a report

For more information about additional query parameters, see Export a PDF of a report.

Finally, a macro program (collection_pdfs) iterates through every collection in the collections macro variable and passes the value to the pdfs macro to create a PDF for every collection.

collection_pdfs Macro Program - Creating PDF for each collection

Note: The full SAS program is attached to this article.

Pro Tip! The %QSCAN and %NRBQUOTE functions are used to mask any special characters that may appear in collection names. For example, some collections contain single quotes (Child’s Play Collection), some contain commas (Silent Night, Deadly Night Collection) and some contain ampersands (Shake, Rattle & Roll Collection).

When the program runs, a pdf is created for each collection that meet my specified criteria (collections originally created in English between 1983 and 2001) and is stored in location I specified (SAS Content/My Folder/Blogs/A is for APIs).

Folder containing PDFs of all collections

I can right-click and download a PDF that contains details about any collection.
A Nightmare on Elm Street PDF

If I need to run this program regularly, I can schedule the program. I love using the SAS Viya APIs to automate processes and generally make my life easier. In addition to getExportedReportPdf, I also love to use getExportedReportPackage to generate report packages on a schedule.

For more information about the SAS Viya APIs, check out these resources:
Using REST API to create and modify SAS Visual Analytics Reports
Exporting SAS Visual Analytics Reports to PDF Using REST APIs and Python