Export Options

Owned by Rosen Marinkov
Last updated: May 08, 2024 by Stanley Neychev
5 min read

On this page:

Selecting projects

The first stage of compiling an export file is to select which projects to export and whether to export complete projects or only their configurations.

To select your projects for export, complete the following steps:

  1. In your source instance, select Manage Apps from the Jira Administration menu then select Export Projects under Project Configurator in the left sidebar. This displays the Export Projects screen.

  2. Select one or more projects from the Projects to Export drop-down list or select the Export All Projects checkbox to export all of your projects.

  3. Select the Export mode. Options include Configuration Only or Complete Project. This selection applies to all of the selected projects.

Options

The Export Projects screen displays default options depending on whether you select Configuration Only or Complete Projects. If you wish to define your own custom options, you can then save this configuration to use in subsequent export tasks. This means you only need to select the saved configuration name from the Configuration Options drop-down list and not manually define each option.

Export Filename

The system generates a default filename for you, but you can change it to suit your needs by typing a name in the Export Filename input field. Note that file names must be unique.

The default exported filename looks similar to: config-dump_BDI1-ZH19-A0IA-E1XU_4_PROJECTS.xml.

  • It starts with a fixed string: config-dump for XML files and project-dump for ZIP files.

  • BDI1-ZH19-A0IA-E1XU is the server ID of the instance where the export was run.

  • _4_PROJECTS is displayed in this example because 4 projects are selected. It will state the project key if only one project is selected or ALL if you select all projects.

  • The file extension is .xml for configuration-only exports and .zip for complete project exports.

Attachments Migration Mode

This option is available if you select the Complete Projects Export Mode.

  • Automatic: Project Configurator embeds all necessary attachments for the selected projects into the same ZIP file that contains the project configuration and data.

  • Manual: This is recommended for larger instances with several issues and attachments. The exported ZIP file will not contain any attachments. You will need to move them manually to the target server before importing the projects. Our knowledge base article on manual attachment migration provides more information about this process.

Custom Field Options

The Filtering Custom Fields option allows you to select whether to export all custom fields or only those that are used by the exported projects (default). If you select Only those used in projects (no values considered), this exports only custom fields used by the exported projects, but it ignores whether there are values set for those fields in issues of the exported projects.

Users and Groups

The User Options drop-down list allows you to select how to handle user data during the export. Available options are:

  • Full Export: When a user name is found anywhere in the exported configuration, the app looks for the user and adds its description to the exported items. If the user is invalid, the export process stops with an error.

  • Ignore Invalid Users(default): When a user name is found that is not valid, the user and its description are not added to the exported items. The user name still appears as a component or project lead or in a permission/notification/issue security scheme in the exported file. The export process does not stop in these cases. Currently, the app is able to detect an invalid user name in two situations:

    • When it cannot find a user for that name.

    • When the found user has an invalid email address (it does not conform to the pattern "X@Y" where X and Y are non-empty strings)

  • Do Not Export: No users are exported, whether or not it is valid. The export process does not stop on an invalid user name.

The Group Options drop-down list offers the same options as User Options: Full Export, Ignore Invalid Groups, and Do Not Export. Currently the only case detected as an "invalid" group is when a group cannot be found for a given name.

Filters and Dashboards

The Filters To Export drop-down list allows you to control the export of filters. The choices are:

  • None: No filter is exported.

  • Shared With All Users: Exports filters that are shared with all users, including filters shared with anyone on the Web.

  • Shared With Exported Projects (default): Exports filters that are shared with one or all the roles of any of the exported projects.

  • With All Users or With Exported Projects: Exports filters that are shared with all users or with any of the exported projects. This is equivalent to combining the filter sets exported by the previous two options.

  • All Shared Filters: Exports filters that have been shared with someone else. This means that private filters that are only visible to their respective owners will not be exported.

  • All Filters (Shared or Private): Exports all filters in the instance, both shared and private.

The Dashboards To Export drop-down list offers the same choices as the Filters To Export listed above. Take into account that if you choose to export some or all dashboards but none of the filters, those filters that are used from dashboards will be exported anyway so that the exported configuration is complete.

Software Boards

Agile Board Options acts in a similar way. It allows you to select which boards to include in the export. The available options are:

  • None: No boards are exported.

  • Associated to Exported Projects(default): Boards that are linked to any of the exported projects are included in the export. Boards associated with a project appear under the project name in the project navigation panel.

  • All Scrum and Kanban Boards: All boards existing in the instance are exported, regardless of their relation to the exported projects. This option also exports boards whose filter was deleted, even if these boards are not visible within Jira.

Export of software boards requires that Jira Software application is enabled, otherwise, no boards are exported.

Saving export options

To save a custom export configuration to use in subsequent export tasks, complete the following steps:

  1. Before running the export, click Save Configuration.

  2. In the corresponding pop-up window, enter a name for the export configuration that you can easily identify for future use, e.g., config-only-prod. Names must be unique.

  3. To use the saved configuration, select it from the Configuration Options drop-down list that appears at the top of the Export Projects screen.

  4. If you wish to delete a selected saved configuration, click the Trash icon next to the Configuration Options drop-down list.

Run the export

Once you have selected your projects and configured your export options, click Export Projects. A progress indicator is displayed. Once complete, a success message is displayed. You can then download and save the corresponding .xml or .zip file.

What happens when I import this configuration file?

When you import a configuration file created with "Ignore invalid …​" or "Do not export" options, it is likely that it contains references to users or groups (by their names) where those users or groups are not included in the corresponding section of the configuration file. If a user or group with that name does not already exist in the target instance, there are some implications:

  • In some cases (e.g., users/groups are the default values in a custom field), especially if the owner of a filter or dashboard is missing, the import will fail.

  • Even when the import is successful, you are creating an inconsistency in your target instance. There will be a project, component, scheme, etc., referencing a user name or group name that does not correspond to a valid user or group.