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.
SAS Viya contains the following categories of mapping:
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.
Source tables can be mapped to a different CAS Server, library, or table in the target environment.
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.
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.
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.
Although Viya 4 supports mapping files and mapping sets they are not fully supported in both of the available Content Migration interfaces.
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:
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.
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.
/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.
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.
Find more articles from SAS Global Enablement and Learning here.
Registration is open! SAS is returning to Vegas for an AI and analytics experience like no other! Whether you're an executive, manager, end user or SAS partner, SAS Innovate is designed for everyone on your team. Register for just $495 by 12/31/2023.
If you are interested in speaking, there is still time to submit a session idea. More details are posted on the website.
Data Literacy is for all, even absolute beginners. Jump on board with this free e-learning and boost your career prospects.