MicroStrategy - Upgrade to version 9.5.1

mstr

http://community.microstrategy.com/t5/Release-Notes/tkb-p/releases

DO NOT UNINSTALL THE EXISTING VERSION OF MICROSTRATEGY. MicroStrategy recommends upgrading to the latest version without uninstalling the previous version. However, in rare situations, issues may be encountered as a result of an in-place upgrade. In these situations, you may need to uninstall your existing MicroStrategy installation before installing the new version. If you choose to uninstall the previous version, make sure you backup your metadata before uninstalling. Uninstalling MicroStrategy also delete your metadata.

What can I do if the upgrade fail for some reason?

Upgrading the metadata database is probably the most complex part, and it may fail for whatever reason, but there is hope.

If you attempt to upgrade a project through the Configuration Wizard, and the upgrade fails, the project is locked. You must unlock the project before you attempt to upgrade the project again. To unlock the project using Developer, from the Administration menu, point to Locking, and select Unlock Project

Restart the Configuration Wizard, and retry the metadata upgrade may help.

Contact the MicroStrategy Support hotline.

Worst case scenario (abort): Shutdown MicroStrategy. Restore the metadata, history and statistics database from backup. Restore the VMs.

What are the things that I need to do in my DEV environment?

What we've outlined here is not a substitute for reading the upgrade guide. You should copy this procedure to your own document, read the upgrade guide and update your version to suite your need.

  1. Review the "New Features" Tech Note for all intervening release. Review information specific to your version upgrade, pre-upgrade information and prerequisites, checking for supported warehouse data types, and backing up production metadata.
  2. Create a test environment
    1. Setup the hardware (servers). This should match the production servers.
    2. Install your current version of MicroStrategy
    3. If your production environment is clustered, then your test environment should also be clustered.
    4. Make sure that your test environment Intelligence Server is connected to your test environment metadata.
    5. Make sure that your ODBC DSN point to appropriate database
    6. Using the Project Duplication Wizard, duplicate the production metadata into the test environment.
    7. Make sure that we install appropriate license
    8. Make sure that Tomcat has the latest SDK code
    9. Only projects that are loaded on Intelligence Servers can be upgraded. To upgrade an unloaded project, first load the project on Intelligence Server, perform the upgrade and then unload the project.
    10. Test the test environment using your current version of MicroStrategy to make sure that it works appropriately prior to the upgrade
  3. Create and save an Integrity Manager integrity test baseline of your reports and documents. You can then execute an integrity test against this baseline when the upgrade is complete, to ensure that the upgrade has not altered any of your report results. For detailed information about using Integrity Manager to execute integrity test, see the Integrity Manager chapter of the System Administration Guide.
  4. Perform basic stability testing. These tests may include such tasks as logging into a project, running a report, and creating a simple report. During the test, ensure that you are satisfied with the status and efficiency of the Intelligence Server.
  5. Re-apply previous customization
  6. Create an integrity test comparing reports from the upgraded test environment with the same reports in the production environment, so that you can easily see where any differences are. If possible, plan to execute data integrity and performance load tests against the production warehouse. This ensures that the test scenarios are as representative of the production environment as possible. If you are creating reports and documents specifically for an upgrade integrity test, create those reports and documents before you duplicate the production metadata.
  7. Check privileges
  8. Test the upgrade

What do I need to do prior to the upgrade?

  1. Inform IT folks on the timeline of the upgrade so that they can plan on it. If they cannot perform their required task on the upgrade day, perhaps we can reschedule the upgrade. We need to take the snapshot of the machines (we need to find out how long it will take him to take these snapshots, how long it will take us to restore from these snapshots, and exactly what we need to do to restore from these snapshots). We need DBA to backup the metadata, history, and statistics databases. We also need to inform them to review system requiremnts:
    1. Before updating your metadata, MicroStrategy recommends that you have an amount of free disk space equal to at least twice the on-disk size of the metadata database.
    2. If you are using Oracle for your metadata database, make sure that the Maximum Open Cursors parameter for the database is set to at least 1500.
    3. A license key from MicroStrategy for the version of the MicroStrategy software that you are installing.
  2. On the day prior to the upgrade, I need to back up the log files.
  3. Purge the history
  4. Copy the installation files and our code to the servers.
  5. Delete projects that are not loaded
  6. Obtain appropriate license key

