Zephyr On-Premise Upgrade Instructions

Owned by Helen Kosova (Deactivated)
Apr 28, 2021
7 min read

Download Zephyr

Please download Zephyr on the following page: Zephyr Download.

Pre-Upgrade Process

Step 1: Delete the existing folder in Elasticsearch (folder present in \elasticsearch-<version>\data\nodes or /var/lib/elasticsearch/nodes) before starting the upgrade process. If Elasticsearch is not installed, please refer to Steps to Install Elasticsearch.

Deleting the node will remove the authentication details of Elasticsearch.

Step 2: Take a backup of the entire database: Steps to take database backup.

Step 3: Take a backup of the attachments, which are located in the file system (separate from the database).

  • We suggest you take a backup of the entire folder which can be found in Windows under the Zephyr Directory (ZephyrDir) or in Linux within /zephyrdata.

  • If you're using Jira OAuth in a previous version of Zephyr, take a backup of the applicationContext-resources.xml file located within C:\Program Files\Zephyr\tomcat\webapps\flex\WEB-INF\classes.

Step 4: Check the Server.xml file for the AJP connector.

  1. Stop the Zephyr Server.

  2. Open the file zephyr/tomcat/conf/server.xml and comment out the line below:

    <!-- <Connector port="8009" protocol="AJP/1.3" redirectPort="8443" /> -->

  3. Save the file, exit and then you can start the upgrade process.

If SSL is previously setup in Zephyr, please take a copy of your Java keystore file which is present under the Zephyr/tomcat/conf path file. For special SSL consideration, we recommend viewing the following page: Special SSL Consideration.

Upgrade on Linux

Step 1: Stop the Zephyr Service.

sh /opt/zephyr/tomcat/bin/shutdown.sh

Step 2: Stop Elasticsearch.

service elasticsearch stop

Step 3: Open the file {directory}\elasticsearch-<version>\config\elasticsearch.yml and save somewhere the http.port and transport.tcp.port values. You will need to specify these exact values later when installing Elasticsearch 7.9.2.

Step 4: Uninstall the previous Elasticsearch version:

If you installed it using the ZIP file:

  • Stop Elasticsearch. Stop the process and delete the folder.

If you installed it using the RPM file:

  • Stop Elasticsearch by using the command below:

   /etc/init.d/elasticsearch stop

  • Uninstall Elasticsearch using the following command:

   yum remove elasticsearch

  • Delete the elasticsearch folder from the locations below by using the command rm -rf foldername :

    • /etc/elasticsearch

    • /var/lib/elasticsearch

    • /var/log/elasticsearch

Step 5: Download and configure Elasticsearch 7.9.2 as described in Steps to Install Elasticsearch.

Step 6: Start Elasticsearch:

Step 7: Check the Elasticsearch version by pinging the HTTP port in the browser or terminal. Elasticsearch should be up and running:

Step 8: Run the installation file of Zephyr Enterprise:

Step 9: Select the Upgrade option:

Step 10: Select the Zephyr installation folder where Zephyr was installed:

Step 11: Specify the Elasticsearch IP address and port:

Step 12: The upgrade has completed successfully:

Step 13 (Optional): If needed, enable authentication in Elasticsearch. See detailed instructions.

Step 14: Once Zephyr is installed successfully, launch the application and wait until reindexing is completed.

Please refer to the Post-Upgrade Process section below.



Upgrade on Windows

Step 1: Stop the Zephyr Server:

Step 2: Stop Elasticsearch.

Step 3: Uninstall Elasticsearch:

  • If you installed it as a service, go to Control Panel > Uninstall a program and uninstall Elasticsearch.

  • If you just unpacked the ZIP file, stop Elasticsearch and delete the elasticsearch-<version> folder from the computer:

Step 4. Download and configure Elasticsearch 7.9.2 as described in Steps to Install Elasticsearch.
Step 5: Start Elasticsearch by double-clicking the elasticsearch.bat file:

