Content promotion in Viya: overview and details

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

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.

Exporting

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:

Folders
Files
Rules
Comments

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.

Importing

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:

Content promotion in Viya: overview and details was published on SAS Users.