What are the things that I need to do in my production environment?

  1. Disable Kaspersky
  2. Stop Tomcat
  3. Stop all Intelligence servers.
  4. Backup the metadata, history, and statistics databases. MicroStrategy recommends that you back up your metadata before any significant installation or upgrade. Once you update your metadata, you cannot revert that metadata to a previous version. Therefore MicroStrategy recommends that you perform a full database backup of your original metadata prior to the upgrade.
  5. Backup all of your servers. MicroStrategy also recommends that you do a tape backup, image, or ghost the production server before upgrading.
  6. Back up the configuration files that are used by the SDK.
    1. Copy the CustomESM and CustomTask folder C:\Khai\MSTRUpgradeConfigBackup
    2. Go into these folders (inside C:\Khai\MSTRUpgradeConfigBackup) and delete everything that are not our configuration files. This will leave these folders with just the configuration files. We will back up the entire MicroStrategy webapp folder (in case we need to restore everything) a bit later on.
  7. Stop Tomcat
  8. Delete log files
  9. Backup the entire MicroStrategy webapp folder to a C:\Khai\MSTRUpgradeBackup.
  10. Start Tomcat (with the Intelligence servers still offline)
  11. Undeploy MicroStrategy.war
  12. Stop Tomcat
  13. Delete any left over files (the entire MicroStrategy folder from the webapp folder)
  14. Bring back one Intelligence Server if we want to create an integrity test.
  15. Create and save an Integrity Manager integrity test baseline of your reports and documents. You can then execute an integrity test against this baseline when the upgrade is complete, to ensure that the upgrade has not altered any of your report results. For detailed information about using Integrity Manager to execute integrity test, see the Integrity Manager chapter of the System Administration Guide.
  16. Stop All Intelligence Servers
  17. Only projects that are loaded on Intelligence Servers can be upgraded. To upgrade an unloaded project, first load the project on Intelligence Server, perform the upgrade and then unload the project.
  18. Install Microsoft .Net framework v4 from http://download.microsoft.com/download/1/B/E/1BE39E79-7E39-46A3-96FF-047F95396215/dotNetFx40_Full_setup.exe
  19. Install the latest version of MicroStrategy (from \\SFO\Groups\Engineering\Dev\downloads\Temp\Microstrategy\Installs\9.5.1\9.5.0200.0057_9.5.1_GA_WIN_Fullzip ) without uninstalling the previous version on all servers
  20. Disable Kaspersky
  21. Apply the latest hot fix (in this case, none)
  22. Activate the servers. If the activation process hang, do the following:
    1. Run the cmd shell as administrator
    2. Navigate to the folder where the license manager is install: cd C:\Program Files (x86)\Common Files\MicroStrategy)
    3. MALicMgr.exe -console
    4. Follow on-screen instruction
    5. Alternatively, we can find the Activate.xml file in %Program Files%\Common Files\MicroStrategy and upload to https://licensing.microstrategy.com/. This will ask you to provide a username and password. This is the same credential that you use to access the support portal. Click on "Activate a Server Installation" to upload the file. After the file is uploaded, you will receive the email with the activation code. The activation code is also display on the screen so you can copy it and use it to activate the server.
  23. Disable Kaspersky
  24. Establish connection to the metadata
    1. Launch the Configuration Wizard
    2. Select the "Configure Intelligence Server" option.
    3. Click Next
    4. Select the right MetaData DSN and provide the correct database credential
    5. Click Next
    6. This will display a warning dialog
    7. Click Yes
  25. Upgrade the metadata.
    1. Launch the Configuration Wizard
    2. Select the Upgrade an existing environment … option.
    3. Click Next
    4. Select the Intelligent Server Components option
    5. Click Next
    6. Check the Local Host Intelligent Server check box.
    7. Uncheck the Migrate History List messages check box. This check box is for migrating the History List feature from file-based to database-based. Because we already have done this separately from the upgrade, we do not need to do it again. Therefore, we need to uncheck this check box. Otherwise, the upgrade process will fail.
  26. Upgrade the history list database.
    1. Launch the Configuration Wizard
    2. Select the Upgrade an existing environment … option.
    3. Click Next
    4. Select the History List Repository option
    5. Click Next
  27. Re-cluster
    1. Using MicroStrategy Desktop, log into a project source.
    2. Expand Administration, then expand System Administration, and then select Cluster. Information about each node in the cluster displays on the right-hand side.
    3. From the Administration menu, point to Server, then select Join cluster. The Cluster Manager dialog box opens.
    4. Type the name of the machine running the Intelligence Server to which you wish to add this node, or click … to browse and select it.
    5. Once you have specified or selected the server to join, click OK.
    6. From the Administration menu, select Server -> Configure MicroStrategy Intelligence Server, drill down on Clustering, select the checkboxes, and hit OK
  28. Perform basic stability testing. These tests may include such tasks as logging into a project, running a report, and creating a simple report. During the test, ensure that you are satisfied with the status and efficiency of the Intelligence Server.
  29. Fix the issue with email displaying raw HTML code
    1. Launch desktop
    2. Connect to appropriate project source
    3. Drill down on Administration -> Delivery Managers -> Devices
    4. Right click on "Generic Email" and select Edit
    5. Click on the Options button next to MIME
    6. Uncheck the "Use only tables to position elements in HTML (Enable for Microsoft Outlook 2007)" check box
  30. Run the Command Manager script to revoke or apply certain privileges
  31. Go through the screenshots and verify that previous governing settings are retained
  32. Reboot the Intelligence servers.
  33. Install the remaining MicroStrategy products
    1. Web
      1. Deploy the new MicroStrategy.war file
      2. Re-connect Tomcat to the Intelligence Server
      3. Re-establish the trust relationship. Lie if you have to. Either way, we will restore the trusted token file later on.
      4. Click on the Default properties link on the left
      5. Select the "Automatically connect to Intelligence Server when Web Server or Intelligence Server is restarted" radio button
      6. Check the "Keep the connection alive" check box
      7. Check the check box next to Standard (user name & password)
      8. Click on the radio button next to Standard (user name & password)
      9. Check the check box next to Trusted Authentication Request
      10. Check the Override project login mode settings check box
      11. Select the Log in, then show the projects accessible by the supplied login option for Project list
      12. Check the Show login page after user logout check box
      13. Select the Custom SSO option for the Trusted Authentication Providers field.
      14. Click the Save button
      15. Enable Verbose Logging
      16. Disable the "Share" functionality (TN44360)
        1. Log into MSTR Web Admin page
        2. Click on Security
        3. Locate the "URL" section and uncheck the "Session information is included on the URL" check box
      17. Stop Tomcat
      18. Deploy our customizations and delete the _Interface plugin
      19. Deploy the webapps\MicroStrategy\WEB-INF\xml\config\browserSettings.xml file (hide the navigation tree by default)
      20. Re-deploy the MicroStrategy\images\quantros folder from the backup folder
      21. Go through the screenshots to verify that previous settings are applied / retained in the preferences screen
      22. Re-deploy the configurations files from C:\Khai\MSTRUpgradeConfigBackup
      23. Add the <distributable/> tag near the end of the web.xml file to enable Tomcat session replication
      24. Run the ALTER TABLE statement to increase the length of the SESSION_STATE column
      25. Restore the trusted token files.
    2. Developer
    3. Enterprise Manager
    4. Command Manager
    5. Object Manager
  34. Disable Kaspersky
  35. Check for licensing
  36. Manage user privileges
    1. If you have made any changes to the privileges assigned to the out-of-the-box MicroStrategy user groups and security roles, updating the metadata may overwrite those changes. In particular, if you have made any changes to groups that use any privileges mentioned in the List of updated privileges on page 48, updating the metadata will overwrite those changes.
  37. Reboot the Intelligence servers and restart the Web servers as well
  38. Run the integrity test
  39. Re-enable Kaspersky

