Creating your own Jira issues file

Owned by Iryna Ihnatiuk
Last updated: Aug 16, 2021
3 min read

Jira issues file is XML file containing a list of issues. This file can be added to any Gaia template to generate new Jira projects containing a list of pre-defined issues. 

This section contains the instructions to create your own Jira issues files.

Creating a Jira issues file

1. Go to the "Issues" menu in Jira → Search for issues.

This menu shows existing filters and search options for finding issues based on search criteria. A Jira issues file can be generated from any filter or list of issues.



2. Filter the issues you want to export. Open an existing filter or launch a new JQL query to get the list of issues you want to export. If you need information on JQL, read this article.

Note

Please note that the maximum number of issues that can be exported is limited to 1000. Also note that the more issues you try to import, the longer it will take.


3. To generate the XML file, click Export button on the upper right corner of the page and select XML" from the drop-down list.


4. The generated file will automatically be displayed on your web browser. To save the file, search for a save option within the menus of your browser or hit Ctrl+S (which is normally the default shortcut on most browsers).

5. Before adding exported XML file to your Gaia Project Template, open the file in the text editor that supports XML format and escape special characters (except when they're used as markup delimiters or within a comment, a processing instruction, or a CDATA section).

The XML specification defines "predefined entities" representing special characters, and requires that all XML processors honor them. These characters need to be escaped to obtain a well-formed document:

  • The < must be escaped with  &lt; entity. Since it is assumed to be the beginning of a tag.
  • The & must be escaped with  &amp; entity. Since it is assumed to be the beginning an entity reference.
  • The > should be escaped with &gt; entity. It is not mandatory and depends on the context but it is strongly advised to escape it.
  • The ' should be escaped with  &apos; entity. Mandatory in attributes defined within single quotes but it is strongly advised to always escape it.
  • The " should be escaped with  &quot; entity. Mandatory in attributes defined within double quotes but it is strongly advised to always escape it.

See the example:

Incorrect XML formatCorrect XML format

Custom Field Support

If your issues have custom fields (these are automatically added in the XML file by the Jira exporter), Gaia will import the values of the associated custom fields (see supported custom field types) and associate the custom field to the project being created by Gaia.

If the custom field doesn't exist in the Jira instance, it will be automatically created and associated with the corresponding issue type (and to the project being created by Gaia).

If the custom field exists but doesn't have the right type, a new custom field will be created (with a (X) suffix) and will be automatically associated with the corresponding issue type (and to the project being created by Gaia).

Note

Only Jira's native custom field types that do not require options are automatically created if they do not already exist. If the custom field types that do require options exist but the options contained in the issues do not, those new options are not automatically created.

For example, these custom fields types and associated options are not automatically created if they do not already exist:

  • Checkboxes;
  • Radio Buttons;
  • Select List (cascading);
  • Select List (multiple choices);
  • Select List (single choice).


What's next

Now that you have your own Jira template file, use it in a Gaia for Jira template. See how to create a template guide for more information.