Promote a User or Group Permissions Tree

About Promoting a Permissions Tree

As an incremental alternative to promoting the entire Portal Application Tree, you can promote the Permissions Tree for a particular user or group. This is less comprehensive than promoting the entire Portal Application Tree, but it still offers the advantage of moving a complete content set. All supported content types that the specified user or group can access are promoted together, so you do not have to manage the dependencies and relationships among the promoted objects.
Before promoting a permissions tree, other types of portal content (for example, portal page templates, content objects, portlet instances, and portal pages) should be promoted first, Unlike promoting the entire Portal Application Tree, promoting a single Permissions Tree does not cause a loss of personalizations for all users. It does cause loss of personalizations for the specified user or group.
This is the best practice approach for promoting Group Permission Trees with shared content [Shared Pages] from a development system to a production system. You initialize the development system as a copy of the production system. Updates to group content are made in the development system. The entire set of group content, along with the updates, is promoted to replace the group content in the target system. Such promotions occur routinely, so it is important that they do not repeatedly disrupt your end users' experience (by causing a loss of personalizations).
Note: With SAS Information Delivery Portal 4.3 and later, you can configure unchallenged users to manage the content for unchallenged access. In order to use the unchallenged access capabilities on the target SAS 9.2 or SAS 9.3 system, you should enable and define the unchallenged access user. For information about unchallenged user access, see Enabling Unchallenged Portal Access.

Step 1: Perform the Required Promotion Tasks on the Source System

To prepare the source system, follow these steps:
  1. Perform a complete backup of the source system (including the metadata repository, the configuration directories, and the WebDAV).
    Note: For instructions, see the SAS Intelligence Platform: System Administration Guide. Use either the SAS 9.1.3, SAS 9.2, or SAS 9.3 version of this document, as appropriate for the version of your source system.
  2. In the source host, create a PortalPromotion subdirectory within your equivalent of SAS-Configuration-Directory\Lev1\Web\Applications\SASPortal<ver>\. Copy the promotion scripts into that directory. The portal promotion scripts use the directory paths specified for the JAVA_HOME and the SAS_HOME environment variables.
    • If you have SAS Information Delivery Portal 4.31, the scripts are in the configuration directory under your equivalent of \Lev1\Web\Applications\SASPortal4.3\PortalPromotion
    • If you do not have SAS Information Delivery Portal 4.31, obtain the scripts by contacting SAS Technical Support.
    Note: The scripts use relative paths, so it is essential that they are present in the correct location.
  3. Edit the source copy of the PortalPromotion\PermissionsTree.xml file as follows:
    1. Locate the source metadata repository's ID. In SAS Management Console, you can find the ID by navigating to Metadata Managerthen selectActive Server and selecting Foundation. The repository ID is displayed in the right panel and consists of two 8-digit numbers separated by a period (for example, A0000031.A5BQ25K2).
    2. Edit the PermissionsTree.xml file to specify the source metadata repository's ID in the ReposId parameter. For example: <ReposId>A0000031.A5BQ25K2</ReposId>
  4. In the PermissionsTree.xml file, search for this line: 
    <Tree search="*[@Name='SAS Guest Permission Tree']"
TemplateName="PortalPermissionsTree"/>
  5. Modify the value for the @Name parameter by specifying the user's name. Here is an example: 
    <Tree search="*[@Name='Analyst Permission Tree']"
TemplateName="PortalPermissionsTree"/>
    Note: A search string is limited to 60 characters in metadata. If the user name is longer than 47 characters, edit the user name to ensure that the full string is 60 characters or less. Spacing and capitalization for the Name parameter must match the exact name for the User Permissions Tree. If you need to obtain the correct name for the User Permissions Tree, access SAS Management Console. Then, navigate to Environment Managementthen selectUser Manager. Select the Show Users check box to display the user names.
  6. Save the PermissionsTree.xml file.
  7. Open a host command window.
  8. If the source is SAS 9.1.3, set environment variables for SAS_HOME and JAVA_HOME. For example: 
    set SAS_HOME=C:\Program Files\SAS-Installation-Directory
set JAVA_HOME=C:\Program Files\Java\jre1.5.0_15\
    or 
    export SAS_HOME=/disk2/SAS9.3/SAS-Installation-Directory/
export JAVA_HOME=/usr/java/jdk1.5.0_07/
  9. Run the appropriate extraction command: 
    extractPortalversion.bat PermissionsTree.xml  -user ID
-password AdminPwd
    or 
    extractPortalversion.sh  PermissionsTree.xml  -user ID
