BookmarkSubscribeRSS Feed

Promotion from SAS Visual Analytics 7.x to 8.2

Started ‎01-30-2018 by
Modified ‎04-03-2018 by
Views 8,043

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.


1-Promotion high level overview1-Promotion high level overview

Just to recap, the promotion process is made of four steps:

  1. Export
  2. Download
  3. Upload
  4. 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, the output type, which you can type “text,” and whether or not you want to enable colored output. The profile was named “82.”


2-Command to create a profile2-Command to create a profile

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).


3-Command to renew the authentication token3-Command to renew the authentication tokenThe transfer CLI is an extension to the sas-admin command.  You can use it to the export, download, upload, and import steps, where applicable. Each step has additional arguments, as we will see later.




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).


04-Option to Export SAS Package in SAS Management Console04-Option to Export SAS Package in SAS Management Console

  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.


5-Exporting SPK package from SAS Management Console5-Exporting SPK package from SAS Management Console

6-Selecting dependencies when creating a package in SAS Management Console6-Selecting dependencies when creating a package in SAS Management Console


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.


7-Command to upload SPK file7-Command to upload SPK file


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.


8-Command to import package into SAS Visual Analytics 8.28-Command to import package into SAS Visual Analytics 8.2

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:

 9-Example of template mapping file9-Example of template mapping file

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:


10-Example of edited mapping file10-Example of edited mapping file

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>





Export package from SAS Management Console failed and it is not possible due to following error: "Property 'serviceUrl' is required"


Hi Peter,


That could be a lot of things, such as version incompatibility between SAS Management Console and SAS Metadata Server, issues with SSL certificates that were not added to the SASSecurityCertificateFramework, etc.


I recommend you contacting SAS Technical Support.




Hello @piotrkuzmiak,


that is a 9.4 specific question (not Viya), but I understand it is part of the process.

To complete @Renato_sas ' s answer, please let me share with you the answer to a similar question here:


Here you can find the details of his answer. The solution is to fix the certificates stored in your SAS Private Java Runtime certificate store, on the machine where you are running the SAS Management Console. Another option, interesting in Citrix environment because this change might take a while, is that an administrator might create the export for you from the SAS Management Console, in the server itself, which should contain the certificate correctly.





Hello @Renato_sas,


I tried this process in SAS VA 8.1 (not 8.2 yet), and the viya mapping file, created the target values with the full path, however and of course, the VA 8.2 expects only the name of the object, with quotes, exactly as you describe here. Hence, we had to change this mapping file, manually, which can be quite a tedious taks for most of the VA environment promotions to Viya, because the number of objects will be surely 20/50+.


Is this already fixed/handled in Viya 3.3 / VA 8.2 or do we need still to do the manual changes?

And if it is the second one: is there a tool to help us making that change? Is this fix in the roadmap and when is it planned to be released?


Thank you in advance!

Kind regards,


Hi @JuanS_OCS,


The promotion process to VA 8.2 is similar, but not exactly the same compared to VA 8.1. The mapping file for VA 8.2 does not require a full path. The example provided in the article is a functional mapping file for VA 8.2.




Hello @Renato_sas,


sorry, not sure to understand, because the previous 8.1 was also mandatory not to including full path, cause of having to edit the file afterwards. Hence, what is the difference exactly?




Hi @JuanS_OCS,


All I wanted to say is that this article was written for VA 8.2, and VA 8.1 is slightly different. VA 8.2 is a little better because it already provides the target table names for you and you have a default section that affects all the other entries. All you need to do is fill in the library and server information once. Mapping file for VA 8.2 is also different because it allows for Stored Process endpoint information to be added. Of course, the intent of future releases is to make the promotion experience even better. If this isn't what you are asking, please let me know.




Thank you JuanS_OCS for hints, I will pass them to our admins.

Renato - thank you very much , the steps mentioned were very simple. We did face an issue though; after creating a profile, we got an error during the upload. Changing the profile id to a character sequence instead of a number, seemed to solve this problem. I'm yet to try and replicate this issue, but just wondered if you had encountered this.




Hi @SundareshS,


No, I have never faced any problems like that. As you can see in my screenshots, I've actually named my profile 82 and it worked just fine. The documentation doesn't mention anything either.




Hi Renato,


Do you know if there is a tool being developed for promoting 

  • Users and groups
  • Access permissions


Hi @sid_3284. yes, the next VA release will have enhancements related to promotion and support for those items that you've asked among others.




Version history
Last update:
‎04-03-2018 10:14 AM
Updated by:


Available on demand!

Missed SAS Innovate Las Vegas? Watch all the action for free! View the keynotes, general sessions and 22 breakouts on demand.


Register now!

Free course: Data Literacy Essentials

Data Literacy is for all, even absolute beginners. Jump on board with this free e-learning  and boost your career prospects.

Get Started

Article Labels
Article Tags