Why and how to upload metadata in Zephyr Enterprise Edition?

March 01, 2016

Overview on The Usefulness of Uploading Metadata

Zephyr Edition features the ability to manually upload an entire metadata dataset that completely describes a project within JIRA. When Zephyr customers have a larger-than-average dataset, we recommend using this method to at the very least prime Zephyr and make complete custom field collections available to its users. Large metadata datasets can cause Zephyr to timeout (taking too long to process the entire set as its fetched from JIRA) and some projects may not show all or any custom fields or entire option set for standard fields within Defect Tracking.

How to Fetch Metadata for JIRA Projects

JIRA allows users with the proper credentials to gather the metadata for projects within JIRA. In order to be successful, a user must have access to the entirety of the project in order for JIRA to allow display of all necessary information about a project.

To retrieve project metadata from JIRA browse to this URL in a browser that already has a logged-in JIRA session (separate tabs are acceptable):


This will generate a JSON-formatted output of metadata for every JIRA project available. This can be large, so JIRA allows users to specify projects to fetch. To do so, add the projectKeys variable to the URL string and specify a project key or several comma-separated project keys like so:


In the above example, only the projects with keys ABC, DEF, and GHJ will be displayed.

If your browser does not automatically prompt you to download this output, copy and paste it into a text editor and save it either as a .txt or a .json file. The name of the file is not important.

Manually Uploading JIRA Metadata to Zephyr

  1. Log into Zephyr with admin level credentials. You do not need to log in as the super-admin to complete this task.
  2. From the dropdown menu in the top left corner of the screen, choose Department.
  3. Choose Defects Admin from the left-hand menu.
  4. In the window that opens, choose the JIRA Custom Fields Management tab.Kindly refer the screen shot attached
  5. From within the Update Custom Field Metadata for JIRA Projects panel (seen above), enter the path to the file saved in the How to Fetch Metadata for JIRA Projects section. This path can be of one of these three types:

http:// or https://



  1. For file:///, append the absolute path in your system to the file in question. For example, if the file was named json and existed in the root of the C: drive, the path in this example would be file:///C:/metadata.json.
  2. Click the Upload button. If you receive an error saying the file size is too large, see the section Increasing File Size Limit for JIRA Metadata Upload and try again.

Once the data is uploaded, give Zephyr some time to work through the metadata. You will not see any indicators on screen when it is done, but this shouldn’t take more than a few minutes. 

Note: Technically speaking, the term “uploading” is misleading as no uploading actually takes place. What happens is more of a simple file read by the Zephyr client of a file on a user system.