---
title: "Creating your own Jira issues file"
canonical: "https://support.appfire.com/space/GFJ/17629228/Creating%20your%20own%20Jira%20issues%20file"
format: markdown
---
> Macro (aura-html)

<span style="color: #003300">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. </span>

<span style="color: #003300">This section contains the instructions to create your own Jira issues files.</span>

## <span style="color: #003366">Creating a Jira issues file</span>

<span style="color: #003300">1. Go to the "</span>**<span style="color: #003300">Issues</span>**<span style="color: #003300">" menu in Jira → </span>**<span style="color: #003300">Search for issues</span>**<span style="color: #003300">.</span>

<span style="color: #003300">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.</span>

![image](media://5c83f20e-364c-4075-b969-3c3be4f1e86c)

<span style="color: #003300">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</span> [article](https://confluence.atlassian.com/display/JIRA/Advanced+Searching).  
  
> Macro (inline-media-image)



> ⚠️ **Note**
> ⚠️ 
> ⚠️ <span style="color: #003300">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.</span>


<span style="color: #003300">3. To generate the XML file, click </span>**<span style="color: #003300">Export</span>**<span style="color: #003300"> button on the upper right corner of the page and select </span>**<span style="color: #003300">XML</span>**<span style="color: #003300">" from the drop-down list.</span>

![image](media://ccdd63e3-c390-48c7-9b1b-7be1cb56dcb6)


<span style="color: #003300">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).</span>

<span style="color: #003300">5. Before adding exported XML file to your Gaia Project Template, open the file in the text editor that supports XML format and </span>**<span style="color: #003300">escape </span>****<span style="color: #003300">special characters</span>**<span style="color: #003300"> (except when they're used as markup delimiters or within a comment, a processing instruction, or a CDATA section).</span>

> ❌ <span style="color: #333300">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:</span>
> ❌ 
> ❌ - <span style="color: #333300">The </span>`<`<span style="color: #333300"> </span><u><span style="color: #333300">must</span></u><span style="color: #333300"> be escaped with  </span>`&lt``;`<span style="color: #333300"> entity. Since it is assumed to be the beginning of a tag.</span>
> ❌ - <span style="color: #333300">The </span>`&`**<span style="color: #333300"> </span>**<u><span style="color: #333300">must</span></u><span style="color: #333300"> be escaped with  </span>`&amp``;`<span style="color: #333300"> entity. Since it is assumed to be the beginning an entity reference.</span>
> ❌ - <span style="color: #333300">The </span>`>`<span style="color: #333300"> should be escaped with </span>`&gt``;`<span style="color: #333300"> entity. It is not mandatory and depends on the context but it is strongly advised to escape it.</span>
> ❌ - <span style="color: #333300">The </span>`'`**<span style="color: #333300"> </span>**<span style="color: #333300">should be escaped with  </span>`&apos;`<span style="color: #333300"> entity. Mandatory in attributes defined within single quotes but it is strongly advised to always escape it.</span>
> ❌ - <span style="color: #333300">The </span>`"`<span style="color: #333300"> should be escaped with  </span>`&quot;`<span style="color: #333300"> entity. Mandatory in attributes defined within double quotes but it is strongly advised to always escape it.</span>

See the example:

| **Incorrect XML format** | **Correct XML format** |
| --- | --- |
| ![image](media://5ec0486b-b31f-4ce3-89a6-31e837f746e3) | ![image](media://37861b2a-ab05-4c02-8d35-b48adb6d9bc4) |

## <span style="color: #003366">Custom Field Support</span>

<span style="color: #003300">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</span> [supported custom field types](https://appfire.atlassian.net/wiki/spaces/GFJ/pages/17629696/Configuring+Gaia+for+Jira#ConfiguringGaiaforJira-Configuringatemplate)) <span style="color: #003300">and associate the custom field to the project being created by Gaia.</span>

<span style="color: #003300">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).</span>

<span style="color: #003300">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).</span>

> ⚠️ **Note**
> ⚠️ 
> ⚠️ <span style="color: #003300">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.</span>
> ⚠️ 
> ⚠️ <span style="color: #003300">For example, these custom fields types and associated options are not automatically created if they do not already exist:</span>
> ⚠️ 
> ⚠️ - <span style="color: #003300">Checkboxes;</span>
> ⚠️ - <span style="color: #003300">Radio Buttons;</span>
> ⚠️ - <span style="color: #003300">Select List (cascading);</span>
> ⚠️ - <span style="color: #003300">Select List (multiple choices);</span>
> ⚠️ - <span style="color: #003300">Select List (single choice).</span>


## What's next

Now that you have your own <span style="color: #444444">Jira </span>template file, use it in a Gaia for <span style="color: #444444">Jira </span>template. See [how to create a template guide](https://appfire.atlassian.net/wiki/spaces/GFJ/pages/17629696/Configuring+Gaia+for+Jira#ConfiguringGaiaforJira-Configuringatemplate) for more information.