In a previous post, I looked at promotion from SAS 9.4 to Viya. In this post, I will look at promotion within SAS Viya. I will look at what can be promoted, the tools that support promotion, and some details about how the process works and what happens to your content. If you are used to promotion using the import export wizards in SAS 9.4, I will point out some of the current differences in promotion within Viya.
Firstly, you must be an Administrator in Viya to be able to export and import content. This is currently (as of Viya 3.4) something that cannot be changed. The two main tools you can use for promoting content between Viya Environments are SAS Environment Manager import/export wizards and the sas-admin command-line interface.
For a lot of Viya content, promotion is supported using the transfer plug-in of the sas-admin command-line interface. The transfer plug-in and SAS Environment Manager both use the transfer service under the covers. This post will focus on the content supported by the transfer service. The list of Viya content supported by the transfer service has increased with each Viya release. The table below shows the supported resources for export by Viya release.
When performing an export/import, the transfer service coordinates the export process and the creation of the package. However, it calls other related services which deal with their specific content. For example, services related to Visual Analytics will deal with reports, and Model Manager with models, etc.
The result of the export process is a Viya promotion package, which is a json file containing a collection of transfer objects describing the content that has been exported. The transfer service's package will include the objects you select for export and the following related platform objects:
There is no mechanism in Viya, like there was in 9.4, to automatically include all dependent objects in a package. To see what is included in a package, let's look at an example. In this example, we will use a Visual Analytics report, but this could apply to any supported content type.
The report “Sales Correlation” is in the folder /gelcontent/GELCorp/Sales/Reports.
In scenario 1, if we select the report and export it, the package will contain the report and the folders that are included in its path /gelcontent/GELCorp/Sales/Reports. What about authorization settings? Currently, the two interfaces behave slightly differently. The transfer plug-in will always include authorization settings in the package. However, exporting from SAS Environment manager does not include authorization settings. In terms of what authorization is included, directly set authorization are included for objects that are explicitly included in the package. In the export example above, that means we would only get any authorization rules applied directly to the report. To include authorization rules for a folder, we would need to select the folder or one of its parent folders for export.
In scenario 2, if we select the GELCORP folder and do an export, we will get all sub-folders and content below that folder, including any authorization rules applied directly to those objects. In Viya 3.4, you cannot export the complete folder tree. There is no way in the cli or environment manager to select the root of the folder tree. To export the complete folder tree, you need to export each root folder separately. A tool (exportfoldertree.py) has been added to the pyviyatools that can help with this issue. It will loop the folders and export each root folder to a package in a directory.
Viya content is uniquely identified by its Uniform Resource Identifier (URI). When importing to Viya, objects in the package are matched to objects in the target based on the URI. When matching on URI during an import, if:
- no match occurs, then a new object is created.
- a match does occur, then the object is overwritten.
The match on URI is an important concept. It can have some results that you might not expect if you don’t understand it. For example, if a report is renamed, a subsequent import may rename the report back based on the name of the report in the package.
In the example below, a report, identified by the uri /reports/reports/c99s5a2-ccb-4552-b1a5-d8b0e3cb1afo, has been moved to a different folder than the same report in the package being imported.
You might expect in this scenario that a new report will be created in the original folder that the report was moved from. However, since the import matches on URI, the location in the folder structure is not relevant. The report is not added to the folder location stored in the package but is overwritten in its new location. The import process will issue a clear warning that this has happened.
How is authorization dealt with during import? In general, when importing a resource that already exists in the target environment, the authorization settings will be merged with the target resource authorization. During the merge, if the rule (by URI of the rule):
- already exists, then it may be updated.
- does not exist, then a rule may be created.
Authorization is not synched during an import, it is a merge. A rule will never be deleted during an import.
Finally, there is some functionality during import that you may be used to in SAS 9.4 that is not available in Viya yet. When importing a package to Viya you cannot:
- Subset the content from the package during import.
- Specify a new location in the target folder tree for imported objects.
I hope this helps you gain a better understanding of the features of promotion within SAS Viya and how they work. Here are some related resources that may also help:
- SAS® Viya® 3.4 Administration: Promotion (Import and Export)
- SAS Viya 3.4 Promotion Workshop
- Promotion of Viya Resources that are not stored in folders
- Promoting caslibs between Viya environments
- Saving and reloading Viya Configuration
- Creating Viya authorization from 9.4 metadata
- New functionality for transitioning from Visual Analytics on 9.4 to Viya
Thanks for you blow. In it I read that imported objects in the package are matched to objects in the target based on the URI.
I see something different in the below. These are my (simplified) steps:
1. I import report /Projects/Report1 from a json package file from another Viya environment; the report has URI /reports/reports/1. The report is now stored at /Projects/Report1 with URI /reports/reports/1.
2. I delete report /Projects/Report1. The report with URI /reports/reports/1 is now located in the Recycle Bin,
3. I import report /Projects/Report1 again from the json package file; the report in the recycle bin is updated, that is expected from your blog as it is matched on the URI.
4. I create a new report and save it as /Projects/Report1; the report gets URI /reports/reports/2. So now there are two instances of Report1:
1) /Recycle Bin/Report1 with URI /reports/reports1
2) /Projects/Report1 with URI /reports/reports/2
5. I import report /Projects/Report1 again from the json package file; the existing report /Projects/Report1 with URI /reports/reports/2 is overwritten by the imported report. I had expected /Recycle Bin/Report1 to be overwritten as that report has the same URI as the report in the json package file. Instead it now seems to match by path and name.
Can you explain what I am missing?
I did a quick test in Viya 3.5 and I saw exactly what you are seeing. I also just tried moving Report1 to a different folder and reimporting it and it did create a new report in the original location. Something may have changed since I wrote the blog. I need to do some more testing but I still see the old behavior for folders and some other content.
Thanks for pointing this out.
@Gerry Nelson, Good morning, I need to know how, using SAS VIYA rules, I can limit or prohibit the export data option on a VA 8.3 dashboard. Thank you
The endpoints and their meaning are documented in the Admin Guide:
I believe it is one or both of these:
Export data from reports.
Export detail data from reports.