SAS Visual Analytics Report States

1 Like

The State of a report describes the view of a report across sessions. As the report creator you define what the default of a report will be for everyone that opens it up - so make sure that your final save in the editing mode as all of the filters set to the appropriate values and drills states are set as expected. This final state is also known as the Default State of a report, as it is a default if a user opens up the report for the first time.

But as your users use the report they might change the filters and selections as they use it and when they close the report a user specific state for that report is created. This new user specific state will enable the user to pick up from where they left off last time. Note this doesn't change the report itself or the state for any other user, so this is something that happens in the Viewing mode of the report.

If a user wants to go back to the Default State, they can use the report level kebab menu (1) and then select Restore default report state (2) - note we are in the viewing mode of the report:

That every user can pick off of where they last were is a great default and very helpful to a lot of users. But you might disagree in general or for a specific report it doesn't really make sense. So can we change this default behavior? Of course we can.

Let us first talk where this default is set, before we take a look at how to change it:

This rule /reports/reports/*/state (3) grants the right to all Authenticated Users (so not Guests) to Create a report state.

What we want to do

We want to change this default behavior in two scenarios:

We want to set the default to be prohibited instead of granted
We want to deny the ability to create report states for a specific report

Now before we get into this there are two things to keep in mind:

Users of the SAS Administrator group will not be impacted by this change, but will always be able to create a report state, as long as they clicked Yes when prompted to assume membership of the SAS Administrators group at login
If a user has previously created a report state they will still load this report state, it will be overwritten once the report creator makes a change to the underlying report

In order to change or create rules there are three main ways of doing it. The first way is by using SAS Environment Manager, which enables us to do this in a visual way by hand, this is great as an introduction to understand the different components and how they relate to each other. The second way is to use the SAS Viya CLI, this is a great way to make use of if you are mass creating rules, changing them in batch or want to document everything. The third and final way are the SAS Viya APIs, these give you the highest degree of flexibility in my opinion, but also require you to write code.

We will be taking a look at all three ways here in order. If you are unfamiliar with how rules work in general within SAS Viya, please read the SAS Environment Manager section, even with you are more interested in an automated way, as I will explain key concepts only there and not repeat them in the other two.

Note: As changing the default behavior for everybody is a one time job we will only be covering it in the section on the SAS Environment Manager.

Doing it with the SAS Environment Manager

Open up SAS Environment Manager, click on the Rules (1) page, enter /reports/reports/\*/state in the search field (2) & press enter, then select the Conditional Grant row (3) and click on the edit icon (4):

This opens up the Edit Rule dialogue, let us first take a look at it and then discuss all the different elements afterwards:

The Object URI is the unique identifier of a piece of content inside of SAS Content. Here you can not only enter a specific URI, but also a URI pattern using an asterixis (*) as a wildcard
The Container URI is similar to the Object URI, but it can only be a folder. A rule that is applied to a folder will apply to the folder and all of its members (including subfolders) - Optional
The Principal type specifies to whom the rule should be applied. There is five types, lets look at them from the most general to the most specific:
1. Everyone, this means exactly that, everyone with some sort of access to the SAS environment (think of it as Guest + Authenticated Users)
2. Guest, provides access to content of the SAS environment without the need to login - in the screenshot below we see part of the SAS Logon Manager interface where when you click the button Guest (2) you would be signed in as a guest
3. Authenticated Users, this covers everybody that has a SAS user account and is authenticated - in the screenshot below this would happen once you click on the Sign in button (1)
4. Group, this applies the rule to all members of this group, both Groups and Custom groups can be used here
5. User, finally the most granular level is to apply a rule a specific user - as this generates a lot of implementation work it is best to create rules here only if unavoidable
The Rule type specifies if this rule Grants some permission or Prohibits it. If you select Prohibit a warning dialogue will pop up with the following message: "A Prohibit rule blocks all access within its scope, even if a more specific Grant rule exists. Are you sure you want to select Prohibit as the rule type?" - so only use Prohibit if it is unavoidable, usually it is better to use more specific Grant rules instead
The Condition limits the applicability of the rule, i.e. the rule is only applied if the expression evaluates to true. These conditions are written in the Spring Expression Language (SpEL) and if you want to dive deeper into this topic check out this page in the SAS documentation - Optional
The Permissions specify what the rule grants/prohibits. There are seven permissions: Read, Delete, Add, Create, Remove, Secure & Update
The Description is meant to help communicate what this rule is for - Optional
The Reason is information that is displayed to the user for diagnostic purposes, if they are denied - Optional
The Rule status specifies if a rule is active or not
You can save any changes made using the Save button

Now if we want to change it generally you would have to change the Rule type from Grant to Prohibit.

Ok but now let's talk about the second scenario, where we want to change the report state behavior of a specific report for a specific group of users and for that we will be creating a new rule:

Click on the New icon
In the New Rule dialogue click on the folder icon

Navigate to the report for which you want to create the rule
Click OK

