Upgrading In Place From Release 8.1 Version 05M to Release 8205.14 and Higher for Windows

This topic describes how to perform an upgrade in place of content from Release 8.1 Version 05M to Release 8205.14 and higher, while using the existing WebFOCUS 8.1 installation directory, in a Windows environment.

Note: The upgrade in place feature only applies to Release 8.1 Version 05M Gen 172 and higher. If you are using Release 8.1 Version 05M Gen 14, contact Customer Support Services.

Prerequisites for Upgrading in Place

The following are prerequisites for upgrading in place from Release 8.1 Version 05M to Release 8205.14 and higher:

  • Ensure the database used for the WebFOCUS repository is backed up prior to proceeding with the upgrade installation.
    This is required as the installation program performs database changes and a restore may be required in case of failures.
     
  • For the installation that will be upgraded, it is recommended to back up the existing installation folder and files on disk.
    The installation program backs up the entire directory prior to upgrading and will restore all files in case there are failures that do not allow the installation to proceed. This is a safety measure in case there are installation failures.
     
  • Ensure the application server used by the Release 8.1 Version 05M installation meets the WebFOCUS Release 8205.14 and higher requirements:
    • WebFOCUS is configured for Java 8 64-bit or higher.
    • Application server supports the servlet API 3.0 specifications.
    • If using Tomcat, it is recommended that you use the latest 8.5.x version. Tomcat 8 or higher is supported.
    • You are using a supported database.
       
  • Prior to running the upgrade installation, ensure the application server used by the existing WebFOCUS installation is stopped to ensure files are not locked and there is no product usage.
    If Tomcat is used, the installation program attempts to stop the Apache Tomcat service.
     
  • Ensure the ReportCaster service for the existing installation is stopped.
    The installation program attempts to stop the ReportCaster service.
     
  • To avoid files being locked, ensure files from the existing installation are not opened by File Explorer, CMD Window, or another application, such as an editor or browser.
     
  • Ensure the connection to the database hosting the WebFOCUS repository is running.

The following are tasks performed by the installation after selecting to upgrade an existing Release 8.1 Version 05M to Release 8205.14 and higher on Windows:

  1. Check for existence of a supported Java version (8 or higher 64-bit).
  2. Check for Tomcat and stop service.
  3. Check for ReportCaster service and attempt to stop it.
  4. Check database connection to run required database scripts.
    This is done based on connection information available in the install.cfg file.
  5. Upon successful connection, you are prompted to provide WebFOCUS administrator credentials to be used when the installation runs the update_repos script.
  6. User authentication and authorization is performed to ensure the provided WebFOCUS account is valid and has privileges to perform import of Change Management packages.
  7. Backup all files to the following folder:
    ..\ibi\WebFOCUS81\backup_files\
    
    If the backup fails, for example, due to locked files, a message displays. The installation restores all backed up files and exits.
  8. The new Release 8205.14 and higher installation is performed in the same WebFOCUS Release 8.1.x folder and the installation properly applies required edits to configuration files, in addition to restoring files, as specified in step 9.
  9. Files updated by the installation get backed up in the following folder:
    ..\ibi\WebFOCUS81\update_files\
    
    The following files are restored and updated during installation:
    • web.xml. Updated during installation, using default values.
    • odin.cfg. Restored from backup.
    • site.wfs. Restored from backup.
    • license.cfg. Restored from backup.
    • wflicense.key. Restored from backup.
    • olapdefaults.js. Restored from backup.
    • nls.txt. Restored from backup.
    • security_metadatasource.xml. Restored from backup.
    • multidrill.css. Restored from backup.
    • config/caster/ApplicationPreferences.xml. Restored from backup.
    • /config/was/. Restored from backup.
    • /config/web_resource/map/. Restored from backup.
    • nlscfg.err. Lang and code page will be updated, based on configuration of existing
      installation.
  10. Migration of configuration files is performed.
    Files updated by the migration utility are backed up in the following folder:
    ..\ibi\WebFOCUS81\merge_files\
    • webconfig.xml and install.cfg
      The install.cfg file in Release 8205.14 and higher will be updated. The following settings will be added while moving entries from the install.cfg and webconfig.xml files from the earlier Release 8.1.x installation:
      IBI_APPROOT_DIRECTORY IBI_WEBAPP_CONTEXT_DEFAULT
      IBI_WEBFOCUS_CONTEXT IBI_STATIC_CONTENT_CONTEXT
      IBI_HELP_CONTEXT IBI_REPORTCASTER_CONTEXT
      IBI_REPOS_DB_USER IBI_REPOS_DB_PASSWORD
      IBI_REPOS_DB_DRIVER IBI_REPOS_DB_URL
      
      Note:
      • Any additional updated settings found in the webconfig.xml file will be moved to the webfocus.cfg file.
      • File types specified in the WebFOCUS Administration Console for inclusion in the Change Management export packages are preserved during upgrades and an entry with these values is added to the webfocus.cfg file. By default, 8.2.x releases support the following file types for exports created by the change management feature: acx, bmp, css, fex, gif, htm, html, ico, jpe, jpeg, jpg, js, mas, mnt, png, sty, and svg. The file type list can be adjusted from the WebFOCUS Administration Console.
         
      The configuration file migration utility will not move the following settings. The Release 8205.14 and higher defaults will be used for the following:
      IBI_CSRF_ENFORCE IBI_CM_RETAIN_HANDLES
      IBI_CUSTOM_SECURITY_PARAMETER IBI_CUSTOM_SECURITY_DRIVER
      IBI_ENCRYPTION_PROVIDER IBI_MOVE_CONFIRMATION_MESSAGE
      IBI_REPOSITORY_SYNC_INTERVAL IBI_REST_METHOD_ENFORCE
      
      The IBI_WEBAPP_DEFAULT_URL setting is created in install.cfg and is used by the InfoSearch Dimension Index Loader. The default value is:
      http://<hostname>:80
      This can be configured through the WebFOCUS Administration Console to provide the proper WebFOCUS protocol, host name, and port.
       
    • mime.wfs. Entries in this file for Release 8.1.x will be combined with the entries in the Release 8205.14 and higher version of the file.
       
    • Security files: These security files will get copied from Release 8.1.x to Release 8205.14 and higher.
      • securitysettings.xml
      • securitysettings-mobile.xml
      • securitysettings-portlet.xml
      • securitysettings-zone.xml
         
    • languages.xml. Entries in this file for Release 8.1.x will be combined with the entries in the Release 8205.14 and higher version of the file.
       
    • OLAP. OLAP settings are not maintained during the migration process. To manage the display and configuration of OLAP, apply OLAP settings through the Administration Console.
       
  11. Check database collation.
  12. If the database is MS SQL Server or MySQL and collation is CI, the installation program changes the database collation to the best matched CS collation.
  13. Run the database update.
  14. Run the update_repos utility.
  15. Update the Program group, ReportCaster service, and registry entries.
  16. Tomcat cache is cleared.
  17. Tomcat is restarted.
  18. Installation completes by running the verification page.
    Note: If you are using another application server, redeploy the WebFOCUS web application WAR or EAR file, clear cache manually, and restart the application server.

