This section provides step by step instructions to upgrade from Zephyr Enterprise Edition version 4.8 (Build 13818) to Zephyr Enterprise Server 5.0.  Note that with the introduction of version 4.8, Zephyr Community Edition is now retired.  If interested in upgrading to Zephyr Enterprise Server 4.8 from Community Edition, please contact your Zephyr Sales Account Manager or send an email to sales@getzephyr.com for information on purchasing Zephyr Enterprise Server licenses.

Before you begin

• Review all /wiki/spaces/ZEE50/pages/77856795 thoroughly
• Download required software that matches your Zephyr server configuration:
  • Zephyr version 5.0 (Build 14587) installation file:
    • Download from here
  • Zephyr Upgrade Utility:
    • Download from here
• If your Zephyr server has SSL setup, backup these files:
  • server.xml (%Zephyr_Home%/tomcat/conf)
  • setenv.sh (%Zephyr_Home%/tomcat/bin)
  • You will replace these files with your backup once the upgrade is complete
• Backup any file that has been manually customized after the original Zephyr installation. These files will be overwritten during the upgrade process.
  
  

It is recommend that you read the entire upgrade instruction set prior to beginning the upgrade process. If you have any questions, please contact our Technical Support team. The time taken to complete the upgrade mode process is mainly dependent on the size of your Zephyr 4.8 (Build 13818) backup, but shouldn’t take more than 3 hours to complete.

The process of upgrading your Zephyr Enterprise Server instance consists of four major parts:

1. Create a full backup with attachments
2. Verify that the backup file can be migrated to version 5.0 (Build 14587)
3. Uninstall the current version of Zephyr Enterprise and install Zephyr Enterprise Server version 5.0
4. Upgrade and restore 4.8 (Build 13818) backup file to 5.0 (Build 14587)

Note: If you are running Zephyr 4.5 or Zephyr 4.6 (Build 7993 or 8411 or 8521), you need to upgrade them to 4.7 (Build 9213) before attempting this upgrade process. If you have any questions, please contact our Technical Support team.

The Linux Upgrader Utility is available in 2 offerings -- GUI and Console. Both follow the same basic workflow but in console mode inputs need to be typed in via keyboard and the output is displayed in a terminal window

Running the upgrade via Linux GUI

Step 1: Create a full backup with attachments

Open a command line and run:

• backupAll.sh Y
• Store the backup file that is created with the above command where the upgrade utility is located
• Any work done in Zephyr after this backup is made WILL NOT be migrated to the new Zephyr Enterprise 5.0 instance
   

Step 2: Launch upgrader utility:

Step 3: Identify location of the backup file.

Step 4:  Upgrade utility confirms installation location of Zephyr (during the verification process, no actual upgrade will occur)

Step 5:  Select “Check Mode” to ensure the integrity of the backup file 

Step 6:  Click “Next” to begin verification

Step 7: Once verification is completed, the following dialog box is displayed identifying either a successful or unsuccessful verification of the backup files. If unsuccessful, view the logs, identify and address the issue or contact Technical Support for assistance.

Step 8: Follow the steps below to uninstall the current version of Zephyr - 4.8 (Build 13818):

• 1. Every installation of ZEE comes with a script file to uninstall Zephyr called ‘ZephyrUninstaller.sh’.

     1. Make sure the script file has execute permissions by using the comman

        shell> ls –l

     2. If the execute permission is not present, use the following command:

        shell> chmod +x ZephyrUninstaller.sh

  2. Run this script file as a root using the following command:

     shell> sudo ./ZephyrUninstaller.sh

     1. 1. This will remove directory locations and content that was installed as a part of Zephyr installation
           1. 1. If no files or folders were added manually after initial Zephyr installation then running the ‘ZephyrUninstaller.sh’ script file would be sufficient. Otherwise, continue with steps 3 and 4.

  3. Verify all the files and folders inside the ‘Zephyr’ folder were deleted. Delete any leftover files or folders using the remove command:

     shell> rm

  4. Once all the content of the 'Zephyr' folder is deleted, delete the ‘Zephyr’ folder using the command:

     shell> rmdir

Step 9: Install Zephyr Enterprise Server 5.0 (build 14587).  Follow the instructions for installation on Linux:

• • /wiki/spaces/ZEE50/pages/77922389

Step 10: Launch the Upgrader from the Command Prompt with the following required parameters:

• VzMySQLPath
• VzMySQLCnfFilePath

• Both parameters highlighted in red above are using the default locations mentioned in our installation guides. However, these locations can be customized during installation and may be different than shown. Once started, the first prompt is simply confirming the user wishes to continue or cancel the upgrade
• Once the Upgrader is launched, follow steps 2 through 4 above
• Select “Upgrade Mode” in Select Mode dialog box to run the upgrade utility 

Step 11: Click Next to continue after reading the prompt

Step 12: Progress will be visible above the progress bar. Logs can be viewed from the 'View Logs' link

Step 13: Once the upgrade process is complete, a result window will appear. Successful upgrades will have a 'successful' label for each area and you can select 'Next' to finalize the process. If unsuccessful, view the logs, identify and address the issue or contact Technical Support for assistance.

