Mapping SAS Viya Resources during Content Migration

2 Likes

Content Migration is the process of moving content from one environment to another environment. Typically the process happens in two steps, in the export step you export resources from the source environment to a package file, and in the import step, you import content from the package to the target environment. Mapping is a key aspect of the content migration process. During import, mappings determine how resources are transformed. In this post, I will look at how to create and manage mappings in SAS Viya.

First lets' take a closer look at mappings. Mappings allow the user to map resources in a package like servers, libraries, caslibs, and tables to their matching resource in the target environment. For example, suppose that you are migrating a Base library from SAS 9.4, and you need to specify a different directory path for SAS Viya. This is something you would use a mapping to accomplish.

Categories of Mapping

SAS Viya contains the following categories of mapping:

Users and Groups

Users and Groups from the source environment can be mapped to target Users and Groups. User and Group mapping are used to help preserve group memberships and convert authorizations for imported content.

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

Tables

Source tables can be mapped to a different CAS Server, library, or table in the target environment.

Data Resources

Data Resources (labeled "Properties" in earlier releases) allow you to specify a different value for a resource. For example, for a library, if the path to a directory is different you can specify a different target value so that the resource functions correctly in the target environment. Libraries can also be mapped to Compute Servers and Contexts and to CAS Servers.

Other

Any other resources in the mapping set are listed by name, source, and target. You can enter or select a different target value so that the resource functions properly in the target environment.

Mapping Viya 3.x and Viya 4

In Viya 3.x mappings were stored and maintained in mapping files. A mapping file is in either JSON or YAML format and can be managed and maintained using your favorite text editor. When importing content in Viya 3.x mapping files could be used in both the Import Wizard in SAS Environment Manager and the transfer plugin of the sas-admin CLI. In Viya 4 mapping files are still available, however new to Viya 4 are mapping sets. Mapping sets serve the same role as mapping files. However, they are stored in the SAS Infrastructure Data Server and managed and maintained in the SAS Environment Manager Viya user interface.

Mapping Files v Mapping Sets

Although Viya 4 supports mapping files and mapping sets they are not fully supported in both of the available Content Migration interfaces.

The transfer plugin of the sas-viya CLI can use JSON mapping files but NOT mapping sets.
SAS Environment Manager can only use mapping sets during the import process. However, you can create or add to a mapping set by uploading a JSON mapping file.

A great feature of SAS Environment manager is an easy-to-use user interface for maintaining and managing mapping sets. As an administrator imports content from a package mappings can be accumulated and saved in either the system default mapping set or in any number of user-defined mappings sets. In addition, an administrator can maintain mapping sets out with the import process. The mapping set interface can:

Load and Save mapping sets from/to the SAS Infrastructure Data Server.
Upload mappings from a JSON File mapping file to create or add to a mapping set.
Edit, Merge, and Delete mapping sets.

SAS Environment Manager user provides a very convenient interface to build and maintain mappings. It is a lot easier than editing JSON or YAML files. However, the fact that the CLI does not use mapping sets and there is no way to create a mapping file from a mapping set causes problems for users who would like to take advantage of the UI to maintain their mappings, while at the same time automating the import of their content with the transfer plug-in of the sas-viya CLI. There are plans to fill this gap.

Until that occurs, we have added a new tool to the pyviyatools that will allow an administrator to create a JSON Mapping File from a Mapping Set. This will allow the administrator to manage mappings in the SAS Environment Manager User Interface and still automate import/export processing using the sas-viya CLI and downloaded mapping files. Let's look at how this works.

View existing Mappings

You can use the callrestapi tool from pyviyatools to view the existing mapping sets in the SAS Viya Infrastructure Data Server. In this case, only the system default mapping set is available.

/opt/pyviyatools/callrestapi.py -m get -e /transfer/mappings -o simple

Create a Mapping File from a Mapping Set

A new tool gettransfermapping.py allows an administrator to create a mapping file from a mapping set. The usage is very simple, pass the tool the name of the mapping set you wish to download and a directory location to store the mapping file. A mapping file with the same name as the mapping set is created in the directory.

gn_5mapping_set07.-1.png

/opt/pyviyatools/gettransfermapping.py -d /tmp/mymappings -n @systemMap

The resulting mapping file can be used with the transfer plugin of the sas-viya CLI. This allows the mapping set to be maintained in SAS Environment Manager and downloaded to the JSON file for use with the CLI.

Summary and more information

Mapping is a key aspect of the content migration process. During import, mappings determine how resources are transformed. In Viya 3.x mappings were stored and maintained in mapping files. In Viya 4 mapping files are still available, however new to Viya 4 are mapping sets. Mapping sets serve the same role as mapping files, however, they are stored in the SAS Infrastructure Data Server and managed and maintained in the SAS Environment Manager Viya user interface. The Environment Manager user interface provides an easy way to build and maintain mappings. The sas-viya cli cannot use mapping sets, however, the gettransfermapping.py pyviyatool allows the administrator to maintain mapping sets in SAS Environment Manager and when needed download a mapping set to a mapping file. For more information on Content Migration check out these related resources.

SAS Help Center: SAS Viya: Content Migration from SAS 9.4

SAS Help Center: Concepts: Mapping Sets

Managing SAS Viya Transfer Packages

Migrating SAS 9 Libraries to Viya Compute Libraries

Migration of Stored Processes to Jobs (update)

Content Assessment delivers utility applications to support SAS Viya Content Migration

Go with the flow; migrating Enterprise Guide Projects to SAS Studio Flows

A first look at Migration from SAS 9.4 to Viya 4

SAS Demo | SAS Viya Migration of Enterprise Guide Project to SAS Studio Flows

SAS Demo | Migration of SAS Stored Processes to SAS Viya Jobs

SAS Demo | SAS Viya Migration of SAS Data Integration Studio Jobs to SAS Studio Flows

SAS Demo | SAS Viya Content Migration Using the sas-viya CLI Transfer Plugin