How to upgrade the metadata?

  1. Open the Configuration Wizard. Start menu -> All Programs -> MicroStrategy Tools -> Configuration Wizard
  2. Select the Upgrade existing environment to MicroStrategy 9 option and then select the Intelligence Server components option. Then click Next
  3. On the MicroStrategy Authentication page, type the username and password of a MicroStrategy system administrator. Then click Next.
  4. On the Select Components page, select the check boxes for each Intelligence Server you want to upgrade
  5. Under each selected Intelligence Server, select the system components you want to upgrade:
    • Upgrade metadata repository: The metadata repository contains the definitions of your MicroStrategy applications and supporting objects. An upgrade of your metadata is required to provide support for all new and updated features in the most recent version of MicroStrategy. If this upgrade has already been completed, this option is named Re-execute metadata repository upgrade.
    • Lean Object migration: MicroStrategy 9.3.1 introduce Lean Objects, a new, significantly more compact form of object representation in the metadata tables. All new objects are created in this format, and existing objects are converted to this new format as they are saved. Selecting Lean Objects migration convert all objects in the repository to the new format at once. This migration can require a significant amount of time and resources to complete. Lean Object migration decrease the amount of disk space used by your objects. However, this migration causes all objects in your projects to be resaved, and depending on your database transaction logging policy, this may cause a temporary increase in the size of your metadata database.
    • Update privileges
    • Migrate History List messages: Select this check box to migrate your existing History List repository to a new format. A file-based repository can be migrated to a database-based repository for a hybrid repository, and a database-based repository can be migrated to a hybrid repository. If this option is selected, then during the upgrade process, this Intelligence Server and any other Intelligence Servers in the cluster are stopped and restarted.
  6. Select each project you want to upgrade. Only projects that are currently loaded on Intelligence Server can be upgraded. Project upgrades can include any or all of the following options:
    • Execute project logical upgrade: Updates the project to the most recent version of MicroStrategy. This option also updates the report and document definitions to improve performance and reduce the memory usage and storage requirements of reports and documents. If this update has already been completed, this option is named Re-execute project logical upgrade. This upgrade is required to execute any additional project upgrade options. Depending on the number of reports and documents, this update may take a significant amount of time.
    • Lean Objects migrations
    • Update Schedules: Make previous subscriptions viewable in MicroStrategy Analytics Enterprise.
    • Update MDX Source Objects: Update the MDX data source objects (MDX Cubes) to take advantage of improve performance. Depending on the number of MDX objects, this update may take a significant amount of time. By default, if you update multiple projects and the update fails for one project, the update process will continue for other projects. This allows you to complete all possible updates and then review any errors. To abort the update process for other projects when one project fails, clear the Update the remaining projects, even when one project update fails check box.
  7. Click Next
  8. On the Metadata Connection page, type the DSN, database login, and database password to access the MicroStrategy metadata. Then click Next.
  9. If you selected the Migrate History List messages option, then on the History List Target Database page, specify the necessary information for the History List database. For detailed information about the configuration options on this page, click Help
  10. Click Next
  11. On the Summary page, review your upgrade choices and click Update to update the metadata.

