Download Zephyr

Download Zephyr on the following page: Zephyr Download.

• Zephyr Enterprise currently supports only upgrades to the supported versions. See Zephyr End-of-Life Policy.
  If you need to upgrade from an older version, contact support.

• Zephyr Enterprise Release 8.1 and later supports the latest Java 17 or OpenJDK 17.0.10 versions. You can download Java 17 and OpenJDK 17.0.10  from the respective download page.

Pre-upgrade steps

Step 1: Zephyr Enterprise supports MySQL v8.0.35, which is effective from Zephyr Enterprise v7.17. Therefore, if you use MySQL, upgrade your MySQL DB to v8.0.35 before upgrading your Zephyr Enterprise to v7.17 and above.

The current Elasticsearch settings, by default, allow automatic index creation if a document is pushed into a non-existent index. With this feature and a loophole in Zephyr's indexing process, users can create those indexes without intending to. This causes an indexing issue, as the indexing percentage will drop to ~1%, and the index-relate functionality is affected.

To stop this, configure Elasticsearch to disallow any index for Zephyr. As a result, any index that begins with the name "Zephyr" will not be allowed for automatic creation.

Step 2: Follow this step if you want to use ES 8.6.2

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

Step 4: Restart MySQL DB before doing the upgrade.

Step 5: Back up the attachments located in the file system (separate from the database).

We suggest you back up the entire folder, which can be found in Windows under the Zephyr Directory (ZephyrDir) or in Linux within /zephyrdata.

Step 6: 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.

Step 7: Replace the recommended connector jar file.

Refer to the steps below to replace the recommended connector jar file for MySQL or MSSQL. The instructions are provided separately for each connector:

Step 8: Take a backup of the node data located in the file system.

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 /node data.

Step 9: Install RabbitMQ 3.12.10 (Optional):

RabbitMQ 3.12.10 is a robust messaging and streaming broker that's easily deployable across cloud environments and on-premises setups. Currently, installing RabbitMQ 3.12.10 is optional for the users. You can download RabbitMQ 3.12.10 - here.

Step 10: Install ZE-Services (Optional):

• ZE-Webhook Service is the component responsible for accepting the incoming events from Jira and enqueues them to the message broker for further processing. You can download ZE-Webhook Service - here and find the installation instructions - here.

• ZE-Consumer Service is the component that picks the enqueued events from the message broker and updates ZE with the incoming data. You can download ZE-Consumer Service - here and find the installation instructions - here.

• ZE-AuditService is the component that acts as the incoming endpoint for the Audit Logs generated during the incoming webhook event processing and enqueues them to the message broker. You can download ZE-AuditService - here and find the installation instructions - here.

• ZE-AuditProcessor is the component responsible for reading the enqueued audit logs from the message broker and inserting them into ZE. You can download ZE-AuditProcessor - here and find the installation instructions - here.

Upgrade on Linux from Root to Non-root user

Step 1: Stop the Zephyr Service.

Step 2: Run the installation file of Zephyr Enterprise:

Step 3: Select the Upgrade option:

Step 4: Select the Zephyr installation folder where Zephyr was installed:
a. If you select option 2- No, Manually, then you will have to change the ownership of the files manually. Click here for more steps.

b. If you select option 1- Yes, automatically, then the installer changes the ownership of the files automatically. Depending on the number of files, this operation may take time.

Step 5: Specify the Elasticsearch IP address and port:

Step 6: The upgrade has been completed successfully:

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

Step 8: Once the upgrade is complete, navigate to {ZephyrDir}/tomcat/conf/server.xml
You need to change the port to 1024 and above.

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

Please refer to the Post-Upgrade Process section below.

Post-upgrade steps

Post-upgrade recommendations

Step 1: After upgrading, we recommend users clear their browser cache when accessing their Zephyr application if they 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. For more details on reindexing refer to Full Reindex.

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’s key name and the consumer’s private key.

Step 4: Update the Tomcat configuration.

1. Stop the Zephyr application server.

2. Locate the server.xml file under the Zephyr installation directory. (Zephyr Directory}\tomcat\conf)

3. Open the server.xml file and locate the <Host> tag.

4. Add the following value below the <Host> tag:

5. Save the server.xml file.

6. Start the Zephyr application server.

Step 5: If the Zephyr application does not start

1. Verify the connector files in {Zephyr Directory}\tomcat\webapps\flex\WEB-INF\lib folder after the upgrade.

2. Remove one file (older file) if there are 2 connector files and start Zephyr application.

Step 6 (optional): This Step is only applicable If ZE-Service is Enabled. Once the upgrade is successful,

1. On logging into Zephyr, user will get the below popup (if Jira is integrated before the upgrade)

2. Once the user navigates to the Jira Integration page → the Jira connections will be highlighted in RED as shown in the below screenshot:

3. Once all services are up and running → For Automatic webhook management → click on the Update Webhook button from the Jira Integration page.

4. In Jira, the webhook URL will be updated as per the new webhook URL:

The new webhook URL would be something like: https://webhook.yourzephyr.com/v1/jira/webhooks/callback

Step 7 (optional): This Step is only applicable If ZE-Service is Enabled.
For Manual webhook management, copy the URL from the popup as shown in the below screenshot and go to Jira, to create a webhook with the new URL. The below popup will appear when integrating a Zephyr project with a Jira project or In Jira Integration → click on the Edit icon under the Action column and save the Jira Integration again.

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).

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 .

Step 4: Users must disable binary logging in the MySQL 8.0.35. By default, the binary logging is enabled in MySQL 8.0.35.

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

Rollback process

Rollback may be required in the following cases:

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

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

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