-password AdminPwd
    Note: Choose the version of the script that matches your source. For example: extractPortal913.bat (for a SAS 9.1.3 source on Windows), extractPortal92.sh (for a SAS 9.2 source on UNIX), or extractPortal93.sh (for a SAS 9.3 source on UNIX). For more information, see About the Portal Promotion Tools.
    The extraction script generates the following files:
    • PermissionsTree_deployFile.xml
    • PermissionsTree_expand.xml
    • PermissionsTree_extract.xml
    • extract.log
  10. If you are promoting the permissions tree for a user or group whose name contains DBCS characters or non-latin characters, open the PermissionsTree_extract.xml file. Verify that the user or group name is accurate in that file. DBCS characters typically appear in certain languages including Hebrew, Chinese, or Japanese.
  11. Open the extract.log file and verify that the file does not contain any errors. If .xml files are not generated, the extract.log file should provide an explanation.
  12. If the SAS installation of the target host is on a different machine or platform, copy the extracted .xml files to the PortalPromotion subdirectory on the target host.

Step 2: Perform the Required Promotion Tasks on the Target System

To prepare the target system, follow these steps:
  1. Perform a complete backup of the target system (including the metadata repository, the configuration directories, and the WebDAV). For instructions, see the SAS Intelligence Platform: System Administration Guide.
  2. Obtain the metadata repository ID from the target SAS 9.3 or SAS 9.2 system. Later, you will replace the value for the ReposID parameter with the target system's metadata repository ID. As a result, commands that import portal content will verify that the target repository does not contain duplicate content.
    CAUTION:
    If the metadata repository ID in .xml import files is different from the metadata repository ID on the target system, the import processes will fail.
  3. To obtain the metadata repository ID on the target SAS 9.3 or SAS 9.2 system, follow these steps:
    1. On the SAS Management Console on the target system, right-click Foundation, and select Properties.
    2. Expand Metadata Server Active Manager. The metadata repository ID is displayed in the dialog box. (for example, A0000031.A5BQ25K2).
    3. Make a note of the metadata repository ID so that you can specify it in the appropriate .xml import files.
  4. If the target system's version is different from the source system's version (for example, you are promoting content from a SAS 9.1.3 system to a SAS 9.2 or SAS 9.3 system), install the following JAR files in the ANT_HOME/lib directory:
    • bsf.jar
    • BeanShell JAR files: bsh*.jar
    • commons-logging.jar
    You can obtain JAR files from the following locations:
    On Windows: SAS_Installation_Directory \Program Files\SAS\SASVersionedJarRepository\9.3\eclipse\plugins
    On UNIX: SAS_Installation_Directory/SASVersionedJarRepository/9.3/eclipse/plugins
    JAR files can also be obtained from http://ant.apache.org/manual/install.html. In the section on Library Dependencies, click the appropriate URL paths to download each set of JAR files.
  5. If a PortalAdmins group exists on the source system with the SAS Web Administrator and SAS Administrator, the same group with these users should exist on the target system. The default name in SAS 9.1.3 is SAS Trusted User. The default name in SAS 9.2 and SAS 9.3 is sastrust. To ensure that the groups and users that exist in the source system also exist in the target system, the values for the metadata repository IDs, the SAS Administrator accounts, and the SAS Trusted User accounts should be specified.
    Note: Any users or groups that exist only in the target are unaffected by the promotion.
  6. There are two methods available to ensure that the correct values are specified and used to prepare the target system for the import process. Determine which method is appropriate for your environment and follow that method.
    • If the source is a SAS 9.1.3 or SAS 9.2 system, and the default values for the SAS Administrator and the SAS Trusted User accounts were retained in those deployments without any changes, then modify the build.properties file to customize and provide the values for the metadata repository IDs, the SAS Administrator accounts, and the SAS Trusted User accounts. Here is an example of the build.properties file: 
      xml.file=PermissionsTree
source.reposid.of.metadata.repository=A0000031.A5BQ25K2
target.reposid.of.metadata.repository=A0000001.A5T8FYJJ
source.sasadm.name=SAS Administrator
target.sasadm.name=sasadm
source.sastrust.name=SAS Trusted User
target.sastrust.name=sastrust
      In the build.properties, specify the name of the Permissions Tree and the repository ID for the source and target systems. Specify the default values for the names of the SAS Administrator and SAS Trusted User accounts in the source and target systems.
    • If you modified the build.properties file, skip this step. If you did not modify the build.properties file (because the source is a SAS 9.1.3 or SAS 9.2 system, and the default values for the SAS Administrator and the SAS Trusted User were previously customized and modified in the source or target deployments), then you should manually specify the values for these internal accounts in these generated .xml files:
      PermissionsTree_deployFile.xml, PermissionsTree_expand.xml, and PermissionsTree_extract.xml.
      In each applicable .xml file, specify the values for the @Name parameter as it applies to the SAS Administrator and SAS Trusted User. Note that some .xml files might not require these values for the @Name parameter.
      This manual process of modifying the generated .xml files is required because the build.properties file can be edited and used only in deployments where the default values for the internal accounts were retained and not modified.
  7. If you modified the build.properties file, skip this step. When you run the upgrade metadata commands later, the generated .xml files are updated with the required values. If you manually updated the values in the .xml files, open the PermissionsTree_deployFile.xml file. Search for the RepositoryBase Deploy_Id parameter. Specify the target system’s metadata repository ID as the value for RepositoryBase Deploy_Id and the target systems’s metadata name as the value for the Deploy_Name parameter. Here is an example:
    <Repository Base Deploy_Id="A0000001.A5T8FYJJ"