Step 6. Check the Elasticsearch version by pinging the HTTP port in the browser. Elasticsearch should be up and running:

Step 7: Run the installation file of Zephyr Enterprise and select Upgrade on the Welcome screen:

Step 8: Click OK in the subsequent dialog:

Step 9: Select the destination folder and click Next:

Step 10: Specify the Elasticsearch IP address and port and click Next:

Step 11: After creating a shortcut, click Next.

Step 12: Once the upgrade is complete, click Finish.

Step 13 (Optional): If needed, enable authentication in Elasticsearch. See detailed instructions.

Step 14: Start Zephyr and wait until reindexing is completed.



Post-Upgrade Process

Post Upgrade Recommendations

Step 1: After upgrading, we recommend users clear their browser cache when accessing their Zephyr application if you are experiencing issues regarding cached pages.

Step 2: After upgrading, we strongly recommend users to perform a re-index of your Zephyr instance to ensure the integrity of your data and information within the Zephyr instance.

Step 3: After upgrading, your users must update their OAuth keys from within Zephyr again on the Defect Tracking page in the administration section.

  • With the updated authentication for Jira, Zephyr saves the entries in the database and requires a manual update for the OAuth keys. The user needs to manually reset the consumer key name and the consumer private key.

Post Upgrade Recommendations for Special Considerations and Scenarios

These scenarios are based on whether or not users may have certain features enabled (SSO/etc.) These are not applicable to all customers.

Step 1: If SSL is setup in the previous version of Zephyr, then follow the instructions in Special SSL Consideration.

Step 2: Create and Validate Webhooks (May apply to users upgrading from either Zephyr Enterprise 6.2 or an earlier release).

Re-create the Webhook

1. The user must map a Zephyr project to their Jira instance/project. When users map a single project to their Jira, all other projects will be mapped creating the webhook. Users can choose to select any project to map as it does not matter which project is selected. Once the user finishes mapping the project to their Jira, the webhook will be created successfully in Zephyr.

Validate the Webhook

2. For users, you may want to double check that the webhook is created by navigating to the Jira webhook page and validating that all of the Jira projects are included in the webhook JQL.

Step 3: Update ZBot. You can download the ZBot installation file either from Zephyr by clicking the username in the top-right corner and selecting Download ZBot from the dropdown, or by going directly to http://<your_zephyr_server>/zephyr/zbot .

SSO Consideration: If you have SSO set up, your users may run into the following scenario.

The Zephyr login page will now auto-redirect to the SSO page if zephyr is integrated with SSO. 

For the Internal-login page, there will be no redirection. On that page, the login will contain the same behavior in the scenario that the admin wants to change the integration.

https://<Zephyr domain>/flex/html5/internal-login

When a user logs out of the system, they will be able to view the 2 following options:

A normal login (Internal login for users)

A Single Sign-On login (SSO)

The advantage of this is that if an SSO user is logged into their SSO already and that user hits the Zephyr URL, the user does not need to type their username and password. When navigating to the Zephyr URL, the SSO user will automatically be logged into Zephyr. 

Linked test case statuses in Jira

In Zephyr Enterprise 6.3 and later, we've implemented a new behavior to show the latest Execution Status when a Zephyr test-case is mapped to a Jira requirement in the Jira. However, this information will not be automatically updated after upgrading. Any old or existing links in Jira that have remote links pointing to test cases in Zephyr will not display the latest execution status and will not work for the latest update.

The reason for this is that Zephyr cannot update those existing remote links during the upgrade process.

However, as the system is used after the upgrade, any new test cases linked to Jira or existing test case links that are executed again will be updated with the latest status and with working links.

Rollback Process

Rollback may be required in the following cases:

  • When the Zephyr server is not stopped prior to the user starting the upgrade process.

  • When Zephyr is configured with Tomcat VisualVM memory configuration and then the Zephyr server stopped and user performs an upgrade process.

If a rollback is required, follow the instructions in Zephyr On-Premise Rollback Process.