SAS Visual Analytics: Saving and applying report states using REST API

[#1]

By default, SAS Visual Analytics maintains the state of each user's report (or the most recent view of a report) across sessions. The first time a report viewer opens a report, they see it in the state the report was saved. Then, suppose the report viewer changes prompt values and drills into a hierarchy. The next time that user views the same report, SAS Visual Analytics displays the report with the prompt values and drill state from the previous session (unless report state has been disabled).

The report state contains:

• Prompt values
• Drill-down
• Selections in objects
• Interactions between objects
• Sorts
• Filter applied by the report viewer
• Ranks applied by the report viewer
• Display Rules applied by the report viewer
• Data Roles assigned by the report viewer
• Options modified by the report viewer

Suppose you have a dashboard that displays comprehensive data about a company's operations. You are responsible for different parts of the business and find yourself always selecting the same interactive filters, drill-downs and sorts. You might be interested in saving each report state, so you can easily reapply it later. In this post, we will learn how to use REST API, specifically the Reports API, to do exactly this.

The Code

You can find the full code on my GitHub.

Key Concepts

The documentation for the Reports API can be found here. For an introduction to REST API, ETags, and how to read the documentation, read this post.

We need to understand the following key points:

1. When a report viewer opens the report for the first time, they will see the report in the state a report editor left it in. Subsequently, unless report state is disabled, the report viewer will see the report in the state they last left it in. Other report viewers will see the report in the state they left it in. They can revert to the original state by restoring the default report state. A user cannot directly manipulate the report states of another user.
2. A report can have only one primary state. The primary report state is the state that is currently active. In other words, it is the report state that you see if you open the report in view mode. When we modify the report state, for example by drilling down in an object in the Visual Analytics user interface, this overwrites the primary report state. Using the reports API, we can create multiple report states, as long as only one state is set as primary. If we delete the primary report state and open the report, it opens in the state the author last left it in.
3. Conversely, if you just edited the report and haven't viewed it since, there will be no primary report state. We need to handle this case in the code.
4. If you only make selections to prompt values in either the report or page prompt areas, your selections might not be immediately captured in the primary report state. You must click on an element in the report canvas for the report state save to be triggered.
5. When you create a report state using the reports API, it is just an empty shell. You need to save a report state's content into it. For example, you can save the primary report state content (the report state that is currently visible) to reapply it later. Similarly, when applying a report state, we need to create a new report state, upload some report state content into it, and then make it primary so it is visible in the UI.
6. A report and each of its states have different ETags. The report also returns the reportModified. We need to supply these for non-GET requests. This is to avoid mid-air collisions, where different clients try to modify a resource at the same time, potentially corrupting it.

Overview of the Code

To save the report state, we perform the following steps:

1. Get the ETag and modified timestamp of the report
2. Get the state ID of the primary state. If no primary report state exists, we need to create it. To create a state, we need the modified timestamp of the report.
3. Get the ETag of the primary state
4. Save the report state content.

To apply the report state later, we need to:

1. Get the ETag and modified timestamp of the report
2. Get the primary state ID. If no primary report state exists, we need to create it. To create a state, we need the modified timestamp of the report.
3. Get the ETag of the primary state
4. Make the primary state secondary
5. Create a new report state. For this, you will need to modified timestamp of the report.
6. Get the ETag of the new report state
7. Put the saved state content into the new report state. Here, we need to supply the ETag of the primary state in the request header to avoid a mid-air collision.
8. Make the new report state primary

Trying it out yourself

Open any report in view mode (for example Warranty Analysis from SAS Content/Products/SAS Visual Analytics/Samples) and change the report state by selecting prompt values, adding labels, changing object types and sorts:

Select any image to see a larger version.
Mobile users: To view the images, select the "Full" version at the bottom of the page.

Note that if the report author gave you viewer capabilities, you can also change data item assignments, filters, ranks and display rules. The next step is to get the report ID. To find the report ID, you can click on the Report Menu, Copy embeddable markup and copy the part of the reportUri after the last forward slash:

Next, in SAS Studio, open a new SAS program and paste the code from the repository (see above) to save the state. Change the value for the report ID (line 1) and the location to save the report state (line 4). You may click on SAS Server on the left pane and find a folder in which you want to save the report state, and right-click on it to insert the path into the program. Ensure you add a filename at the end:

Run the code. If you get a 401 HTTP response running the code, just reset the SAS session and try again. You know that the run is successful by checking the log and checking whether the report state file has been saved:

Note, you can open and view the file - the details on the report state are usually at the very end. Then, return to SAS Visual Analytics and change the report state in some way - this is just so we can have a different state before we reapply the saved state. Then, return to SAS Studio and repeat the abovementioned steps with the code to apply a report state. Here, you can also give a label to the new state on line 2:

Run the code and check the return codes in the log - they should be 200, 201 or 204 (see screenshot):

 Lastly, return to Visual Analytics and reopen the page with the report:

You should see the state reapplied:

Conclusion

In this post, you have access to the code (see above) needed to use the reports API to save and then apply a report state. In the next post, we will integrate this code into a SAS® Viya Job, with which a report viewer can do this without interacting with the code.

Find more articles from SAS Global Enablement and Learning here.