Deploy_Name="Foundation"
Id="A0000031.A5BQ25K2"
Name="Foundation"/>
  8. Verify that the portlets that are going to be imported have already been registered and deployed in the target system. Portlets exist independently of the Permissions Tree, so they are not within the scope of its promotion.
  9. Ensure that all SAS content that needs to be associated with the incoming portal data is present in the target. This step is essential to success and can require significant effort. This step involves tasks that are outside the scope of the portal promotion process. See What Cannot Be Promoted through Portal Promotion.
    Note: As part of this effort, make sure that the supporting SAS content is at the appropriate version level. For example, beginning with the 4.3 release of SAS Information Delivery Portal, data explorations must be converted to reports. Typically, this conversion occurs during a migration or an upgrade to SAS Information Delivery Portal 4.3. If you did not convert data explorations to reports, you will need to manually update the content and adjust directive URLs. Because data explorations can have dependencies on OLAP cubes, make sure the cubes have been built after you migrate, and before you run the scripts for updating content and adjusting directive URLs. For more information, see “Performing Post-migration Tasks” in SAS Intelligence Platform: Migration Guide. Also, see Update Content Manually for the SAS Content Server in SAS Intelligence Platform: Middle-Tier Administration Guide.
  10. If the User or Group Permissions Tree existed previously on the target system, remove that Permissions Tree from the target system. Complete this task before importing the new Permissions Tree on the target system. If the existing Permissions Tree contains non-DBCS characters or non-latin characters, use either one of these commands to remove it: 
    removePortalversion.bat PermissionsTree.xml  -user AdminID
-password AdminPwd
    or 
    removePortalversion.sh PermissionsTree.xml  -user AdminID
-password AdminPwd
    If the User or Group Permissions tree existed previously on the target system, and the user or group name contains either DBCS characters or non-latin characters, then use either one of these commands: 
    removePortalversion.bat PermissionsTree_extract.xml  -user AdminID
-password AdminPwd
    or 
    removePortalversion.sh PermissionsTree_extract.xml  -user AdminID
-password AdminPwd
    DBCS characters are typically found in Chinese, Japanese, Hebrew, and several other languages.
    CAUTION:
    This action is irreversible.

Step 3: Import Content into the Target Metadata Repository

To import content into the target metadata repository, follow these steps:
You can import a Permissions Tree to:
  • a SAS 9.2 target system that runs the 4.2 or 4.3 version of the SAS Information Delivery Portal.
  • a SAS 9.3 target system that runs the 4.31 version of the SAS Information Delivery Portal.
To import a Permissions Tree, run the appropriate import command: 
importPortalversion.bat PermissionsTree.xml -user ID
-password AdminPwd
or 
importPortalversion.sh  PermissionsTree.xml -user ID
-password AdminPwd
Note: You can import only into a SAS 9.3 or SAS 9.2 system. Use the appropriate version of the script. For more information, see About the Portal Promotion Tools.
Review the feedback in the output command window. This output is also saved in the import.log file that is located in the PortalPromotion directory

Step 4: Upgrade the Portal Metadata in the Target Repository

Determine How to Upgrade the Portal Metadata

There are two ways to upgrade the portal metadata:

Upgrade the Portal Metadata After Editing the build.properties File

To upgrade the portal metadata in the target repository, follow these steps:
  1. Open a host command window.
  2. When preparing the target system, if you edited the build.properties file, run the following upgrade command: 
    upgradeMetadata updateXMLSource -user ID -password AdminID
    When the upgradeMetadata command runs, the values specified for the metadata repository IDs, name for the SAS Administrator, and the SAS Trusted User are retrieved from the build.properties file to update the values in these files:
    • PermissionsTree.xml
    • PermissionsTree_deployFile.xml
    • PermissionsTree_expand.xml
    • PermissionsTree_extract.xml

