Zephyr Essential Integration

In this page

What is Zephyr Essential?

(supported since Better PDF Exporter 4.5.0)

Zephyr Essential is the next-generation version of Zephyr Squad, offering enhanced performance, a new REST API, and improved integration with Jira.

Zephyr Essential integration features

• You can export the test steps for any test case. Zephyr Essential test cases are attached to Jira issues. This enables creating self-containing PDF exports that contain issue field values, test case details, like name, priority, status, objective and precondition and the following test step data: test step instructions, test step data, expected result.
• You can export the test executions that belong to test cases attached to any Jira issues. Executions are exported with their (customizable) details for a comprehensive report: test case, execution status, assignee, executor user, execution date and comments.
• You can export the test step results of the test executions for detailed test reports. In this case, the following (customizable) details are exported for each step: step instructions, test data, expected result, execution status and the actual result.

(Need more features? Tell us in a support ticket!)

Zephyr Essential integration vs. the Zephyr Essential built-in PDF exports

You may want to ask: if Zephyr Essential has a built-in PDF export feature, why would you use another app for the same?

While the Zephyr Essential built-in PDF exports may be sufficient for basic use cases, the Better PDF Exporter integration is more powerful in, at least, these:

• It is extremely customizable.
  Instead of accepting the pre-defined export types in Zephyr Essential, you can define your own types via PDF templates.
• It supports all the powerful PDF features.
  You can use custom calculations in Groovy (sorting, complex math, data integration, etc.), embedded attachments, PDF bookmarks, charts, graphics (in Groovy, SVG, etc.), among others.
• It is integrated with all the popular Jira apps.
  You can freely combine Zephyr Essential data and other apps' data in the same PDF file.
• It comes with powerful templates optimized for Zephyr Essential.
  You can use those "as is", or customize them to your needs.
• It is well-documented with the customization guide, the Expression Reference Manual, the recipes, and such.

If at least one of these is important for you, give the app a try.

Configuration

Configuring the Zephyr Essential REST API access

As this integration relies on the Zephyr Essential REST API, you need to configure the credentials for the REST API calls in issue-fo.vm. The logic can be found in zephyr-v2-tool.groovy.

Configuring the Zephyr Essential API keys

1. Click your Jira profile icon in the top right and select Zephyr Essential API Access Tokens.
2. Click Create access token, click Copy, then Close.
3. Click the cog icon "⚙" in the top right → Apps → PDF Templates (under Better PDF Exporter).
4. Open the issue-fo.vm template for editing and paste the key to the value of the zephyrEssentialAccessToken variable (don't remove the quotation marks around the string!):

   ## issue-fo.vm
   
   #set($zephyrEssentialAccessToken = "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjb250ZXh0Ijp7ImJhc2VVcmwiOiJodHRwczovL21pZG9yaWdlcmdlbHlkZXY2LmF0bGFzc2lhbi5uZXQiLCJ1c2VyIjp7ImFjY291bnRJZCI6IjVjMzM0OTg1YTAzNzZkNGZlMWU1MWY3NCIsInRva2VuSWQiOiI5OGJhZTgxYy04ZDI1LTQ2YmEtODBkOC02NTA2ZDBkZGY5NDEifX0sImlzcyI6ImNvbS5rYW5vYWgudGVzdC1tYW5hZ2VyIiwic3ViIjoiZjEzMDNkODMtYTM5NC0zNDcyLWE0NTYtNmIyYmM5ZmE5YTYyIiwiZXhwIjoxNzc4OTIwMzc2LCJpYXQiOjE3NDczODQzNzZ9.LYGX01BFvLKjKZdzHe8Q9M81NmxawQkL5ES5F7dcn7M")
   

5. Save the changes in issue-fo.vm. (Don't worry about storing keys here: this file is visible only for Jira administrators, who would have super-user permissions anyway.)

Configuring the Zephyr Essential PDF templates

The template issue-fo.vm contains the following configuration parameters in its top part, to enable these features:

## issue-fo.vm

#set($exportZephyrTestCases = true)
#set($exportZephyrTestCycles = true)
#set($exportZephyrTestPlans = true)
#set($exportZephyrTestSteps = $pdfView.name.contains('Steps'))
#set($exportZephyrTestExecutions = $pdfView.name.contains('Executions'))
#set($exportZephyrTestExecutionDetails = $pdfView.name.contains('Results'))

As you see, the template checks if the view name contains certain words, and turns on the different features accordingly. If the export is made with the default Zephyr-related views (like "Zephyr Test Steps"), these will work as expected. But, nothing prevents you from enforcing them to true or false like this:

## issue-fo.vm

#set($exportZephyrTestSteps = true)
## ...

About performance: exporting test execution details (test step results) will significantly increase the number of required REST API calls and thus the total rendering time. If you are experiencing timeout issues, either set $exportZephyrTestExecutionDetails to false or export a smaller number of tests in one go.

Learn more about Zephyr Essential

• Zephyr Essential product information (at its own vendor)
• Zephyr Essential documentation
• Zephyr Essential app page (on the Atlassian Marketplace)