Migrating Model Studio Projects between Environments: changing ownership

[#1]

A SAS Model Studio project is a top-level container for analytic work in Model Studio. A Model Studio project contains the data source, the pipelines, and related project metadata (such as project type, project creator, share list, and last update history). SAS Model Studio projects are, by default, saved in Viya Content to the user’s “My Folder”. Content Migration of Viya Model Studio Projects has been troublesome in some cases because of the strict prerequisites. Now we have improved functionality that makes life easier. In this post, I will examine these improvements.

Firstly, what are the prerequisites? To import a Model Studio Project:

• The user who owns the project must exist and must have logged on in the target environment​​
• Before import, data must be available and loaded into the memory in the target environment (in the same caslib as in the source environment).
• A user-created pipeline or node template must be promoted separately.

For more details on these items see the documentation here.

These prerequisites, particularly the requirement that the user that owns the project must already exist and have logged in, have at times made it challenging to migrate Model Studio projects.  This requirement makes it difficult to migrate Model Studio Projects when the source owner:

• is no longer at the organization.
• doesn’t have authorization to the target.
• is a different user in the target.
• is the same in the target, but the user ID is managed differently. For example, on the development server, the id is dev_user1 and on the test server, the id is test_user1.

One solution to the problem is to change the ownership of a Model Studio Project to a user who does exist and has logged on to the target environment. In the past, there was no supported way to change ownership of a project. New functionality in the transfer plugin of the sas-viya CLI now allows an administrator to change the ownership of Model Studio Projects and other content types prior to import.

New functionality in sas-viya transfer

There are two methods to migrate Model Studio projects between environments you can export using:

• The transfer service using SAS Environment Manager or the sas-viya CLI, this creates a transfer package (JSON file)​
• SAS Model Studio creates a ZIP file containing one JSON transfer file per project

The new method of changing ownership works with the transfer method of migrating. The process works like this:

• Use the transfer plug-ins list-owners command to generate an "owners list" JSON file from the transfer package
• Modify the generated file to map the old owner to a new owner
• Use the transfer plug-in replace-owners command and the edited "owners list" file's content to create a new transfer package file with the ownership of the content in the package changed.

NOTE: to be clear the ownership of the object is changed in the transfer package not in the source system.

Changing Ownership of Model Studio Projects for Import to Viya

Let’s look at the process in detail using an example. In this example, Sarah has some Model Studio projects in one Viya environment and she needs to share them with a different user in another environment.

She starts by using SAS Environment Manager to export a transfer package and shares that transfer package with the other user GEL Administrator (geladm).

Review the Transfer Package

Firstly, let’s review the content of the provided transfer package.

packageid=$(/opt/sas/viya/home/bin/sas-viya --output json transfer upload --file /tmp/viyapackages/SarahMyFolder.json | jq | jq -r '.["id"]')
echo "View the package with id" $packageid
sas-viya --output text transfer show --details --id $packageid

The output shows that the package contains the folder path to Sarah’s “My Folder” and the content of the folder which consists of the Model Studio Project and supporting resources.

Generate the  "owners list" file

The first step is to generate the "owners list" file from the transfer package. To do that we can use the new “list-owners” command pass it the transfer package file and output the results to an owners list file. The owner's list file is in JSON format and contains a map of the existing owner(sourceUserID) to a potential new owner(targetUSERID). The source and target are initially the same.

sas-viya transfer list-owners --source-file  "/mnt/workshop_files/SarahModelStudio/SarahMyFolder.json" --owners-list-file /tmp/theowners.json

[
 {
  "sourceUserID": "Sarah",
  "targetUserID": "Sarah"
 },
 {
  "sourceUserID": "anonymousUser",
  "targetUserID": "anonymousUser"
 }
]

 

Update the "owners list" file and change ownership

To change the ownership of objects in this package edit the file and change the targetUserID to the user in the target system who you want to own the content.

[
 {
  "sourceUserID": "Sarah",
  "targetUserID": "geladm"
 },
 {
  "sourceUserID": "anonymousUser",
  "targetUserID": "anonymousUser"
 }
]

Using the updated file create a new transfer package with the ownership changed from the user Sarah to the user geladm. Pass to the transfer replace-owners command:

• --source-file the source transfer package
• --owners-list-file the update owners list file
• --target-file a file to store the updated transfer package

sas-viya transfer replace-owners --source-file /mnt/workshop_files/SarahModelStudio/SarahMyFolder.json --owners-list-file /tmp/theowner-geladm.json --target-file /tmp/geladm-modelstudio.json

Notice the output indicates that the ownership in the package has been changed based on the content of the file. Simple as that. Of course, to truly test if this works we need to import the package.

Import the new transfer package file

In SAS Environment Manager import the package (you could also use the CLI). When we open the package in the Environment Manager import interface notice that the content will be imported to the user geladm’s personal folder. This is the first clue that we have successfully changed the ownership of the content.

After walking through the import wizard the summary screen shows the content, including the Model Studio projects was imported successfully into the My Folder area of the geladm user.

In the Content Area of SAS Environment Manager, we can see the content, originally owned by Sarah in the source environment is now owned by geladm and is located in geladm's "My Folder".

Wrap Up

When migrating Model Studio projects there are specific prerequisites required to ensure a successful migration. One of those requirements is that the user that owns the project must already exist and have logged in to the target system. This has at times made it challenging to migrate Model Studio projects. One solution to the problem is to change the ownership of a Model Studio Project to a user who does exist and has logged on to the target environment. New functionality in the transfer plugin of the sas-viya CLI now allows an administrator to change the ownership of Model Studio Projects and other content types prior to import.

For more information:

Content Migration Considerations for SAS Visual Data Mining and Machine Learning

Machine Learning Users Guide: Importing and Exporting Projects