Using REST API to transform a Visual Analytics Report

This post was kindly contributed by SAS Users - go there to comment and to read the full post.

There are three types of visualization APIs defined in the SAS Viya REST API reference documetation: Reports, Report Images and Report Transforms. You may have seen the posts on how to use Reports and Report Images. In this post, I’m going to show you how to use the Report Transforms API. The scenario I am using changes the data source of a SAS Visual Analytics report and saves the transformed report.

Overview of the Report Transforms API

The Report Transforms API provides simple alterations to SAS Visual Analytics reports, and it uses the ‘application/vnd.sas.report.transform’ media type for the transformation (passed in the REST API call header). When part of a request, the transform performs editing or modifications to a report. If part of a response, the transform describes the operation performed on the report. Some typical transformations include:

Replace a data source of a report.
Change the theme of a report.
Translate labels in a report.
Generate an automatic visualization report of a specified data source and columns.

To use the Transforms API, we need to properly set the request body and some attributes for the transform. After the transform, the response contains the transformed report or a reference to the report.

Prepare the source report

This step is very straight-forward. In SAS Visual Analytics, create a report and save it to a folder (instructions on creating a report are found in this video). For this example, I’ll use the ‘HPS.CARS’ table as the data source and create a bar chart. I save the report with name ‘Report 1’ in ‘My Folder’. I’ll use this report as the original report in the transform.

Generate the request body

I will use PROC HTTP to call the Transforms API using the ‘POST’ method and appending the URL with ‘/reportTransforms/dataMappedReports‘. The call needs to set the request body.

Get the ReportURI: In an earlier post I outlined how to get the reportURI via REST API, so I won’t go into details. If you’d like an easy way, try this: in SAS Visual Analytics, choose ‘Copy Link…’item from the menu. In the pop-up dialog, expand the ‘Options’ and choose ‘Embedded Web Component’, and you see there is a string in the form reportUri=’/reports/reports/…’, that’s it. In the request body, we set the string to the ‘inputReportUri’ to specify the original report – the ‘Report 1’.

Report URI from SAS Visual Analytics

Decide on changes to the data source: Here I’d like to change the data source from ‘HPS.CARS’ to ‘CASUSER.CARS_NEW’. The new table uses three columns from ‘HPS.CARS’ as mapped below.

Select columns to include in new table

Specify the data sources in the request body: The request requires two data sources, ‘original’ and ‘replacement’, respectively, representing the data sources in original report and the transformed report. Note that the ‘namePattern’ value is used to enumerate the way of identifying the data source. If it is set to ‘uniqueName’, the data source is identified by its unique data item name in the XML file of the report. If it is set to ‘serverLibraryTable’, the data source is identified by the CAS Server, CAS Library and Table names together. The snippets below show the data source section in the request body. I like to use the ‘serverLibraryTable’ to specify the data source for both original and transformed report, which is clear and easy.

/* data source identification for original report */
  {
    "namePattern": "serverLibraryTable",
    "purpose": "original",
    "server": "cas-shared-default",
    "library": "HPS",
    "table": "CARS"
  }
 
/* data source identification for transformed report */
  {
    "namePattern": "serverLibraryTable",
    "purpose": "replacement",
    "server": "cas-shared-default",
    "library": "CASUSER",
    "table": "CARS_NEW",
    "replacementLabel": "NEW CARS",
    "dataItemReplacements": [
      {
        "originalColumn": "dte",
        "replacementColumn": "date"
      },
      {
        "originalColumn": "wght",
        "replacementColumn": "weight"
      },	
      {
        "originalColumn": "dest",
        "replacementColumn": "region"
      }
    ]
  }

Set more attributes for transform

Besides the request body, we need to set some other attributes for the transform API when changing the data source. These include ‘useSavedReport’, ‘saveResult’, ‘failOnDataSourceError’ and ‘validate’.

useSavedReport specifies whether to find the input (original) report as a permanent resource. Since I am using the saved report in the repository, I will set it to true.
saveResult specifies to save the transformed report permanently in the repository or not. I am going to save the transformed report in the repository, so I set it to true.
failOnDataSourceError specifies whether the transform continues if there is a data source failure. The default value is false, and I leave it as such.
The validate value decides if the transform will perform the XML schema validation or not. The default value is false, and I leave it is as such.

Decide on a target report and folder

I’ll save the transformed report with the name ‘Transformed Report 1’ in the same folder as the original ‘Report 1’. I set the ‘resultReportName’ to ‘Transformed Report 1’, and set the ‘resultReport’ with ‘name” and ‘description’ attributes. I also need to get the folderURI of the ‘My Folder’ directory. You may refer my previous post to see how to get the folderURI using REST APIs.

Below is the section of the settings for the target report and folder:

"resultReportName": "Transformed Report 1",
"resultParentFolderUri": "/folders/folders/cf981702-fb8f-4c6f-bef3-742dd898a69c",
"resultReport": {
			    "name": "Transformed Report 1",
			    "description": "TEST report transform"
			}

Perform the transform

Now, we have set all the necessary parameters for the transform and are ready to run the transform. I put my entire set of code on GitHub. Running the code creates the ‘Transformed Report 1’ report in ‘My Folder’, with the data source changing to CASUSER.CARS_NEW’, containing the three mapped columns.

Check the result

If the API failed to create the transformed report, the PROC SQL statements displays an error code and error message. For example, if the replacement data source is not valid, it returns errors similar to the following.

Invalid data source error message

If the API successfully creates the transformed report, “201 Created” is displayed in the log. You may find more info about the transformed report from the response body of tranFile from PROC HTTP. You can also log into the SAS Visual Analytics user interface to check the transformed report is opened successfully, and the data sources are changed as expected. Below is the screenshot of the original report and transformed report. You may have already noticed they use different data sources from data labels.