How to upgrade the History List repository?

  1. Launch the Configuration Wizard: Start menu -> All Programs -> MicroStrategy Tools -> Configuration Wizards
  2. Select Upgrade History List Repositories and click Next. The Upgrade History List Tables page opens.
  3. Select the DSN for the History List database, and specify the login information.
  4. To upgrade existing History List messages to the current format, select the Copy History List content check box.
  5. If you select to upgrade your existing History List message, you can also select the Compress data check box to compress all existing History List message. This compression can improve the performance of using History List messages. However, the compression of your History List message can require significant system resource during the upgrade. To avoid the overhead of compressing your existing History List messages, clear the Compress data check box. Existing History List messages are not modified, but any new History List messages will be created with the new compressed format.
  6. Click Next. The Summary page open.
  7. Review the available information, and click Finish. This History List repository is upgraded.

What are the best practices for upgrading?

  1. Follow The upgrade process checklist
  2. Always upgrade Intelligence Server prior to upgrading client application such as MicroStrategy Web or Developer
  3. Create an upgrade test environment by duplicating your production environment and production metadata.
  4. Upgrade this test environment and test it before upgrading your production environment.
  5. Before upgrading your metadata, MicroStrategy recommends that you have an amount of free disk space equal to at least twice the on-disk of the metadata database.
  6. If you are using Oracle for your metadata database, make sure that the Maximum Open Cursors parameter for the database is set to at least 1500
  7. Do not downgrade MicroStrategy products or components on a machine to previous versions.
  8. All MicroStrategy products on a machine must use the same version.
  9. If you are using clustered Intelligence Servers, then to maintain stability in your Intelligence Server cluster while upgrading, shutdown Intelligence Servers on all nodes in the cluster before proceeding with the upgrade.
  10. Every node in the MicroStrategy cluster must run the same version of MicroStrategy for the cluster to work appropriately.

