Promotion of SAS Viya resources that are not stored in folders

[#1]

Promotion is the process of moving resources from between environments. In SAS Viya promotion of content within folders like reports, data plans, or models is accomplished using the sas-admin transfer command-line interface, or the import and export wizards in the SAS Environment content area. There are some resources in SAS Viya that don't reside in folders which it may also be desirable to promote between environments.

In this post I will look at exporting and importing content that does not live in folders using the sas-admin transfer command-line interface (CLI) and SAS Environment Manager. In SAS Viya, a uniform resource identifier (URI) is used to identify unique resources. The transfer plug-in of the sas-admin cli has the flexibility to be able to export based on the URI of a resource in SAS Viya. In this post we will look at promoting custom groups and general authorization system rules.

In SAS Viya, most identities are read from an LDAP server. The exception is custom groups which are groups that exist in SAS Viya but not in the LDAP server. There are some default custom groups that come with the software, and administrators can also create their own custom groups. When would you want to promote custom groups? You may want to export and import custom groups when you have a dev/test/prod or multi-tenant scenario and you want to replicate your custom groups in a separate environment.

In the scenario used in that article, I have implemented a report developers group and I want to promote my group to production. The report developers group is a group created to support separating users into report viewers, who can only view reports in SAS Viya, and report developers, who can create reports in Visual Analytics. This setup is supported by a rule in the SAS Viya authorization system. The process of doing this is illustrated in that article.

Let's look at how we would promote this setup one environment to another. The screen shot below shows the report developers custom groups which contains three member custom groups.

Click any image to see a larger version.

In addition there is a rule that grants read access to the Visual Analytics application only to members of the Report Developers group. Since SAS Viya authorization has an implicit deny, this means that anyone who is not a member of the Report Developers group cannot build reports in Visual Analytics.

To export the groups and the rule we will need the URI of the resources we are exporting. The first step for custom groups is to get there "id" so that we can construct the URI. We could get this from SAS Environment Manager, or use the sas-admin identities command-line interfaces (CLI).

/opt/sas/viya/home/bin/sas-admin --output text identities list-groups

Similarly, we need the id of the general authorization system rule. In SAS Environment Manager we can get the id, by right-clicking on the rule and selecting properties. The id of the rule is the last item.

Following that we need to build a json file that will define what will be exported. The format of the json file can be found in the SAS Viya administration guide.

Here is the file we will use to export the rule and the custom groups. The items array contains the list of URI's of any resource supported by the transfer cli, e,g report, data plan, folder, rule. In the previous step we returned the id, which is the last element in the URI. The first part of the URI is the rest endpoint of the resource. If you don't know the REST endpoint you can find documentation on developer.sas.com.

{

"version": 1,
"name": "My custom groups",
"description": "Export Viya Custom groups and Rule",
"items": [
"/identities/groups/Finance Content Developers",
"/identities/groups/HR Content Developers",
"/identities/groups/Sales Content Developers",
"/identities/groups/ReportDevelopers" ,
"/authorization/rules/00b08a2f-847f-4c2a-98b5-e1711860d02d"
]
}

To perform the export, as a SAS Administrator, use the following command. You can pass the request as a string, or when you include the information in a file, the first character following the request option must be the at sign (@). Therefore, if a pathname is used, it must start with the at sign (@).

/opt/sas/viya/home/bin/sas-admin transfer export --request @/tmp/export_groups.json

The export package is created in the SAS Viya environment, to move it to your target environment download it, passing the id of the package to the download command.

/opt/sas/viya/home/bin/sas-admin transfer download --id 2916d2cb-14bd-4418-9aff-2d90feb4397e --file /tmp/package_groups.json

This creates a SAS Viya transfer package json file that can be imported to the another environment. You can open the JSON file and view the content. There should a JSON representation of each object in the package.

Copy the json file to the target environment. In the target environment you have two choices for import. You can import with the command-line interface or with SAS Environment Manager. Let's look at SAS Environment Manager first.

As a SAS Administrator in the Content Area select import and select the package. Walk through the wizard (there are no mappings) to import the resources. View the status of the import.

During import any custom group that did not exist in the target environment is created. If a custom group did exist it is not imported. Group membership is preserved as long as the the members of the group exist in the target environment as either LDAP identities or Custom groups.

The import of the rule behaves differently: If a rule with the same id exists the contents of the rule are updated, if no rule exists the rule is added.

The same import process can also be accomplished with the transfer command-line interface. Using the CLI there are a few more steps. However, you can script a work around for the inability to replace existing groups by deleting any custom groups that exist prior to the import. For example:

/opt/sas/viya/home/bin/sas-admin identities delete-group --id "ReportDevelopers"

To import with the CLI, upload the package to the target SAS Viya environment.

/opt/sas/viya/home/bin/sas-admin transfer upload --file /tmp/package_groups.json

After the upload do an import, passing the id of the uploaded package. The message should indicate that the 5 resources have been successfully imported.

/opt/sas/viya/home/bin/sas-admin transfer import --id <id>

For more information on Promotion and the transfer CLI, take a look at:

• SAS Viya Administration Guide: Transfer CLI
• SAS Viya Administration Guide: Promotion

Thanks for reading. I hope you will find this information valuable.

[touwen_k]

This is very good article, however I was wondering how to export data sources from caslibs between viya environments. I could not find much info about that. Is it possible to write a blog about that?

[GerryNelson]

Glad you found it useful. If you want to promote the definition of CASLIB's check out tis section in the documentation: Promote CASLIB's and Access Controls https://go.documentation.sas.com/?cdcId=calcdc&cdcVersion=3.5&docsetId=calpromotion&docsetTarget=n0u...

Does that help?

[touwen_k]

Hello Gerry,

Thank you for you reply. It is indeed helpful but my migration is not finished. I have done that what is written in the documentation and it migrated the definition of the library and the authorization. However I have in my old Viya in just one library 60 tables in data sources. How to migrate that?

Kind regards

[GerryNelson]

Understand. Yes, for the source data you have some choices. If the new Viya system can access that location and it is a format like csv or sas7bdat then you can still access the data from the existing location. If that is not good then you can copy the data to a new location and update the caslibs to point to that location. You can copy using OS commands, or with SAS provided tools such as PROC COPY or PROC DATASETS.