Note: If any of the database update tasks fail, for example due to connectivity issues or not having database or WebFOCUS account credentials, the database update tasks can be performed post installation.

Post-Installation Review for Upgrading in Place

  1. Ensure all required services are running (application server, ReportCaster service).
  2. Ensure the connection to the database is working.
  3. Connect to WebFOCUS to ensure the product is working and content is accessible.
    WebFOCUS uses the web application context that was configured in the earlier Release 8.1.x version.
  4. If the web application fails to load:
    1. Check the application logs and WebFOCUS event.log.
    2. Ensure the product uses a valid license supported by Release 8205.14 and higher.
  5. Ensure configuration file migration was successful by checking the existence of the following folder:
    ..\ibi\WebFOCUS81\merge_files\
  6. Verify the contents of the install.cfg and webfocus.cfg files in the following folder:
    ..\ibi\WebFOCUS81\config\
  7. Ensure the jdbc driver set in the following folder is correct, based on the database used as the WebFOCUS repository.
    ..\ibi\WebFOCUS81\utilities\setenv\utiluservars.bat
  8. If collation check or change failed during the installation, the following needs to be performed post installation:
    1. Stop the application server.
    2. Ensure connection to the database is accessible and you have credentials that allow database changes (create/edit tables).
    3. Change database collation manually or using the tools available with the updated
      installation in the following folder:
      ..\ibi\WebFOCUS81\utilities\dbupdate\collation\
    4. Run the database update by opening a Command Window and navigating to the following folder:
      ..\ibi\WebFOCUS81\utilities\dbupdate\
    5. From this location, run:
      db_inplace_update.bat USERNAME=username PASSWORD=password
      SOURCE_CLASS_PATH=source_class_path
      
      where:
      username
      
      Is a database user account with db_owner rights to the repository database.
      password
      
      Is the password of the database user account.
      source_class_path
      
      Points to the location of the IBFSCommands.jar file from the original installation that was upgraded. Do not include the file name.

      This file is backed up in the following folder:
      C:\ibi\WebFOCUS81\backup_files\utilities\lib\
      
      For example:
      C:\ibi\WebFOCUS81\utilities\dbupdate\db_inplace_update.bat
      USERNAME=sa PASSWORD=pswd
      SOURCE_CLASS_PATH=C:\ibi\WebFOCUS81\backup_files\utilities\lib\
      
    6. Run the following to import the required Change Management packages.
      ..\ibi\WebFOCUS81\utilities\WFReposUtil\update_repos.bat
    7. Clear the application server cache.
    8. Restart the application server.