Promote the Entire Portal Application Tree

About Promoting the Entire Portal Application Tree

You can promote an entire portal application tree in any one of the following scenarios:
  • from SAS 9.1.3 (SAS Information Delivery Portal 2.0) to SAS 9.2 (SAS Information Delivery Portal 4.2 or 4.3). This is the best-practice process for promoting portal content after an upgrade or migration of the rest of the system from SAS 9.1.3 to SAS 9.2.
  • from SAS 9.1.3 (SAS Information Delivery Portal 2.0) to SAS 9.3 (SAS Information Delivery Portal 4.31). This is the best-practice process for promoting portal content after an upgrade or migration of the rest of the system from SAS 9.1.3 to SAS 9.3.
  • from SAS 9.2 (SAS Information Delivery Portal 4.2 or 4.3) to SAS 9.2 (SAS Information Delivery Portal 4.2 or 4.3). This is the easiest way to promote all portal content from a development system to a production system.
  • from SAS 9.2 (SAS Information Delivery Portal 4.2 or 4.3) to SAS 9.3 (SAS Information Delivery Portal 4.31). This is the easiest way to promote all portal content from a development system to a production system.
  • from SAS 9.3 (SAS Information Delivery Portal 4.3) to SAS 9.3 (SAS Information Delivery Portal 4.31). This is the easiest way to promote all portal content from a development system to a production system.
When a new deployment of SAS 9.2 is completed, you can easily promote all portal content from the SAS 9.1.3 or SAS 9.2 system to the SAS 9.2 system.
When a new deployment of SAS 9.3 is completed, you can easily promote all portal content from a SAS 9.1.3 or SAS 9.2 system to the SAS 9.3 system.
The advantage of promoting the entire Portal Application Tree is that it is comprehensive. All supported content types are promoted together. Supported content types in this promotion process include portal page templates, portal content objects, portlet instances, and portal pages. include You do not have to keep track of dependencies among those content types or follow a specific sequence in order to preserve those relationships.
CAUTION:
Promoting the entire Portal Application Tree causes all users to lose all of their Portal personalizations (such as preferences, layout customizations, and favorites).
Due to this limitation, this approach is not ideal for regular or frequent promotions.

Step 1: Prepare the Source System

To prepare the source system for portal promotion, 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. If the source system does not contain the SAS-Configuration-Directory\Lev1\Web\Applications\SASPortalVersion\PortalPromotion directory, create this directory path. For example, on a source SAS 9.1.3 system, create this directory path:
    SAS-Configuration-Directory\Lev1\Web\Applications\SASPortal4.2\PortalPromotion
    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\PortalApplicationTree.xml file so that it points to the source metadata repository.
    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 PortalApplicationTree.xml file to specify the source metadata repository's ID in the ReposId parameter. For example: <ReposId>A0000031.A5BQ25K2</ReposId>

Step 2: Extract Content from the Source Metadata Repository

To extract content from the source metadata repository, follow these steps:
  1. Open a host command window.
  2. Set environment variables for SAS_HOME and JAVA_HOME. The following examples apply to a SAS 9.3 environment: 
    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
    Note: The JAVA_HOME environment variable must be set to match the version used by the Web application server.
  3. Run the appropriate extraction command: 
    extractPortalversion.bat PortalApplicationTree.xml  -user ID
-password AdminPwd
    or 
    extractPortalversion.sh  PortalApplicationTree.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:
    • PortalApplicationTree_deployFile.xml
    • PortalApplicationTree_expand.xml
    • PortalApplicationTree_extract.xml
    • extract.log
  4. 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.
  5. If the target is on a different machine or platform from the source, copy the extracted .xml files to the PortalPromotion directory on the target host.