Step 14: Select 'Finish' to close the upgrader utility window. Zephyr server will automatically startup once this window is reached. However, startup time may vary. Please allow up to a few minutes before the Zephyr Desktop can be reached.

Running the upgrade via Linux Console

Step 1: Create a full backup with attachments

Open a command line and run:

• backupAll.sh Y
• Store the backup file that is created with the above command where the upgrade utility is located
• Any work done in Zephyr after this backup is made WILL NOT be migrated to the new Zephyr Enterprise 5.0 instance

Step 2: Open a terminal and navigate to the directory where the upgrade utility is located, then type using the format below:  

Both parameters highlighted in red above are using the default locations mentioned in our installation guides. However, these locations can be customized during installation and may be different than shown. Once started, the first prompt is simply confirming the user wishes to continue or cancel the upgrade. 

Step 3: Press [Enter] then type the location of the Zephyr backup file in the next prompt:

Step 4: Press [Enter] then type Zephyr installation location in the next prompt:

The location shown above is the default location mentioned in our installation guides. Your location may be different.

Step 5: Press [Enter]. You will be prompted to type the desired mode of upgrade: [1] - Check mode, [2] - Upgrade mode. For now, use [1] - Check Mode:

As soon as you press [Enter], the upgrade utility will start checking the backup for any issues. Please be patient as this process can take awhile.

The steps the utility takes in detail are:

• Fetch backup file version 
• Version compatibility check 
• Unzip backup file 
• Verify backup file contents
• Check database “itcc” character set

At the end of the backup file verification, results will be returned including the time it took for each step to complete and if backup file can be upgraded. If any issues arise based on the verification check, please reach out to Technical Support before proceeding to the next step(s).

Step 6: Follow the steps below to uninstall the current version of Zephyr 4.8 (Build 13818):

1. Every installation of ZEE comes with a script file to uninstall Zephyr called ‘ZephyrUninstaller.sh’.

   1. Make sure the script file has execute permissions by using the command:

      shell> ls –l

   2. If the execute permission is not present, use the following command:

      shell> chmod +x ZephyrUninstaller.sh

2. Run this script file as a root using the following command:

   shell> sudo ./ZephyrUninstaller.sh

   1. 1. This will remove directory locations and content that was installed as a part of Zephyr installation
         1. 1. If no files or folders were added manually after initial Zephyr installation then running the ‘ZephyrUninstaller.sh’ script file would be sufficient. Otherwise, continue with steps 3 and 4.

3. Verify all the files and folders inside the ‘Zephyr’ folder were deleted. Delete any leftover files or folders using the command:

   shell> rm

4. Once all the content of the 'Zephyr' folder is deleted, delete the ‘Zephyr’ folder using the command:

   shell> rmdir

Step 7: Install Zephyr Enterprise Server 5.0 (build 14587).  Follow the instructions for installation on Linux:

• /wiki/spaces/ZEE50/pages/77922389

Step 8: Launch the Upgrader using the command line and parameters below:

• VzMySQLPath
• VzMySQLCnfFilePath

• Both parameters highlighted in red above are using the default locations mentioned in our installation guides. However, these locations can be customized during installation and may be different than shown. Once started, the first prompt is simply confirming the user wishes to continue or cancel the upgrade
• Once the Upgrader is launched, follow steps 2 through 4 above

Step 9: Now, when prompted to run Check or Upgrade mode, please select [2] - Upgrade Mode: 

As soon as you press [Enter], the upgrade utility will start migrating the backup information to the newly installed Zephyr Enterprise 5.0 instance.

The steps the utility takes in detail are:

• Fetch backup file version
• Version compatibility check 
• Unzip backup file 
• Verify backup file contents 
• Verify database connectivity
• Check database “itcc” character set
• Stop Zephyr server 
• Restore itcc
• Check and migrate database character set
• Restore Zephyrdata
• Restore dversion
• Upgrade SQL to 4.8.1
• Replace DB user name 
• Migrate attachments
• Upgrade SQL to 5.0
• Copy license file 
• Verify Zephyr Home
• Delete zcform folder 
• Start Zephyr server 
• Verify Zephyr installation

 At the end of upgrade, the results summary will be returned including the time it took for each of the above processes to complete. You may now use your new Zephyr Enterprise 5.0 instance after following the below 'Post Server Upgrade Tasks'. If any issues arise based on the verification check, please reach out to Technical Support.

Post Server Upgrade Tasks

Client-side Notes:

When upgrading to the latest Zephyr Enterprise version 5.X, each client browser should clear their browser cache and cookies and perform a hard refresh of Zephyr by using Ctrl+F5 in your browser. This will ensure a smooth transition to the newest version. Internet Explorer is especially sensitive to history settings.

Automation Notes:

If your company has utilized automation integration with ZBots, you will need to download and install 5.0 ZBots. These can be accessed via the Zephyr Client Logon Screen by clicking on the ZBot image. If you use a custom ZIP with your ZBot, this ZIP may need to be recompiled with the latest Zephyr API library (found in the ZBot 5.0 directory).

Index Notes:

After upgrading, please re-index your database so that the search functionality will perform as expected. To do so, log in as the test manager, navigate to the Department area, click on the Administration Module, select the Customization Tab and click on the Re-Index button. Note this should be done during a low-use time period as it is a resource intensive process.