Upgrade the Portal Metadata After Editing .xml Files

To upgrade the portal metadata in the target repository, follow these steps:
  1. Open a host command window.
  2. Run the commands in the order shown in the following table, if the source is not at the appropriate version level. For example, if you are promoting portal content from a SAS 9.2 to a SAS 9.3 system, the source will not be at an appropriate version level, and you should run the upgrade commands. If you are upgrading to the 4.31 or 4.3 version of SAS Information Delivery Portal (on SAS 9.3 or SAS 9.2) from another version of the product, you must run these commands. If you are promoting portal content from a SAS 9.3 to a SAS 9.3 system, the version of SAS is identical in both systems, and you should not run these upgrade commands.
    Commands for Portal Metadata Upgrade
    Windows Commands (for UNIX use .sh instead of .bat)
    Parameters
    upgradeMetadata.bat convertAces
    -user ID -password AdminPwd -trusted_user sastrust@saspw1
    upgradeMetadata.bat renameAlertsPortlet
    -user ID -password AdminPwd
    upgradeMetadata.bat fixDav
    -user ID -password AdminPwd
    upgradeMetadata.bat deleteOrphanedForeignKeys
    -user ID -password AdminPwd
    upgradeMetadata.bat reparentPermTrees
    -user ID -password AdminPwd
    upgradeMetadata.bat movePublicKioskInfo
    -user ID -password AdminPwd
    upgradeMetadata.bat convertIMVtoReportPortlet
    -user ID -password AdminPwd
    1The trusted_user parameter uses the logon password that is used for the SAS Trusted User account. Typically, this default password is sastrust@saspw.
  3. Start the Web application server.
  4. Run the following commands in the order shown in the table. Note that you run these commands after you restart the Web application server.
    Commands for Portal Metadata Upgrade After Starting the Web Application Server
    Windows Commands (for UNIX use .sh instead of .bat)
    Parameters
    upgradeMetadata.bat convertAlertstoSharedAlertsPortlet (footnote1)
    -user ID -password AdminPwd-repository repositoryName
    upgradeMetadata.bat adjustUrls
    -user ID -password AdminPwd
For more information, see About the Portal Promotion Tools.

Step 5: Convert Data Explorations to Reports (Optional)

During the portal promotion process, supporting SAS content should be at the appropriate version level. Beginning with the 4.3 release of SAS Information Delivery Portal and later, data explorations must be converted to reports. Typically, this conversion occurs during a migration or an upgrade to SAS Information Delivery Portal 4.3 or later. Because data explorations can have dependencies on OLAP cubes, make sure the cubes have been built after you migrate.
If you did not convert data explorations to reports, then you must manually convert data explorations and bookmarks to SAS Web Report Studio reports. Then, adjust directive URLs and references to the reports. In the SAS 9.3 environment, the manualLoadContent-OrderNumber and the manualAdjustUrls–OrderNumber scripts are available for converting data explorations and bookmarks to reports. These scripts are located in the SAS-Configuration-Directory\Lev1\Web\Utilities directory.
To load content into the SAS Content Server and manually convert data explorations and bookmarks into reports, follow these steps:
  1. Start the Web application server with the SAS Content Server.
  2. Rebuild OLAP cubes.
  3. Run the following command to convert data explorations and bookmarks to SAS Web Report Studio Reports.
    On Windows:
    SAS-configuration-directory\Lev1\Web\Utilities\
manualLoadContent-OrderNumber.bat
    On UNIX and z/OS:
    SAS-configuration-directory/Lev1/Web/Utilities
/manualLoadContent-OrderNumber.sh
  4. Run the following command to adjust directive URLs and references to the new reports:
    On Windows:
    SAS-configuration-directory\Lev1\Web\Utilities\
manualAdjustUrls-OrderNumber.bat
    On UNIX and z/OS:
    SAS-configuration-directory/Lev1/Web/Utilities
/manualAdjustUrls-OrderNumber.sh
  5. Validate and verify that the conversion was successful. Review the logs saved to the log file in the SAS-Configuration-Directory\Lev1\Logs\Configure directory.
  6. Either delete the manualLoadContent-OrderNumber and the manualAdjustUrls–OrderNumber script files or remove the credentials for the SAS Administrator and the SAS Trusted User accounts from these script files.

Step 6: Validate the Promoted Content

Log on to the portal as the Permissions Tree user or as a member of the Permissions Tree group. Then, verify the creation of the content for the User or Group Permissions Tree.
FOOTNOTE 1:Run this command if the target system has SAS 9.3 and the source system has a different version of SAS such as SAS 9.1.3 or SAS 9.2.[return]
Copyright © SAS Institute Inc. All rights reserved.