How can we determine if the VLDB settings were changed?

The default options for VLDB settings may change between releases. You can determine what VLDB default settings have changed by creating a VLDB setting report for your database type before the upgrade, and comparing it to a VLDB settings report created after the upgrade. For instruction on how to create a default VLDB settings report, see the section on Default VLDB settings for specific data source in the Supplemental Reference for System Administration.

What are the database and storage requirements?

  1. If you are using Oracle for your metadata database, make sure that the Maximum Open Cursors parameter for the database is set to at least 1500.

What problem did I have with upgrading to 9.5.1?

The servers already had 9.4.1 installed, but I need to downgrade it to 9.2.1 before I can do the upgrade to 9.5.1. I uninstall MicroStrategy 9.4.1, and re-install 9.2.1m. There were some weird issues. At first I thought that some components were not cleanly, and because the metadata could not be downgrade, and I didn't want to bother the DBA, so I delete all the tables in the metadata, history, and statistics database using SQL Developer from Oracle, and hope that MicroStrategy would re-create those tables, but for some reason, the Configuration Wizard failed. I had to use SQL Developer copy the metadata, history, and statistics database (version 9.2.1m) from another source, and then do the upgrade.

Where is the log file for the upgrade process?

**C:\Program Files (x86)\Common Files\MicroStrategy\Log\MACfgWiz.xml**

This log file is located in the Log subfolder of the main MicroStrategy directory. You can analyze the log file using Apache Chainsaw log viewer, which can be downloaded from http://logging.apache.org/chainsaw/index.html

The MicroStrategy Readme contains troubleshooting scenarios aimed to assist you during or after an upgrade.

How can we create a response file?

If we have a lot of servers, using a response file will help.

As an alternative to stepping through each page of the Configuration Wizard, you can create a response file with the upgrade information, and use that response file to automatically upgrade your MicroStrategy systems.

MicroStrategy recommends that you create a response file through the GUI mode of the Configuration Wizard. You step through the Configuration Wizard and make your selections. Then, at the end of the Configuration Wizard, do not click Finish. Instead, click Save. You are prompted to save your selections in a response file.

You can also create or modify a response file with a text editor. If you do not have access to the GUI mode of the Configuration Wizard, this is the only way to create a response file. MicroStrategy supplies a blank response file template, Response.ini, that you can copy and modify to create your response file. This file is located in the Common Files folder of your MicroStrategy installation. By default, this folder is C:\Program Files (x86)\Common Files\MicroStrategy.

MicroStrategy recommends that you always create the response file through the GUI mode of the Configuration Wizard. However, you can also modify a response file with a text editor to make minor changes such as entering different user login and password information.