Step 3: Prepare 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 following portal promotion scripts, or verify that they exist in the PortalPromotion directory:
    • UpgradeMetadata.bat or UpgradeMetadata.sh
    • removePortalversion.bat or removePortalversion.sh
    • importPortalversion.bat or importPortalversion.sh
    • build.properties
    • build.xml
  3. From a host command window, verify that SAS_HOME and JAVA_HOME environment variables have been set.
  4. 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 either the build.properties or the appropriate .xml files.
      CAUTION:
      If the target system’s metadata repository ID in the build.properties file or the .xml import files is different from the metadata repository ID on the target system, the import processes will fail.
  5. 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.
  6. 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.
    Note: Any users or groups that exist only in the target are unaffected by the promotion.
  7. If you have content that is associated with SAS BI Portlets based on JSR 168, copy the content to the same metadata location on the target system. For example, if you have SAS reports that are displayed with the SAS Report Portlet, copy those reports from the source system’s folder to an identical folder on the target system. If the content associated with these portlets is not available in an identical target location, these portlets will not be updated during promotion.
  8. Skip this step if you are promoting content from a SAS 9.3 system to another SAS 9.3 system.
    If the source is a SAS 9.1.3 or SAS 9.2 system, 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=PortalApplicationTree
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 Portal Application 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:
      PortalApplicationTree_deployFile.xml, PortalApplicationTree_expand.xml PortalApplicationTree_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. This manual process is also applicable if the names for the portal content on either the source or target systems were similar to sasadm or sastrust.
  9. Skip this step if you are promoting portal content from a SAS 9.3 system to another SAS 9.3 system or you modified the build.properties file.
    When you run the upgrade scripts later, the .xml files are updated with the required values. If you manually updated the values in the .xml files, open the PortalApplicationTree_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"/>
  10. If you modified the build.properties file, skip this step. When you run the upgrade scripts later, the .xml files are updated with the required values. If you manually updated the values in the .xml files, open the PortalApplicationTree_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"/>
  11. Verify that the portlets that are going to be imported have already been registered and deployed in the target system. Portlets exist independent of the Portal Application Tree, so they are not within the scope of its promotion.
  12. 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.
  13. If the Portal Application Tree exists on the target system, remove it: 
    removePortalversion.bat PortalApplicationTree.xml -user AdminID
-password AdminPwd
    or 
    removePortalversion.sh PortalApplicationTree.xml -user AdminID
-password AdminPwd
    CAUTION:
    This action is irreversible.
  14. Run the following command only if you edited the build.properties file. Specify the values for the metadata repository ID, and the SAS Administrator and SAS Trusted User accounts:
    upgradeMetadata updateXMLSource -user ID -password AdminID
    When the upgradeMetadata command runs, the values specified for the metadata repository IDs, SAS Administrator, and the SAS Trusted User are retrieved from the build.properties file to update the values in these files:
    • PortalApplicationTree.xml
    • PortalApplicationTree_deployFile.xml
    • PortalApplicationTree_expand.xml
    • PortalApplicationTree_extract.xml

Step 4: Import Content into the Target Metadata Repository

To import content into the target metadata repository, follow these steps:
  1. Open a host command window.
  2. Set the JAVA_HOME and SAS_HOME environment variables.
  3. Run the appropriate import command: 
    importPortalversion.bat PortalApplicationTree.xml -user ID
-password AdminPwd
    or 
    importPortalversion.sh  PortalApplicationTree.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.
  4. 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 5: Upgrade the Portal Metadata in the Target Repository

Upgrade the Portal Metadata

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
    Command (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 start the Web application server.
    Commands for Portal Metadata Upgrade After Starting the Web Application Server
    Command (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 6: 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, 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 7: Clean Up and Validate

To clean up and validate, follow these steps:
  1. Apply the Portal ACT to the Portal Application Tree. In SAS Management Console, follow these steps:
    1. Log on to SAS Management Console as the SAS Administrator.
    2. Navigate to Authorization Managerthen selectResource Managementthen selectBy Typethen selectTree, select Portal Application Tree, and right-click and select Properties.
    3. In the Portal Application Tree Properties dialog box, click Authorization.
    4. Click Access Control Templates.
    5. In the Add and Remove Access Control Templates dialog box, expand the Foundation node in the panel on the left.
    6. Select Portal ACT, and move it to the panel on the right.
    7. Click OK to save your changes.
  2. In the target system, undo any modifications to metadata that were made only for the purpose of the promotion (for example, any changes that were made to the unrestricted name, trusted name, and Portal Admins group).
  3. Verify the following results to determine the successful importing of the Portal Application Tree:
    • The Public Kiosk page was created as a shared page for all users.
    • The Public guest page was created.
    • Guest content for public is moved to the SAS Guest User account.
    • WebDAV content and graph portlets moved successfully after DAV content is imported.
    • The DAV content for reports moved over to SAS Folders.
    • The DAV folder locations were successfully updated from WebDAVDemo to WebDAV.
    • Data explorations work after content was made available.
    • Bookmarks are available for SAS Information Maps and for SAS Web Report Studio reports.
    • Existing SAS BI Dashboard portlets successfully use the content and data.
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.