5. Now the current Object URI is /reports/reports/811c3000-d999-4163-b1ec-f976b4e756d7/** which we do not want, as this would change the definition of all the different aspects on the usage of this report so will have to modify it to read /reports/reports/811c3000-d999-4163-b1ec-f976b4e756d7/state

6. Going ahead you can see I changed the Principal type to Group
7. Selected the target group fkt_analyst using the person icon
8. Set the Rule type to Prohibit
9. As the Permissions only select Create, as we want to remove the ability for users to create a report state
10. Add a description to review later on - note I omitted the Reason as there is no failure message to users, that no report state is created
11. Finally click Save

Now when you open up the report as a user of that group change the filters or drill hierarchy, close the report and reopen it the state will remain as the default report state. But if you are a user that isn't part of that group, or has assumed the SAS Administrators group, you will still be able to create a report state.

Doing it with the SAS Viya CLI

If you are unfamiliar with the SAS Viya CLI, I recommend you check out this excellent tutorial on the SAS Users YouTube channel - watch until 7:02.

For the CLI we will be looking at two ways of doing it:

Creating a single rule at a time
Creating a single rule but from a file to showcase how you could create many rules at once

The assumption for the following is that you are logged in with the SAS Viya CLI and you have the Authorization plugin installed - more about this specific plugin in the SAS Documentation. It is also assumed that you have already retrieved the reports URI and know the group name to which we will be applying to rule to.

We are going to create a prohibit rule and pass it the report URI, the group name (to be very percise use the group ID, this can be the same as the group name but it can also differ, e.g. group name: SAS Administrators vs. group id: SASAdministrators), the create permission and a description:

sas-viya authorization prohibit \
	--object-uri /reports/reports/811c3000-d999-4163-b1ec-f976b4e756d7/state \
	--group fkt_analyst \
	--permissions create \
	--description "Prohibits the report state creation for the report Release-Notes"

Here is the result of running this command - note that the id here represents the rule id which you can than use via viya-host/authorization/rules/rule-id:

{
    "acceptItemType": "",
    "acceptType": "",
    "contentType": "",
    "createdBy": "gerdaw",
    "creationTimestamp": "2024-06-07T16:01:11.809Z",
    "description": "Prohibits the report state creation for the report Release-Notes",
    "enabled": true,
    "id": "6a5c2f02-3ea0-499c-acb1-cf5976e5fc6c",
    "mediaType": "",
    "modifiedBy": "gerdaw",
    "modifiedTimestamp": "2024-06-07T16:01:11.809Z",
    "objectUri": "/reports/reports/811c3000-d999-4163-b1ec-f976b4e756d7/state",
    "permissions": [
        "create"
    ],
    "principal": "fkt_analyst",
    "principalType": "group",
    "reason": "",
    "type": "prohibit",
    "version": 10
}

You can delete this rule using the following command:

# The id shown below can be retrieved from the output above
sas-viya authorization remove-rule \
	--id 6a5c2f02-3ea0-499c-acb1-cf5976e5fc6c

You can of course also mass add rules using a file - here it is demonstrated with just one and the file that it is stored in is called Report-State-Rule.json:

[
   {
    "op": "add",
    "value": {
      "description": "Prohibits the report state creation for the report Release-Notes",
      "objectUri": "/reports/reports/811c3000-d999-4163-b1ec-f976b4e756d7/state",
      "permissions": [
        "Create"
      ],
      "principalType": "group",
      "principal": "fkt_analyst",
      "type": "prohibit"
      }
   }
]

Command to create the rule:

.\sas-viya.exe authorization create-rules \
	--file ./Report-State-Rule.json

This returns the following output: "1 rules were created."

Doing it with the SAS Viya APIs

Using the SAS Viya APIs you can of course call them from many different programming languages. Here I will be demonstrating how to do it using proc http in SAS Studio, this has the advantage of leveraging the build in authentication. But if you are interested in other languages check out the SAS Documentation.

It is also assumed that you have already retrieved the reports URI and know the group name (to be very percise use the group ID, this can be the same as the group name but it can also differ, e.g. group name: SAS Administrators vs. group id: SASAdministrators) to which we will be applying to rule to. Let's get started:

* Get the Viya Host URL;
%let viyaHost=%sysfunc(getoption(SERVICESBASEURL)); 

filename in temp;

* Create the rule JSON - you could of course also store the file on disk/SAS Content;
data _null_;
	file in;
	put '{';
	put '"type": "prohibit",';
	put '"permissions": ["create"],';
	put '"principal": "fkt_analyst",';
	put '"principalType": "group",';
	put '"objectUri": "/reports/reports/811c3000-d999-4163-b1ec-f976b4e756d7/state"';
	put '}';
run;

filename out temp;

* For more information on this API endpoint please check out - https://developers.sas.com/rest-apis/authorization-v8?operation=createRule;
proc http url = "&viyaHost./authorization/rules"
	method = 'Post'
	out = out
	in = in
	oauth_bearer = sas_services;
	headers 'Accept' = 'application/json';
	headers 'Content-Type' = 'application/json';
run;

libname out json;

title "The new rule was created succesfully - &SYS_PROCHTTP_STATUS_CODE. - &SYS_PROCHTTP_STATUS_PHRASE.";
title2 'Navigate to the URI below to find out more';
proc print data = out.links(where=(method='GET') keep=method uri) noobs;
quit;
title;

* Clean up;
filename in clear;
libname out clear;
filename out clear;
%symdel viyaHost;

The result should look like this:

Supplemental

The information in this post are based on the following SAS Support Note.

To learn more about the *Rules* page in SAS Environment Manager check out the SAS Documentation.