If you are manually editing the response file, make sure to save the file using ANSI encoding.

How can we execute a response file?

To use a response file with the Configuration Wizard:

  1. From the Windows Start menu, point to All Programs, then MicroStrategy Tools, and then select Configuration Wizard. The Configuration Wizard opens.
  2. Click Load. The Open dialog box displays.
  3. Browse to the path where the response file is saved and click Open. The Summary page opens.
  4. An overview of all of the configuration tasks performed by the response file is displayed. Review the configuration tasks and click Finish to perform the configuration.

To use a response file from a Windows command line:

macfgwiz.exe -r “Path\response.ini”

Other helpful hints:

By default, privileges are upgraded based on the version of your MicroStrategy metadata. However, if you previously upgrade your MicroStrategy metadata and did not upgrade privileges along with the metadata upgrade, you must identify the MicroStrategy version you most recently upgraded your privileges for. To do this, to right of Upgrade privileges, click Advanced. The Select Privilege Version dialog box opens, with the version of your MicroStrategy metadata selected by default. From the drop-down list, select the version of MicroStrategy that privileges were most recently upgraded for and click OK. See page 30 of the upgrade guide.

List of updated privileges: See page 48 - 49 of the upgrade guide.

Any errors during the upgrade process are likely to be written to the installation log file (install.log). This file is located in the directory that you specify as the installation directory during the upgrade.

When you use the Configuration Wizard to add tables to the metadata or upgrade your projects, each SQL statements that is executed is logged to the Configuration Wizard log file (MACfgWiz.xml).

If you choose to uninstall the previous version of MicroStrategy, make sure that you back up your metadata before uninstalling. Uninstalling MicroStrategy also deletes your metadata.

How much time did it take me to upgrade the test environment?

  • 11:05 - 11:21 Backup MicroStrategy webapp folder
  • 11:21 - 11:23 Stop the I-server
  • 11:23 - 11:24 Undeploy the MSTR war file
  • 12:08 - 12:15 Download and install .Net framework V4
  • 12:15 - 12:49 Install base 9.5.1
  • 01:48 - 01:57 Apply latest hotfix
  • 01:57 - 02:52 Apply latest Windows update
  • 05:50 - 05:58 Establish connection to metadata
  • 05:58 - 06:52 Upgrade Metadata
  • 10:00 - 10:51 Upgrade MSTR Web

Overall, it took roughly 2 hours for 1 Intelligence server and one Web server. On a clustered environment with 2 Intelligence servers, and 2 Web servers, it may take approximately 3 hours.

How can we create an integrity test using the Integrity Manager?

After upgrading your system, you should ensure that the changes involved do not alter any of your report results. MicroStrategy Integrity Manager is designed to execute reports and documents from a project, note whether or not they execute, view their results, and compare them against reports and documents from another project.

MicroStrategy recommends the following best practices when testing your upgrade with Integrity Manager:

  1. Create an integrity test comparing reports from the upgraded test environment with the same reports in the production environment, so that you can easily see where any differences are.
  2. Execute the tests against the production data warehouse. If this is not possible, then test against a data warehouse that resembles the production data warehouse as closely as possible.
  3. Execute the tests under production users, groups, and security roles, instead of specially-created integrity test users and groups, so that the tests match the production environment as closely as possible.
  4. Use prompt answers that are used in the production environment.
  5. Use default personal prompt answers for prompts.

Ideally you can execute an integrity test on all reports and documents in your system. This gives you complete coverage of your system and ensures that none of your reports have any significant differences.

Depending on the size and number of your reports, you may not be able to test them all. There are several ways you can reduce the number of reports to test while still conducting a satisfactory integrity test.

One possibility is to execute a SQL-only integrity test for all reports and documents. Then execute a data test for any reports whose SQL does not match. This approach reduces the time needed for the integrity test, while still covering all the reports and documents. It can be used in combination with any of these methods of integrity testing.

For detailed information about Integrity Manager, including instructions, see the Integrity Manager chapter in the MicroStrategy System Administration Guide.

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License