Promotion from SAS Visual Analytics 7.x to 8.2
This is the second article of a series of three that talks about promoting content to VA 8.2. If you haven’t seen it yet, I recommend you reading the first one here, before continuing.
While the previous article gives an overview, this one expands the discussion and provides details about taking content from SAS Visual Analytics (VA) 7.1, 7.2, 7.3, and 7.4, and promoting it to VA 8.2.
The diagram below is where we left previously. It summarizes the entire promotion process, but we will be focusing on VA 7.x as a source.
Just to recap, the promotion process is made of four steps:
- Export
- Download
- Upload
- Import
Before we dig deeper in each one of them, let’s talk about the command line interface that is new in VA 8.x, and is used for most of the steps in the promotion process.
Command Line Interface
The command line interface is executed by running sas-admin and it is available in the VA 8.2 server (SAS Viya CAS Controller node - or wherever the microservices are deployed, to be more precise) in /opt/sas/viya/home/bin
Note: In the screenshots presented here I’m logged in the CAS Controller (microservices) node as root, but you don’t need root access.
The first thing you need to do is create a profile for your target VA 8.2 environment. You only need to do that once. You do that by issuing the command below:
sas-admin --profile <profile name> profile init
The option --profile is optional in all commands. If a profile name is not provided, a “default” profile name is used, or the name provided in the SAS_CLI_PROFILE environment variable.
It will prompt you for service endpoint (your VA 8.2 host, in this example, it’s http://XXXXXXXX.sas.com), the output type, which you can type “text,” and whether or not you want to enable colored output. The profile was named “82.”
Once you have the profile, you need to create an authentication token. Authentication tokens are good for up to 10 hours only, so this is a command that you may need to issue once a day, before you use the transfer CLI:
sas-admin --profile <profile name> auth login
You are going to be prompted for a userid and a password. The account provided must have admin privileges in VA environment indicated by the service endpoint (VA 8.2 in this case).
sas-admin --profile <profile name> transfer export ...
sas-admin --profile <profile name> transfer download ...
sas-admin --profile <profile name> transfer upload ...
sas-admin --profile <profile name> transfer import ...
Other useful commands are:
sas-admin --help
sas-admin profile --help
sas-admin transfer --help
sas-admin transfer [export|download|upload|import] --help
sas-admin profile list /* list all existing profiles */
sas-admin --profile <profile name> transfer list /* list all existing packages in that profile */
sas-admin --profile <profile name> transfer get-mapping --id <package id> -m <mapping file> /* generates a new mapping file for the provided package id */
Observe that many command line options have aliases, such as -f for --file, -m for --mapping, -s for --spk, etc.
Additional information about the command line interface and the transfer CLI can be found here:
SAS® Viya™ 3.3 Administration: Command-Line Interfaces
SAS® Viya™ 3.3 Administration: Promotion (Import and Export)
Now let’s cover the steps of the promotion process.
1. Export
For VA 7.x as source, we don’t use the transfer CLI to export, but instead, we use SAS Management Console (SMC) to navigate in the metadata folders and export the content to be promoted as a package (SPK file in this case).
The metadata objects you can select for promotion are:
- Visual Analytics reports
- Visual Analytics explorations
- Graph templates (custom graphs)
- Folders
Selecting folders and subfolders is a quick way to select a lot of content with just a few clicks, but only the objects above can be promoted. If your report has images or links to other reports, make sure you add them to the SPK file by selecting them in the Dependencies tab when exporting the package. As a reminder, SAS Stored Processes and tables cannot be promoted, so there is no reason to include them in the package.
2. Download
For VA 7.x and SPK files, there is not much to do in this step, except for making sure the SPK file is in a location that your VA 8.2 server (SAS Viya CAS Controller node - or microservices node) can access it. You might need to perform a file transfer with your preferred FTP tool or simply copy the file in a shared network location.
3. Upload
For this step, you need to use the transfer CLI, in the sas-admin command line. As explained before it’s assumed you have created a profile and have a valid authentication token for your target VA 8.2 environment.
sas-admin --profile <profile name> transfer upload -s <spk file> -m <mapping file>
This command takes the SPK file as the input and creates a package in a repository in the VA 8.2 server. If you are familiar with Docker container administration, you will notice that this repository isn’t very different from the repo that Docker uses to store and manage Docker images. Packages are referred by their ID. The output of the upload command displays the ID for the package just created, which you will need in the next step, the import.
The mapping file is optional, but highly recommended in this step. Providing the mapping file option will get the yml mapping file created for you. This file is pre-filled with a template of source tables identified in your SPK package, so you just need to inform where those tables are mapped to in the target VA 8.2 environment. This mapping file is required in the import step.
Observe that if you upload the same content multiple times, it will add multiple packages in the repository. Refer to the transfer CLI help file (sas-admin transfer --help) to know more about managing packages with transfer list, transfer delete and transfer show-contents.
4. Import
This is the last step in the promotion process, and the command line looks like this:
sas-admin --profile <profile name> transfer import --id <package id> -m <mapping file>
This command line takes the package ID and the mapping file as input and creates the content in the target VA 8.2 environment. The package ID was provided in the output of the previous command, but in case you don’t have access to it anymore, you can issue the transfer list command as explained before in the Command Line Interface section to retrieve the package ID.
If you issued the previous upload command with the --mapping option, you already have a template of a mapping file. If the package was uploaded by someone else or for some other reason you don’t have the mapping file anymore, you can generate a new one based on the package ID with the transfer get-mapping command, as explained in the Command Line Interface section. Before executing the transfer import command, you must fill in the mapping file template with required information. The mapping file is discussed in the section below.
To avoid naming conflict, all VA 7.x explorations will have “(Exploration)” added to their names. This is because VA 7.x allows you to have a report and an exploration with exactly the same names in the same folder, but VA 8.x doesn’t differentiate between reports and explorations (they all become reports after promotion).
Content is placed in the same folder structure as the source environment. If you import the same package multiple times or a package which content is already imported, the content will be replaced.
Don’t Forget the Mapping File
Mapping file is where you inform source table mapping from the source to the target environment (VA 7.x to 8.2 in this particular case). As seen before, a template is generated for you and all you need to do is provide additional required information and/or make changes where needed.
The following is a template of a mapping file that contains three source tables:
The syntax of the target attribute is the following:
<table name> , <library name> , <CAS server name> , <language>
Except for <language>, which is optional and defaults to English, all other three values must be informed. If a value is not informed for a particular table, the corresponding value from the default section (source: default) is used.
Observe that the table names were already provided, assuming they will have the same name in VA 8.2 environment. If that’s not the case, you must change them. In the example above, if all of the tables are loaded in a library called “PromotionData”, under the “cas-shared-default” CAS server, you can add that information in the target attribute for each of the three tables, or you can simply add that information in the target attribute for the default source (source: default), like this:
target: “, <library name> , <CAS server name>”
It starts with a comma to indicate that the table name varies and should be obtained from target attributes that follow below. This is how the edited mapping file would look:
Stored Processes are not promoted to VA 8.2. If you have content that contains Stored Processes, you can add its SAS 9 base URL in the options section of the mapping file, like in the example above (the port number 9999 is just a placeholder). By doing that, reports promoted to VA 8.2 will point to Stored Processes in their SAS 9.4 source environment, where the Stored Processes are executed. You will also need to add a whitelist entry for the SAS Viya host machine (VA 8.2) into the SAS 9.4 system where the Stored Process is running. To know more about this and how to obtain the Stored Process URL for your environment, please, refer to Modifying the Whitelist for URLs and HTTP Request Methods.
Mapping files can be reused and don’t necessarily need to go one-on-one with the package that generated them. For instance, you could have one single mapping file that describes all the tables you have, and use that mapping file to import any package.
Mapping files used to promote content from VA 8.x to VA 8.2 have some minor differences, so be aware. We will explain that in the next article of this series.
Quick Reference
/* getting content from 7.x */
SMC: export package as spk file
Copy spk file to location accessible by SAS Viya (shared network, ftp, etc.)
/* adding content to 8.2: commands executed in VA 8.2 CAS controller (microservices) node */
sas-admin --profile <target82> profile init /* only once */
sas-admin --profile <target82> auth login /* good for up to 10 hours, needs admin access to 8.2 */
sas-admin --profile <target82> transfer upload -s <spk file> -m <mapping file>
sas-admin --profile <target82> transfer import -m <mapping file> --id <package id>
Don't miss out on SAS Innovate - Register now for the FREE Livestream!
Can't make it to Vegas? No problem! Watch our general sessions LIVE or on-demand starting April 17th. Hear from SAS execs, best-selling author Adam Grant, Hot Ones host Sean Evans, top tech journalist Kara Swisher, AI expert Cassie Kozyrkov, and the mind-blowing dance crew iLuminate! Plus, get access to over 20 breakout sessions.
